What is the API Codec?
If you are working with TCP/IP or Wireless communications, you might want to consider using the API Codec to handle all communication functions. The API Codec will “wrap” standard commands with a Header, Byte Counter, and a Checksum, which eliminates the need for timeout command processing (the standard method of communications which stalls processing of commands). he API Codec is a faster, more reliable method of communicating to NCD devices, particularly when working with network- or wireless-based devices. The API Codec makes communications more resilient to errors and eliminates timeout requirements of standard communication methods. While you will benefit from speed and reliability, data must be encoded and decoded to fully support the API Codec.
To better understand why the API Codec was created, it is important to understand standard timeout based communications. Timeout based communications means you send your command to the controller, the controller waits until you stop sending data, times out, processes your command, and reports data back to the host computer. The API Codec eliminates the Timeout (and delay) from the standard protocol. Because the API Codec includes a checksum, invalid data is automatically discarded to prevent false processing of commands.
The API Codec does not interfere with standard communications in any way. If you send a standard command to an API capable controller, you will get a standard response. If you send an API Encoded command to an API capable controller, you will get an API Encoded response. So any controller that supports the API Codec is 100 percent backward compatible with standard communication protocols. The API Codec should be thought of as a new layer of communications that operates 100 percent independent of standard communication protocols. Your software may be written with a mix of API and Standard communication functions. Commands that require optimal reliability can be sent using API communications while standard communications can be used to preserve compatibility with older portions of your software.
Device Identification
Not all controllers support the API Codec. Click Device Identification and look at the API Support status field. All NCD devices with firmware version 3.2 or later will support API Communications. If your controller supports the API Codec, the word “Supported” will be displayed as shown below:
API in Base Station
Beginning with Version 3.2 of Base Station, the Base Station software attempts to communicate all commands in API format if API mode is supported. The “Use API Mode when Possible” check box will be checked by default and all subsequent portions of Base Station will communicate in API mode when possible.
The top of all forms that support API will indicate (API Mode) as shown here indicating all communication is formatted in API Format.
You may turn this off by unchecking the “Use API Mode when Possible” on the main Base Station screen.
Base Station: API Codec
To help users better-understand the API Codec, a new control panel was created that allows you to enter commands in Standard Format and encode/decode the responses. This is a valuable learning tool for users who may wish to learn and troubleshoot the API Codec.
Move the Slider to select how many bytes you would like to send. This value should match the number of bytes in the standard command. In the example above, the Standard command that we want to encode is 254, 166 (two bytes). By clicking the blue “Encode” button as shown above, these data are wrapped with a Header, Number of Bytes, and is finished with a checksum (a value of 80 shown above). When a command is sent in API format, the controller responds in API format. In this case, the controller will report back 8 bytes indicating the 8-bit A/D values of analog inputs 1-8 (not supported by all controllers). The controller will respond with a header byte of 170, followed by the number of bytes to expect (8), followed by 8 bytes of data, concluding with a checksum of 210 as shown above.
The API decoded data that you actually want to obtain and use is shown at the bottom text field (102 48 48 38 21 22 10 255).
Coding Commands in API Format
Coding Commands in API Format is easy. Let’s take a simple command and encode it for API Communications. The command 254, 33 is used to test two-way communications. If we send this command to the controller, the device will return 85 in Run Mode, 86 in Configuration Mode, and 87 in Security Lockdown Mode.
Standard Command
Send Bytes: Byte 1: Byte 2:
Function: Test Two-Way Communications
Decimal Value 254 33
Receive Byte: 85
Send in API Encoded Format
Send Bytes: Byte 1: Byte 2: Byte 3: Byte 4: Byte5:
Decimal Value 170 2 254 33 203
Byte 1: 170 (API Header) Enter API Encoding Format Command
Byte 2: 2 (API Payload Bytes) Contains the Number of Bytes in the Command that will be sent to the controller
Byte 3: 254 (Payload) Standard Command (Byte 1 of 2)
Byte 4: 33 (Payload) Standard Command (Byte 2 of 2)
Byte 5: 203 (API Checksum) LSB Checksum (170+2+254+33)=459 (459 AND 255)=203
Receive in API Encoded Format
When an API Command is sent, the controller will send all responses to your commands in API Mode. You will receive the following bytes from the controller:
Receive Bytes: 170 1 86 1
Byte 1: 170 (API Header) Controller will encode the Response Beginning with 170 as a Header
Byte 2: 1 (API Payload Bytes) Number of Bytes to expect from the Controller
Byte 3: 86 (Payload) 86 is the actual data byte you will receive from the controller
Byte 4: 1 (API Checksum) LSB Checksum Value of Response (170+1+86)=257 (257 AND 255)=1
Calculating the Checksum
In order to use the API Codec, it is important that you properly calculate the Checksum for both coding and decoding API communications. The Checksum is very easy to calculate. Simply add all bytes together (including the Header Byte 170, and the Byte that indicates of number of bytes in the packet) then use the Mathematical “AND” function to isolate the Least Significant Byte:
459 AND 255 = 203
257 AND 255 = 1
Checksum Notes
Some standard commands (Non-API) may require a Checksum to process properly. This checksum must be wrapped into the API Codec, so essentially these commands will have two checksums. The first checksum will be required as part of the original command, the second checksum will be required by the API Codec. Make sure both checksums are included or the API Codec will not function properly.
Testing for API Support
To ask the controller if API Mode is supported, read EEPROM Location 246 and Test Bit 8 (the most significant bit). If Bit 8 is High, API is supported by the controller. Please refer to the EEPROM Quick Start Guide for complete details.
Updated API Structure for E3C DropNet Devices
In September of 2015, an updated API Protocol was introduced to cover E3C DropNet Devices, which is included with ALL devices sold as E3C DropNet Devices. The current API Protocol is still valid, and works with all DropNet devices without interruption; however, a shortcut was introduced to consolidate device targeting and command processing as a single unified command. By using the updated API Structure, users may effectively target and control a device using one command. Older versions of firmware required two commands: One for targeting a device and one for controlling a device. Using the updated API Structure for E3C DropNet Devices, you can effectively double communication speed with minimal changes to the API Structure.
This portion of the guide explains the updated API Packet Structure:
171 Header Byte for updated E3C DropNet Structure
0 Device you would like to control (0-255 Valid Range)
3 Number of Bytes to Send in the Command
254 Header Byte for Command
131 Toggle Relay Command
0 Apply Command to the first Relay
46 Checksum Calculations do NOT Change
Note: To simplify integration of this new packet structure, Checksums are calculated EXACTLY as before. The 171 does NOT recalculate the checksum, checksum is calculated as though the header byte were 170. The Device Number is NOT included in the Checksum calculations.
Note: Each E3C DropNet Device MUST be configured with a DIFFERENT E3C Device Number. Use our Base Station Software and choose: “Device Configuration” to set the device number.