Serial Line Commands

The μPanel module is capable of receiving commands via its serial port.
Some of the wireless module configurations can be managed equally also through the module configuration menu on the μPanel App.
The supported serial commands are divided into two groups:

1) normal commands
2) protected commands

The first group contains commands that are usually required during the normal use of the system, e.g. for configuring the WiFi radio (name, password, etc). The second group, instead, contains commands that may alter permanently the system functions (e.g. firmare upgrade, serial line speed, etc). Since the execution of protected command by the user should be avoided in a final product, a special command exists to restrict the execution of protected commands only to the microcontroller connected to the serial line, preventing the change of important configurations from the App.

General remarks

Commands must begin with the dollar character ($) and terminate with the carriage return character (i.e. ascii code 10, or \n). The system is however tolerant to other types of line termination (such as \r and \r\n).

The default speed of the serial line is 57600 baud. This value can be changed through its specific command or from the module configuration menu on the app.

The list of supported command follows in this section.

$P (protected)

This command defines the graphical layout and elements of the panel in HCTML format. The maximum length of the HCTML string that defines the panel is 1000 characters.

Command syntax

$P: Panel_Design_in_HCTML_code

Command results

$OK-PANEL immediately after command reception and execution

Example
A simple panel with a button containing the text Start:  $P:B1:Start;

$APP-CLIM (protected)

This command permits to lock the execution of the protected commands by the WiFi Radio (e.g. from the mobile application). When the protected commands are locked, their execution can occur only through the serial line. This command may be useful before distributing a final product in which it is necessary to avoid that the final user can alter or change the WiFi module functions. This command can be executed only through the serial line.

Command syntax

$APP-CLIM

Command results
$OK-APPLIM immediately after command reception on success
$ERR-DENIED immediately after command reception if issued from the WiFi

Command retention
The configuration is saved into the non-volatile memory, so there is no need to issue this command at each reboot

$APP-CFULL (protected)

This command gives full control of the user through the WiFi, allowing the WiFi interface to execute also protected commands. Please note that this is the default situation.

Command syntax

$APP-CFULL

Command results
$OK-APPFULL immediately after command reception

Command retention
The configuration is saved into the non-volatile memory, so there is no need to issue this command at each reboot

$RESET (protected)

This command generates a software reset

Command syntax

$RESET

 

 

Command result

$OK-RES before to reset

System reboot

The module takes about 2 seconds to boot and to send the initial message:

{miuPanel STARTED – Ver. XXYYYZ – Fri Jul 10 11:13:03 CEST 2017}
$RES

$FIRMWARE_UPGRADE (protected)

This command upgrade the µPanel Firmware of the WiFi Module. To execute this command the WiFi module has to be connected to the Internet (with $CONNECT command) and to the server (confirmed by the $NOTIFY message).

This command can be protected by $AP-CLIM. When protected the command can be executed only from the serial line (i.e. it can not be executed from the mobile application)

Command syntax

$FIRMWARE_UPGRADE

Command results
$UPGRADE-NOT-ALLOWED immediately after command reception to indicate that the firmware upgrade is currently not permitted
$UPGRADE-NOT-NEEDED immediately after command reception to indicate that the WiFi module already runs the latest firmware
$UPGRADE-NOT-POSSIBLE immediately after command reception to indicate that the upgrade is not possible (e.g. no internet connection, no connection to server)
$WAIT immediately after command reception to indicate that the download process started
$ERROR:DNS after command execution to indicate that the process failed since the WiFi Module was unable to contact the server.
$ERROR-UPGRADING after command execution to indicate that the process timed out
$ERROR:BAD-CODE after command execution to indicate that the process failed since the server rejected the request or the received data were corrupted
$INSTALL-AND-REBOOT after command execution to indicate that the system is rebooting with the new firmware.

Command retention
/

$DOWNLOAD_AT (protected)

This command downloads and executes from internet the AT-Firmware. To execute this command the WiFi module has to be connected to the Internet (with $CONNECT command). By default, the AT-Firmware is already present in the WiFi Module memory, however, its space in memory might be reused in some cases.

This command can be protected by $AP-CLIM. When protected the command can be executed only from the serial line (i.e. it can not be executed from the mobile application)

Please note that, the execution of wrong AT commands may stuck the device into AT mode or even damage the device. If you need TCP/UDP sockets and network communication use the functions provided directly by the µPanel firmware instead (since version 003A). The use of the AT commands is at your own risk!

Command syntax 

$DOWNLOAD_AT

Command results
$WAIT immediately after command reception to indicate that the download process started
$ERROR:DNS after command execution to indicate that the process failed since the WiFi Module was unable to contact the server.
$ERROR-UPGRADING after command execution to indicate that the process timed out
$ERROR:BAD-CODE after command execution to indicate that the process failed since the server rejected the request or the received data were corrupted
$INSTALL-AND-REBOOT after command execution to indicate that the system is rebooting with the AT-Firmware

Command retention
After this command the WiFi Module will always boot on AT mode. To re-enable the µPanel use the AT command: AT+PANEL

NOTE: never perform a firmware upgrade using the AT commands since the µPanel firmware will be lost forever

$AT-REVERT (protected)

This command reboots the module with the AT-Firmware instead of µPanel. After this command is executed, the only way to re-enable µPanel is to send the command AT+PANEL from the serial line. Please note that the AT-Firmware configures the serial line at 115200 baud.

This command can be protected by $AP-CLIM. When protected the command can be executed only from the serial line (i.e. it can not be executed from the mobile application)

Please note that, the execution of wrong AT commands may stuck the device into AT mode or even damage the device. If you need TCP/UDP sockets and network communication use the functions provided directly by the µPanel firmware instead (since version 003A). The use of the AT commands is at your own risk!

Command syntax

$AT-REVERT

Command results
$SWITCH TO AT FIRMWARE immediately after command reception and right before execution
$ERROR AT NOT PRESENT immediately after command reception to indicate that the AT-Firmware is not loaded on the WiFi module. To download the firmware use $DOWNLOAD_AT

Command retention
After this command the WiFi Module will always boot on AT mode. To re-enable the µPanel use the AT command: AT+PANEL

NOTE: never perform a firmware upgrade using the AT commands or the µPanel firmware will be lost forever

$BAUD (protected)

This command permits to change the speed (baud) of the serial interface. The default value is 57600 baud. Standard values in the range 9600 – 115200 are accepted.

This command can be protected by $AP-CLIM. When protected the command can be executed only from the serial line (i.e. it can not be executed from the mobile application)

