TECHNOLOGY CO.,LTD.

SOYAL Product Line Training Course

SOYAL SDK Overview

SOYAL SDK provide protocol, resource and demo code to assist you quickly develop application software for the
SOYAL products.

SOYAL SDK Advantage

Between software and hardware communication: establish communication channels for software and hardware
communication.

Promotion between software and hardware communication efciency: input transfer value and receive value
to complete between software and hardware communication.

Promotion the efciency of application software development: Help software engineers to develop application
software can quickly and easily communicate with the hardware.

Seamless Integration of software and hardware: Full support for protocol all features and full highlight SOYAL
product characteristics.

SOYAL SDK Content

AR-721E

E Series

AR-401E
AR-716E
AR-829E

1. Protocol

H Series

AR-721H
AR-727H
AR-321H
AR-327H
AR-757H
AR-725E
AR-401DI16
AR-401RO16

U Series

AR-737P

Serial Port

SoyalComm.dll

Ethernet

VSCOM

2. Resource

VB2005 Demo Code

3. Demo Code
VC2005 Demo Code

Protocol
Protocol provide SOYAL all products Protocol and command code, application software developer utilize
Protocol and command code to seamless Integration of software and hardware. The same package command
code divided into three categories: E series command code, H series command code and U series command
code. E series command code SOYAL products: AR-721E, AR-401E, AR-716E and AR-829E, H series command code SOYAL products: AR-721H, AR-727H, AR-321H, AR-327H, AR-757H, AR401DI16, AR401RO16
and AR-725E, U series command code SOYAL products: AR-737P.

6-1

Chapter 6 SDK

Section 1 SOYAL SDK Overview

Resource

Communication Driver Program: SoyalComm.dll

SoyalComm.dll is the program for communicate with hardware, uuu provide complete hardware interface functions to software (e.g. VB, VC, Java etc.) to more efciently complete the hardware data
transmission and receiving functions, communicate with the hardware isnt low-level communication.
SoyalComm.dll function API is dened in SoyalComm.vb and SoyalComm.h.

Basic Programming Language Declare Import ModuleSoyalComm.vb

SoyalComm.vb declared the definition of SoyalComm.dll function, include function type, variables
and return value of function etc. If you wish to efcient development of application software be used
in hardware data transmission and receiving based on Visual Basic, you just include SoyalComm.vb
declare module will utilize all function of SoyalComm.dll. The following will introduce the contents of
SoyalComm.vb:

Declaration of function name, variables, variable type and return value of function from the SoyalComm.dll.

IsPortAvailable()check whether the COM port is available

OpenSComm()to determine whether COM port is opened successfully

CreateSPort()establish communication object be used in the communications for serial device

CloseSComm()closed COM port

ReadWriteSComm()delivering and receiving command code

GetSCommStatus()capture the state of port

DeleteSPort()deleting communication object

CongSCommParity()switch the parameters of serial device content to 9600,N,8,1

Setting error code

Declaration variables type

6-2


TECHNOLOGY CO.,LTD.

SOYAL Product Line Training Course

C Program Function Declare Import File: SoyalComm.h

SoyalComm.h declared the denition of SoyalComm.dll function, include function type, variables and
return value of function etc. If you wish to efficient development of application software be used in
hardware data transmission and receiving based on C, you just include SoyalComm.h declare le will
utilize all function of SoyalComm.dll. The following will introduce the contents of SoyalComm.h:

BOOL IsPortAvailable( int CommPort )

IsPortAvailable() return value type is Boolean, delivering int variable CommPort to Call IsPortAvailable().
In :
Serial port number (0 ... n) for COM:1 ... COM:n+1
If the deliver number is 0 that is mean COM port is COM 1...If the deliver number is n that is mean COM port is
COM n+1.
Returns: If the port is available or not
IsPortAvailable() can check whether the COM port is available.

void*

CreateSPort( void )

CreateSPort() dont have return value and no variable to Call CreateSPort().

Returns: If create successfully return the pointer of Item object that
represents the communication object that is created. otherwise return NULL
Return pointer if communication object builded successful else return NULL.
Effect: Use the method to create a objec for communication to a serial device
CreateSPort() can establish communication object be used in the communications for serial device.

BOOL DeleteSPort( void *pComm )

DeleteSPort() return value type is Boolean, delivering pointer variable CommPort to Call DeleteSPort().
Returns:

Nonzero if successful; otherwise zero

If DeleteSPort() return value not 0 mean COM port deleted successful else deleted fail.
Effect: Delete the object created by CreateSPort()
DeleteSPort() can delete communication object established by CreateSPort().

6-3

Chapter 6 SDK

Section 2 SOYAL SDK Resource

