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
| Table of Contents | ||||||
|---|---|---|---|---|---|---|
|
Interface Version History
The table shows the changes history of the NB | EASY Interface Specification:
| Version | Date | Changes |
|---|---|---|
| 1.3 |
| |
| 1.2 |
| |
| 1.1 |
| |
| 1.0 |
|
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.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Message Syntax
The message syntax of a typical EASY-IF message looks as follows:
...
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
EASY~ExampleOperationId2<CR> |
Confirm Messages
A confirm message informs the user about a finished operation triggered by a request message:
...
| 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 | 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.
...
| Parameter | Description |
|---|---|
| <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.
...
| Drawio | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Mode
The Exelonix NB-IoT device can work in two different modes: EASY mode or 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.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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:
...
| Drawio | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Detach
In case the modem is in Attached state an Detach operation can be triggered the detach the device from the NB-IoT network.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
| 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.
|
| 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 |
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
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.
...
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
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.
...
| Drawio | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Example Usecases
The folowing examples show typical usecases of the EASY interface.
Booting, Attach, Transmission & Reception
| Drawio | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|