Neo.cortec NCxxxx series Use and care manual

Integration Manual for NCxxxx series Modules
Doc Status:
Release
Doc version:
2.2
Date:
Dec 2015
neo.cortec
.

neo.cortec
.
Table of Contents
1!Document revisions ........................................................................................................3!
2!Introduction .....................................................................................................................3!
3!Abbreviations ..................................................................................................................3!
4!Definitions .......................................................................................................................3!
5!System Considerations...................................................................................................4!
5.1!Power Supply ..................................................................................................................4!
5.1.1!Voltage capabilities.................................................................................................4!
5.1.2!I/O Voltage levels....................................................................................................4!
5.1.3!Current sourcing capabilities.................................................................................4!
5.2!Sleep ................................................................................................................................5!
6!Serial UART Interface.....................................................................................................6!
6.1!Physical interface............................................................................................................6!
6.2!Easy Integration with PC................................................................................................7!
7!Communication Specification – Application UART .........................................................8!
7.1!Logical data exchange...................................................................................................8!
7.2!Commands and Application data ................................................................................8!
7.2.1!List of commands ....................................................................................................9!
List of application data ..................................................................................................... 11!
7.3!API for embedded controllers ................................................................................... 12!
8!Communication Specification – System UART............................................................. 15!
9!Examples ......................................................................................................................16!
9.1!Acknowledged Payload data transmission through the network ......................... 16!
9.2!Wireless Encrypted Setup .......................................................................................... 17!

- 3 of 18 –
neo.cortec
.
1Document revisions
Document version
Details
1.4
Initial release
1.5
Added details for HAPA & corrected application data 0x50 &
0x51
2.0
Document updated to include details for NC1000 & NC0400 as
well.
Also added documentation regarding the API for embedded
controllers.
2.1
Added details for Wireless Encrypted Setup – WES
2.2
Fixed error in WES doc.
2Introduction
This document describes how to integrate the NEOCORTEC NCxxxx series modules
with a Host Controller both from a SW and HW perspective. The Host Controller can be
an embedded micro controller or a PC.
3Abbreviations
•HW – Hardware
•SW – Software
•UART - Universal Asynchronous Receiver/Transmitter
•RX – Receive
•TX - Transmit
4Definitions
•Host – A system consisting of HW and SW which is interfacing to the NCxxxx
module in order to use the module as a wireless transmission system for data
such as sensing data or control parameters.

- 4 of 18 –
neo.cortec
.
5System Considerations
When designing a product that contains the NCxxxx module, there are a few items from
a System point of view that need to be considered. This section of the document lists
these items, and where applicable provides recommendations on solutions.
5.1 Power Supply
5.1.1 Voltage capabilities
The NCxxxx module series is designed such that it can be powered directly from a
single cell battery in the voltage range of 2.0V to 3.6V DC. However, the module
contains an internal linear voltage regulator, which regulates the voltage down to 1.8V
for some parts of the system. Supplying the module at higher voltages (above 2.0V DC)
leads to some level of inefficiency due to the nature of the linear converter.
Before considering the addition of a Switching Mode Regulator in the supply though, it
should be noted that the extreme low power capabilities of the NCxxxx module is
achieved through very low duty cycle. Therefore most of the average current
consumption stems from the actual sleep mode current of the module. This means that
the leakage current of the potential Switching Mode DC/DC regulator needs to be very
low in order not to jeopardize the low Power Consumption.
5.1.2 I/O Voltage levels
The NCxxxx modules I/O voltage levels follow the supply voltage. This means that the
external controller needs to use the same logical voltage range.
5.1.3 Current sourcing capabilities
Even though the average current consumption is ultra low, the module does draw
current at a higher level in short bursts. This happens when the module is transmitting
or receiving data or control information (see data sheet for active mode RX and TX
current consumption).
The worst-case situation is when the module is performing its Beacon Scan. The
duration of the individual Beacon Scans is dependent on configuration settings.
The power supply should stay within the supply voltage range of the NEOCORTEC
module during the current bursts.
When operating the module from a battery supply, it should be noted that some
batteries will greatly reduce their lifetime when their max rated current sourcing
capabilities are violated.
Be careful to select batteries that match both the average current consumption as well
as the peak current consumption.

