SDK Instruction

TECHNOLOGY CO.,LTD.

SOYAL Product Line Training Course

SOYAL SDK Overview

SOYAL SDK Advantage

SOYAL SDK Content

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

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

communication.

Promotion between software and hardware communication ef ciency: input transfer value and receive value

to complete between software and hardware communication.

Promotion the ef ciency 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.

1.

2.

3.

ProtocolProtocol

AR-721E

E SeriesAR-401E

AR-401DI16AR-401RO16

H Series

U Series

VB2005 Demo Code

VC2005 Demo Code

Serial Port

Ethernet

AR-716EAR-829E

AR-721HAR-727H

AR-725E

AR-327HAR-321H

AR-757H

AR-737P

ResourceResource

Demo CodeDemo Code

SoyalComm.dll

VSCOM

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 com-

mand 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.

ProtocolProtocol

6-1

Communication Driver Program: SoyalComm.dllSoyalComm.dll is the program for communicate with hardware, uuu provide complete hardware in-terface functions to software (e.g. VB, VC, Java etc.) to more ef ciently complete the hardware data transmission and receiving functions, communicate with the hardware isnt low-level communication. SoyalComm.dll function API is de ned in SoyalComm.vb and SoyalComm.h.

Basic Programming Language Declare Import ModuleSoyalComm.vbSoyalComm.vb declared the definition of SoyalComm.dll function, include function type, variables and return value of function etc. If you wish to ef cient 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:

ResourceResource

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 Con gSCommParity()switch the parameters of serial device content to 9600,N,8,1

Setting error code

Declaration variables type

Chapter 6 SDK Section 1 SOYAL SDK Overview

6-2

TECHNOLOGY CO.,LTD.


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 deviceCreateSPort() can establish communication object be used in the communications for serial device.

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+1If 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 notIsPortAvailable() can check whether the COM port is available.

C Program Function Declare Import File: SoyalComm.hSoyalComm.h declared the de nition 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 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

BOOL OpenSComm( void *pComm, int Port )

OpenSComm() return value type is Boolean, delivering int and pointer variable pComm and Port to Call Open-SComm().

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 successfulIf 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,1Communication 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 CreateSPortAddress be delivered to *pComm is communication object established by CreateSPort().

Returns: Nonzero if the opening was successfulIf CloseSComm() return value not 0 mean COM port closed.

Effect: DisConnect the communication object with serial portCloseSComm() can disconnect communication object and serial device.

Chapter 6 SDK Section 2 SOYAL SDK Resource

6-4

TECHNOLOGY CO.,LTD.


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 *pLenIf DeleteSPort() return value not 0 mean all that information has been sent completed and be saved in pLen po-sition.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 RxBfxReadWriteSComm() can deliver data saved in TxBfx pLen position to serial port and receive data saved in Rx-

Bfx.

DWORD GetSCommStatus( void *pComm )

GetSCommStatus() return value type is WORD, delivering pointer variable pComm to Call GetSCommStatus().

In : Communication Object address, that create by CreateSPortAddress 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

BOOL Con gSComm( void *pComm, int baud )Con gSComm() return value type is Boolean, delivering int and pointer variable baud and pComm to Call Con- gSComm().

In : Communication Object address, that create by CreateSPort Serial port speedAddress be delivered to *pComm is communication object established by CreateSPort().

Value delivered to baud is serial port speed.

Returns: Nonzero if successedIf Con gSComm() 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.Con gSComm() can modify baud parameters to 9600,N,8,1.

BOOL Con gSCommParity( void *pComm, int baud, int Parity )Con gSCommParity() return value type is Boolean, delivering following variable to Call Con gSCommParity():


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 ParityAddress 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 successedIf Con gSCommParity() 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.Con gSComm() can modify baud parameters to 9600,N,8,1.


6-6

TECHNOLOGY CO.,LTD.


BOOL ReadSComm( void *pComm, BYTE* RxBfx, WORD* pLen )ReadSComm() return value type is Boolean, delivering following variable to Call ReadSComm():


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 readAddress be delivered to *pComm is communication object established by CreateSPort().

RxBfx: data will be received from SOYAL products save in RxBfxSendLength: bytes to be read.

