NB | EASY Interface Specification (Version 1.3)

Owned by Safa Hkiri (Unlicensed)
Last updated: 10 Sept, 2019
10 min read

The NB | EASY Interface (short EASY-IF) defines a message protocol for communicating with an Exelonix NB IoT device via the serial UART hardware interface.
The user is able to control the Exelonix NB-IoT device by sending and receiving EASY-IF messages transmitted on the serial hardware interface. The EASY-IF protocol defines which, when & how the messages shall interact with each other.

Content

Interface Version History

The table shows the changes history of the NB | EASY Interface Specification:

VersionDateChanges
1.3 
  • Removed state restrictions of operations Device & Debug
  • Advanced CellInfo operation response with new measurements
  • Corrected CellInfo response parameter names
  • Added Example Usecase
1.2 
  • Removed state restrictions of operations Help & ModemStatus.
    They now can be triggered at any time, even when another operation is already ongoing.
  • Added new operation Debug, to be able to set level of device debug information transmitted on serial interface
  • Added RX payload to RX indication
  • Added UDP address to RX response and indication
1.1 
  • Added parameter PLMN to operation Attach to support manual operator selection
1.0 
  • Initial Version

Definitions

In this document the following naming conventions and abbreviations are used:

TermDescription
EASY-IFNB | EASY Interface
DeviceThe Exelonix NB-IoT device to be controlled with the NB | EASY Interface
UserTerminal program or other hardware that issues requests to the device
NB-IoTNarrowband Internet Of Things
IMEIInternational Mobile Equipment Identity
IMSIInternational Mobile Subscriber Identity
PLMNPublic Land Mobile Network

Message Protocol

The EASY-IF protocol defines which, when & how the messages shall interact with each other.

There are four message types:

Message TypeDescription
RequestThe user can send a request message to trigger a specific operation to be done by the device.
ResponseThe device informs the user during an ongoing operation about the the current state or the result of the operation. Depending on the requested operation the device can sent multiple responses mapping to the same request message.
ConfirmThe device confirms the finished operation. The message includes a status parameter which informs the user about the result of the operation.
IndicationIndications are messages which are sent by the device independent of an ongoing operation. They can occur at any time.

The interface generally does not allow a new request until the previous one has been confirmed by a confirm message. In specific cases, the operation may be aborted by a abort request before the operation has ended.

The following diagram shows a generic message sequence chart including all message types.

Message Syntax

The message syntax of a  typical EASY-IF message looks as follows:

EASY-IF Message Syntax
EASY<MessageType><OperationIdentifier>:<Payload><CR>

Where:

ParameterDescription
EASYThe prefix string to be set at the beginning of every EASY-IF message. This string is case sensitive and must be all upper case.
<MessageType>

A single character that defines what kind of message type is used:

  • + : Request
  • - : Response
  • # : Confirm
  • ~ : Indication
<OperationIdentifier>
  • A unique string identifying the operation the message is part of. This string is case sensitive.
:The colon character that separates the message header from the message payload. In case the message does not include any payload the colon character is also not part of the message.
<Payload>
  • A string of variable length which in most cases contains a list of operation parameters specific for the set <OperationIdentifier>
    • The number of parameters is fixed for the combination of <MessageType> and <OperationIdentifier>.
    • Parameters are separated by the comma character: ","
    • There are two types of parameters:
      • Numbers: positive and negative counting numbers, as well as zero {..., -2, -1, 0, 1, 2,...}.
      • String: sequence of characters. The following special characters are not allowed:
        • comma:  ","
        • colon:  ":"
        • control characters: NUL (0x00), LF (0x0A), CR (0x0D)
<CR>Message termination character CR (carriage return): Hex value: 0xD

The following strings show some example messages:

Example request message with payload
EASY+ExampleOperationId1:12,TestString,34<CR>
Example indication message without payload
EASY~ExampleOperationId2<CR>

Confirm Messages

A confirm message informs the user about a finished operation triggered by a request message:

Confirm Message Syntax
EASY#<OperationId>:<OperationResult><CR>

Where:

  • <OperationId>: Operation identifier of the finished operation
  • <OperationResult>: String indicating the result of the operation.