- 5 of 18 –
neo.cortec
.
5.2 Sleep
As the external controller, as well as the NEOCORTEC Module, is expected to spend a
lot of time in sleep mode to save power, it is important that wake-up is synchronized, so
that the modules can communicate with each other.
The external controller can enter sleep mode when it has finished processing of e.g.
sensor data on its inputs, or data received from the NEOCORTEC module.
The NEOCORTEC node controls wake-up exclusively. When the NEOCORTEC node is
active, the WakeUp signal is active. Likewise, when the NEOCORTEC node is in sleep,
the WakeUp signal is inactive1.
The external controller will have to be in active state whenever the NEOCORTEC node is
in active state. This to ensure that the external controller is ready to receive UART data
whenever the NEOCORTEC node potentially can send such data.
For more details, see chapter 7 Serial UART Interface.
6WES –Wireless Encrypted Setup
The nodes can be configured for a particular network using WES (see user guide
document). The client mode of WES, can be started in two ways:
6.1 Auto WES after power up
If the node ID is configured to 0xFFFF, the node will start up in WES client mode after
power up. See the user guide for further details.
6.2 Force WES client mode
Any node can be forced into WES client mode by pulling the WES Client Enable Pin (see
data sheet) low for at least 2 seconds. When the WES Client Enable Pin is pulled low, the
node will change its Node ID to 0xFFFF, reboot, and thereby enabling WES Client
mode.
This process cannot be undone, and a full WES setup will have to be completed – or the
Node ID will have to be programmed to a valid ID manually.
1See NCxxxx datasheets for details on the WakeUp signal.

- 6 of 18 –
neo.cortec
.
7Serial UART Interface
The NEOCORTEC NCxxxx module provides two serial communications ports, which are,
used for each their own individual purpose:
Name
Desciption
Application API
Used to interface the Host Controller Application layer
with the NC2400 Module. Provides functions for sending
and receiving payload data through the NEOCORTEC
wireless network
System API
Used for configuration and debugging purposes. Will
typically be connected to a PC when the user either
configures the module, or during the development
process to provide trace outputs.
The Host Processor can communicate with the NCxxxx module through a standard
UART serial interface (see module data sheet for electrical details and Pin locations).
7.1 Physical interface
The following signals are used:
Abbreviation
Name
Module pin number
Origin
Purpose
Application
System
RxD
Received Data
17
5
NEO
Carries data from the
NEOCORTEC node to
the external controller.
TxD
Transmitted Data
16
3
EXT
Carries data from the
external controller to the
NEOCORTEC node
CTS
Clear to Send
19
4
(nWU used
as CTS)
NEO
Indicates that the
NEOCORTEC node is
ready to accept
commands (see below)
nWU
Wake Up
4
n/a
NEO
Indicates the activity
mode of the
NEOCORTEC node
(sleep/active). Active low

- 7 of 18 –
neo.cortec
.
Figure 1 - Generic UART Interface drawing
nWU is used as a wake-up signal, to indicate that the NEOCORTEC module is waking
up, and that it may have data to send. The external controller must not ignore this wake-
up, and must start the UART receiver at latest at the time specified by WU setup time,
after wake-up. This parameter can be changed by changing the module configuration,
but it is default set to 100us.
The CTS is used to signal the controller that the NEOCORTEC module can receive data.
The UART should be configured with the following settings:
•Transfer Speed: 115.2 kbps
•Data bits: 8
•Stop bits: 1
•Parity Check: None
7.2 Easy Integration with PC
For easy integration with a PC, it is recommended to use a UART to USB converter. The
TTL-232R-3V32cable from FTDI (www.ftdichip.com) has been proven to work with the
NC2400 module directly.
Connect the pins according to this table:
Name
Module pin number
FTDI Pin
number
Application
System
RxD
17
5
5
TxD
16
3
4
2Note that the FTDI cable expects logic levels at 3.3v, and as such the NEOCORTEC Module will have to
be supplied from a 3.3v supply. Pin 3 of the FTDI cable is a 5V output, and if regulated properly, it can be
used as a supply for the NEOCORTEC Module.
TX
RX
CTS
nWU
NEOCORTEC
Module
RX
TX
CTS
nWU
External
Controller
RxD
TxD
CTS
nWU

- 8 of 18 –
neo.cortec
.
CTS
19
4
2
nWU
13
n/a
n/a
GND
1,6,9,15, 26
1
Note: nWU is not connected, as it is assumed the PC will not be entering sleep mode,
and will always be ready to send and receive data.
8Communication Specification –Application UART
8.1 Logical data exchange
Data is exchanged over the interface in Big Endian byte order.
The general format of a data frame is:
Section
Code
Length
UART Payload
Length
1 byte
1 byte
(Length) bytes
The Length field indicates the length of the “UART Payload” in bytes.
8.2 Commands and Application data
There are two categories of frames exchanged, Commands and Application data:
Commands are frames accepted by the NEOCORTEC node.
Application data is data sent from the NEOCORTEC node to the External Host.
Some commands will cause values to be returned. These values are sent as application
data (frames).
Some data frames come from information received from another node in the network,
and as such it can be subject to long delays. The principle is that the application should
continue execution, and react on the return value based on the Application Data Code,
which associates it with the command previously issued.
If the command listed hereunder has a corresponding return frame, the Application
Data code is listed under the “Return” column. For a definition of these codes, please
refer to 0