BOOL OpenSComm( void *pComm, int Port )

OpenSComm() return value type is Boolean, delivering int and pointer variable pComm and Port to Call OpenSComm().
In :

Communication Object address, that create by CreateSPort

Serial port number
( Ex: 0 for port COM1, 1 for port COM2 )

Address be delivered to *pComm is communication object established by CreateSPort().

If the delivered number is 0 that is mean COM port is COM 1...If the deliver number is n that is mean COM port
is COM n+1.
Returns: Nonzero if the opening was successful
If OpenSComm() return value not 0 mean COM port opened successful else opened fail.
Effect: Connect the communication object to serial port in 9600,N,8,1
Communication between communication and serial port is 9600,N,8,1.

BOOL CloseSComm( void *pComm )

CloseSComm() return value type is Boolean, delivering pointer variable pComm to Call CloseSComm().
In :
Communication Object address, that create by CreateSPort
Address be delivered to *pComm is communication object established by CreateSPort().
Returns: Nonzero if the opening was successful
If CloseSComm() return value not 0 mean COM port closed.
Effect: DisConnect the communication object with serial port
CloseSComm() can disconnect communication object and serial device.

6-4


TECHNOLOGY CO.,LTD.

SOYAL Product Line Training Course

BOOL ReadWriteSComm( void *pComm, BYTE* TxBfx, BYTE* RxBfx, WORD* pLen )
ReadWriteSComm() return value type is Boolean, delivering following variable to Call ReadWriteSComm():
Variable type is pointer and variable name is pComm
Variable type is BYTE and variable name is TxBfx
Variable type is BYTE and variable name is RxBfx
Variable type is WORD and variable name is pComm

In :

Communication Object address, that create by CreateSPort

TxBfx: Address of data block to transmit
RxBfx: reserved memory block to receive data
Set RxBfx to NULL for send only.
SendLength: number of bytes to transmit

Address be delivered to *pComm is communication object established by CreateSPort().

TxBfx: data will be delivered to SOYAL products save in TxBfx.
RxBfx: data will be received from SOYAL products save in RxBfx, if RxBfx is NULL mean RxBfx be used to
received data.
SendLength: data length can be delivered.
Returns: Nonzero if all bytes transmited and put the received bytes in *pLen
If DeleteSPort() return value not 0 mean all that information has been sent completed and be saved in pLen position.COM port deleted successful else deleted fail.
Effect: Transmits *pLen bytes of data from TxBfx to the serial port,
and receive the return data in RxBfx
ReadWriteSComm() can deliver data saved in TxBfx pLen position to serial port and receive data saved in RxBfx.

DWORD

GetSCommStatus( void *pComm )

GetSCommStatus() return value type is WORD, delivering pointer variable pComm to Call GetSCommStatus().
In :
Communication Object address, that create by CreateSPort
Address be delivered to *pComm is communication object established by CreateSPort().
Returns: Return unsigned long data of last ReadWriteSComm status
GetSCommStatus() return value is latest GetSCommStatus() status.

6-5

Chapter 6 SDK

Section 2 SOYAL SDK Resource

BOOL CongSComm( void *pComm, int baud )

CongSComm() return value type is Boolean, delivering int and pointer variable baud and pComm to Call CongSComm().
In :

Communication Object address, that create by CreateSPort

Serial port speed
Address be delivered to *pComm is communication object established by CreateSPort().
Value delivered to baud is serial port speed.
Returns: Nonzero if successed
If CongSComm() return value not 0 mean execute successful.
Effect: After OpenSComm the serial port parameters will be 9600,N,8,1
Use this function can change baud.
CongSComm() can modify baud parameters to 9600,N,8,1.

BOOL CongSCommParity( void *pComm, int baud, int Parity )

CongSCommParity() return value type is Boolean, delivering following variable to Call CongSCommParity():
Variable type is pointer and variable name is pComm
Variable type is int and variable name is baud
Variable type is int and variable name is Parity
In :

Communication Object address, that create by CreateSPort

Serial port speed
Parity: 0: Non Parity 1:Even Parity, 2:Odd Parity
Address be delivered to *pComm is communication object established by CreateSPort().
Value delivered to baud is serial port speed.
Different value delivered to Parity have different meanings, Parity is used to verify the accuracy of the data,
Parity=0: non-Parity bit mean no bit be used to verify the accuracy of the data; Parity=1: odd parity bit; Parity=2:
even parity bit.
Returns: Nonzero if successed
If CongSCommParity() return value not 0 mean execute successful.
Effect: After OpenSComm the serial port parameters will be 9600,N,8,1
Use this function can change baud.
CongSComm() can modify baud parameters to 9600,N,8,1.