Command syntax 

$BAUD :Baud_Value

Command results
$OK-BAUD immediately after command reception and execution on success
$ERR-BAUD immediately after command reception and execution on error (e.g. bad parameters)

Command retention
This command and its parameters are saved into the non-volatile memory, so there is no need to issue this command at each reboot

$ROUTER

This command configures the router auto-configurator. In order to be able to communicate with your module from the Internet (i.e. from everywhere in the world) you have to configure your router to allow incoming TCP connections to reach the module port 80 and 81. The µPanel firmware is able to automatically configure most of the routers so that they will accept and forward these incoming connections. The currently supported protocols are the NAT-PMP and UPnP.

Command syntax

$ROUTER :PORT 1 :PORT 2

The command issued without parameters simply enables the router auto-configurator using two default TCP ports. The user can however specify the available ports to be used by the router to accept incoming TCP connections. If the first parameter is specified, also the second one has to be specified.

Command results
$OK-ROUTER immediately after the command reception
$ROUTER:IP,Port 1,Port 2 upon successful command execution (depending on the router, the command may require from a few seconds up to 1 min to complete. If the command fails no reply is provided)

Command retention
This command and its parameters are saved into the non-volatile memory, so there is no need to issue this command at each reboot.

$NOROUTER

This command disables the router auto-configurator.

Command syntax 

$NOROUTER

Command results
$OK-NOROUTER immediately after the command reception and execution

Command retention
The configuration is saved into the non-volatile memory, so there is no need to issue this command at each reboot

$APSET

This command permits to configure name, password and channel of the Access Point created by the WiFi module. By default, the name is miuPanel followed by the WiFi module ID, and the password is uPanel11.

Command syntax 

$APSET :SSID :PASSWORD :CHANNEL

The password and channel fields are optional. If the password is not specified, an open Access Point will be created. Channel can be an integer number in the range 1-13.

Command results
$OK-APSET after the command execution on success
$ERR-APSET after the command execution on error

Command retention
This command and its parameters are saved into the non-volatile memory, so there is no need to issue this command at each reboot

$CONNECT

This command permits to configure name, password and channel of the Access Point created by the WiFi module. By default, the name is miuPanel followed by the WiFi module ID, and the password is uPanel11.

Command syntax 

$CONNECT :SSID :PASSWORD :CHANNEL

SSID represents the name of the existing WiFi network to join (usually this is the name of your own home WiFi network). Password is the password for accessing the network. If the network is open the password field has to be omitted. If both the command parameters are omitted, the WiFi module try to connect using the las used parameters.

Command results
$OK-CONN immediately after the command reception to indicate that the WiFi module is trying to join the network
$ERR-CONN immediately after the command reception if the specified parameters are not valid
$CONNECTED when the connection succeeds
$NOTIFY after the connection to indicate that the WiFi module correctly registered itself on the cloud server by communicating its IP address. The cloud will provide on request to the App (when the “Discover IP” button is pressed) the new IP to use to reach the module.

$DISCONNECT

This command disconnects the WiFi module from the WiFi network (joined with the $CONNECT command)

Command syntax 

$DISCONNECT

Command results
$OK-DISC immediately after the command reception and execution

Command retention
The configuration is saved into the non-volatile memory, so there is no need to issue this command at each reboot.

$CONFIG

This command displays most of the WiFi Module configuration parameters

Command syntax 

$CONFIG

$PING

This command set the maximum communication interval between App and WiFi Module. Decreasing the PING interval results in a more responsive communication but it increases the traffic. The default PING value is of 500 ms. PING values lower than 250 ms maybe necessary to achieve real-time response.

Command syntax 

$$PING ms

 

$PASSWORD

This command protects the access to the module with a password. The password will be requested by the APP when the user starts the connection with the module. The password can be any number composed by up to 15 digits in the range {0..9}.

Please note that the App will remember the password, so it will be requested only once or only if the password has been changed.

Command syntax 

$PASSWORD:numeric_password:

Don’t forget the colon after the numeric_password

To disable the password simply set an empty one with the command $PASSWORD::

Command results
$OK-PASSWORD-SET  when the password has been successfully changed
$OK-PASSWORD:xxxxxx  when the password has been requested (i.e. numeric_password is not provided)
$ERR-PASSWORD  if the given password is invalid and can not be set

$ECHO

This command send a message to the micro-controller through the serial port

Command syntax 

$ECHO:message

$STAIP

This command can be used to display or set the static IP settings. If the command is executed without parameter the current setting are displayed.

Display current STATIC IP settings – Command syntax 

$STAIP

Command results
$STAIP AAA.AAA.AAA.AAA BBB.BBB.BBB.BBB CCC.CCC.CCC where A, B and C are respectively IP, Gateway, and Mask.

Assign a STATIC IP – Command syntax 

$STAIP AAA.AAA.AAA.AAA BBB.BBB.BBB.BBB CCC.CCC.CCC.CCC

Where A,B and C are respectively IP, Gateway and Mask. To disable static IP (and enable DHCP) set A,B  and C to 255.255.255.255

Command results
$OK-STAIP  immediately after the command execution if the parameters are accepted
$ERR-STAIP   immediately after the command execution if the parameters are invalid
$SET-STAIP  when the static IP takes affect (this message will appear also after boot)

Command retention
This command and its parameters are saved into the non-volatile memory, so there is no need to issue this command at each reboot.

$CONNSTA

This command displays the status of the connection with the router.

Command syntax 

$CONNSTA

Command results
$CONNSTA XXX AAA.AAA.AAA.AAA BBB.BBB.BBB.BBB RSSI   immediately after the command reception and execution

Where XXX is a decimal number (3 digits) representing the connection state: (005 = Connected, 255 = Disconnected)

A and B represent respectively the module’s IP and the gateway.

RSSI is a negative number that represents the strength (RSSI in dB) of the router WiFi connection.

$APSTA

This command displays the status of the Access Point

Command syntax 

$APSTA

Command results
$APSTA XXX AAA.AAA.AAA.AAA    immediately after the command reception and execution

Where XXX is a decimal number (3 digits) representing the number of devices (clients) connected to the module’s access point, and A is the module’s IP of the access point’s interface.

$AP-CLIMSET