- 9 of 18 –
neo.cortec
.
8.2.1 List of commands
Command
Code
Length
Data
Return
Description
API_CMD_TX_UN
ACKNOWLEDGED
3
0x02
n
NEOCORTEC
ID + 1 byte
port + payload
n/a
Write data to device / port.
Maximum payload size is 19 byte
Refer to text below table for
more details.
API_CMD_TX_ACK
NOWLEDGED
0x03
n
NEOCORTEC
ID + 1 byte
port + payload
0x50,
0x51
Write data to device / port.
Maximum payload size is 19 byte
Refer to text below table for
more details.
API_WES_CMD
0x10
1
1 byte CMD
0x604
Command to control the
Wireless Encrypted Setup.
API_WES_SETUP_
RESPONSE
0x11
7
5 byte UID + 2
byte
NEOCORTEC
ID
n/a
If a node setup request is
accepted, the application can
send this command with UID and
Node ID as arguments.
NEOCORTEC ID is the address of the NEOCORTEC Module, for which the payload data
is intended.
The NEOCORTEC ID is two bytes. The first 127d addresses should be used for the sink
nodes in the network. The sink nodes are the ones that can be addressed directly as a
destination for payload data. Addresses over 127d should be used for nodes which are
only sources of payload data or routers of payload data. If the total number of nodes are
less than 127d, then it is recommended to use addresses in the range 1d…127d.
Addresses 0x00 00 and 0xFF FF are not allowed.
The port field of the data, can be used at the application layer, to direct the data to
different applications. One can for instance be a lower level control application, used to
set parameters of the application, while other ports is ordinary application data.
IMPORTANT: Only the last two bits (LSB) in the port argument can be used:
For the application layer, only 2 bit port numbers are available (i.e. 4 ports total).
Send Unacknowledged Packet:(currently not supported)
The command is used to initiate a transmission of application payload data to another
NEOCORTEC Module inside the NEOCORTEC network. The NEOCORTEC ID should be
given as well as a port number. The port number is used to direct the payload data to a
given handler/service at the receiving NEOCORTEC application layer.
3Unacknowledged transmission of payload data is currently not supported by the protocol stack.
4If CMD is ”Request Status”

- 10 of 18 –
neo.cortec
.
Once the packet has been enqueued in the NEOCORTEC module, there will be no
messaging back to the application layer indicating if the transmission to the destination
was successful.
Send Acknowledged Packet:
Similar to the above mentioned command, this command initiates the transmission of
application payload data to another NEOCORTEC module inside the NEOCORTEC
network. The difference is that the payload data is transmitted with end-to-end
acknowledge enabled. This means that once the application payload data is received at
the destination, an acknowledge message is transmitted back. When the Ack or NAK is
received, a corresponding Application code will be transmitted from the NEOCORTEC
module to the external controller (see next chapter).
API_WES_CMD:
This command controls the Wireless Encrypted Setup functionality in a Node who is
announcing a network, or a node who wants to start looking for a new network to join.
There are 3 arguments in the command, which has different functionality:
API_WES_SETUP_RESPONSE:
When a “API_WES_SETUP_REQUEST” has been received from a Node who is trying to
join the network, the application layer can add the node to the network using this
command. The arguments to the command is the Node ID which the joining Node shall
be configured with, and the UID of the joining Node (as given by the
API_WES_SETUP_REQUEST).
Argument
Meaning
0x00
Stop WES
0x01
Start WES server
0x02
Request WES status

- 11 of 18 –
neo.cortec
.
List of application data
Code
Length
Data
Description
0x50
2
ID(2)
Acknowledge for previously sent
packet
0x51
2
ID(2)
Non-Acknowledge for previously
sent packet
0x52
n
Header + Payload
Data received from another device
(see below)
0x53
n
Header + Payload
Data received from another device
with HAPA (see below)
0x60
1
Status (1)
API_WES_STATUS – the response for
a previously send status request.
Status can be either 0x00 (WES
stopped) or 0x01 (WES server
running)
0x61
5
UID (5)
API_WES_SETUP_REQUEST – a node
with UID is requesting to be
configured for the network
0x50:
Receiving an Acknowledge is a guarantee that the recipient (with address = ID) has
received the packet sent previously in acknowledged mode.
Acknowledges from a recipient node is received for packets in the order they were
enqueued.
0x51:
Receiving a Non-acknowledge only happens if the maximum global retries were
exceeded. This can happen if, for example, the destination node has been destroyed, or
otherwise has been removed from the network.
0x52:
Header + Payload data is: Originator ID(2) + Package Age(2) + Port(1) + Payload
Data(max. 19)
0x53:
Header + Payload data is: Originator ID(2) + High Accuracy Package Age(4) + Port(1) +
Payload Data(max. 15)
0x60:

- 12 of 18 –
neo.cortec
.
Receiving a API_WES_STATUS happens after previously having send a API_WES_CMD
with 0x03 as argument. The returned value indicates the status of the WES Server. A
value of 0x00 indicates that the WES functionality is stopped. A value of 0x01 indicates
that the WES server is.
0x61:
When a unconfigured node is requesting to be setup for the network,
API_WES_SETUP_REQUEST is received. The UID of the node requesting the setup, is
included with the request.
The application layer must decide if the node is allowed to join the network or not. If the
node is not allowed, the API_WES_SETUP_REQUEST can be ignored. If the node is
allowed to join, the application layer must use the API_WES_SETUP_RESPONSE
command to provide the Node ID to the joining node. The protocol stack handles the
rest of the process, and delivers all necessary setup information to the joining node,
such that it can write the configuration parameters to the non volatile memory and
reboot to start joining the network.
In general:
Packet Age is a measure from the point in time where the data was enqueued at the
originator, to the time when the packet was delivered to the host application at the
destination node.
For the UART interface, enqueue happens at the time the external controller has send
the package through the UART interface, and dequeue happens at the time when the
data is transmitted over the UART interface to the external controller. Packet Age has a
resolution of 0.125 seconds, and as such the value received should be multiplied with
0.125 seconds to get a time indicator in seconds.
HAPA (High Accuracy Package Age) is used when higher resolution is required on the
Package Age. When enabled, the Package Age field is replaced with a HAPA field. The
HAPA has a resolution of 1/(219) seconds.
See the USER GUIDE for more information about how to enable HAPA.
8.3 API for embedded controllers
A C90 compliant API is provided which simplifies the integration of the NCxxxx series
modules, with an embedded controller.
When using the API, the user does not need to worry about how to generate UART
frames, nor how to decode them.
The API is structured according to the illustration below:

- 13 of 18 –
neo.cortec
.
Figure 2 - NcApi structure
The API serves as layer, which implements high-level functions for sending and
receiving payload data through the mesh network.
The API provides two basic functions to the application layer: NcApiInit &
NcApiSendAcknowledged.
NcApiInit will have to be called once to initialize the API.
The NcApiSendAcknowledged function can be used to send payload data to another
node inside the mesh network.
When data is received from the mesh network, a series of call-back functions will call the
Application with the received data. Depending on what type of data is received, a type
specific call-back is issued. It is optional for the application layer to register for the call-
backs.
ReadCallback will deliver a byte array containing the raw UART frame received
following the formats in section 0 “List of application data”. It is normally not necessary
to register for this callback, as there are other callbacks which are specific to the various
types of application data. These are described here:
The application layer can register for HostAckCallback. The callback is issued when the
module receives an ACK message for a previously send payload package. The callback
function delivers the NEOCORTEC ID for the node, which has send, the ACK.
The application layer can register for HostNAckCallback. The callback is issued when
the module receives an NAC message for a previously send payload package. The
callback function delivers the NEOCORTEC ID for the node, which has send, the NACK.

- 14 of 18 –
neo.cortec
.
The application layer can register for HostDataCallback. The callback is issued when
the modules receives payload data from another module in the NEOCORTEC mesh
network. The callback function delivers a pointer to a struct containing the following
information: OriginatorID, Port number, PayloadLength, Packet Age & Payload.
The application layer can register for HostDataHapaCallback. The callback is issued
when the modules receives payload data from another module in the NEOCORTEC
mesh network which has been configured to use the High Precision Packet Age feature.
The callback function delivers a pointer to a struct containing the following information:
OriginatorID, Port number, PayloadLength, Packet Age & Payload.
To enable the API on a particular embedded controller, certain support functions are
required, which are specific to the controller:
The API will call NcApiTxData every time data is to be written to the UART. The function
is called with a pointer to the actual data, which is to be written. The function shall
implement the necessary code required to output the data to the UART.
The API will call NcApiMessageWrittenCallback once a message has successfully been
written in full to the module. This can be used by the application layer to check that a
previous call to NcApiSendAcknowledged was completed successfully.
Similarly, there are functions inside the API, which has to be called when certain events
occur:
NcApiCallbackCtsActive is a function inside the API, which shall be called each time
the CTS line on the UART transitions to active (low) state. As such, an interrupt handler
for the particular pin on the controller must be implemented, such that the API is
“aware” of when CTS is active. There is no need to do anything when the CTS line
transitions to passive (high).
NcApiRxDataReceived is a function inside the API, which shall be called each time a
byte is received on the UART. The byte shall be included as an argument when the
function is called.
The functions related to Wireless Encrypted Setup are not mentioned here, but are fully
documented in the API documentation.

