The firmware supports two API operating modes: without escaped characters and with escaped characters. Use the AP command to enable either mode. To configure a device to one of these modes, set the following AP parameter values:
| AP command setting | Description |
|---|---|
|
AP = 0 |
Transparent operating mode, UART serial line replacement with API modes disabled. This is the default option. |
|
AP = 1 |
API operation. |
|
AP = 2 |
API operation with escaped characters (only possible on UART). |
The API data frame structure differs depending on what mode you choose.
The firmware silently discards any data it receives prior to the start delimiter. If the device does not receive the frame correctly or if the checksum fails, the device discards the frame.
We recommend this API mode for most applications. The following table shows the data frame structure when you enable this mode:
| Frame fields | Byte | Description |
|---|---|---|
| Start delimiter | 1 | 0x7E |
| Length | 2 - 3 | Most Significant Byte, Least Significant Byte |
| Frame data | 4 - n | API-specific structure |
| Checksum | n + 1 | 1 byte |
Set API to 2 to allow escaped control characters in the API frame. Due to its increased complexity, we only recommend this API mode in specific circumstances. API 2 may help improve reliability if the serial interface to the device is unstable or malformed frames are frequently being generated.
When operating in API 2, if an unescaped 0x7E byte is observed, it is treated as the start of a new API frame and all data received prior to this delimiter is silently discarded. For more information on using this API mode, refer to the following knowledge base article:
http://knowledge.digi.com/articles/Knowledge_Base_Article/Escaped-Characters-and-API-Mode-2
The following table shows the structure of an API frame with escaped characters:
| Frame fields | Byte | Description | |
|---|---|---|---|
| Start delimiter | 1 | 0x7E | |
| Length | 2 - 3 | Most Significant Byte, Least Significant Byte | Characters escaped if needed |
| Frame data | 4 - n | API-specific structure | |
| Checksum | n + 1 | 1 byte | |
When sending or receiving a UART data frame, you must escape (flag) specific data values so they do not interfere with the data frame sequencing. To escape an interfering data byte, insert 0x7D and follow it with the byte to be escaped XOR’d with 0x20. If not escaped, 0x11 and 0x13 are sent as is.
Data bytes that need to be escaped:
Example - Raw UART data frame (before escaping interfering bytes): 0x7E 0x00 0x02 0x23 0x11 0xCB
0x11 needs to be escaped which results in the following frame: 0x7E 0x00 0x02 0x23 0x7D 0x31 0xCB
Note In the previous example, the length of the raw data (excluding the checksum) is 0x0002 and the checksum of the non-escaped data (excluding frame delimiter and length) is calculated as:
0xFF - (0x23 + 0x11) = (0xFF - 0x34) = 0xCB.
This field indicates the beginning of a frame. It is always 0x7E. This allows the device to easily detect a new incoming frame.
The length field specifies the total number of bytes included in the frame's data field. Its two-byte value excludes the start delimiter, the length, and the checksum.
This field contains the information that a device receives or will transmit. The structure of frame data depends on the purpose of the API frame:
|
Start delimiter |
Length |
Frame data |
Checksum |
||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
|
Frame type |
Data | ||||||||||
| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | ... | n | n+1 |
| 0x7E | MSB | LSB |
API frame type |
Data |
Single byte |
||||||
Checksum is the last byte of the frame and helps test data integrity. It is calculated by taking the hash sum of all the API frame bytes that came before it, except the first three bytes (start delimiter and length).
The device does not process frames sent through the serial interface with incorrect checksums, and ignores their data.