NB | EASY Interface Specification (Version 1.3)
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
- 1 Interface Version History
- 2 Definitions
- 3 Message Protocol
- 4 Message Syntax
- 5 Confirm Messages
- 6 Indication Messages
- 7 Operations - Device
- 8 Operations - Modem
- 8.1 Modem Status
- 8.2 Attach
- 8.3 Detach
- 8.4 Cell Info
- 8.5 Transmission
- 8.6 Reception
- 8.7 Abort
- 9 Example Usecases
Interface Version History
The table shows the changes history of the NB | EASY Interface Specification:
Version | Date | Changes |
|---|---|---|
1.3 | Apr 11, 2018 |
|
1.2 | Mar 14, 2018 |
|
1.1 | Mar 26, 2018 |
|
1.0 | Feb 23, 2018 |
|
Definitions
In this document the following naming conventions and abbreviations are used:
Term | Description |
|---|---|
EASY-IF | NB | EASY Interface |
Device | The Exelonix NB-IoT device to be controlled with the NB | EASY Interface |
User | Terminal program or other hardware that issues requests to the device |
NB-IoT | Narrowband Internet Of Things |
IMEI | International Mobile Equipment Identity |
IMSI | International Mobile Subscriber Identity |
PLMN | Public 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 Type | Description |
|---|---|
Request | The user can send a request message to trigger a specific operation to be done by the device. |
Response | The 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. |
Confirm | The device confirms the finished operation. The message includes a status parameter which informs the user about the result of the operation. |
Indication | Indications 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:
Parameter | Description |
|---|---|
EASY | The 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:
|
<OperationIdentifier> |
|
: | 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> |
|
<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 Result | Description |
|---|---|
Success | The operation finished successfully. |
Aborted | The operation was aborted by the user. |
Failure | Generic operation failure |
NotSupported | The operation identifier is not know or not ye supported. |
Incorrect | The request message syntax is incorrect. |
Busy | A new operation can not be started as another operation is already ongoing. |
InvalidState | The requested operation can not be started in the current device state. |
NoSimCard | No SIM card is inserted into the device. So the requested modem operations is not possible. |
AttachFailure | The modem was unable to attach to the NB-IoT network. |
TxFailure | The 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 Status | Description |
|---|---|
PowerOff | The modem is not power on. |
PoweringUp | The modem is currently powering on. |
PoweringDown | The modem is currently powering down. |
Detached | The modem is powered on but not attachted to the network. |
Attaching | The modem is currently trying to attach to the network. |
Attached | The modem is attached to the NB-IoT network |
Detaching | The modem is currently detaching from the network. |
Transmitting | The modem is transmitting data. |
Receiving | The 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:
Parameter | Description |
|---|---|
<IpAddress> | IP address of sender |
<UdpPort> | UDP port of sender |
<DataLength> | Indicates the number of bytes in <Data>. |
<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:
Parameter | Description |
|---|---|
<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:
|
<NumberOfParameters> | Number which indicates how many parameters the message requires in its payload. In case number = 0, the message has no parameter. |
<Parameter1Name>, | 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:
Parameter | Description |
|---|---|
<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:
Number | Parameter | Description |
|---|---|---|
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.
|
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:
|
12 | <SignalBars> | Signal bars: Indicates strength of the received signal; more bars indicate a better signal quality. |