This command protects (blocks) the access to some commands by the App. Four groups of commands can be protected:

  • Hardware ($P, $PASSWORD, $RESET, $LINK, $UNLINK, $FIRMWARE_UPGRADE, $DOWNLOAD_AT, $AT_REVERT, $BAUD, $TCP, $UDP, $ECHO, $STAIP, $DISK, $FILE)
  • Access Point ($APSET)
  • Router ($CONNECT, $DISCONNECT, $ROUTER, $NOROUTER)
  • Configuration (UART Monitor, $CONFIG, $PASSWORD)

Each group correspond to one ID code, as follow:

  • Hardware = 1
  • Access Point = 2
  • Router = 4
  • Configuration = 8

Command syntax 

$AP-CLIMSET[:SumOfGroupCodes]

Command results
$AP-CLIMSET: Sum_of_protected_group_codes

Where Sum_of_protected_group_codes represents the sum of the IDs of the groups currently protected/to proctect. For instance if the Hardware and Configuration groups are protected, the reply is: $AP-CLIMSET:9

If the optional parameter :SumOfGroupCodes is omitted, the command simply displays the current settings

The legacy command $APP-CFULL corresponds to $AP-CLIMSET:0

The legacy command $APP-CLIM corresponds to $AP-CLIMSET:1

$APLIST

This command displays the list of devices connected to the module’s access point

Command syntax 

$APLIST

Command results (for each connected device)
$APLIST XXX MM:MM:MM:MM:MM:MM AAA.AAA.AAA.AAA    immediately after the command reception and execution

Where XXX is the client number (sequential number of connected devices, starting from 1), MM is the device’s MAC Address, and A is the IP assigned to the connected device.

If no devices are connected the output will be

$APLIST 000

$TCP

This command permits to create and use TCP sockets.

For the full documentation please refer to the TCP SOCKETS – File/Data Transfer section.

$DISK

This command permits to manage the virtual disk created into the WiFi module’s flash memory.

For the full documentation please refer to the FILE SYSTEM – DISK section.

$FILE

This command permits to manage the file stored into the virtual disk created into the WiFi module’s flash memory.

For the full documentation please refer to the FILE SYSTEM – DISK section.

$UDP

This command permits to create and use UDP sockets.

For the full documentation please refer to the UDP SOCKETS – Panel Networks section.

File System (Disk) – Data Storage

Since Firmware version 003 (AA003A), µPanel implements a storage disk that can be used by the micro-controller to store non volatile data, such as measurements, calibration parameters, configuration data, and so on. A special filesystem (FS-RT78) has been designed by the µPanel engineers in order to implement an efficient high-reliable disk within the WiFi module flash memory. The main features are:

  • 163.898 bytes of user space
  • sectors of 3563 bytes
  • file name length up to 12 characters
  • immediate flush to disk (no latency)
  • write and verify architecture
  • up to 4 file simultaneously open (the same file allowed)
  • supported access modes: read / read-write / append / circular
  • file seek supported
  • case-sensitive names

Since reliability is one of the main feature that has been kept in mind during the design of the file-system, each sector can not contain more that one file. This means that the minimum space consumed by a file is of 3563 bytes and, therefore, no more than 43 files can be stored on the disk. Please note also that to make the file-system as much efficient as possibile, all the file are stored in the same root folder, and no sub-folder structure has been implemented.

Since one of the most important application for the storage disk on µPanel based-systems is the storage of log or measurement files, a special file mode has been implemented: the circular mode. When a file is open in write-circular or append-circular modes it is possibile to set the number of sectors that the file should use on the disk. When the file size reaches the number of specified sectors, and a new write is required, the oldest sector is deleted and a new one is allocated. This way the disk will be never full and the file will always contains the latest written data.

Two groups of commands exist to use storage disk:

  • DISK commands (provide functions to manage the disk content)
  • FILE commands (provide functions to work with files)

Disk commands permit to initialise and manage the disk content. All the implemented commands start with $DISK: followed by a suffix that specifies the command. The full list of command follows.

$DISK:FORMAT (protected)

This command delete all the disk content and prepare the disk to be used. This command must be execute the first time the module is used to prepare the disk.

Command syntax

$DISK: FORMAT

Command results
$WAIT immediately after command reception and execution
$OK-FORMAT on completion

Example
To prepare the disk to be used the first time:  $DISK:FORMAT

$DISK:AUTOFORMAT (protected)

This command calls the $FORMAT command only if the DISK needs to be formatted, otherwise it does nothing

Command syntax

$DISK: AUTOFORMAT

Command results
$WAIT immediately after command reception and upon format execution
$OK-FORMAT on format completion
$OK-AFORMAT if the disk does not require to be formatted

Example
To prepare the disk to be used, formatting it only if necessary:  $DISK:AUTOFORMAT

$DISK:LS (protected)

This command shows a list reporting all the files stored on the disk. The command can be abridged as $DISK:L

Command syntax

$DISK: LS

Command results
$DISK-LS
  immediately after command reception before the list is displayed
$LS: size file-name a formatted line reporting one list item (file name begins at column 15)
$OK-LS on completion, after the whole list has been displayed

Example
To obtain the file list:  $DISK:LS

Command:
$DISK:LS

Response
$DISK-LS
$LS:    34769 measures.txt
$LS:     1755 calib.bin
$OK-LS

$DISK:SPACE (protected)

This command shows the amount of free space on the disk. The command can be abridged as $DISK:S

Command syntax

$DISK: SPACE

Command results
$DISK-FREE: x bytes  immediately after command reception before the list is displayed

Example
To obtain the amount of disk free:  $DISK:SPACE

Command
$DISK:SPACE

Response
$DISK-FREE: 163898 bytes

$DISK:DEL (protected)

This command delete one file from the disk. The command can be abridged as $DISK:D

Command syntax

$DISK: DEL:FileName

Command results
$FILE-DELETED  immediately after command reception, after the file is deleted

Example
To delete a file whose name is measures.txt:  $DISK:DEL:measures.txt

Command
$DISK:DEL:measures.txt

Response
$FILE-DELETED

File Commands

This set of commands permits to create, write and read file content. The current µPanel firmware support up to 4 files. Each file is identified by a digit in the range 0 to 3. Each command begins with the prefix $FILE followed by the digit file ID.

The full list of file commands follows.

$FILE:OPEN (protected)

This command opens a file. The command can be abridged as $FILE:O

Command syntax

$FILE FILE_ID: OPEN: File_Name: File_Mode