The following operation result string can be returned

Operation ResultDescription
SuccessThe operation finished successfully.
AbortedThe operation was aborted by the user.
FailureGeneric operation failure
NotSupportedThe operation identifier is not know or not ye supported.
IncorrectThe request message syntax is incorrect.
BusyA new operation can not be started as another operation is already ongoing.
InvalidStateThe requested operation can not be started in the current device state.
NoSimCardNo SIM card is inserted into the device. So the requested modem operations is not possible.
AttachFailureThe modem was unable to attach to the NB-IoT network.
TxFailureThe modem was unable to transmit the requested data to the network.

Indication Messages

Indication messages are sent by the device independent of an ongoing operation. They can occur at any time and indicate a new event or a status change.

Modem Status Indication

The modem status indication message informs the user about a change of the current modem status:

Modem Status Indication Message Syntax
EASY~ModemStatus:<ModemStatus><CR>

The following <ModemStatus> is indicated:

Modem StatusDescription

PowerOff

The modem is not power on. 

PoweringUpThe modem is currently powering on.
PoweringDownThe modem is currently powering down.
DetachedThe modem is powered on but not attachted to the network.
AttachingThe modem is currently trying to attach to the network.
AttachedThe modem is attached to the NB-IoT network
DetachingThe modem is currently detaching from the network.
TransmittingThe modem is transmitting data.
ReceivingThe modem is receiving data from the network.

Reception Indication

The reception indication message informs the user about a new NB-IoT data reception. The user can get the received data by triggering a Reception operation.

Reception Indication Message Syntax
EASY~RX:<IpAddress>,<UdpPort>,<DataLength>,<Data><CR>

Where:

ParameterDescription
<IpAddress>IP address of sender
<UdpPort>UDP port of sender

<DataLength>

Indicates the number of bytes in <Data>.
In case no data was received <DataLength> is set to zero and <Data> is an empty.
<Data>Received data

Operations - Device

Help

The Help operation can be used to get a list of all supported EASY-IF messages by the device.
This operation can be triggered at any time, even when another operation is already ongoing.

Help Request Message Syntax
EASY+Help<CR>

The following response message informs the user about one EASY-IF message. Multiple messages are sent to the user to inform about all available message.

Help Response Message Syntax
EASY-Help:<OperationId>,<MessageType>,<NumberOfParameters>,<Parameter1Name>,<Parameter2Name>,...,<ParameterNName><CR>

Where:

ParameterDescription
<OperationId>String of the operation identifier to be used by the request.
<MessageType>

A single character that defines what kind of message type is used:

  • + : Request
  • - : Response
  • ~ : Indication
<NumberOfParameters>Number which indicates how many parameters the message requires in its payload. In case number = 0, the message has no parameter.

<Parameter1Name>,
<Parameter2Name>,
...
<ParameterNName>

String indicating all parameter names in the same order as in the message.

The following message sequence charts shows an successful device operation.

Device

The device operation can be used by the user get information about the device type and its static device parameters.
This operation can be triggered at any time, even when another operation is already ongoing.

Device Request Message Syntax
EASY+Device<CR>


The following response message informs the user about the device information.

Device Response Message Syntax
EASY-Device:<DeviceType>,<HardwareRevision>,<FirmwareVersion>,<EasyIfVersion>,<IMEI><CR>

Where:

ParameterDescription
<DeviceType>String that indicates device type of the Exelonix NB-IoT device
<HardwareRevision>String that indicates the hardware revision number of the device type

<FirmwareVersion>

String that indicates the installed firmware version

<EasyIfVersion>

String that indicates the used EASY-IF version

<IMEI>

String that indicates the unique NB-IoT modem IMEI (International Mobile Equipment Identity)

The following example message shows a device response of an Exelonix NB|DESK device:

Device Response Message Example
EASY-Device:NB|DESK,1.2,3.0,1.0,357518081238813<CR>

The following message sequence charts shows an successful help operation.

Mode

The Exelonix NB-IoT device can work in two different modes: EASY mode or AT mode.

The EASY modem is set by default when the device is started. There the device reacts to EASY-IF messages sent to the device.
The AT mode can be used to control the NB-IoT modem directly with AT commands as specified by the modem manufacturer. In this case no EASY-IF messages can be anymore to control the device, as all messages sent via serial interface are directly forwarde to the modem unchanged.