- 15 of 18 –
neo.cortec
.
Further details of the data structures as well as the functions, can be found in the
Documentation folder, which is part of the API delivery. Open the “index.html” file in
your preferred browser.
9Communication Specification –System UART
The System UART serves three purposes; trace messages5for debugging purposes are
being transmitted over the port while the Protocol stack is running. The second purpose
is for setting various parameters, which configures the operating mode of the module.
Finally it can be used to update the firmware of the module.
NEOCORTEC provides a PC tool that can be used to interface with the System UART
port. The tool – NeoTools.ConfigApp – can be downloaded from www.neocortec.com.
The tool is available both as a command line version and with a Windows GUI. The
command line version is well suited for production testing/configuration.
Please review the documentation for the tool for more details on usage and options.
If it is desired to interface directly with the System API UART, more information about
the messaging format etc. can be given upon request.
5Trace messages can be switched on or off by controlling the settings of the module.

- 16 of 18 –
neo.cortec
.
10Examples
10.1 Acknowledged Payload data transmission through the
network
In the following example, payload data is send from a sensor node to a PC which is
attached to another node in the NEOCORTEC network.
Figure 3 - Network example
In the example, the Originator node has the NEOCORTEC ID 0x00 20 and the Receiving
node has the NEOCORTEC ID 0x00 2A. Port 0x00 is used throughout the example.
This example only uses the Application API.
When the uController has a sensor measurement that it wants to send to the PC, this is
what happens:
1) uController sends a frame to the Originator node. The frame instructs the Originator
node to send the sensor data to the Receiving node. The sensor data is 1 byte and has
the value 0x23:
Section
Code
Length
UART Payload
Content
0x03
0x04
0x002A0023

- 17 of 18 –
neo.cortec
.
2) The payload data arrives at the Receiving node and is delivered to the PC via the
UART interface:
Section
Code
Length
UART Payload
Content
0x52
0x06
0x002000500023
At the same time, an acknowledge message is send from the Receiving node back to
the Originator node
3) The acknowledge message arrives as the Originating node:
Section
Code
Length
UART Payload
Content
0x50
0x04
0x002A0055
10.2 Wireless Encrypted Setup
In the following example, a network consisting of a mesh of nodes, has one node which
is announcing the network through the Wireless Encrypted Setup Channel. Another
node, which is unconfigured, discovers the network, and sends a request to the
announcing node to receive setup information for the particular network.
Figure 4 - WES Example
1) The unconfigured node is in WES client mode. Either the node comes directly from
the factory, with the Node ID set to 0xFFFF, or the host controller on the device has
started the WES client with the following command:
Section
Code
Length
UART Payload
Content
0x10
0x01
0x02

- 18 of 18 –
neo.cortec
.
2) The WES Announcing Node is now put into WES server mode by issuing the
following command from the uController (or Host in general) to the node:
Section
Code
Length
UART Payload
Content
0x10
0x01
0x01
3) When the unconfigured node discovers the announced network, it will send a setup
request to the announcing node. The announcing node will send the following message
to the uController:
Section
Code
Length
UART Payload
Content
0x61
0x05
0xnnnnnnnnnn
Where “nnnnnnnnnn” is the UID of the unconfigured node.
4) The application layer on the uController will now decide to accept the request, and it
will assign the Node ID 0x002A to the unconfigured node by sending this command to
the announcing node:
Section
Code
Length
UART Payload
Content
0x11
0x07
0xnnnnnnnnnn002A
Where “nnnnnnnnnn” is the UID of the unconfigured node.
5) The WES Announcing Node will now send the full configuration to the unconfigured
node. The unconfigured node will now write the setting to its non volatile memory, and
reboot in order for the changes to take effect.
6) The application layer at the WES Announcing Node can decide to stop the WES
server by sending this command:
Section
Code
Length
UART Payload
Content
0x10
0x01
0x00