Where:

  • FILE_ID is a digit in the range 0 to 3 to be used to identify this file during the file operations
  • FILE_NAME is a string up to 12 character long representing the file name (case sensitive)
  • FILE_MODE is a combination of the following (lower-case) characters that identify the open mode:
    • r – read mode: an existing file is opened for reading its content
    • w – write mode: existing file is deleted, a new file is created
    • a – if the file does not exist, it will be created. If the file exists it is opened in appending mode
    • c – circular mode. This mode has to be used along with w or a and permits to specify the maximum length in KB of the file. After this size the file is written as circular buffer. This parameter can be followed by the number of KB (e.g. wc7 will create a file for circular access with size no larger than 7 KB. Please note that, the c flag will never shrink a file already bigger than the specified size. If no size is specified a default value of 1 KB is used.

Command results
$FILEn:OPEN x bytes  immediately after command reception and file open (where n is the file ID and x the current file size)

Example
To open the file measure.txt in read-write-append mode using the ID 0:  $FILE0:OPEN:measures.txt:a

Command
$FILE0:OPEN:measures.txt:a

Response
$FILE0:OPEN 34769 bytes

$FILE:SEEK (protected)

This command move the current file pointer on a different position. Please note that this command can be used both for read and write modes, however, due to the flash memory, writing on file positions already written can not change the byte values but can only set bits not yet set of those bytes (a full re-write capability may by supported in future releases). The command can be abridged as $FILE:S

Command syntax

$FILE FILE_ID: SEEK: New_Position

Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies an open file
  • NEW_POSITION is the desired position in bytes from the file beginning. If the new position is bigger than the actual file size, the file pointer is positioned at the file end (if the file is opened in read mode), or the file size is increased (with empty bytes) until the pointer reaches the specified value.

Command results
$FILEn:SEEK: x 
 immediately after command reception and execution (where x is the new file position in bytes)

Example
To read an opened file (with ID 2)  from the byte number 10: $FILE2:SEEK:10

Command
$FILE2:SEEK:10

Response
$FILE2:SEEK: 10

$FILE:WRITE (protected)

This command permits to write data into an open file. The command MUST be abridged as $FILE:W

Command syntax

$FILE FILE_ID: W Write_Mode: DATA

Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies the open file to write into
  • WRITE_MODE is a combination of the following (uppercase) characters that define the write mode:
  • A (ascii) : the file is written in ASCII mode, which means that the DATA content passed in the write command is managed as pure text. Therefore, this mode does not allow to write to file special characters such as return carriage or null bytes.
  • B (binary) : the file is written in BINARY mode where all ASCII codes can be passed in the DATA content with the exception of the ASCII codes \r (13), \n (10), \0 (0), \\ (92), which have  to be “escaped”. E.g. to write the ascii code 13 (\r) the sequence composed by the two chars \ and  has to be included into the DATA content.
  • R (return carriage \r) : append a return carriage (ascii code 13) at the end of the DATA content
  • N (new line \n) : append a new line (ascii code 10) at the end of the DATA content 
  • L (line end \r\n) : append a return carriage (ascii code 13) and a new line (ascii code 10) at the end of the DATA content

Please note that either the A or B mode must be specified after the W command. Please also note that if more than one termination option (R,N,L) is specified, the actual write order is L,N,R.

Command results
$FILEn:WR: x bytes
 immediately after command reception and execution (where x is the number of written bytes)

Example
To write the string “Hello World” terminated with a new line (\n) to the file with ID 1: $FILE1:WAN:Hello World

Command
$FILE1:WAN:Hello World

Response
$FILE1:WR: 12 bytes

To write the string sequence of bytes 0x41 0x42 0x00 0x13 0x43 to the file with ID 0, the following command can be used:
$FILE0:WB:AB\0\rC

Command

$FILE0:WB:AB\0\rC

Response

$FILE0:WR: 5 bytes

$FILE:READ (protected)

This command permits to read data from an open file. The command MUST be abridged as $FILE:R

Command syntax

$FILE FILE_ID: R Read_Mode :Parameters

Where:

FILE_ID is a digit in the range 0 to 3 that identifies the open file to read from

READ_MODE is a ONE of the following (uppercase) characters that define the read mode:

  • A (ascii) : the file is read in ASCII mode: the file is managed as text file and it is read line by line. When this file mode is used the Parameter field can specify the number of lines to be read and the maximum number of characters per line. If the line length exceeds the specified number of characters the line is truncated. Please note that the new line character (\n) is used to detect the line end. Example 1: $FILE0:RA:5,20 reads from file 0, 5 lines up to 20 characters for each line
    Example 2: $FILE0:RA:3 reads from file 0, 3 lines
    Example 3:
    $FILE0:RA read from file 0 only 1 line

The command result for each read line has the following format:

$FILE0:>A:Read_Line

  • B (binary) : the file is read in BINARY mode: a specified number of bytes are read from the file and then sent directly to the micro-controller, without any encoding. Before the bytes are sent, however, a text line is sent reporting the format and the number of read bytes. When this mode is used, the Parameter field can specify the number of bytes to read. The maximum value is 256. If the parameter is not given the default used value is 256.Example:$FILE0:RB:10 reads 10 bytes from the file with ID 0 and send them to the micro-controller. Before the bytes are sent, however, the following line is also sent (which as always includes the new line terminator \n):

 

$FILE0:>B#0010:

where #0010 represent the number of bytes that will be sent to the micro-controller (without encoding)

  • X (hexadecimal) : the file is read in Hexadecimal mode: a specified number of bytes are read from the file and displayed in hexadecimal format. When this mode is used the Parameter field can specify the number of bytes to read. The maximum number of bytes that can be read with a single command is 256. If the parameter is not specified the default used value is 256.Example: $FILE0:RX:8 reads 8 byte from the file with ID 0 and displays them in hexadecimalThe command result of the previous example would be:$FILE0:>X#0008:xx xx xx xx xx xx xx xxwhere #0008 represents the number of following bytes, and xx the read bytes in hex format
  • D (decimal) : the file is read in Decimal mode: a specified number of bytes are read from the file and displayed in decimal format. The parameter syntax is the same as for X modeExample: $FILE0:RD:4 reads 4 byte from the file with ID 0 and displays them in decimal (always 2 digit)The command result of the previous example would be:$FILE0:>D#0004:xxx xxx xxx xxxwhere #0004 represents the number of following bytes, and xxx the read bytes in decimal format (always 3 digits)

 

Please note that only one of the previous mode can selected. Please also note that the number of bytes actually returned by the reading function can be less than the requested number when the end of file is reached.

Command results
The command results depends on the read mode, please see the previous description

$FILE:CLOSE (protected)

This command permits to close an open file, freeing the allocated resources. Please note, that data are written to the file immediately after the write command. Therefore, this command has no effect on the disk content and if the system is turned-off before the close is executed, no data are lost. The command can be abridged as $FILE:C

Command syntax

$FILE FILE_ID: CLOSE

Where:

  • FILE_ID is a digit in the range 0 to 3 that identifies the open file to close

Command results

$FILEn:CLOSED where n is the ID of the file that has been closed

Example

To close the file with ID 1: $FILE1:CLOSE 

Command

$FILE1:CLOSE

Response

$FILE1:CLOSED

Error Messages

Different error messages can appear after the execution of DISK and FILE commands. The full list of message follows.

$ERR-FS: 01 (Generic) Internal unexpected error

$ERR-FS: 02 (Memory) No enough memory to complete the operation

$ERR-FS: 03 (Disk) Flash memory support error

$ERR-FS: 04 (Disk IO) Impossible to read or write on flash memory

$ERR-FS: 05 (Generic) Unexpected error looking for a sector

$ERR-FS: 06 (Format) Disk not formatted

$ERR-FS: 07 (Permission) Operation not permitted (e.g. write on read file)

$ERR-FS: 08 (Write) Write operation error

$ERR-FS: 09 (Read) Read operation error

$ERR-FS: 10 (File Not Found) Specified file name not found

$ERR-FS: 11 (Disk Full) Operation not completed since the disk is full

TCP Sockets – File and Data Transfer

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 or to arrange networks of µPanel devices. In addition, the Socket functions can interact with the file system permitting the direct transfer of files over HTTP protocol (TCP), both for downloading and uploading data. The main features of TCP socket functions are:

  • Up to 2 TCP Sockets (operating either as client or as server)
  • Low level access to stream (either in binary or ascii mode)
  • Connect-and-Transfer or Listen-and-Transfer functions in a single command
  • HTTP support over TCP sockets for data transfer (both GET and POST methods supported)
  • Interaction with the uPanel File System for file transfer with HTTP protocol over TCP sockets
  • Both file upload and download, both with GET and POST methods
  • File Transfer protectable with custom password

The syntax of socket commands has been designed to minimise the micro-controller intervention during the implementation of simple data transfer. For instance a TCP server can be started with a preloaded first data packet to be transferred as soon as the client connects, or can be programmed to transfer a whole file with the remote device (both upload and download). TCP commands start with the prefix $TCP.

TCP commands permit either to establish a connection with a server or to listen to a given TCP port (server mode). In both the cases, when the connection with the remote device is established, an automatic action can be executed, such as:

  • transmission of a preloaded message
  • transmission of a predefined file
  • execution of a simple HTTP daemon (server mode)

TCP Socket Initialisation

The general syntax for initialising a TCP socket follows:

TCP Command syntax

$TCP N_Socket :Connection_Flags :Remote_Address :Port,[Parameter] [:File_Name[:Password]] [: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, L, D, X, Q}: C for connect (initialise the client mode); L for listen (initialise the server mode); D for disconnect socket; X for destroy socket (disconnect, 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.
    • F to enable the File transfer mode. This flag can be followed by one or more lower-case characters that represent the file-mode (e.g. Fac3 means File Mode in “Append,Circular,3 kB”). Please refer to the File section to obtain the full list of file modes.
    • H to enable the HTTP protocol for data transfer (both raw data and files)
    • {D, U}: D for download mode (default in C client mode), U for upload mode (default in L server mode)
    • K to enable the keep-alive connection mode
    • Q to enable auto-disconnect (quit) mode (i.e. the socket will be automatically disconnected after the first data packet is correctly sent)

    Please note that the flag order in not important, with the exception of {C, L, 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 L simultaneously)

  • Remote_Address is either the domain name or the IP address of the remote device
  • Port represents the destination port in client mode (connect) or the local port to listen to in server mode
  • Parameter represents the local port in client mode (connect) or the timeout in seconds (in server mode)
  • File_Name is an optional parameter that specifies the file name in “File Mode”. The File name can be followed by a password to protect the transfer.
  • Message represents the data to be sent to the remote device as soon as the connection is established

Please Note: File_Name and Message can not be both specified, but they are mutually exclusive.

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

$ERR-TCPn:Query   The socket could not be queried
$TCPn:IS-FREE    Not created
$TCPn:IS-DISCONNECTED
$TCPn:IS-CONNECTING
$TCPn:IS-CONNECTED
$TCPn:IS-ON-ERROR
$TCPn: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)
To connect the TCP socket with ID=1 to the Google Web server on port 80 with ascii transfer mode

$TCP1:CA:www.google.com:80
$OK-TCP1-Connecting
$TCP1:CONNECTED

TCP Data Send (Write)

The syntax of the command for sending some data through an already initialised and connected socket is as follow:

Command syntax

$TCP 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-TCPn-Sending
immediately after command reception to acknowledge the command execution (n represents the socket number)
$TCPn:ERR-BUSY immediately after command reception to indicate that the operation could not be executed because the socket is still busy with another operation (n represents the socket number)
$TCPn:ERR-SENDING immediately after command reception to indicate that the socket is not ready for sending (n represents the socket number)
$TCPn:SENT:x  when the data has been transferred; n represents the socket number and x represents the number of the sent packet, counted from the socket initialisation

Example
To write the string “Hello World” terminated with a new line (\n) to the TCP socket with ID 1:

$TCP1:W:Hello World\n
$OK-TCP1-Sending
$TCP1:SENT:1

TCP Data Receive (Read)

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

Header Message format

$TCP N_Socket: #NNNN,IP :Port

Where:

  • N_Socket is number of the socket that received data
  • NNN  is the number of received bytes formatted on 3 digit (e.g. 5 bytes will be 005)
  • IP is the IP of the remote device that sent data (formatted as XXX.XXX.XXX.XXX)
  • PORT is the TCP port of the remote sender

Data message format

$TCP 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\r\n” is received from the socket #0 configured in ASCII mode, the following output will appear:
$TCP0:#0007,192.168.1.103:64292
$TCP0:>A:HELLO
$TCP0:DISCONNECTED

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

2) If the message “Hello\r\n” is received from the socket #0 configured in Binary mode, the following output will appear:
$TCP0:#0007,192.168.1.103:64292
$TCP0:>B:#0007:
HELLO

