UDP Sockets - Network of µPanels

 

Since Firmware version 003 (AA003A), µPanel implements functions for the direct use of TCP and UDP sockets, providing an easy and effective way to perform both low-level and high-level data transfer. In particular, UDP sockets can be easily used to arrange a network of µPanel devices. The main features of UDP socket functions are:

  • Up to 2 UDP Sockets (operating both for transmission and reception)
  • Low level access to datagram (either in binary or ascii mode)
  • Configure-and-Send-Datagram or Receive-and-Send-Datagram functions in a single command

The syntax of socket commands has been designed to minimise the micro-controller intervention during the implementation of simple data transfer. UDP commands start with the prefix $UDP. 

UDP Commands

UDP commands permit both to receive and transmit datagram using a given UDP port. When an UDP socket is created a user-defined datagram can be automatically sent.


UDP Socket Initialisation 

The general syntax for initialising an UDP socket follows: 

UDP Command syntax

$UDP N_Socket :Connection_Flags :Remote_Address :Remote_Port,[Local_Port] [:Message]


Where

  • [ ] brackets denote optional arguments
  • N_Socket is a digit in the range {0,1} indicating the number of the socket to use
  • Connection_Flags is a combination of one or more of the following characters, which specify the action to be performed with the socket:

    • {C, D, X, Q}: C for create (initialise socket); D for delete socket; X for destroy socket (delete and free resources); Q for query socket status.
    • {A, B}: A for transferring data in ascii mode, B for binary mode. The A flag can be followed by a number indicating the maximum allowed line length. If the line exceeds the specified length the line will be truncated. When the maximum line is specified and the line is not truncated the sequence of characters \ and n is appended to the line. For example, the flag A100 will set the maximum line length to 100 characters.
    • M: to enable the incoming IP/Port Mask. When the mask is enabled only those UDP packets coming from the IP Remote_Address and Port Remote_Port are accepted and displayed (if Remote_Port is not specified all Port values are accepted. If Remote_Address is not specified all IP values are accepted).


    Please note that the {C, D, X, Q} flags that must be the first ones in the sequence and of {A, B} that must be the second ones in the sequence. Please also note that the flags in curly brackets are mutual exclusive (i.e. you can not specify C and D simultaneously)

  • Remote_Address is either the domain name or the IP address of the remote device 
  • Remote_Port represents the port of the remote device
  • Local_Port is an optional field that can be specified to set the local port to use
  • Message represents the first datagram to send to the remote device as soon as the socket is created

-


Command results

The possibile responses to the Query command (Q) are:

$ERR-UDPn:Query   The socket could not be queried
$UDPn:IS-FREE    Not created
$UDPn:IS-DELETED
$UDPn:IS-CREATED
$UDPn:IS-ON-ERROR
$UDPn:IS-SENDING

Please refer to the end of this section for the list of the other messages

Basic Examples (a complete list of examples is provided at the end of this section)

Create the UDP socket with #ID 0 to send the UDP datagram "HELLO" (four bytes) to the remote device with IP 192.168.1.103 on the port 5700. The incoming datagram should be displayed in ascii mode 

$UDP0:CA:192.168.1.103:5700:HELLO

$OK-UDP0-Create
$UDP0:CREATED
$UDP0:SENT:1

 


UDP Data Send (Write)

The syntax of the command for sending a datagram through an already initialised UDP socket is as follow:

Command syntax

$UDP N_Socket: W: DATA


Where:

  • N_Socket is a digit in the range {0,1} indicating the number of the socket to use
  • DATA is a string containing the data to send. Data can contain all characters with the exception of the following 4 bytes, which have to be escaped:
    • return carriage byte 13 (escape sequence \r)
    • new line byte 10 (escape sequence \n)
    • null byte 0 (escape sequence \0)
    • back slash byte 92 (escape sequence \\)

Command results

$OK-UDPn-Sending immediately after command reception to acknowledge the command execution (n represents the socket number)

$UDPn:ERR-SEND immediately after command reception to indicate that there was an error in sending the datagram

$UDPn:ERR-BUSY immediately after command reception to indicate that the socket is not ready for sending (n represents the socket number)

$UDPn:SENT:n  when the data has been sent; n represents the socket number and x represents the number of the sent datagram, counted from the socket initialisation

  

Example

To write the string "Hello World" terminated with a new line (\n) to the UDP socket with ID 1: 

$UDP1:W:Hello World\n

$UDP1:SENT:1
$OK-UDP1-Sending


UDP Data Reply (to last received datagram)

The syntax of the command for sending a datagram to the device from which it has been received the last datagram is as follow:

Command syntax

$UDP N_Socket: R: DATA


