|
|
| Line 18: |
Line 18: |
| | o 1.2 Command Reference | | o 1.2 Command Reference |
| | | | |
| − | Serial Communication | + | [[Serial Communication|Serial Communication]] |
| | | | |
| | | | |
| Line 64: |
Line 64: |
| | [[Category:EtherCAT]] | | [[Category:EtherCAT]] |
| | [[Category:Control:Offline]] | | [[Category:Control:Offline]] |
| − |
| |
| − | <!-- @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -->
| |
| − |
| |
| − | = TCP/IP Communication =
| |
| − | Use TCP/IP communication with other computers and intelligent I/O devices over the Ethernet network. MC-BASIC uses TCP/IP API (sockets).
| |
| − |
| |
| − | TCP/IP provides multi-thread communications. The same physical link (Ethernet) is shared between several applications. This way, the softMC can connect to BASIC Moves and one or more intelligent I/O devices.
| |
| − |
| |
| − | The softMC supports both client and server roles for TCP/IP communications. The TCP/IP client connects to a remote system, which waits for a connection while the TCP/IP server accepts a connection from a remote system. Usually, the softMC serves as client while interfacing to an intelligent I/O connected to the LAN, and as a server when working toward remote host like a software PLC. The softMC uses Realtek RTL8019AS Ethernet NIC at a bit rate of 10 M bps.
| |
| − |
| |
| − | == Setup ==
| |
| − | TCP communication starts by opening a socket either to connect to a remote computer (remote host) or accept a connection from a remote host. Use '''CONNECT''' or '''ACCEPT''', depending on the softMC functionality (client or server).
| |
| − |
| |
| − | '''OPENSOCKET''' creates a TCP socket and assigns the socket descriptor to the specified device handle. The socket is created with '''OPTIONS '''NO_DELAY (send data immediately= 1). Otherwise, the data is buffered in the protocol stack until the buffer is full or a time-out is reached. This improves responsiveness when small amounts of data are sent. This option is recommended for interactive applications with relatively small data transfer. Otherwise, '''OPTIONS''' = 0.
| |
| − |
| |
| − | <pre>
| |
| − | OPENSOCKET OPTIONS=1 AS #1
| |
| − | </pre>
| |
| − |
| |
| − | '''OPENSOCKET''' <br/>assigns a device handle to the communication port (as '''OPEN'''). Any further reference to the communication port uses the device handle number. The device handle range is 1…255.
| |
| − |
| |
| − | There are several ways to set the IP address of the controller. By default, the softMC boots without a valid IP address. The following options are available to set the IP address of the controller:
| |
| − |
| |
| − | '''Static IP address setting'''<br/>Use SYS.IPADDRESSMASK in the Config.prg file to assign the IP address and Subnet mask:
| |
| − | <pre>
| |
| − | SYS.IPADDRESSMASK=”212.25.84.109:255.255.255.128”
| |
| − | </pre>
| |
| − | '''Dynamic address setting by Windows API'''<br/>API assigns an IP address to the softMC when it establishes TCP communication with the controller. The IP address and Subnet mask are taken out of a pre-defined address pool. BASIC Moves uses this address assigning method. Refer to the ''BASIC Moves Development Studio<sup>®</sup> User Manual'' and ''MC Reference Manual'' for detailed information.
| |
| − |
| |
| − | '''DHCP'''IP address is assigned by the DHCP server. If your network does not support DHCP, the controller tries to get the address from the DHCP server and times out after few minutes. During that time, communication with the controller is not possible.
| |
| − | <pre>
| |
| − | SYS.IPADDRESSMASK=”dhcp”
| |
| − | </pre>
| |
| − | If DHCP is used, select ''Automatic'' connection method as shown below:
| |
| − |
| |
| − | [[Image:Axsystems;UserManual-3-Setup.png|caption]]
| |
| − |
| |
| − | '''Get the controller’s IP address'''<br/>Use '''SYS.IPADDRESSMASK''' to query the IP address and Subnet mask of the softMC.
| |
| − | <pre>
| |
| − | -->?SYS.IPADDRESSMASK
| |
| − | 172.30.3.11:255.255.0.0
| |
| − | </pre>
| |
| − |
| |
| − | {{Note|'''''The softMC has several IP interfaces: Ethernet and IP over serial. However '''SYS.IPADDRESSMASK''' is only valid for Ethernet interfaces. Others have fixed IP addresses, which cannot be changed.'''''}}
| |
| − |
| |
| − | '''PING''' tests that a remote host is reachable. The remote host must support ICMP echo request.
| |
| − | <pre>
| |
| − | ?PING(”212.25.84.109”)
| |
| − | </pre>
| |
| − |
| |
| − | == softMC as TCP Client ==
| |
| − | When acting as a client, the softMC tries to connect to a remote server until a time out value expires or the connection is rejected. Use '''CONNECT''' when the softMC acts as a client.
| |
| − |
| |
| − | The softMC requests a connection from a remote host, according to a specific IP address and port. '''CONNECT''' blocks task execution until the connection is established or until the command fails. To unblock a task waiting in '''CONNECT''', close the corresponding socket using '''CLOSE'''. In addition, killing a task ('''KILLTASK''') blocked by '''CONNECT''' closes the socket to release the task. '''CONNECT''' may fail due to the following reasons:
| |
| − |
| |
| − | # Invalid socket descriptor
| |
| − | # Remote host has no application attached to specified port.
| |
| − | # Destination address is not reachable
| |
| − |
| |
| − | The following example illustrates a typical procedure of establishing a connection to a remote host, and sending and receiving data:
| |
| − | <pre>
| |
| − | OPENSOCKET OPTIONS=0 AS #1
| |
| − | CONNECT (#1,”212.25.84.100”,6002)
| |
| − | PRINT #1,”HELLO”
| |
| − | ?INPUT$(LOC(1),#1)
| |
| − | CLOSE #1
| |
| − | </pre>
| |
| − |
| |
| − | == softMC as TCP Server ==
| |
| − | When acting as a server. the softMC endlessly waits for a connection from the remote host. Use '''ACCEPT''' when the softMC acts as server. '''ACCEPT''' binds a socket to a specified port and waits for a connection. Simultaneous '''ACCEPT'''s on the same port are not allowed. '''ACCEPT''' blocks the execution of the calling task until a connection is established. To unblock the task waiting in '''ACCEPT''', close the corresponding socket with '''CLOSE'''. In addition, killing a task ('''KILLTASK''') blocked in '''ACCEPT '''closes the socket and releases the task. The following example illustrates a typical procedure of waiting for a connection from a remote host, and sending and receiving data:
| |
| − | <pre>
| |
| − | OPENSOCKET OPTIONS=0 AS #1
| |
| − | ACCEPT (#1,20000)
| |
| − | PRINT #1,”HELLO”
| |
| − | ?INPUT$(LOC(1),#1)
| |
| − | CLOSE #1
| |
| − | </pre>
| |
| − |
| |
| − | <!-- @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ -->
| |
| − |
| |
| − | = Serial Communication =
| |
| − | The softMC has RS-232 ports, which can be used for user communication. COM1 is reserved for maintenance purposes and not available for the application.
| |
| − |
| |
| − |
| |
| − | == Open Serial Port ==
| |
| − | Configurate the serial port with '''OPEN'''. Set the following port properties:
| |
| − |
| |
| − | '''BaudRate''' - baud rate of the device set to a specified value.
| |
| − |
| |
| − | '''Parity''' – enable/disable parity detection. When enabled, parity is odd or even.
| |
| − |
| |
| − | '''DataBits''' - number of data bits.
| |
| − |
| |
| − | '''StopBit''' - number of stop bits.
| |
| − |
| |
| − | '''Xonoff''' – sets raw mode or ^S/^Q flow control protocol mode (optional parameter disabled by default).
| |
| − |
| |
| − | For example:
| |
| − | <pre>
| |
| − | OPEN COM2 BUADRATE=9600 PARITY=0 DATABITS=8 STOPBIT=1 AS #1
| |
| − | </pre>
| |
| − | Opens COM2 at 9600 bps baud-rate, No parity, 8-bit data, 1 stop bit.
| |
| − |
| |
| − | '''OPEN''' assigns a device handle to the communication port. Any further references to the communication port uses the device handle number. The device handle range is 1…255. To change the communication parameters, close the serial port and reopen it using the new parameters. For more information, see '''PRINT #''' and '''INPUT$'''.
| |
| − |
| |
| − | = Send /Receive Data =
| |
| − | Serial and TCP communication use the same commands to send and receive data. After establishing communication over TCP or after configuring the serial port communication parameters, send and receive data regardless the communication type. Data flow differences are communication speed and the size of the input and output buffers. TCP/IP communication uses larger communication buffers.
| |
| − |
| |
| − | == Receive Data ==
| |
| − | The input-buffer of the serial ports is a fixed512 bytes size. User communication allows receiving strings using '''INPUT$'''. To check if data is ready at the input buffer, use '''LOC'''. The following example checks the number of bytes available at the input buffers and reads all the available data:
| |
| − | <pre>
| |
| − | -->?LOC(1)
| |
| − | 11
| |
| − | -->STRING_VAR = INPUT$(11, #1)
| |
| − | -->?STRING_VAR
| |
| − | Hello World
| |
| − | </pre>
| |
| − |
| |
| − | If '''INPUT$''' requests reading a data length larger than available data, the command returns only the available data:
| |
| − | <pre>
| |
| − | -->?LOC(1)
| |
| − | 11
| |
| − | -->STRING_VAR = INPUT$(20, #1)
| |
| − | -->?STRING_VAR
| |
| − | Hello World
| |
| − | </pre>
| |
| − |
| |
| − | '''LOC''' can be used within the '''INPUT$''':
| |
| − | <pre>
| |
| − | STRING_VAR = INPUT$(LOC(1), #1)
| |
| − | </pre>
| |
| − |
| |
| − | A partial read of the input buffer is allowed. This way, several calls to '''INPUT$''' empty the input-buffer:
| |
| − | <pre>
| |
| − | -->?LOC(1)
| |
| − | 11
| |
| − | -->STRING_VAR = INPUT$(3, #1)
| |
| − | -->?STRING_VAR
| |
| − | Hel
| |
| − | -->?LOC(1)
| |
| − | 8
| |
| − | -->STRING_VAR = INPUT$(8, #1)
| |
| − | -->?STRING_VAR
| |
| − | lo World
| |
| − | </pre>
| |
| − |
| |
| − | When calling '''INPUT$''', the system does not wait for data. If the input-buffer is empty, the command returns without any return value:
| |
| − | <pre>
| |
| − | -->?LOC(1)
| |
| − | 0
| |
| − | -->STRING_VAR = INPUT$(10, #1)
| |
| − | -->?len(STRING_VAR)
| |
| − | 0
| |
| − | </pre>
| |
| − |
| |
| − | == Send Data ==
| |
| − | '''PRINT #''' and '''PRINTUSING #''' send data over the serial port. Both commands use the same formatting as '''PRINT''' and '''PRINTUSING'''.
| |
| − |
| |
| − |
| |
| − | {{Note|''PRINT #''' and '''PRINTUSING #''' appends a carriage-return (ASCII value 13) and line-feed (ASCII value 10) characters at the end of each message. To print a message without the terminating carriage-return and line-feed characters use a semicolon at the end of the command.'''''}}
| |
| − |
| |
| − | For example, the following uses '''PRINT #''' to send data:
| |
| − | <pre>
| |
| − | -->STRING_MESSAGE = "ERROR"
| |
| − | -->PRINT #1, STRING_MESSAGE,"A1.PCMD=";A1.PCMD;
| |
| − | </pre>
| |
| − |
| |
| − | The output is:
| |
| − | <pre>
| |
| − | ERRORA1.PCMD=0.000000000000000e+00
| |
| − | </pre>
| |
| − |
| |
| − | The values of the following variables are sent one after the other. The output is (hexadecimal) 0x37 0x28:
| |
| − | <pre>
| |
| − | I1=55
| |
| − | I2=40
| |
| − | PRINT #1, I1;I2
| |
| − | </pre>
| |
| − |
| |
| − | The output is:
| |
| − | <pre>
| |
| − | 5540
| |
| − | </pre>
| |
| − |
| |
| − | == Send Data Block ==
| |
| − | '''PRINTTOBUFF # '''and '''PRINTUSINGTOBUFF # a'''llows buffering of data before actually being sent. This eliminates inter-character delays.
| |
| − | <pre>
| |
| − | printtobuff #handle,chr$(0); chr$(message_length); chr$(0);send=false
| |
| − | <nowiki>printtobuff #handle,chr$(request[ii]);send=false</nowiki>
| |
| − | <nowiki>printtobuff #handle,chr$(request[ii]);send=true</nowiki>
| |
| − | </pre>
| |
| − |
| |
| − | == Send/Receive NULL Character for Firmware Versions, Not Supporting UTF-8 Format ==
| |
| − | When using a specific protocol over Serial or TCP/IP ModBus RTU or ModBus TCP), the NULL character is part of the message. The message block cannot be saved in a STRING type variable since the NULL character terminates the string.
| |
| − |
| |
| − | In UTF-8 supporting versions 4.5.1 and higher, NULL characters are no longer cut out from strings, resulting in a different behavior:
| |
| − |
| |
| − | The string resulting from concatenation is composed from 'A''\0''B'; that is, there is a NULL character in the MIDDLE of the string:
| |
| − |
| |
| − | Len of Chr$(0) is 1:
| |
| − |
| |
| − | In previous versions NULL characters could not appear in the middle of strings, since the concatenation process cut these characters from the resulting string. End to send a NULL character in a message, send the data as single bytes instead of a string type message:
| |
| − | <pre>
| |
| − | <nowiki>COMMON SHARED X[10] AS LONG</nowiki>
| |
| − | <nowiki>X[1]=0x10</nowiki>
| |
| − | <nowiki>X[2]=0</nowiki>
| |
| − | <nowiki>X[3]=0x10</nowiki>
| |
| − | <nowiki>PRINT #1, CHR$(X[1]);CHR$(X[2]);CHR$(X[3]);</nowiki>
| |
| − | </pre>
| |
| − |
| |
| − | The output is the following stream of bytes:
| |
| − | <pre>
| |
| − | 0x10, 0x0, 0x10
| |
| − | </pre>
| |
| − |
| |
| − | When the received data contains a NULL character, read the data from the input buffer as single bytes instead of reading it into a string type variable. Convert the incoming data to a numeric value to get its ASCII value:
| |
| − | <pre>
| |
| − | <nowiki>DIM SHARED TEMP[10] AS DOUBLE</nowiki>
| |
| − | FOR IDX = 1 TO LOC(1)
| |
| − | <nowiki>TEMP[IDX] = ASC(INPUT$(1,#1))</nowiki>
| |
| − | NEXT IDX
| |
| − | </pre>
| |
| − |
| |
| − | The figure below gives a general description of the TCP/IP communication for both the client and host.
| |
| − |
| |
| − | [[Image:Axsystems;UserManual-4-SendReceive.png|caption|600px]]
| |
| − |
| |
| − | == Close Connection ==
| |
| − | '''CLOSE''' closes the connection and releases the device handle:
| |
| − | <pre>
| |
| − | -->CLOSE #1
| |
| − | </pre>
| |