$TCP0:DISCONNECTED

Please note that the binary message starts on a new line and that also the message terminators “\r\n” are sent through the serial line.

TCP Sockets – Examples

Example 1
Download the file logo.png from the www.miupanel.com server and save it with the name picture.png, using the TCP socket ID #0:

Command
$TCP0:CBFH:www.miupanel.com:80:picture.png:http://www.miupanel.com/logo.png

Response
$OK-TCP0-Connecting
$TCP0:CONNECTED
$TCP0:SENT:1
$TCP0:FILE-LEN:14125
$TCP0:FILE-SAVED
$TCP0:DISCONNECTED

Explanation: use TCP #0 to connect (C) in binary (B) mode for File (F) transfer over HTTP protocol (H) with the server www.miupanel.com on port 80. Save the received data into the file with name picture.png. The URL of the remote data is http://www.miupanel.com/logo.png 

Please Note: the FILE-LEN value can be -1 if the server does not specify the content-length header.

Example 2
Download and send to the micro-controller in ASCII mode the remote file robots.txt from the TCP port 80 of server  www.google.com, using the TCP socket with ID #0:

Command
$TCP0:CAH:www.google.com:80:/robots.txt

Response
$OK-TCP0-Connecting
$TCP0:CONNECTED
$TCP0:SENT:1
$TCP0:FILE-LEN:-1
$TCP0:#1440,149.003.177.026:00080
$TCP0:>A:User-Agent: *
$TCP0:>A:Disallow: /search
$TCP0:>A:Allow: /search/about

