(https://ncd.

io)  

 Jacob Youngblood(https://ncd.io/author/jacob/)
 March 1, 2017(https://ncd.io/2017/03/01/)  5:24 pm

API Codec Quick Start Guide

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.

COMPANY HELP POLICIES

About (//ncd.io/about- Forum(https://community.ncd.io/)Forum(//ncd.io/info/forum-

Us us) Get a (https://ncd.io/info/get- First first)
Business(//ncd.io/business- Quotea-quote) (//ncd.io/info/privacy-
Privacy
Hours hours) Letter policy/)
(https://ncd.io/letter-
Contact (//ncd.io/contact- of (//ncd.io/info/support-
of-volatility/) Support
Us us) Volatility policy/)
(https://ncd.io/custom- (https://ncd.io/ncd-Warranty(//ncd.io/info/warranty-
Custom
iot-electronic-design- Distributorsauthorized- & Return return-policy/)
Designs
services/) distributors/) Shipping (https://ncd.io/info/s
(// d i /f tl I f ti i f ti /)
 (//ncd.io/frequently- Informationinformation/)
FAQs
asked-questions) Terms
(//store.ncd.io/terms-
ISO of
(https://ncd.io/iso- of-service/)
9001 Service
9001-certification/)
2015

SUPPORT TOOLS

Follow(https://store.ncd.io/wp-
Travis json/follow/v1/travis)
Follow (https://store.ncd.io/wp-

DeeAnnjson/follow/v1/deeann)
Follow (https://store.ncd.io/wp-
Bhaskarjson/follow/v1/bhaskar)
Load
(https://store.ncd.io/wp-
Travis's
json/cart/v1/travis)
Cart
Load
(https://store.ncd.io/wp-
DeeAnn's
json/cart/v1/deeann)
Cart
Load
(https://store.ncd.io/wp-
Bhaskar's
json/cart/v1/bhasker)
Cart

(https://ncd.io/contact-us)

ncd.io
(https://ncd.io/contact-us)
( p
(866) 960-1270 (https://ncd.io/contact-us)
)
National Control Devices, LLC
(https://ncd.io/contact-us)
Open 9AM to 4:30PM CST
(https://ncd.io/contact-us)
(htt
(htt
ps://
©2021 (https://ncd.io/contact-us)
ww ps:// (htt (htt
w.yo ww ps:// ps://
utub w.fa twitt gith
e.co ceb er.c ub.c
m/u ook. om/ om/
ser/I com ncdi ncd-
ORe /ncd ot) io)
lay) .io)

(https://ncd.io/why-choose-ncd/)
(https://ncd.io/info/warranty-return-policy/)
(https://ncd.io/iso-9001-certification/)

(https://ncd.io/about-us/)
 (https://ncd.io/info/shipping-
information/)

Made in Missouri, USA (https://ncd.io/why-choose-ncd/)

Many Products Carry a 5-Year Warranty (https://ncd.io/info/warranty-
return-policy/)
NCD is a ISO9001:2015 Certified Company (https://ncd.io/iso-9001-
certification/)
All NCD Products are RoHS Compliant
NCD is 25 Years Old! Learn About Us (https://ncd.io/about-us/)
USA Orders May Qualify for Free Shipping
(https://ncd.io/info/shipping-information/)