To enable the AT mode the following message shall be sent to the device:

Mode Request Message Syntax
EASY+Mode<CR>

After the device sents the confirm message the device is set to AT mode.

To re-enable the EASY mode the device must be rebooted.

Restart

With the help of Restart operartion it is possible to restart the device. All settings will be reset as if the device is powered on again.
This operation can be triggered at any time, even when another operation is already ongoing.

To trigger the Restart operation the following message shall be sent to the device:

Restart Request Message Syntax
EASY+Restart<CR>

After the device sents the confirm message the device is restarted.

Debug

With the Debug operation the user is able to set the level of the transmitted device debug information.
This operation can be triggered at any time, even when another operation is already ongoing.

To trigger the Debug operation the following message shall be sent to the device:

Debug Request Message Syntax
EASY+Debug:<Level><CR>

where <Level> can be set to the following values:

  • 0 - Disable all device debug information
  • 1 - Enable all device debug information
  • 2 - Enable only AT command and AT responses exchanged with NB-IoT modem

The following message sequence charts shows an successful Debug operation.

Operations - Modem

The NB-IoT modem is described by the following state machine. Depending on the triggered modem procedure (red arrows) the device will switch in a different state.

Every time the modem changes is state an Modem Status Indication is sent to the user to inform about the change.

Modem Status

In case the user want to know the current modem status (e.g. missed the last Modem Status indication), the Modem Status operation can be triggered.

To start the Modem Status operation the user shall sent the following request message to the device:

Modem Status Request Message Syntax
EASY+ModemStatus<CR>

The device will reply with the following response:

Modem Status Response Message Syntax
EASY-ModemStatus:<ModemStatus><CR>

The <ModemStatus> parameter indicates the same as in the Modem Status indication.

The following message sequence charts shows an successful Modem Status operation.

Attach

In case the modem is in Power Off state or in Detached state an Attach operation can be triggered the attach the device to the NB-IoT network.
There are two possible modes supported by the Attach procedure: automatic and manual operator selection:

  • Manual operator selection: The user can choose which network to attach to by setting the corresponding PLMN (Public Land Mobile Network) identifier.
  • Automatic operator selection: The device will scan automatically on all by the hardware supported frequencies for the NB-IoT network corresponding to the inserted SIM card. Depending on the network conditions this can take up to one hour.

After one hour the device will stop trying to attach to the network with an "AttachFailure" confirm message.

To start the Attach operation the user shall sent the following request message to the device:

Attach Request Message Syntax
EASY+Attach:<PLMN><CR>

Where string parameter <PLMN> indicates the PLMN identifier to be used during the operator selection. A <PLMN> value of 0 indicates the automatic operator selection. Any other value indicates an manual operator selection. A valid PLMN has 5 or 6 digits.

During the procedure the device will inform the user about any modem status change via indications. The following message sequence chart shows an automatic operator selection Attach operation.

Detach

In case the modem is in Attached state an Detach operation can be triggered the detach the device from the NB-IoT network.

To start the Detach operation the user shall sent the following request message to the device:

Detach Request Message Syntax
EASY+Detach<CR>

During the procedure the device will inform the user about any modem status change via indications.

Cell Info

In case the modem is in Attached state an Cell Info operation can be triggered to ask the modem about the current cell conditions.

To start the Cell Info operation the user shall sent the following request message to the device:

Cell Info Request Message Syntax
EASY+CellInfo<CR>

The device will answer with the following response message:

Cell Info Response Message Syntax
EASY-CellInfo:<CellId>,<PCI>,<EARFCN>,<RSSI>,<RSRP>,<RSRQ>,<SNR>,<ECL>,<rxTime>,<txTime>,<rrcConnected>,<SignalBars>,<txPower>,<txBytes>,<rxBytes>,<txBlocks>,<rxBlocks>,<rlcUlRate>,<rlcDlRate>,<macUlRate>,<macDlRate><CR>

Where:

NumberParameterDescription
01<CellId>NB-IoT Cell Identifier Number
02<PCI>Physical Cell Identifier
03<EARFCN>E-UTRA Absolute Radio Frequency Channel Number
04<RSSI>Received Signal Strength Indicator in dBm
05<RSRP>Reference Signal Received Power in dBm
06<RSRQ>Reference Signal Received Quality in dB
07<SNR>Signal-To-Noise ratio in dB
08<ECL>NB-IoT coverage enhancement level; range: level 0 to level 2. It is up to the network, how many CE levels are defined.
  • Level 0 corresponds to normal coverage
  • Level 2 corresponds to the worst case, where the coverage may be assumed to be very poor.
09<rxTime>active time of the modem RF to receive signals in ms
10<txTime>active time of the modem RF to transmit signals in ms
11<rrcConnected>

The state of the Radio Resource Control (RRC). It defines if the modem is connected with the NB-IoT base station:

  • 0 = Idle
  • 1 = Connected
12<SignalBars>Signal bars: Indicates strength of the received signal; more bars indicate a better signal quality.
  • 0: no connection
  • 1: bad
  • 2: marginal
  • 3: OK
  • 4: good
  • 5: excellent
13<txPower>Transmit power in dBm
14<txBytes>Total number of transmitted bytes
15<rxBytes>Total number of received bytes
16<txBlocks>Total number of transmitted transport blocks
17<rxBlocks>Total number of received transport blocks
18<rlcUlRate>RLC (Radio Link Control) layer uplink throughput in kb/s
19<rlcDlRate>RLC (Radio Link Control) layer downlink throughput in kb/s
20<macUlRate>MAC (Medium Access Control) layer uplink throughput in kb/s
21<macDlRate>MAC (Medium Access Control) layer downlink throughput in kb/s

The following message sequence charts shows an successful Cell Info operation.

Transmission

In case the modem is in Attached state an Transmission operation can be triggered to send data via the NB-IoT network to an UDP address.
It is also possible to start a transmission when the modem is in Detached state; in this case the modem is automatically attaching to the network first before starting the transmission.

To start the Transmission operation the user shall sent the following request message to the device:

Transmission Request Message Syntax
EASY+TX:<IpAddress>,<UdpPort>,<DataLength>,<Data><CR>

Where

ParameterDescription
IpAddressIPv4 address of the transmit destination in the format aaa.bbb.ccc.ddd
UdpPortUDP port of the transmit destination
DataLength

Number of bytes to be transmitted - corresponds to number of bytes of <Data>

DataData to be transmitted;
This string can include any ASCII character except control characters CR (0x0D) and LF (0x0A), as these are needed to indicate the end of the message.

The following message sequence charts shows an successful Transmission operation.

In case the transmission fails the confirm message includes the result "TxFailure".

Reception

The device is able to store the last received data. In case the user did not handle the last Reception indication and want to get the last received data again the Reception operation can be triggered.

To start the Reception operation the user shall sent the following request message to the device:

Reception Request Message Syntax
EASY+RX<CR>

The device will answer with the following response message in case data was received before. If no data was received before the status parameter in the confirm message will be set to "Failure".

Reception Response Message Syntax
EASY-RX:<IpAddress>,<UdpPort>,<DataLength>,<Data><CR>

Where:

ParameterDescription
<IpAddress>IP address of sender
<UdpPort>UDP port of sender
<DataLength>Indicates the number of bytes in <Data>.
In case no data was received <DataLength> is set to zero and <Data> is an empty.
<Data>Received data

The following message sequence charts shows an successful Reception operation.

Abort

The Abort operation is a special operation as it allows to stop modem operations early before they finish by themself. Therefore it is only allowed to send the Abort operation in case another modem operation is currently running.
If the abortion is finished successfully the aborted operation will finish with its confirmation message with status set "Aborted". In this case Abort operation itself will not be confirmed.
But if the Abort operation fails, the Abort operation will be confirmed indicating the failure cause. 

To start the Abort operation the user shall sent the following request message to the device:

Abort Request Message Syntax
EASY+Abort<CR>

The following message sequence charts shows an successful abortion of an ongoing Attach operation.

Example Usecases

The folowing examples show typical usecases of the EASY interface.

Booting, Attach, Transmission & Reception