BCE IOTM Protocol PDF
BCE IOTM Protocol PDF
BCE IOTM Protocol PDF
1. Introduction
The BCE "FM IOTM" protocol is based on well-known MQTT protocol.It is a publish/subscribe, extremely
simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-
latency or unreliable networks. The design principles are to minimise network bandwidth and device
resource requirements whilst also attempting to ensure reliability and some degree of assurance of delivery.
These principles also turn out to make the protocol ideal of the emerging “machine-to-machine” (M2M) or
“Internet of Things” world of connected devices, and for mobile applications where bandwidth and battery
power are at a premium.
MQTT was invented by Dr Andy Stanford-Clark of IBM, and Arlen Nipper of Arcom (now Eurotech), in
1999. As of 2016, MQTT is now an ISO standard (ISO/IEC 20922)
You can pass a username and password with an MQTT packet. Encryption across the network can be handled
with SSL, independently of the MQTT protocol itself.
Protocol easy to adopt for the wide variety of IoT devices, platforms, and operating systems. Many
applications of MQTT can be developed just by implementing the CONNECT, PUBLISH, SUBSCRIBE,
and DISCONNECT control packets. A variety of MQTT client libraries are made available through the
Eclipse Paho project. Eclipse Paho MQTT client libraries could be downloaded from the Eclipse Paho
website.
Quality of service (QoS) levels determine how each MQTT message is delivered and must be specified for
every message sent through MQTT. Three QoS for message delivery could be achieved using MQTT:
● QoS 0 (At most once) - where messages are delivered according to the best efforts of the
operating environment. Message loss can occur.
● QoS 1 (At least once) - where messages are assured to arrive but duplicates can occur.
● QoS 2 (Exactly once) - where message are assured to arrive exactly once.
2. MQTT Client
MQTT client includes publisher or subscribers, both of them label an MQTT client that is only doing
publishing or subscribing. A MQTT client is any device or server. MQTT client libraries are available for a
huge variety of programming languages, for example Android, Arduino, C, C++, C#, Go, iOS, Java,
JavaScript, .NET.
3. MQTT Broker
The broker is responsible for receiving all messages and sending them to all subscribed clients. It also holds
the session of all persisted clients including subscriptions and missed messages. Another responsibility of
the broker is the authentication and authorization of clients.
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
4. Integration using MQTT broker
Using broker to distribute traffic is easy and reliable way to create multi server structure. In order to integrate
MQTT support at server side one of multiple existing libraries for most programming languages could be
used. MQTT library could simplify connection to broker to couple lines of code while only parser of payload
would be left to implement. Payload’s structure is described in section 7. Each device or group of devices
can be configured to have different topic names. Having a group of devices with different topic names makes
it easy to distribute messages between servers. Figure 1 shows example of multi server application where
servers are limited to get only certain messages.
BCE FM SERV
MQTT
BCE FM BROKE
SERV
R
BCE FM SERV
BCE FM
SERV
BCE FM ER A
BCE FM
It is important to note that every field of the following chapter (6) except payload (detailed payload
explanation is provided in chapter 7) from data transmission section (6.2) can be handled using MQTT
libraries (e.g. Paho). Flow of communication between BCE IOTM device and server (broker) is illustrated
in figure 3.
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
Connection SERV
BCE Connection ER
IOTM
Publish/data (BROK
device
ER)
Publish confirm
6.1 Connection
After TCP socket between server and BCE tracking module is created device initiates communication with
connection packet which is provided below:
10 3A 00 04 4D 51 54 54 04 C2 00 F0 00 0F 38 36 35 32 30 39 30 33 39 34 35 31 32 39 30 00 07 64 65 76
69 63 65 73 00 14 31 32 33 34 35 36 37 38 39 3A 3B 3C 3D 3E 3F 40 41 42 43 44
For full connection flags field explanation please refer to MQTT protocol description section 3.1.2. (you
can find MQTT protocol description here). If username and password are required on server side and fields
are not present or do not match connection should be closed. If server accepts the connection it should
respond to the BCE tracking module with packet that is described in the following example. Example
packet in hexadecimal:
20 02 00 00
33 20 00 05 42 43 45 2F 44 00 1B 01 02 91 88 75 2D E7 12 03 00 01 09 00 71 BB 19 09 05 00 30 96 35
12
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
Structure of packet is described in the following table:
Parameter name No. of bytes Example value Comment
Packet type 1 33 Packet identifier byte can
identifier be split into following
values:
Bit7-Packet type
Bit6-Packet type
Bit5-Packet type
Bit4-Packet type
Bit3-DUP flag
Bit2-QoS level
Bit1-QoS level
Bit0-Retained
Example packet belongs
to QoS1 and has to be
confirmed by the server.
Data transmission packet
type is always 3.
DUP and Retained values
may be ignored.
Bit1 - 0, Bit2 - 0: QoS0
Bit1 - 1, Bit2 - 0: QoS1
Bit1 - 0, Bit2 - 1: QoS2
Bit1 - 1, Bit2 - 1: reserved
Remaining length 1 if value is less than 20 Length of the remaining
128, 2 bytes otherwise packet starting with next
byte (00 in this case).
Note that remaining
length can encode higher
than 127 value using the
following method. For
example if packet is 279
bytes long (excluding
remaining length itself
and packet identifier) least
significant byte comes
first and its most
significant bit encodes
that packet is longer than
127 bytes. 279 is encoded
as 97 02 where least
significant byte 97 can be
masked to know that
value is higher than 127
bytes. 279 can be
calculated using the
following equation -
0x97&0x7F+2*0x80 in
hexadecimal or 23+2*128
in decimal.
Topic name length 2 00 05 Topic name is 5 bytes
long (0x05 in hex)
Topic name 5* 42 43 45 2F 44 BCE/D stands for data
type that is being sent (D
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
in this case stands for
regular data packet).
Topics are used for
filtering or distribution of
incoming data. Note that
topics can be longer (e.g.
BCE/D/FB01).Modules
can send more than one
data type, for structure
version 1 payload,
however only BCE/D,
BCE/E and BCE/R should
be taken into
consideration. For
structure version 2
payload topic names may
not be taken into
consideration.
Packet identifier* 2 00 1B Value used for packet
confirmation thats
explained later on. Each
QoS1 packet should be
confirmed with ACK
packet that has the same
packet identifier value.
Further explanation of
packet confirmation is
provided in next chapter.
Field is not present with
QoS0 messages.
Payload Length = Remaining 01 02 91 88 75 2D Payload structures for
length - 5 - Topic name E7 12 03 00 01 09 events and regular data
length 00 20 00 AD 59 are explained in section 7.
05 00 30 96 35 12 Example uses payload
structure version 1
Table 3. Data publish packet
*value can vary according to other parameters that are specified previously
Packets that belong to QoS1 should be confirmed (QoS0 packets do not need confirmation). Confirmation
to example packet is explained below.
40 02 00 1B
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
6.4 Connectivity keep-alive
During periods when there are no records or real time data to be sent over present connection BCE IOTM
devices send keep-alive messages (PINGREQ according to MQTT protocol specification) to keep TCP
connection alive. PINGREQ packets have to be responded with PINGRESP in order to keep connection
alive. Maximum period between two data transfers is told by BCE IOTM device during connection phase
(6.1 section Keep alive interval). Keep alive interval can be changed in device’s configuration. Example of
PINGREQ and PINGRESP packets in low level is given below:
Please have in mind that this part of protocol completely compatible with MQTT and only needs to be
considered if direct connection is used.
If the device is configured to be able to control outputs on commands, the first thing it does after connecting
to server is send a subscription packet, that has to be confirmed by the server. Example of subscription
packet is given below and explained in table 7.
82 19 00 01 00 15 38 36 35 32 30 39 30 33 39 35 35 34 37 30 35 2F 4F 55 54 43 01
82 Packet type -
00 01 Packet identifier -
Subscription packets have to be confirmed with the acknowledge packet. Acknowledge packet’s example is
explained below.
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
90 03 00 01 01
03 Remaining length -
If server wants to control outputs it has to send publish packets that are described in Data transmission
section, but topic name has to match output control topic that is configured in device (default is IMEI/OUTC
where IMEI is device’s unique number). Payload field of output control message is explained in 7.1.3
Output control section.
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
7. Payload
7.1 Structure version 2
Structure version 2 allows transmission of messages that can contain different types of data (events,
telemetry, files) in same topic or even packet. Structure version 2 is explained below:
Structure Record (n) Record (n+1) Record (n+2) Record (n+3) Checksum
version=2
Table 9. Structure version 2 payload
Each record starts with a record type and two bytes that describe remaining length of record.
Devices that use BCE IOTM protocol can publish files, telemetry data or events that can be used for
debugging purposes. BCE IOTM devices can also subscribe to output control. Each of those cases may
share the same topic, or topic names can be configured to be different. Files by default are sent over BCE/F
topic, telemetry data by default is sent over BCE/D, events by default are sent over BCE/E topic, real time
telemetry data is sent over BCE/R topic. To receive output commands module with default configuration
subscribes to IMEI/OUTC where IMEI is device’s unique id.
Telemetry data and IMEI records are structured using the same rules as provided in structure version 1
(refer to section 7.1.1).
Example payload that contains telemetry data and IMEI is given below
02 02 08 00 91 88 75 2D E7 12 03 00 01 09 00 20 00 AD 59 05 00 30 96 35 F3
Each payload ends with a checksum of it’s own (In example case checksum is started counting from first
payload byte 02). Sensors array consists of multiple sensors. Each sensor is described with a type, sensor
ID and value fields.
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
Type_zero 3 Used to define sensors whose values are zero.
Note that value field is not present with this
field since type already specifies value.
Type_U8 4 Used to define sensors whose values are 255
and below. Value field is present with this
sensor and is 8 bits long.
Type_U16 5 Used to define sensors whose values are
between 65535 and 256. Value field is present
with this sensor and is 16 bits long.
Type_U32 6 Used to define sensors whose values are
between 4294967295 and 65535. Value field is
present with this sensor and is 32 bits long.
Type_U64 7 Used to define sensors whose values are above
4294967295. Value field is present with this
sensor and is 64 bits long.
Type_S8 8 Used to define sensors values that are signed
and are 8 bits long. Value field is present with
this sensor type.
Type_S16 9 Used to define sensors values that are signed
and 16 bits long. Value field is present with this
sensor type.
Type_S32 10 Used to define sensors values that are signed
and are 32 bits long. Value field is present with
this sensor type.
Type_S64 11 Used to define sensors values that are signed
and are 64 bits long. Value field is present with
this sensor type.
Type_Float 12 Used to define sensors values that expressed
with a floating point number. Value field is
present with this sensor type and is 32 bits long.
Type_Double 13 Used to define sensors values that are expressed
with a double precision number. Value field is
present with this field and is 64 bits long.
Type_GPS 14 Used to define value that comes as GPS data
structure.
GPS structure (16 bytes long) consists of the
following fields:
Latitude (32 bits float)
Longitude (32 bits float)
Speed (16 bits unsigned int)
HDOP (8 bits unsigned int)
Satellites (8 bits unsigned int)
Course (16 bits unsigned int)
Altitude (16 bits signed int)
Type_StringL1 32 Used to define sensors that are represented as
string and are less than 256 bytes long. After
sensor ID field 1 byte length field is present.
After length comes string (length is presented
previously).``
Type_BinaryL1 33 Used to define sensors that are represented as
binary array and are less than 256 bytes long.
After sensor ID field 1 byte length field is
present. After length comes binary array (length
is presented previously).
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
Type_StringL2 64 Used to define sensors that are represented as
string and are less than 65536 bytes long. After
sensor ID field 2 bytes length field is present.
After length comes string (length is presented
previously).
Type_BinaryL2 65 Used to define sensors that are represented as
binary array and are less than 65536 bytes long.
After sensor ID field 2 byte length field is
present. After length comes binary array (length
is presented previously).
Table 14. Sensor value types
Another payload example with a detailed description of data values is provided below (note that payload is
formed in little endian format).
02 02 08 00 91 88 75 2D E7 12 03 00 01 3A 00 20 00 AD 59 05 00 30 B1 35 03 03 40 03 0C 30 03 01 A0
03 02 A0 0E 00 D0 B9 AB 5B 42 03 34 C0 41 00 00 1F 06 00 00 32 00 04 07 20 64 00 8C 00 01 62 00 20
00 C0 04 47 6F 6F 44 01 09 00 21 00 AD 59 05 00 30 BA 35 9B 66 00 00 6D 00 00 67 00 44
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
07 20 Sensor identifier Fuel level sensor
64 Sensor value 100 is fuel level value
00 Sensor value type Boolean false signal
8C 00 Sensor identifier Foot brake signal
01 Sensor value type Boolean true signal
62 00 Sensor identifier Front left door open signal
20 Sensor value type String sensor
00 C0 Sensor identifier String 1 sensor whose length is less than
256
04 Length String 1 is 4 bytes long
47 6F 6F 44 Sensor value String 1 is 4 byte ASCII string “GooD”
01 Record type 1 (Sensors array record)
09 00 Length 9 bytes
21 00 AD 59 Unix timestamp Monday, September 4, 2017 7:26:25 AM
(UTC)
05 Sensor type value Unsigned 16 bit integer
00 30 Sensor identifier VCC
BA 35 Sensor value 13754
9B Checksum Sum of all bytes starting with structure
version 02
Table 15. Explained example packet
*For list of sensor names please contact BCE tech. support team
Payload example that contains events data and IMEI is given below.
02 02 08 00 91 88 75 2D E7 12 03 00 03 0A 00 20 00 AD 59 00 01 46 54 32 50 03 0A 00 22 00 AD 59 64
33 46 54 32 50 FB
Example of output payload that can be used to turn on OUT1 for 1 second is given below:
02 02 08 00 91 88 75 2D E7 12 03 00 04 0A 00 50 00 AD 59 00 11 03 00 64 00 9F
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
03 Output command length in bytes
00 64 00 Output data. For structure please refer to section 8.
9F Sum of all bytes starting with structure version
Table 19. Structure version 2 output control example
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
File part * Part of file. Length of File part 48 65 6C 6C 6F 20
is described in Length of file 77 6F 72 6C 64
part field
Table 21. Explanation of record that’s a file of a part
Every file transmission starts with announce packet. Example payload with file record that has file announce
is given below:
02 02 08 00 91 88 75 2D E7 12 03 00 05 4E 00 01 38 36 35 32 30 39 30 33 39 35 35 34 37 30 35 2D 31 35
32 34 32 33 33 36 33 33 2E 63 61 6E 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 00 00 00 00 00 00 00 20 00 AD 59 0B 00 00 00 3C 04 00 00 01 00 14
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
8. Output data structures
This section explains Output data field that is mentioned in section 7.1.3.
00 OUT1 3
Function Data Description
ID
01 OUT2 3
Function Data Description
ID
02 OUT3 3
Function Data Description
ID
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
resolution)
Output data field is combination of Function ID and
Data fields
03 OUT4 3
Function Data Description
ID
04 OUT5 3
Function Data Description
ID
05 UNLOCK 2
OVER CAN Data Description
06 LOCK OVER 2
CAN Data Description
07 REMOTE 1
DUMP Data Description
COMMAND
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
01 Forces device to log data from CAN1
for up to 20 seconds.
08 STATIC 1
SIGNAL1 Data Description
CONTROL
01 01 is used to set static signal to 1.
Any other data will change static
signal state to 0.
09 STATIC 1
SIGNAL2 Data Description
CONTROL
01 01 is used to set static signal to 1.
Any other data will change static
signal state to 0.
0A STATIC 1
SIGNAL3 Data Description
CONTROL
01 01 is used to set static signal to 1.
Any other data will change static
signal state to 0.
0B STATIC 1
SIGNAL4 Data Description
CONTROL
01 01 is used to set static signal to 1.
Any other data will change static
signal state to 0.
0C STATIC 1
SIGNAL5 Data Description
CONTROL
01 01 is used to set static signal to 1.
Any other data will change static
signal state to 0.
0D SCRIPT n
REMOTE
COMMAND
Table 24. Output data field structure
To form output command Output data field from section 7.1.3 should be formed in following order:
Function ID, Data bytes.
Example of Output data that should be used in order to turn on OUT1 of BCE IOTM device for 500ms is
given below:
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
00 80 00
Please take into consideration that Output control record is a part of payload that has to be wrapped with
MQTT header. During cases where no MQTT broker is used server has to make sure that payload is being
published to BCE IOTM device with preconfigured topic name (IMEI/OUTC by default, where IMEI is
replaced with device’s unique ID) and QoS1. Explanation of data publishing is given in section 6.2.
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS
Annex A.
Specific structure parsing for ISOBUS messages
Some binary array sensors can be parsed to structures.
Sensor with identifier 0xEFFE can be parsed according to structure provided below.
Note that length of binary array should be n*8, otherwise structure should be considered invalid.
Payload’s (in hexadecimal) that contains sensor 0xEFFE example (example is provided with payload of
structure version 1, however same rules can be applied to structure 2 telemetry data record):
01 02 91 88 75 2D E7 12 03 00 01 34 00 20 00 AD 59 0E 00 D0 B9 AB 5B 42 03 34 C0 41 00 00 1F 06 00
00 32 00 41 FE EF 18 00 E4 01 01 00 20 D6 13 00 C0 00 05 00 40 AC 27 00 02 00 06 00 20 D6 13 00 01
09 00 21 00 AD 59 05 00 30 BA 35 64
BALTIC CAR EQUIPMENT Chemijos st. 15 LT-51332, Kaunas, Lithuania www.bce.lt TELEMATICS & IOT SOLUTIONS