$TCP0:>A:D
$TCP0:#1440,149.003.177.026:00080
$TCP0:>A:isallow: /jsky/?

$TCP0:DISCONNECTED

Explanation: use TCP #0 to connect (C) and display in Ascii (A) mode the remote resource robots.txt available with the HTTP protocol (H) on the remote server www.google.com at port 80.

Note 1: the FILE-LEN is -1 since the server does not specify the content-length header.
Note 2: since the file is received in chunks (of 1440 bytes) the last line of the chunk can appear truncated. To avoid this problem define the maximum line length so that the line terminators will be marked as well (see the following example).

Example 3
Download and send to the micro-controller in ASCII mode with line terminators the remote file robots.txt from the TCP port 80 of server  www.google.com, using the TCP socket with ID #0:

Command
$TCP0:CA9999H:www.google.com:80:/robots.txt

Response
$OK-TCP0-Connecting
$TCP0:CONNECTED
$TCP0:SENT:1
$TCP0:FILE-LEN:-1
$TCP0:#1440,149.003.177.026:00080
$TCP0:>A:User-Agent: *\n
$TCP0:>A:Disallow: /search\n
$TCP0:>A:Allow: /search/about\n

$TCP0:>A:D
$TCP0:#1440,149.003.177.026:00080
$TCP0:>A:isallow: /jsky/?\n

$TCP0:DISCONNECTED

Explanation: use TCP #0 to connect (C) and display in Ascii (A) mode (using messages with no more than 9999 characters) the remote resource robots.txt available with the HTTP protocol (H) on the remote server www.google.com at port 80.

Note 1: the FILE-LEN is -1 since the server does not specify the content-length header.
Note 2: truncated lines at the end of the received chunks can be detected since they do not end with characters \ and n

Example 4
Save all the data sent by the remote Web server www.google.com into a local file named reply.txt, including the HTTP headers, sent as a reply to the GET / command, using the TCP socket with ID #0:

Command
$TCP0:CAF:www.google.com:80:reply.txt:GET / HTTP1.0\r\n\r\n

Response
$OK-TCP0-Connecting
$TCP0:CONNECTED
$TCP0:SENT:1
$TCP0:FILE-SAVED
$TCP0:DISCONNECTED

Explanation: use TCP #0 to connect (C) in Ascii (A) mode the server www.google.com on port 80 saving the whole reply to the file (F) name reply.txt. Since we want to save the HTTP headers too, we don’t enable the HTTP parser (H) so that the headers will not be removed. However, we have to manually set the HTTP message to request the remote resource, so we set the automatic message to be sent to the server after connection to: GET / HTTP/1.0

Example 5
Connect to the remote server www.google.com and send to the micro-controller in binary mode the response to the request GET /, using the TCP socket with ID #0:

Command
$TCP0:CB:www.google.com:80:GET / HTTP1.0\r\n\r\n

Response
$OK-TCP0-Connecting
$TCP0:CONNECTED
$TCP0:SENT:1
$TCP0:#0488,149.003.177.050:00080
$TCP0:>B:#0488:
HTTP/1.0 302 Found
Cache-Control: private
Content-Type: text/html; charset=UTF-8


$TCP0:DISCONNECTED

Explanation: use TCP #0 to connect (C) in Ascii (B) mode to the server www.google.com on port 80 and to request GET /, sending the whole reply to the micro-controller. Since we want to receive the HTTP headers too, we don’t enable the HTTP parser (H), so we have to manually send the request of the remote resource: we set the automatic first message to GET / HTTP/1.0

Example 6
Send to a custom server, with GET method, temperature and humidity, reporting to the micro-controller in ascii mode the server reply. In this example we suppose that a remote web server implements an asp/php page capable to read the parameters included in the requested URL. We suppose that the server will reply with a simple text line as well.

Command
$TCP0:CAH:www.miupanel.com:80:http://www.miupanel.com/measure.asp?t=23&h=53

Response
$OK-TCP0-Connecting
$TCP0:CONNECTED
$TCP0:SENT:1
$TCP0:FILE-LEN:15
$TCP0:#239,031.011.032.035:00080
$TCP0:>A:OK (T=23, H=53)
$TCP0:DISCONNECTED

File measure.asp on miupanel.com server

OK<% response.write ” (T=”+Request.QueryString(“t”)+”, H=”+Request.QueryString(“h”)+”)” %>

Explanation: use TCP #0 to connect (C) and display in Ascii (A) mode the reply of the server www.myserver.com to the HTTP (H) requested URL measure.asp. The parameters (temperature 23 °C, and humidity 53%) are included in the URL.

Example 7
Install a simplified WEB server to accept incoming HTTP requests (on TCP port 5555) and transfer (upload) local files (without restrictions on the file name and without password). The file should appear in the browser window.

Command
$TCP0:LAFH::5555

Response
$OK-TCP0-Listen

Browser request (URL) to request the logo of example 1

http://192.168.1.100:5555/picture.png

Response after browser request
$TCP0:CONNECTED
$TCP0:FILE-SENT
$TCP0:DISCONNECTED