Returns: Nonzero if any byte received and put the received bytes in *pLenIf any data received nish that the return value non 0 and save data to pLen position.

Effect: receive the return data in RxBfxReadSComm() can receive data from RxBfx.

6-7

VSCOM SOYAL SDK provide VSCOM to assist you create virtual serial ports in your system, and

redirects all serial data to speci ed TCP-port of remote IP-address. Any serial communication

software can use these virtual COM ports, like typical hardware COM ports, to send and re-

ceive serial data over a local network or the Internet.

VSCOM advantages is to assist application software engineers develope application soft-

ware 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

TECHNOLOGY CO.,LTD.


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.

Demo CodeDemo Code

VB2005 Demo Code Process and Example

N

Start

CheckCOM Portis available

Record thecommunication object

can not be opened

Y

N Create failuremessage

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

Receive / Deliver failure message 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

Open COM port in created communication object / Open successful message 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

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

Succeed

Succeed

Fail

CloseCOM Port

Deletecommunication Object

End

Open successfulmessage

Receivedmessage

Receive / Delivercommand code

Receive / Deliverfailure message

Delete successfulmessage

Delete successful message Txt_echo.Text = "Close CommPort " & Txt_PortNo.Text & " Success"

Delete communication object DeleteSPort(pComm)

Y

Sign out Level 2 TxBfx(0) = &H1TxBfx(1) = &H21

nLen = 2

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

nLen = 6

Receive/Deliver communication code

Check COM Port is available If IsPortAvailable(CInt(Txt_PortNo.Text) - 1) Then

Whether the communication object is successfully created pComm = CreateSPort()

Close COM Port CloseSComm(pComm)

ImportSoyalComm.vb

Import SoyalComm.vbModule 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

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 IntegerEnd Module

OpenCOM Port

RunSign in Level 2

Retry


can be opened

Whether the

communication object

is successfully created

RunSign out Level 2



Retry

Fail

Receivedmessage

6-9

VC2005 Demo Code Process and Example

ImportSoyalComm.h

NY

Import SoyalComm.h #include "SoyalComm.h"

Receive / Deliver failure message} else { 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" ); }}

Open COM port in created communication object if( OpenSComm( pComm, 0 ) {

if( ReadWriteSComm( pComm, TxBfx, RxBfx, &nLen ) ) { /////////////////////////////////////////////////// // The Header code will be included in return data // RxBfx: 7E 0C 01 ... // Do something // ...

Delete communication object DeleteSPort( pComm );

Receive/Deliver communication code

Check COM Port is available if( IsPortAvailable( i ) ) { // Do something like add to selection box }

COM Port is checked for( i=0; i < 6; i++ ) {

Close COM Port CloseSComm( pComm );

Sign in Level 2TxBfx[0] = 0xFF; // Destination Node AddressTxBfx[1] = 0x12; // Get Node informationTxBfx[2] = 0x02; // Read CommandTxBfx[3] = 'R'; // ParametersnLen = 4;

Sign out Level 2TxBfx[0] = 0xFF; // Destination Node AddressTxBfx[1] = 0x04; // Send ACK to reader for door open and no echonLen = 2;

N

N

CheckCOM Portis available


can not be opened

Y

Y

End

Whether the communication object is successfully created pComm = CreateSPort()

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

COM Portis checked

Start


can be opened

Whether the

communication object

is successfully created

Create failuremessage

OpenCOM Port

Open successfulmessage

RunSign in Level 2



Fail

Fail

Succeed

Succeed

Receivedmessage

RunSign out Level 2

Retry

Retry

Receivedmessage

CloseCOM Port

Deletecommunication Object



Chapter 6 SDK Section 3 SOYAL SDK Demo Code

6-10

TECHNOLOGY CO.,LTD.


VSCOM Operation Steps

Instal lat ion VSCOM

Start VSCOM

Step.01

Click start to install VSCOM.

Step.02

After install Visual Studio 2005, Start All Programs Soyal Software VSCOM to start VSCOM.

6-11

Execution VSCOMStep.03

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.

Chapter 6 SDK Section 4 VSCOM Operation Steps

6-12

Documents

SDK Instruction