SCHC Datagram Interface
The content of Acklio FullSDK can be described in its simplistic view as an adaptation layer with the SCHC mechanisms, and a set of interfaces: the Management API, the Datagram API, the Network API and the L2A interface.
Refer to the diagram of layers and interfaces for a better understanding.
The "UDP Client" and "DLMS using Gurux" Demo examples both use the following AT commands in their communication sequences.
About the Error messages
Error messages of the SCHC interfaces use the following format: AT_ERROR,<layer_id>,<status> where:
- The layer ID of the Management API is
1 - The layer ID of the Datagram API is
2 - The status is the numeric value returned by the library and listed in the header file 'fullsdkdtg.h'.
For example, the error message AT_Error,2,12 means that the session has been aborted by the receiver (error 12) at the level of the datagram interface (layer 2).
Error codes 4, 13, and 15 to 20 are not in the table because they are not returned by the FullSDK library.
The commands below are ordered from opening to closing a datagram socket.
Create a Datagram Socket
| What | Detail |
|---|---|
| Command | AT+SCHC=SOCKET |
| Parameter | — |
| Result codes | The socket ID and then OK, or an error (see below) |
AT_ERROR,2,<status> |
The socket ID is a numeric value.
Error Messages
AT_ERROR,2,<status> reports a datagram layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 1 | DTG_ERROR | Error in socket allocation |
| 2 | DTG_CONN_ERR | Not joined yet |
| 7 | DTG_NO_SOCKET_ERR | No socket available |
| 8 | DTG_NOT_IMPL_ERR | Protocol not implemented |
| 21 | DTG_TPL_PARAMS_ERR | Template parameters are not fully configured |
Bind the IP Address and the Port of the Host to a Datagram Socket
| What | Detail |
|---|---|
| Command | AT+SCHC=BIND,<socket_id>,<dev_addr>,<dev_port> |
| Parameters | <socket_id> - The socket ID |
<dev_addr> - See format below | |
<dev_port> - See format below | |
| Result codes | OK |
AT_PARAM_ERROR | |
AT_ERROR,1,<status> - See below | |
AT_ERROR,2,<status> - See below |
Recommendations
The device address may be an IPv6 or an IPv4 address, depending on the template in use. The expected formats must comply with the following rules:
IPv6 address – Format must be 8 groups of 4 hexadecimal numbers:
hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh
Wherehis an hexadecimal number (0 to 9, a to f or A to F).
Leading zeros in an individual field may be omitted, but there must be at least one numeral in every field.
The::notation can be used instead of:.IPv4 address – Format must be
n.n.n.n,nbeing a decimal number between0and255.
The device port must be a number between 0 and 65535.
Error Messages
AT_ERROR,1,<status> reports a management layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 11 | MGT_NOT_INIT_ERR | Acklio FullSDK has not been yet initialized |
| 13 | MGT_NETWORK_PROTOCOL_ERR | Invalid network protocol |
AT_ERROR,2,<status> reports a datagram layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 2 | DTG_CONN_ERR | Not joined yet |
| 7 | DTG_NO_SOCKET_ERR | No socket available or socket not allocated |
| 21 | DTG_TPL_PARAMS_ERR | Template parameters are not fully configured |
Send ASCII Data to a Remote Application
| What | Detail |
|---|---|
| Command | AT+SCHC=SEND,<socket_id>,<app_addr>,<app_port>,<ascii_data> |
| Parameters | <socket_id> - The socket ID |
<app_addr> - See format below | |
<app_port> - See format below | |
<ascii_data> - The data to be sent in ASCII format | |
| Result codes | OK |
AT_PARAM_ERROR | |
AT_ERROR,1,<status> - See below | |
AT_ERROR,2,<status> - See below | |
+SENDOK,<socket_id> | |
+SENDFAIL,<socket_id>,<status>,<error> |
Recommendations
The application address may be an IPv6 or an IPv4 address, depending on the template in use. The expected formats must comply with the following rules:
IPv6 address – Format must be 8 groups of 4 hexadecimal numbers:
hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh
Wherehis an hexadecimal number (0 to 9, a to f or A to F).
Leading zeros in an individual field may be omitted, but there must be at least one numeral in every field.
The::notation can be used instead of:.IPv4 address – Format must be
n.n.n.n,nbeing a decimal number between0and255.
The application port must be a number between 0 and 65535.
Transmissions
The OK result code or an error is returned immediately. If OK was returned, a transmission is attempted.
- If the transmission succeeds,
+SENDOKand the associated socket ID are returned at the end of the transmission. - If the transmission fails,
+SENDFAIL, the associated socket ID, a status and an error are returned at the end of the transmission.
The status that can be returned after a transmission failure are:
| Numeric value | Error code | Comment |
|---|---|---|
| 1 | DTG_ERROR | Internal error |
| 10 | DTG_L2_ERR | Error from L2 layer |
| 11 | DTG_SEND_ABORT_ERR | Session aborted by the sender |
| 12 | DTG_RECV_ABORT_ERR | Session aborted by the receiver |
Error Messages
The errors depend on layer 2.
AT_ERROR,1,<status> reports a management layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 11 | MGT_NOT_INIT_ERR | Acklio FullSDK has not been yet initialized |
| 13 | MGT_NETWORK_PROTOCOL_ERR | Invalid network protocol |
AT_ERROR,2,<status> reports a datagram layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 1 | DTG_ERROR | F/R layer unhandled error |
| 2 | DTG_CONN_ERR | Not joined yet or the connectivity is no more available |
| 5 | DTG_BUSY_ERR | Layer is busy, request is ignored |
| 7 | DTG_NO_SOCKET_ERR | No socket available or socket is not allocated |
| 3 | DTG_BUFFER_ERR | Provided buffer size is bigger than supported |
| 6 | DTG_NO_BIND_ERR | Bind has not been called and IP headers are requested |
| 9 | DTG_TOO_BIG_ERR | Data is too large to be sent without fragmentation |
| 10 | DTG_L2_ERR | Error from L2 layer |
| 14 | DTG_CD_ERROR | C/D layer error |
| 21 | DTG_TPL_PARAMS_ERR | Template parameters are not fully configured |
Send Binary Data to a Remote Application
| What | Detail |
|---|---|
| Command | AT+SCHC=SENDB,<socket_id>,<app_addr>,<app_port>,<binary_data> - SENDB where the B stands for "binary" |
| Parameters | <socket_id> - The socket ID |
<app_addr> - See format below | |
<app_port> - See format below | |
<binary_data> - The data to be sent as an ASCII string containing an hexadecimal value | |
| Result codes | OK |
AT_PARAM_ERROR | |
AT_ERROR,1,<status> | |
AT_ERROR,2,<status> | |
+SENDOK,<socket_id> | |
+SENDFAIL,<socket_id>,<status>,<error> |
Recommendations
The application address may be an IPv6 or an IPv4 address, depending on the template in use. The expected formats must comply with the following rules:
IPv6 address – Format must be 8 groups of 4 hexadecimal numbers:
hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh
Wherehis an hexadecimal number (0 to 9, a to f or A to F).
Leading zeros in an individual field may be omitted, but there must be at least one numeral in every field.
The::notation can be used instead of:.IPv4 address – Format must be
n.n.n.n,nbeing a decimal number between0and255.
The application port must be a number between 0 and 65535.
Transmissions
The OK result code or an error is returned immediately. If OK was returned, a transmission is attempted.
- If the transmission succeeds,
+SENDOKand the associated socket ID are returned at the end of the transmission. - If the transmission fails,
+SENDFAIL, the associated socket ID, a status and an error are returned at the end of the transmission.
The status that can be returned after a transmission failure are:
| Numeric value | Error code | Comment |
|---|---|---|
| 1 | DTG_ERROR | Internal error |
| 10 | DTG_L2_ERR | Error from L2 layer |
| 11 | DTG_SEND_ABORT_ERR | Session aborted by the sender |
| 12 | DTG_RECV_ABORT_ERR | Session aborted by the receiver |
Error Messages
The errors depend the layer 2.
AT_ERROR,1,<status> reports a management layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 11 | MGT_NOT_INIT_ERR | Acklio FullSDK has not been yet initialized |
| 13 | MGT_NETWORK_PROTOCOL_ERR | Invalid network protocol |
AT_ERROR,2,<status> reports a datagram layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 1 | DTG_ERROR | F/R layer unhandled error |
| 2 | DTG_CONN_ERR | Not joined yet or the connectivity is no more available |
| 5 | DTG_BUSY_ERR | Layer is busy, request is ignored |
| 7 | DTG_NO_SOCKET_ERR | No socket available or socket is not allocated |
| 3 | DTG_BUFFER_ERR | Provided buffer size is bigger than supported |
| 6 | DTG_NO_BIND_ERR | Bind has not been called and IP headers are requested |
| 9 | DTG_TOO_BIG_ERR | Data is too large to be sent without fragmentation |
| 10 | DTG_L2_ERR | Error from L2 layer |
| 14 | DTG_CD_ERROR | C/D layer error |
| 21 | DTG_TPL_PARAMS_ERR | Template parameters are not fully configured |
Reception of Data from a Remote Application
| What | Detail |
|---|---|
| Command | — |
| Parameters | — |
| Result codes | +RECVOK,<socket_id>:<binary_data> |
Received data is an ASCII string containing an hexadecimal value.
Close a Datagram Socket
| What | Detail |
|---|---|
| Command | AT+SCHC=CLOSE,<socket_id> |
| Parameter | <socket_id> - The socket ID |
| Result codes | OK |
AT_ERROR,2,<status> |
Error Messages
AT_ERROR,2,<status> reports a datagram layer error with the following possible values:
| Numeric value | Error code | Comment |
|---|---|---|
| 2 | DTG_CONN_ERR | Not joined yet |
| 7 | DTG_NO_SOCKET_ERR | No socket available or the socket is not allocated |