Explanation: use TCP #0 to listen (L) and send in Ascii (A) mode a local file (F) using HTTP (H) protocol on TCP port 5555. Please note that the file is always transferred in binary mode to the browser, but the ascii mode (A) has the effect to display the transferred file into the browser window. The binary (B) mode would trigger the download dialog instead.

Example 8
Install a simplified WEB server to accept incoming HTTP requests (on TCP port 5555) for transferring (upload) the local file picture.png with password secretword. The file should be downloaded on the remote computer and not displayed in the browser window.

Command
$TCP0:LBFH::5555:picture.png:secretword

Response
$OK-TCP0-Listen

Browser request (URL) to request the logo of example 1

http://192.168.1.100:5555/picture.png?secretword

Response after browser request
$TCP0:CONNECTED
$TCP0:FILE-SENT
$TCP0:DISCONNECTED

Explanation: use TCP #0 to listen (L) and send in binary (B) mode the local file (F) picture.png using HTTP (H) protocol on TCP port 5555 protecting the transfer with the password secretword. Please note that using the binary mode, the browser will trigger the download dialog instead of displaying the file in the browser’s window.

Example 9
Install a simplified WEB server to accept incoming HTTP requests (on TCP port 5555) for transferring to the module’s flash memory (download!!) the file abc.txt with password secretword. The file is transferred from the remote computer to the module’s disk.

Command
$TCP0:LBFHD::5555:abc.txt:secretword

Response
$OK-TCP0-Listen

The browser can open a local html page to upload the file (source code follows)

http://127.0.0.1/upload.html

Response after browser request
$TCP0:CONNECTED
$TCP0:FILE-SAVED
$TCP0:DISCONNECTED

HTML File upload.html that can be used by a computer browser for selecting and transferring a file to the module’s disk

<html>
<body>
<form id=’uPost’ method=”post” enctype=”multipart/form-data” action=”http://192.168.1.100:5555/?file=abc.txt&secretword”>
<input type=”file” name=”ufile”>
</form>
<button onclick=’document.getElementById(“uPost”).submit();’>SEND</button>   </body>
</html>

Explanation: use TCP #0 to listen (L) and in binary (B) mode for downloading (D) a file (F) using the HTTP protocol (H) a file with name abc.txt on TCP port 5555 protecting the transfer with the password secretword. Please note that on the remote computer a browser can use the upload.html page reported above to perform the transfer.

Example 10
Install a simplified WEB server to display into a browser’s window the user defined message “Hello World” (or any other content). The system will accept incoming HTTP requests (on TCP port 5555).

Command
$TCP0:LAHQ::5555:HTTP/1.0 OK\r\n\r\nHELLO WORD

Response
$OK-TCP0-Listen

Browser request (URL)
http://192.168.1.100:5555/

Response after browser request
$TCP0:CONNECTED
$TCP0:>H:GET / HTTP/1.1
$TCP0:SENT:1
$TCP0:DISCONNECTED

Content of the browser window after the request

HELLO WORLD

Explanation: use TCP #0 to listen (L) in ascii mode (A) on the TCP port 5555, managing the HTTP protocol (H) of incoming requests, replying to them with the predefined message and quitting the communication immediately after the reply (Q). Please note, that in this specific case, the HTTP (H) mode has the effect to display only the first line of the HTTP request from the browser, while all the other lines are hidden (the first line is sent as: $TCP0:>H:….. where >H means received header)

Example 11
Install a simplified WEB server to display into a browser’s window the message the micro-controller decides depending on the required content. In this example, the a browser will request the content results (on TCP port 5555) and the micro-controller will reply with the message Result 1351

Command
$TCP0:LAHQ::5555

Response
$OK-TCP0-Listen

Browser request (URL)
http://192.168.1.100:5555/results

Response after browser request
$TCP0:CONNECTED
$TCP0:>H:GET /results HTTP/1.1

The microcontroller processes the request and execute the following command

$TCP0:W:Result 1351

Response after write request
$OK-TCP0:Sending
$TCP0:SENT:1
$TCP0:DISCONNECTED

Content of the browser window after the request

Result 1351

Explanation: use TCP #0 to listen (L) in ascii mode (A) on the TCP port 5555, managing the HTTP protocol (H) of incoming requests, quitting the communication immediately after the reply (Q). Please note, however, that no message is defined so the reply must be managed by the micro-controller. The HTTP (H) mode has the effect to display only the first line of the HTTP request from the browser, which is useful for the micro-controller to read the requested data. Please also note that the micro-controller reply does not include the HTTP response. A full compliant reply would require to send all the HTTP headers, for instance:

$TCP0:W:HTTP/1.0 200 OK\r\n\r\nResult 1351

The communication is automatically closed after the reply (Q), however, consider that, the socket is not deleted, so it is ready to receive other requests.

TCP Socket Messages and Errors

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

$TCPn:ERR-NET (err) Network error (number err)

$TCPn:FILE-SAVED The received file has been saved

$TCPn:DISCONNECTED The socket has been disconnected

$TCPn:FILE-SENT The local file has been sent

$TCPn:SENT:x The packet x has been sent

$TCPn:CONNECTED The socket has been connected

$TCPn:FILE-ERR-REPLY Malformed or unknown HTTP server response

$TCPn:FILE-ERR-RESP (x) The remote server responded with HTTP error x

$TCPn:FILE-LEN:x The server responded with Content-Length of x bytes

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

$TCPn:ERR-CONNECT (x) Failed to connect to the remote server (error x)

$TCPn:ERR-SOCKET-BUSY The socket is already busy with the previous operation

 

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

Serial Line Commands (available since firmware version 004A)

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

$NAME (protected)

This command sets the name of the product. This name will appear automatically in the APP when the user registers the module.

Command syntax

$NAME:Product_name
The maximum name length is of 63 characters (or 63 bytes). The name is NOT stored into the flash memory, so it has to be set each time the system is powered up or reset.

$WIFI (protected)

This command temporarily switch OFF/ON the WiFi radio, either as access point or as client.

Command syntax

$WIFI:Mode
Mode can be a number as follow:

Mode = 0: Access Point OFF, Client OFF
Mode = 1: Access Point OFF, Client ON
Mode = 2: Access Point ON, Client OFF
Mode = 3: Access Point ON, Client ON

$PWRD (protected)

This command enters/exits the power down mode.

Command syntax

$PWRD:E
Where E can be:E = 0: Power down disabled
E = 1: Power down enabled