Where:

  • N_Socket is a digit in the range {0,1} indicating the number of the socket to use
  • DATA is a string containing the data to send. Data can contain all characters with the exception of the following 4 bytes, which have to be escaped:
    • return carriage byte 13 (escape sequence \r)
    • new line byte 10 (escape sequence \n)
    • null byte 0 (escape sequence \0)
    • back slash byte 92 (escape sequence \\)

Command results

$OK-UDPn-Sending immediately after command reception to acknowledge the command execution (n represents the socket number)

$UDPn:ERR-SEND immediately after command reception to indicate that there was an error in sending the datagram

$UDPn:ERR-BUSY immediately after command reception to indicate that the socket is not ready for sending (n represents the socket number)

$UDPn:SENT:n  when the data has been sent; n represents the socket number and x represents the number of the sent datagram, counted from the socket initialisation

  

Example

To reply with the string "Received" terminated with a new line (\n) to the sender of the last received packet: 

$UDP1:R:Received\n

$UDP1:SENT:1
$OK-UDP1-Sending

 


UDP Data Read (datagram received)

When a datagram is received from a initialised socket, the following two messages are sent to the controller, containing Header and Data respectively:

Header Message format

$UDP N_Socket: #NNNN,IP :Port


Where:

  • N_Socket is number of the socket that received data
  • NNNN  is the number of received bytes formatted on 4 digit (e.g. 5 bytes will be 0005)
  • IP is the IP of the remote device that sent data (formatted as XXX.XXX.XXX.XXX)
  • PORT is the UDP port of the remote sender

Data message format

$UDP N_Socket: >X: [#NNNN:] [ASCII_DATA]

 

Where:

  • N_Socket is number of the socket that received data
  • X can be the character A (for ascii mode), and B (for binary mode). This character specifies how the received data will be sent to the micro-controller (the same mode used during the socket initialisation)
  • NNNN is a four-digit number that specifies the number of data bytes that follow the message (this field is sent only for Binary mode)
  • ASCII_DATA is the text line received in ASCII mode. If the socket is set in Binary mode, this field is empty and the binary message follows after a new line byte (\n).

Example

1) If the message "Hello" is received from the socket #0 configured in ASCII mode, the following output will appear:

$UDP0:#0005,192.168.001.103:64292
$UDP0:>A:HELLO

where 192.168.1.103 and 64292 are the sender's IP and Port respectively.

2) If the message "Hello" is received from the socket #0 configured in Binary mode, the following output will appear:

$UDP0:#0005,192.168.001.103:64292
$UDP0:>B:#0005:
HELLO

Please note that the binary message starts on a new line. 



UDP Sockets - Examples

 

Example 1

Send a datagram containing the 6 characters "HELLO\n" to a remote device with IP 192.168.1.103 on the UDP port 5700, using the UDP socket with ID #0:

Command

$UDP0:CA:192.168.1.103:5700:HELLO\n

Response

$UDP0:CREATED
$UDP0:SENT:1
$OK-UDP0-Create

Explanation: use UDP #0 to create (C) a socket in ascii (A) mode for sending datagrams to the remote IP 192.168.1.103 on UDP port 5700 and send the first datagram "HELLO\n". 

The system will automatically select a free local port. All datagrams received on this port will be accepted and processed regardless the IP and Port of the remote sender (i.e. the mask M flag is not used).

 

Example 2

Send a datagram containing the 6 characters "Hello\n" to a remote device with IP 192.168.1.103 on the UDP port 5700, using the local port 5600. Accept incoming datagram only with the IP and Port of the remote device (192.168.1.103:5700):

Command

$UDP0:CAM:192.168.1.103:5700,5600:Hello\n

Response

$UDP0:CREATED
$UDP0:SENT:1
$OK-UDP0-Create

Explanation: Use UDP #to create (C) a socket in ascii (A) mode for sending datagrams from the local port 5600 to the remote IP 192.168.1.103 on UDP port 5700 and send the first datagram "HELLO\n". 

Only those datagrams received from the specified remote IP and port will be accepted and processed.

 

Example 3

Create an UDP socket to receive/send datagrams in ascii mode from any devices on the local port 5600:

Command

$UDP0:CA::,5600

 

Example 4

Create an UDP socket to receive/send datagrams in ascii mode from any device sending from the remote port 5700 to the local port 5600:

Command

$UDP0:CAM::5700,5600

 

Example 5

Create an UDP socket to receive/send datagrams in binary mode from the remote device with IP 192.160.1.103 and port 5700, to the local UDP port 5600:

Command

$UDP0:CBM:192.168.1.103:5700,5600

 

UDP Socket Messages and Errors

Different messages can appear after the execution of UDP commands. The full list of message follows (where n is the socket ID number)

$UDPn:ERR-SOCK (err) Socket error (number err)

$UDPn:CREATED The socket has been created

$UDPn:SENT:x The datagram number x has been sent

$UDPn:ERR-DNS The remote server name could not be resolved