6-6


TECHNOLOGY CO.,LTD.

SOYAL Product Line Training Course

BOOL ReadSComm( void *pComm, BYTE* RxBfx, WORD* pLen )

ReadSComm() return value type is Boolean, delivering following variable to Call ReadSComm():
Variable type is pointer and variable name is pComm
Variable type is BYTE and variable name is RxBfx
Variable type is WORD and variable name is pLen
In :

Communication Object address, that create by CreateSPort

RxBfx: reserved memory block to receive data
SendLength: number of bytes want to read
Address be delivered to *pComm is communication object established by CreateSPort().
RxBfx: data will be received from SOYAL products save in RxBfx
SendLength: bytes to be read.
Returns: Nonzero if any byte received and put the received bytes in *pLen
If any data received nish that the return value non 0 and save data to pLen position.
Effect: receive the return data in RxBfx
ReadSComm() can receive data from RxBfx.

6-7

Chapter 6 SDK

Section 2 SOYAL SDK Resource

VSCOM
SOYAL SDK provide VSCOM to assist you create virtual serial ports in your system, and
redirects all serial data to specied TCP-port of remote IP-address. Any serial communication
software can use these virtual COM ports, like typical hardware COM ports, to send and receive serial data over a local network or the Internet.
VSCOM advantages is to assist application software engineers develope application software in TCP/IP and don't modify original serial application or additional hardware devices
case, serial data will be sent directly to the network.

6-8

SOYAL Product Line Training Course

TECHNOLOGY CO.,LTD.

Demo Code
SOYAL SDK provide 2 different language structure example code: VB2005 Demo Code and VC2005 Demo
Code to assist software developer understand how to use SOYAL SDK and develop application software.

VB2005 Demo Code Process and Example

Import SoyalComm.vb
Module SoyalComm
Public Declare Function IsPortAvailable Lib "SoyalComm.dll" (ByVal CommPort As
Integer) As Boolean
Public Declare Function OpenSComm Lib "SoyalComm.dll" (ByVal pComm As
Integer, ByVal port As Integer) As Boolean
Public Declare Function CreateSPort Lib "SoyalComm.dll" () As Integer
Public Declare Function CloseSComm Lib "SoyalComm.dll" (ByVal pComm As
Integer) As Boolean
Public Declare Function ReadWriteSComm Lib "SoyalComm.dll" (ByVal pComm As
Integer, ByRef TxBfx As Byte, ByRef RxBfx As Byte, ByRef pLen As UShort) As
Boolean
Public Declare Function GetSCommStatus Lib "SoyalComm.dll" (ByVal pComm As
Integer) As Integer
Public Declare Function DeleteSPort Lib "SoyalComm.dll" (ByVal pComm As
Integer) As Boolean
Public Declare Function ConfigSCommParity Lib "SoyalComm.dll" (ByVal pComm
As Integer, ByVal Baud As Integer, ByVal Parity As Integer) As Boolean

Start

Public Const Comm_RxTimeOut As ULong = &H10

Public Const Comm_RxErrSum As ULong = &H80
Public Const comm_TxErrLength As ULong = &H200
Public pComm As Integer
Public TxBfx(1024 - 1) As Byte 'Declare array(1023) as Byte will allocate
1024(0~1023) bytes buffer
Public RxBfx(1024 - 1) As Byte
Public nLen As UShort
Public dwError As ULong
Public Baud As Integer
Public Parity As Integer
End Module

Import

SoyalComm.vb

Check
COM Port
is available

Record the
communication object
can not be opened

Check COM Port is available

If IsPortAvailable(CInt(Txt_PortNo.Text) - 1) Then

Y
Record the
communication object
can be opened

Whether the communication object is successfully created

Whether the
communication object

pComm = CreateSPort()

Create failure
message

is successfully created

Create failure message

If pComm = 0 Then
Txt_echo.Text = Txt_echo.Text & "Can't creat SoyalComm object" & vbCrLf

Open COM port in created communication object /

Open successful message

Y
Open
COM Port

If OpenSComm(pComm, CInt(Txt_PortNo.Text) - 1) Then

Baud = 9600
Parity = 0
ConfigSCommParity(pComm, Baud, Parity)
Txt_echo.Text = Txt_echo.Text & "Open CommPort " & Txt_PortNo.Text & "
Success" & vbCrLf
End If

Open successful
message

Receive/Deliver communication code

Run
Sign in Level 2

Retry

Sign in Level 2
TxBfx(0) = &H1
TxBfx(1) = &H20
TxBfx(2) = &H11
TxBfx(3) = &H22
TxBfx(4) = &H33
TxBfx(5) = &H44

Sign out Level 2