During the power down mode the WiFi radio is turned off in order to reduce the power consumption. The serial interface and the internal DISK will continue to operate normally.

$CBRIDGE-ON (protected)

This command enables the cloud-bridge connection mode. When this connection mode is enabled, the communication with the miuPanel APP will transit across the cloud-bridge server, which acts as a bridge and permits the communication even if the module can not use a public IP. When this connection mode is enabled, the connection through router (both local or via Internet) will be disabled. It is still possible, however, to connect to the module through its access point. By default all modules uses our free cloud-bridge server, but on request, a dedicated cloud-bridge server can be created for a set of modules.

Command syntax

$CBRDIGE-ON
This configuration is stored into the flash memory, so it is not necessary to issue the command at each reboot.

$CBRIDGE-OFF (protected)

This command disables the cloud-bridge connection mode.

Command syntax

$CBRDIGE-OFF
This configuration is stored into the flash memory, so it is not necessary to issue the command at each reboot.

$PID

This command displays the Product ID (S/N) and the Full Product ID

Command syntax

$PID

$NEWREG (protected)

This command de-registers all the APP. After this command is issued, the module will be removed from all the mobile devices, and the registration process has to be repeated to add again the module into the list. The APPs that will not repeat the registration process will not receive push-notifications anymore.

Command syntax

$NEWREG

After the execution of this command the µPanel module will reboot


$CLOUD (protected)

This command permits to use some cloud functionalities.

Command syntax

$CLOUD Command:Parameters

Many cloud commands can be made available. The current supported commands are:

$CLOUD GET:DATE

Retrieve the date and time from the cloud. The reply will include the time in Java format followed by readable UTC date time. An example follows:

$CLOUD:TIME:1464599263603 2016-05-30 09:07:43 UTC

$CLOUD GET:DATE+TimeZone

Retrieve the date and time from the cloud. The reply will include the time in Java format followed by readable date time for the specifies time zone. As an example, the request $CLOUD GET:DATE+2 will produce the following reply:

$CLOUD:TIME:1464599263603 2016-05-30 11:07:43 UTC+2

 

$CLOUD SEND:PUSH:Message

Send a push notification (instant message) to all APPs that have registered the module. Please note that, push notification messages are not stored on the cloud, therefore, if a mobile device (e.g. smartphone) is off-line (e.g. turned off), only the last message sent to that spefic mobile device will be received when the device is turned on again.
Currently it is possible to sent a maximum of 100 FREE push messages per day, if you need to extend this limit, contact us!

Syntax

$CLOUD SEND: PUSH: message

 

Command results:

$OK-CLOUD  when the command is corretly sent to cloud
$ERR-CLOUD  when the cloud is busy or an error occours

Moreover, if command is correclty sent, the reply continues with:

$CLOUD:PUSH:n   when push are correctly sent (the field n reports the number of devices who received that push message)
$CLOUD:PUSH-ERR: Daily Limit  when the maximum daily number of free push is reached

Example

$CLOUD SEND:PUSH:Alarm detected!

Remember that all the commands must be termintated with the ‘\n’ character
Instruction example for Arduino:  Serial.println(“$CLOUD SEND:PUSH:Alarm detected!”);

$CLOUD PCODE:SET

The following command allow you to create and manage a pairing code used to add the wi-fi module to a new remote smartphone without the need for the smartphone to be near to the module during the adding procedure.
Because it is the cloud that receive the command and generate the pairing code, the module must be connected to internet through a router when the following command is used.

Command syntax

$CLOUD PCODE: SET: seed [:n]

Where the parameters are:

  • seed is a number of 12 digits (fixed lenght) used from the system to generate your pairing code
  • n is the number of  times the pairing code remains valid and can be used

The parameter n is optional, but we strongly recommend to specify a value. If you do not specify the number of  times, the pairing code remains valid for a unlimited number of uses. However, regardless the value of the number n, the code is deactivated if it is entered wrong for 20 consecutive times.
You can generate a new pairing code (or regenerate the same) in any moment, just launch again the command.

Command results:

$CLOUD:PCODE-SET:seed:n (Pairing-Pin-Code: xxxx-xxxx-xxxx-xxxx-xxxx-xxxx)

when the cloud correctly receive the command and reply with the pairing code to use on the app to add the module.
Note that the pairing code to use to add the module on a new smartphone is a string of  24 exadecimal chars.
The pairing code can be enteres with or without the dash chars ‘-‘.

$ERR-CLOUD

when the cloud does not respond, for instance because the module has not the internet access (note that it’s the µPanel cloud that generate the pairing code).

Disable the pairing code

You can disable in any moment the current pairing code, just sending the command without specify any paramenter:

$CLOUD PCODE: SET:

Note that this command do not cancel the module from the list on the App, but only make unusefull the current pairing code.
So, if you send the command:

$CLOUD PCODE:SET:

the cloud reply:

$CLOUD:PCODE-SET:Disabled:0 (Pairing-Pin-Code: xxxx-xxxx-xxxx-Disa-bled-)

Example

Sending the command:

$CLOUD PCODE:SET:123456789012:10

the cloud replies something like this:

$CLOUD:PCODE-SET:123456789012:10 (Pairing-Pin-Code: 0284-7d83-3567-1234-5678-9012)

$CLOUD PCODE GET

This command permit to check if a pairing code is active and if it has been used.

Syntax:

$CLOUD PCODE: GET:

Command results:

$CLOUD:PCODE-GET:seed:n:failures

When a pairing code has been defined.
seed is the number of 12 digits that you have prevously declared with the command PCODE:SET
n is the times in which pairing code can be used and that you have prevously declared in PCODE:SET
failures is  a number that reports how many consecutive times the pairing code has been entered incorrectly during the pairing procedure. A maximum of 20 consecutive errors are permitted and then the pairing code is disabled (you can generate a new or the same pairing code in any moment using the command PCODE:SET).

$CLOUD:PCODE-GET::0:0

When there is not an active pairing code

Example

Sending the command:

$CLOUD PCODE:GET:

the cloud could reply something like this:

$CLOUD:PCODE-GET:123456789012:8:2

means that the pairing code can be further used for 8 adding procedures but the last 2 times was entered incorrectly.
After that, if the user insert correctly the code, the new command reply will be:

$CLOUD:PCODE-GET:123456789012:7:0

otherwise, if the user insert again incorrectly the code, the new command reply will be:

$CLOUD:PCODE-GET:123456789012:8:3