TxBfx(0) = &H1
TxBfx(1) = &H21
nLen = 2

nLen = 6

Receive / Deliver
command code

Fail

Receive / Deliver
failure message

Succeed
Received
message

Receive / Deliver failure message

Run
Sign out Level 2

Retry

Receive / Deliver
command code

If ReadWriteSComm(pComm, TxBfx(0), RxBfx(0), nLen) Then

Txt_echo.Text = ""
Dim LoopTemp As Int16
If RxBfx(0) = &H7E Then
For LoopTemp = 0 To RxBfx(1) + 1
If RxBfx(LoopTemp) < 15 Then
Txt_echo.Text = Txt_echo.Text & "0"
End If
Txt_echo.Text = Txt_echo.Text & Hex(RxBfx(LoopTemp)).ToString & " "
Next
End If

Fail

dwError = GetSCommStatus(pComm)
If dwError And Comm_RxTimeOut Then
LabMsg.Text = "Timeout!"
End If
If dwError And Comm_RxErrSum Then
LabMsg.Text = "Check Sum Error"
End If
If dwError And comm_TxErrLength Then
LabMsg.Text = "Cann't send to serial Port!"
End If

Receive / Deliver
failure message

Succeed
Received
message

Close COM Port

Close
COM Port

CloseSComm(pComm)

Delete communication object

Delete
communication Object

DeleteSPort(pComm)

Delete successful message

Delete successful
message

Txt_echo.Text = "Close CommPort " &

Txt_PortNo.Text & " Success"

End

6-9

Chapter 6 SDK

Section 3 SOYAL SDK Demo Code

VC2005 Demo Code Process and Example

Start

Import SoyalComm.h

Import
SoyalComm.h

#include

"SoyalComm.h"

Check COM Port is available

Check
COM Port
is available

if( IsPortAvailable( i ) ) {
// Do something like add to selection box
}

Record the
Record the
communication object communication object
can not be opened
can be opened

COM Port is checked

N

for( i=0; i < 6; i++ ) {

COM Port
is checked

Y
Whether the
communication object

Whether the communication object is successfully created

Create failure
message

is successfully created

pComm = CreateSPort()

Create failure message

if( (pComm = CreateSPort()) == NULL ) {
printf( "Cann't create SoyalComm object !\n" );
return;
}

Open COM port in created communication object

Open
COM Port

if( OpenSComm( pComm, 0 ) {

Open successful
message

Receive/Deliver communication code

Sign in Level 2
TxBfx[0] = 0xFF;
TxBfx[1] = 0x12;
TxBfx[2] = 0x02;
TxBfx[3] = 'R';
nLen = 4;

Run
Sign in Level 2

Retry

Receive / Deliver
command code

Fail

Sign out Level 2

TxBfx[0] = 0xFF;
TxBfx[1] = 0x04;
and no echo
nLen = 2;

Receive / Deliver
failure message

// Destination Node Address

// Send ACK to reader for door open

if( ReadWriteSComm( pComm, TxBfx, RxBfx, &nLen ) ) {

///////////////////////////////////////////////////
// The Header code will be included in return data
// RxBfx: 7E 0C 01 ...
// Do something
//
...

Succeed
Received
message

Receive / Deliver failure message

} else {

Run
Sign out Level 2

Retry

Receive / Deliver
command code

// Destination Node Address

// Get Node information
// Read Command
// Parameters

Fail

dwError = GetSCommStatus( pComm );

if( dwError & COMM_RXTIMEOUT ) {
printf( "Timeout !\n" );
}
if( dwError & COMM_RXERRSUM ) {
printf( "Check Sum Error !\n" );
}
if( dwError & COMM_TXERRLENGTH ) {
printf( "Cann't send to serial port !\n" );
}

Receive / Deliver
failure message

Succeed
Received
message

Close COM Port

Close
COM Port

CloseSComm( pComm );

Delete communication object

Delete
communication Object

DeleteSPort( pComm );

End

6-10


TECHNOLOGY CO.,LTD.

SOYAL Product Line Training Course

VSCOM Operation Steps

Step.

01

Installation VSCOM

Click

Step.

02

start to install VSCOM.

Start VSCOM

After install Visual Studio 2005, Start

6-11

All Programs

Soyal Software

VSCOM to start VSCOM.

Chapter 6 SDK

Step.

03

Section 4 VSCOM Operation Steps

Execution VSCOM

Step 1.

Step 3.

Step 1.Input IP address to be simulated.

Step 2.Input virtual COM Port.
Step 3.Press "ADD" button.
Step 4.The COM Port status will be showed.
After VSCOM set up, you can use the above example of transferring data through TCP/IP.

6-12