BitPipe Serial API V1

Rev 1.9

2017-04-28

www.briowireless.com Copyright 2016 Briowireless inc. 1

BitPipe Serial API V1

Table of Contents
Table of Contents .......................................................................................................................................... 2
1. Revision History .................................................................................................................................... 5
2. Serial Protocol Definition ...................................................................................................................... 7
2.1. Concepts and Definitions .............................................................................................................. 7
Messages............................................................................................................................................... 7
Endpoints .............................................................................................................................................. 7
Requests and Replies ............................................................................................................................ 7
2.2. Implementation Details ................................................................................................................ 7
Message Buffer Size .............................................................................................................................. 7
Tips ........................................................................................................................................................ 8
2.3. Configuration ................................................................................................................................ 8
2.4. Reliability....................................................................................................................................... 8
2.5. Message Format............................................................................................................................ 8
2.6. Message Encoding ........................................................................................................................ 9
Reserved Values .................................................................................................................................... 9
Endianness ............................................................................................................................................ 9
CRC Calculation ..................................................................................................................................... 9
3. Messages ............................................................................................................................................. 11
3.1. System (0x00-0x0F) ..................................................................................................................... 11
0x00 - Error Report ............................................................................................................................. 11
0x01 - Set Maximum Message Payload Size ....................................................................................... 14
0x02 - Set UART Speed ........................................................................................................................ 16
3.2. Device Information (0x10-0x1F) ................................................................................................. 17
0x10 - Get Hardware Version .............................................................................................................. 17
0x11 - Get Firmware Version .............................................................................................................. 18
0x12 - Get Product Name.................................................................................................................... 19
0x13 - Get VIN and VIO Voltage .......................................................................................................... 20
0x14 - Get Junction Temperature ....................................................................................................... 21
0x15 - Set Low Power Mode ............................................................................................................... 22
0x18 - Get Latest Firmware Version.................................................................................................... 23
0x19 - Update Firmware ..................................................................................................................... 25
0x1A - Get Autonomous Mode Configuration .................................................................................... 27
0x1B - Set Autonomous Mode Configuration ..................................................................................... 29

www.briowireless.com Copyright 2016 Briowireless inc. 2

BitPipe Serial API V1

3.3. Mobile Status and Information (0x20-0x2F) ............................................................................... 31

0x20 - Power-On Radio ....................................................................................................................... 31
0x21 - Power-Off Radio ....................................................................................................................... 33
0x22 - Radio Start Notify ..................................................................................................................... 35
0x23 - Get Radio Status ....................................................................................................................... 36
0x24 - Get IMEI.................................................................................................................................... 37
0x25 - Get ICCID .................................................................................................................................. 38
0x26 - Get IMSI .................................................................................................................................... 39
0x27 - Get Own Phone Number .......................................................................................................... 40
0x28 - Get APN Configuration ............................................................................................................. 42
0x29 - Set APN Configuration.............................................................................................................. 43
0x2A - Set SIM Access Configuration .................................................................................................. 45
0x2B - Get Mobile Connection Status ................................................................................................. 47
0x2C - Mobile Connection Status Change Notify ................................................................................ 49
0x2D - Get Mobile Date and Time....................................................................................................... 50
3.4. WiFi Status and Information (0x30-0x3F) ................................................................................... 52
3.5. LoRa Status and Information (0x40-0x4F)................................................................................... 53
3.6. IP Socket (0x80-0x8F) .................................................................................................................. 54
0x80 - TCP Initiate Connection ............................................................................................................ 54
0x81 - TCP Connection Established Notify .......................................................................................... 57
0x82 - TCP Write Append .................................................................................................................... 58
0x83 - TCP Write Send......................................................................................................................... 60
0x84 - TCP Rx Notify ............................................................................................................................ 62
0x85 - HTTP Initiate Connection ......................................................................................................... 63
0x86 - HTTP POST Write Ready Notify ................................................................................................ 66
0x87 - HTTP POST Write ...................................................................................................................... 67
0x88 - HTTP Rx Notify.......................................................................................................................... 69
0x8E - IP Connection Close .................................................................................................................. 70
0x8F - IP Connection Close Notify ....................................................................................................... 72
3.7. MQTT Client API (0x90-0x9F) ...................................................................................................... 73
0x90 - MQTT Initiate Connection ........................................................................................................ 73
0x91 - MQTT Connection Established Notify ...................................................................................... 76

www.briowireless.com Copyright 2016 Briowireless inc. 3

BitPipe Serial API V1

0x92 - MQTT Subscribe Topic.............................................................................................................. 77

0x93 - MQTT UnSubscribe Topic ......................................................................................................... 79
0x94 - MQTT Publish ........................................................................................................................... 81
0x95 - MQTT Publication Rx Notify ..................................................................................................... 83
0x9E - MQTT Disconnect ..................................................................................................................... 85
0x9F - MQTT Disconnect Notify .......................................................................................................... 86
3.8. SMS (0xD0-0xD7) ........................................................................................................................ 87
0xD0 - SMS Setup Transmission .......................................................................................................... 87
0xD1 - SMS Message Append / Send .................................................................................................. 89
0xD4 - SMS Message Reception Notify ............................................................................................... 91
0xD5 - SMS Message Part Notify......................................................................................................... 93

www.briowireless.com Copyright 2016 Briowireless inc. 4

BitPipe Serial API V1

1. Revision History
Revision Date Comments
0.9 2016-06-13 Pre Release
0.9.1 2016-07-15 Added SMS Feature
0.9.2 2016-07-20 Get FW Version: Added
bootloader version.
0.9.3 2016-08-08 HTTP API added
0.9.4 2016-08-09 Removed TCP CLOSE and TCP
CLOSE NOTIFY messages and
renamed them to IP
CONNECTION CLOSE and IP
CONNECTION CLOSE NOTIFY,
respectively.
0.9.5 2016-08-16 MQTT API added.
0.9.6 2016-08-23 Augmented Host Maximum
message size to 260. This allows
the host to receive various "* Rx
Notify" messages with 255 bytes
of user data payload.
(Because of the static message
parts).
1.0 2016-08-30 Official Release of API V1
1.1 2016-09-15 Modified POWER-ON RADIO by
introducing a back-off
mechanism.
1.2 2016-09-23 Added 2 new error reports
regarding VIN supervision loop.
1.3 2016-09-26 Limited the possible values for
Autonomous Mode & MQTT
keep-alive intra-interval values.
1.4 2016-10-20 Adding error status 4 for all
message replies that can return it.
1.5 2016-10-28 Fix SET UART SPEED message
definition (aligned with current
implementation).
1.6 2016-11-18 Added a comment in the MQTT
PUBLISH message concerning the
usage of QOS and Retain Ind
parameters.
1.7 2016-11-24 Added error codes to GET LATEST
FW VERSION and UPDATE
FIRMWARE, when sim card status
is invalid.

www.briowireless.com Copyright 2016 Briowireless inc. 5

BitPipe Serial API V1

1.8 2016-12-07 Rework documentation about the

back-off mechanism at POWER-
ON-RADIO.
Add more information in power-
off radio regarding the power-off
method.
1.9 2016-02-15 Added information on network
behavior and timeout related to
establishing TCP connections
using TCP INITIATE CONNECTION
to an unreachable host.

www.briowireless.com Copyright 2016 Briowireless inc. 6

BitPipe Serial API V1

2. Serial Protocol Definition

2.1. Concepts and Definitions

Messages
Information is traded in units called messages. This protocol defines messages as a sequence of bytes,
formatted in a specific way.

See Message Format below for details.

Endpoints
Endpoints are entities that take part in the messaging system described herein. Since this protocol is
point-to-point, only 2 entities, or endpoints, are defined: The Host and the BitPipe.
The Host refers to the endpoint (e.g.: PC, Microcontroller, etc) using or controlling the BitPipe.

The term remote endpoint refers to the other endpoint, where a message is often "sent to" or "received
from". This is context-dependent and may refer to either the Host or BitPipe.

Requests and Replies

Messages can take two forms: Requests and Replies.

Requests are primarily used to instruct the remote endpoint to perform some action. They are also used
to inform the remote endpoint of a new condition or event.

Replies are messages sent following the processing of a request from an endpoint.
Not all request messages have corresponding replies.

2.2. Implementation Details

This messaging protocol allows for request messages to be exchanged asynchronously from both
endpoints at any time.
However, requests received by the BitPipe are treated in the order they are received.

Message Buffer Size

The BitPipe UART buffer is fixed-length at 255 bytes for message data (excluding message header and
footer). Sending messages that are bigger than this limit will cause the BitPipe to send you an Error
Report, because it cannot handle that much data in a single message.

Some messages are of fixed size; these messages are guaranteed to be handled appropriately by the
BitPipe.

Other messages are of variable size, for example TCP read and TCP write messages. These messages
convey payload data of an arbitrary size. Your implementation should make sure that once the message
is serialized to be sent on the UART, it does not exceed the aforementioned limit.

www.briowireless.com Copyright 2016 Briowireless inc. 7

BitPipe Serial API V1

Tips
For an easy time integrating the BitPipe, the following tips should be heeded:

 Never wait indefinitely for a reply: assume messages can be lost.

 Implement retry-send mechanism for requests that are not replied to (Using the same sequence
number).

 After sending a request, never assume the next message received from the BitPipe is the reply you
were expecting. It might be something else. This protocol allows for both endpoints to send
messages asynchronously.

2.3. Configuration
The UART interface must be initially configured with the following parameters:

 Baud Rate: 115200;

 8 data bits;

 No parity;

 1 stop bit;

 No HW flow control.

See the Set UART Speed operation to change the baud rate.

2.4. Reliability
When a request message is sent from the BitPipe to the Host, the BitPipe will expect a reply message
from the Host, as acknowledgement.
Resources in the BitPipe might be held until such a reply is received from the Host.
A retry mechanism will trigger a re-emit of the request (with the same sequence number) to the Host,
after a 1000 milliseconds timeout. This mechanism will be triggered a maximum of 2 times. After this,
the BitPipe will drop the request and any information associated with it.

2.5. Message Format

Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Command Identifier [0x00 - 0xFF]
2 SEQ Message sequence number [0x00 - 0xFF]
3 STATUS Status Code [0x00 - 0xFF]
4 ... DAT Data Payload [0x00 - 0xFF]
[N-2, N-1] CRC CRC of the packet (Big endian) [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc. 8

BitPipe Serial API V1

The Command Identifier is used to interpret the information found in the data payload.

The Message Sequence Number is used to prevent duplicate messages from being processed. This
number should be incremented by 1 for each new message sent.

2.6. Message Encoding

Reserved Values
Value Signification
0x7E Start-of-frame character
0xCE End-of-frame character
0x9E Escape character
If any byte between Start-of-frame and End-of-frame is equal to one of the above reserved values, that
byte needs to be escaped for transmission. This escape character must then be discarded at reception
and must not be used to compute the CRC.

Endianness
Multi-byte integers (UINT16, UINT32) are always transmitted in big endian.

CRC Calculation
The CRC is calculated on every single byte, excluding Escape character, from command to last bytes of
data inclusively. The algorithm used for CRC calculation is a CRC-16-CCITT with a seed value of 0xFFFF,
polynomial as 0x1021 and no final xor. Here is the source code in C:

Table 1 CRC16

#define CRC16_CCITT_SEED_VALUE 0xFFFF /* Initial CRC value */

static unsigned short crc16_ccitt_table[256] = {

0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50a5, 0x60c6, 0x70e7,
0x8108, 0x9129, 0xa14a, 0xb16b, 0xc18c, 0xd1ad, 0xe1ce, 0xf1ef,
0x1231, 0x0210, 0x3273, 0x2252, 0x52b5, 0x4294, 0x72f7, 0x62d6,
0x9339, 0x8318, 0xb37b, 0xa35a, 0xd3bd, 0xc39c, 0xf3ff, 0xe3de,
0x2462, 0x3443, 0x0420, 0x1401, 0x64e6, 0x74c7, 0x44a4, 0x5485,
0xa56a, 0xb54b, 0x8528, 0x9509, 0xe5ee, 0xf5cf, 0xc5ac, 0xd58d,
0x3653, 0x2672, 0x1611, 0x0630, 0x76d7, 0x66f6, 0x5695, 0x46b4,
0xb75b, 0xa77a, 0x9719, 0x8738, 0xf7df, 0xe7fe, 0xd79d, 0xc7bc,
0x48c4, 0x58e5, 0x6886, 0x78a7, 0x0840, 0x1861, 0x2802, 0x3823,
0xc9cc, 0xd9ed, 0xe98e, 0xf9af, 0x8948, 0x9969, 0xa90a, 0xb92b,
0x5af5, 0x4ad4, 0x7ab7, 0x6a96, 0x1a71, 0x0a50, 0x3a33, 0x2a12,
0xdbfd, 0xcbdc, 0xfbbf, 0xeb9e, 0x9b79, 0x8b58, 0xbb3b, 0xab1a,
0x6ca6, 0x7c87, 0x4ce4, 0x5cc5, 0x2c22, 0x3c03, 0x0c60, 0x1c41,
0xedae, 0xfd8f, 0xcdec, 0xddcd, 0xad2a, 0xbd0b, 0x8d68, 0x9d49,
0x7e97, 0x6eb6, 0x5ed5, 0x4ef4, 0x3e13, 0x2e32, 0x1e51, 0x0e70,
0xff9f, 0xefbe, 0xdfdd, 0xcffc, 0xbf1b, 0xaf3a, 0x9f59, 0x8f78,
0x9188, 0x81a9, 0xb1ca, 0xa1eb, 0xd10c, 0xc12d, 0xf14e, 0xe16f,
0x1080, 0x00a1, 0x30c2, 0x20e3, 0x5004, 0x4025, 0x7046, 0x6067,

www.briowireless.com Copyright 2016 Briowireless inc. 9

BitPipe Serial API V1

0x83b9, 0x9398, 0xa3fb, 0xb3da, 0xc33d, 0xd31c, 0xe37f, 0xf35e,

0x02b1, 0x1290, 0x22f3, 0x32d2, 0x4235, 0x5214, 0x6277, 0x7256,
0xb5ea, 0xa5cb, 0x95a8, 0x8589, 0xf56e, 0xe54f, 0xd52c, 0xc50d,
0x34e2, 0x24c3, 0x14a0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405,
0xa7db, 0xb7fa, 0x8799, 0x97b8, 0xe75f, 0xf77e, 0xc71d, 0xd73c,
0x26d3, 0x36f2, 0x0691, 0x16b0, 0x6657, 0x7676, 0x4615, 0x5634,
0xd94c, 0xc96d, 0xf90e, 0xe92f, 0x99c8, 0x89e9, 0xb98a, 0xa9ab,
0x5844, 0x4865, 0x7806, 0x6827, 0x18c0, 0x08e1, 0x3882, 0x28a3,
0xcb7d, 0xdb5c, 0xeb3f, 0xfb1e, 0x8bf9, 0x9bd8, 0xabbb, 0xbb9a,
0x4a75, 0x5a54, 0x6a37, 0x7a16, 0x0af1, 0x1ad0, 0x2ab3, 0x3a92,
0xfd2e, 0xed0f, 0xdd6c, 0xcd4d, 0xbdaa, 0xad8b, 0x9de8, 0x8dc9,
0x7c26, 0x6c07, 0x5c64, 0x4c45, 0x3ca2, 0x2c83, 0x1ce0, 0x0cc1,
0xef1f, 0xff3e, 0xcf5d, 0xdf7c, 0xaf9b, 0xbfba, 0x8fd9, 0x9ff8,
0x6e17, 0x7e36, 0x4e55, 0x5e74, 0x2e93, 0x3eb2, 0x0ed1, 0x1ef0};

unsigned short crc16_ccitt_update(unsigned short crc, unsigned char data)

{
data = (crc >> 8) ^ data;
crc = (crc << 8) ^ crc_table[data];

return crc;
}

www.briowireless.com Copyright 2016 Briowireless inc.

10
BitPipe Serial API V1

3. Messages
3.1. System (0x00-0x0F)

0x00 - Error Report

The BitPipe informs the Host that an error occurred.

The reception of this message does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Error Report 0x00
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 FACILITY Error facility: [0x00 - 0xFF]
0: Communication Facility;
1: Boot Facility;
2: HW Facility.
5 ERROR NUM Error number, depending on facility. [0x00 - 0xFF]
[6, 7] CRC CRC [0x0000 -
0xFFFF]
8 EOF End-of-frame 0xCE

Error Numbers and Meaning

Facility Error Description
Number
0 0 CRC Error on last message received.
(Communication) Resolution: Check your CRC algorithm.
0 1 Message too long.This may occur for variable-sized messages.
(Communication) It indicates that the internal UART communication buffer of the
BitPipe is full and the End-Of-Frame character was not seen.
Resolution: Make sure the messages you send to the BitPipe are
smaller than its internal UART communication buffer.
0 2 Unknown Message Command Identifier.
(Communication) This indicates that the BitPipe has received a message it doesn't
know how to handle. This might mean an error occurred in the
message sent from the Host.
Resolution: Check if the FW version of the BitPipe is the latest.
www.briowireless.com Copyright 2016 Briowireless inc.
11
BitPipe Serial API V1

Check if the message command ID previously sent is defined.

1 0 An unknown error has occurred.
(Boot) Resolution: The BitPipe boot will retry the firmware update
procedure.
1 1 An error occurred during the firmware update procedure.
(Boot) This event indicates that while trying to erase or program a flash
page, the CPU returned BUSY.
Resolution: The BitPipe boot will retry the firmware update
procedure.
1 2 An error occurred during the firmware update procedure.
(Boot) This event indicates that while trying to erase or program a flash
page, the CPU got a write protection fault.
Resolution: This error should never happen; in this case, the
BitPipe will retry the firmware update procedure.
1 3 An error occurred during the firmware update procedure.
(Boot) This event indicates that while trying to erase or program a flash
page, the CPU returned ERROR PROGRAM.
Resolution: This error should never happen; in this case, the
BitPipe will retry the firmware update procedure.
1 4 An error occurred during the firmware update procedure.
(Boot) This event indicates that while trying to erase or program a flash
page, the operation timed out.
Resolution: This error should never happen; in this case, the
BitPipe will retry the firmware update procedure.
1 5 Radio reports the SIM card is missing for firmware update.
(Boot) Resolution: Insert a SIM or try removing and then reinsert the SIM
card
1 6 Radio reports an unhandled error occurred during firmware
(Boot) update.
Resolution: The BitPipe will retry the firmware update procedure.
1 7 Radio report that the remote peer has unexpectedly closed the
(Boot) connection during firmware update.
Resolution: The BitPipe will retry the firmware update procedure.
1 8 An AT command sent to the radio remained unanswered for too
(Boot) long (10 Seconds).
Resolution: The BitPipe will retry the firmware update procedure.
1 9 The BitPipe did not receive an instruction to update, but there is
(Boot) no firmware present in memory.
Resolution: The BitPipe will initiate the firmware update
procedure.
2 0 The BitPipe VIN supervision loop detected an under-voltage. The
(HW) slave device (i.e.: Radio) was shut down.
2 1 The BitPipe VIN supervision loop detected an over-voltage. The
(HW) slave device (i.e.: Radio) was shut down.
www.briowireless.com Copyright 2016 Briowireless inc.
12
BitPipe Serial API V1

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

13
BitPipe Serial API V1

0x01 - Set Maximum Message Payload Size

This message is used by the Host to inform the BitPipe the maximum message size it can process.
Note that this affects only messages of variable size (e.g.: TCP Rx Notify, HTTP Rx Notify, MQTT
Publication Rx Notify, SMS Message Part Notify).

By default, the BitPipe will try to maximize the user data throughput by sending messages to the Host as
big as possible.
When the Host is limited in available resources, use this request to limit the size of messages sent from
the BitPipe to the Host.

This operation is only required once. The BitPipe will memorize the configuration in non-volatile storage.

Note: When configuring a small maximum message payload size, the BitPipe will need to send more
messages to transfer a user data payload.
Note 2: Message payload excludes message header (SOF, CMD, ID, STATUS) and excludes footer (CRC 1,
CRC2, EOF).

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set Maximum Message Payload Size 0x01
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4,5] SIZE Maximum Message Size [48-260]
[6, 7] CRC CRC [0x0000 -
0xFFFF]
8 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set Maximum Message Payload Size 0x01
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-2]
1: Error; Message malformed.
2: Error; Invalid parameter value.
3 7 MSG TYPE REPLY 1
www.briowireless.com Copyright 2016 Briowireless inc.
14
BitPipe Serial API V1

[4, 5] CRC CRC [0x0000 -

0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

15
BitPipe Serial API V1

0x02 - Set UART Speed

This operation allows the Host to inform the BitPipe the speed to use on the UART link. The reply to the
request is sent before the link speed is changed.
On success, the link speed is changed. On error, the link speed remains unchanged.

This operation is only required once. The BitPipe will memorize the configuration in non-volatile storage.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set UART Speed 0x02
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 SPEED New UART Speed: [0-2]
0: 115200 bits per second (Factory default).
1: 9600 bits per second.
2: 460800 bits per second.
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set UART Speed 0x02
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-2]
1: Error; Message malformed.
2: Error; Invalid parameter value.
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

16
BitPipe Serial API V1

3.2. Device Information (0x10-0x1F)

0x10 - Get Hardware Version

Allows retrieving the BitPipe hardware version.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Hardware version 0x10
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Hardware version 0x10
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
1: Error; Message malformed.
3 7 MSG TYPE REPLY 1
4 LEN Length, in bytes, of the hardware version. [0-24]
[5-...] HW Hardware version ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

17
BitPipe Serial API V1

0x11 - Get Firmware Version

Allows Retrieving the BitPipe firmware version, and the Radio firmware version, if available.

For example, if the BitPipe Radio is offline, the Radio FW version will be blank.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Firmware version 0x11
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Firmware version 0x11
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 3]
1: Error; Message malformed.
3 7 MSG TYPE REPLY 1
[4,5] BOOT VER BitPipe Bootloader Version: [0x0000-
MSB: Major version 0xFFFF]
LSB: Minor version
6 BP API BitPipe API version [0x00 - 0xFF]
VERSION
7 BP FW LEN Length, in bytes, of the BitPipe firmware version. [0-24]
[8-X] BITPIPE FW BitPipe Firmware version. ASCII
[X+1] RADIO FW LEN Length, in bytes, of the Radio firmware version. [0-16]
[X+2..N-3] RADIO FW Radio Firmware version. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

18
BitPipe Serial API V1

0x12 - Get Product Name

Allows retrieving the BitPipe product name.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Product Name 0x12
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Product Name 0x12
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
1: Error; Message malformed.
3 7 MSG TYPE REPLY 1
4 LEN Length, in bytes, of the product name. [0-16]
[5-...] PROD NAME Product Name ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

19
BitPipe Serial API V1

0x13 - Get VIN and VIO Voltage

Retrieves the actual voltage for VIN and VIO of the BitPipe, in millivolts, and returns the result.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get VIN and VIO Voltage 0x13
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get VIN and VIO Voltage 0x13
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1]
1: Error; Message malformed.
3 7 MSG TYPE REPLY 1
[4, 5] VIN Voltage, in millivolts: [0-65535]
Normal values are from 3400 to 18000.
[6, 7] VIO Voltage, in millivolts: [0-65535]
Normal values are 2500 or 3300.
[8, 9] CRC CRC [0x0000 -
0xFFFF]
10 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

20
BitPipe Serial API V1

0x14 - Get Junction Temperature

Retrieves the actual internal junction temperature, in Celsius, and returns the result.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Junction Temperature 0x14
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Junction Temperature 0x14
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1]
1: Error; Message malformed.
3 7 MSG TYPE REPLY 1
4 TEMP Temperature, in Celcius degrees. 0
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

21
BitPipe Serial API V1

0x15 - Set Low Power Mode

Sets the BitPipe to Low Power Mode. The Modem will go back in Normal Mode when it will receive any
character on the Serial Communication Interface (UART).

Note: Power-off the radio before initiating the Low Power Mode.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set Low Power Mode 0x15
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set Low Power Mode 0x15
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1,10]
1: Error; Message malformed.
10: Error; Cannot enter Low Power Mode: The radio
is currently powered-on.
3 7 MSG TYPE REPLY 1
[4,5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

22
BitPipe Serial API V1

0x18 - Get Latest Firmware Version

This operation is initiated by the Host. Upon reception of this message, the BitPipe will retrieve the
latest FW string from Briowireless's servers.

The version string is returned in the reply. You may compare it to the actual BitPipe firmware version
using the Get Firmware Version operation.

Prerequisite: The APN must have been previously configured.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Latest Firmware Version 0x18
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Latest Firmware Version 0x18
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1,3-5,10-13]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; Failed to retrieve update URL from storage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No internet resources available (BitPipe
Internal).
11: Error; APN not configured.
12: Error; Cannot initiate internet session.
13: Error; Cannot retrieve version.
14; Error; Sim card status is invalid.
3 7 MSG TYPE REPLY 1

www.briowireless.com Copyright 2016 Briowireless inc.

23
BitPipe Serial API V1

4 LEN Length, in bytes, of the latest firmware version. [0-8]

[5-...N-3] FW Firmware version. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

24
BitPipe Serial API V1

0x19 - Update Firmware

This operation is initiated by the Host. Upon reception of this message, the BitPipe will retrieve the
firmware specified by the version string supplied. After retrieval, the BitPipe will update itself.

The special target firmware version "latest" is always valid and points to the latest firmware version for
your BitPipe hardware.

This operation doesn't check if the target firmware version is already installed, and will not prevent
updating to the same actual version.

Note: The reception of a reply with a status code of SUCCESS indicates that the target firmware version
was verified, and that the update has started. It generally takes approximately 2-5 minutes to update
the firmware, depending on network availability and conditions.

Prerequisite: The APN must have been previously configured.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Update Firmware 0x19
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 LEN Length, in bytes, of the firmware version string to [0-8]
update to.
[5..N-3] FW The target firmware version. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Update Firmware 0x19
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success; Update has started. [0-5,10-13]
1: Error; Message malformed.
2: Error; Invalid parameter value.
www.briowireless.com Copyright 2016 Briowireless inc.
25
BitPipe Serial API V1

3: Info; BitPipe is busy. Try again later.

4: Error; Read/write access to storage failed.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No internet resources available (BitPipe
Internal).
11: Error; APN not configured.
12: Error; Cannot initiate internet session.
13: Error; Firmware version invalid or does not exist.
14; Error; Sim card status is invalid.
3 7 MSG TYPE REPLY 1
[4,5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

26
BitPipe Serial API V1

0x1A - Get Autonomous Mode Configuration

This operations allows retrieving the configuration used by the BitPipe when it is in Autonomous Mode.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Autonomous Mode Configuration 0x1A
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Autonomous Mode Configuration 0x1A
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1,10]
1: Error; Message malformed.
10: Error; Autonomous configuration is not set.
3 7 MSG TYPE REPLY 1
4 0 SECURE Specifies whether SSL/TLS is used at the transport [0,1]
layer:
0: TLS/SSL is not used.
1: TLS/SSL is used.
4 [1-7] Unused. 0
[5,6] KA IVAL MQTT Keep-Alive interval, in seconds. [0, 300-1200]
0 indicates that there is no keep-alive exchanged.
[7,8] PORT MQTT TCP Port. [1-65535]
9 HOST LEN MQTT host name length. [0-64]
10..N HOST MQTT host name. ASCII
N+1 USER LEN MQTT authentication user name length. [0-24]
N+2..M USER MQTT authentication user name. ASCII
M+1 PASSWORD MQTT authentication password length. [0-24]
LEN
www.briowireless.com Copyright 2016 Briowireless inc.
27
BitPipe Serial API V1

M+2..O PASSWORD MQTT authentication password. ASCII

O+1 GLOBAL PFX MQTT global topic prefix length. [0-12]
LEN
O+2..P GLOBAL PFX MQTT global topic prefix. ASCII
[P+1,P+2] CRC CRC [0x0000 -
0xFFFF]
P+3 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

28
BitPipe Serial API V1

0x1B - Set Autonomous Mode Configuration

This operations allows setting the configuration used by the BitPipe when it is in Autonomous Mode.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set Autonomous Mode Configuration 0x1B
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 0 SECURE Specifies whether SSL/TLS is used at the transport [0,1]
layer:
0: TLS/SSL is not used.
1: TLS/SSL is used.
4 [1-7] Unused. 0
[5,6] KA IVAL MQTT Keep-Alive interval, in seconds. [0, 300-1200]
0 indicates that there will not be any keep-alive
exchanged.
[7,8] PORT MQTT TCP Port. [1-65535]
9 HOST LEN MQTT host name length. [0-64]
10..N HOST MQTT host name. ASCII
N+1 USER LEN MQTT authentication user name length. [0-24]
N+2..M USER MQTT authentication user name. ASCII
M+1 PASSWORD MQTT authentication password length. [0-24]
LEN
M+2..O PASSWORD MQTT authentication password. ASCII
O+1 GLOBAL PFX MQTT global topic prefix length. [0-12]
LEN
O+2..P GLOBAL PFX MQTT global topic prefix. ASCII
[P+1,P+2] CRC CRC [0x0000 -
0xFFFF]
P+3 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set Autonomous Mode Configuration 0x1B
www.briowireless.com Copyright 2016 Briowireless inc.
29
BitPipe Serial API V1

2 ID Packet ID [0x00 - 0xFF]

3 [0 - 6] STATUS 0: Success [0-2,4]
1: Error; Message malformed.
2: Error; Invalid parameter value.
4: Error; Read/write access to storage failed.
3 7 MSG TYPE REPLY 1
[4,5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

30
BitPipe Serial API V1

3.3. Mobile Status and Information (0x20-0x2F)

0x20 - Power-On Radio

This operation powers on the Radio. There are two ways the Radio can be powered on, specified using
the power-on method parameter:

 by supplying power using the DC-to-DC converter;

 by supplying power directly, bypassing the DC-to-DC converter.

If desired, a built-in back-off mechanism is featured in the BitPipe to help reduce power consumption in
battery solutions. The back-off basically refuses the Power-On Radio request when too many recent
requests were successful. This effectively postpones the power-up of the Radio, contributing to battery
power saving. When enabled, the following built-in rules are applied:

1. You may issue a Power-On Radio request only after 5 minutes have passed since the last successful
Power-On Radio request;

2. You may not issue a Power-On Radio request more than 6 times in the last hour.

It is important to note that these rules apply to successful Power-On Radio requests; when a request
fails, that attempt is not accounted in the back-off mechanism. When the request is denied because of
the back-off mechanism, the status code of the reply will indicate this (see below).

A Radio Start Notification message will follow a successful Power-On Radio operation.

Note: If Radio is already powered on, the request is ignored and the reply will indicate that the Radio is
already powered on.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Power-On Radio 0x20
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 [0 - 6] PWR METHOD The power-on method: [0x19, 0x25]
0x19: Power-on using the DC-to-DC converter.
0x25: Power-on directly, bypassing the DC-to-DC
converter.
www.briowireless.com Copyright 2016 Briowireless inc.
31
BitPipe Serial API V1

4 7 BACK OFF The back-off mechanism: [0, 1]

ALGO 0: Back-off mechanism is not enabled (default);
1: Back-off mechanism is enabled;
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Power-On Radio 0x20
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0 ,1,2, 10-12]
1: Error; Message malformed.
2: Error; Invalid parameter value.
10: Error; Radio is already powered-on.
11: Error; Input voltage (VIN) is incompatible with
requested power-on method.
12: Error; Back-off mechanism is enabled (see
above) and this request is denied because it goes
against the back-off rules.
3 7 MSG TYPE REPLY 1
[4,5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

32
BitPipe Serial API V1

0x21 - Power-Off Radio

This operation powers off the Radio, whether it was powered via DC-to-DC converter or directly via
bypass. There are two ways the radio can be powered off, specified by the power-off method:

 Graceful: (Recommended) The radio disconnects from the mobile network, and shuts-down cleanly.

 Hard: The radio power is immediately cut. This method should be avoided, as it does not inform
mobile network of disconnection, which is not considered good practice.

Note: If Radio is already powered off, the request is ignored and the reply will indicate that the Radio is
already powered off.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Power-Off Radio 0x21
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 METHOD Power-Off method: [0, 1]
0: Graceful: Performs radio power-off procedure,
followed by power-off of the radio. This method
may fail if the radio is busy.
1: Hard: Power-off of the radio.
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Power-Off Radio 0x21
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4, 10]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later. (Graceful
method only)
4: Error; BitPipe wireless device command timeout.

www.briowireless.com Copyright 2016 Briowireless inc.

33
BitPipe Serial API V1

Usually due to transient state, e.g.: bad network

coverage.
10: Error; Radio is already powered-off.
3 7 MSG TYPE REPLY 1
[4,5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

34
BitPipe Serial API V1

0x22 - Radio Start Notify

The BitPipe notifies the host that the Radio has started successfully or has timed out waiting for the
Radio to boot up.
When a timeout has occurred (i.e.: notif reason = 1), you will need to issue a Power-Off Radio request
with the Hard method, and then eventually, retry a Power-On Radio request.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Radio Start Notification 0x22
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 NOTIF Reason for this notification: [0-2]
REASON 0: Radio is started and ready, as part of a previous
Power-On Radio operation.
1: Radio failed to start (A timeout occurred), as part
of a previous Power-On Radio operation.
2: Radio has unexpectedly rebooted, and is now
ready again.
5 SIM STATUS SIM card status: [0-3]
0: SIM access granted.
1: SIM access denied: PIN required.
2: SIM access denied: PUK required.
3: No SIM card detected.
[6, 7] CRC CRC [0x0000 -
0xFFFF]
8 EOF End-of-frame 0xCE

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

35
BitPipe Serial API V1

0x23 - Get Radio Status

Retrieves the actual status of the Radio of the BitPipe.

Note: The SIM card status be considered valid only when radio status is powered-on and ready.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Radio Status 0x23
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Radio Status 0x23
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1]
1: Error; Message malformed.
3 7 MSG TYPE REPLY 1
4 RADIO STATUS Radio status: [0-2]
0: Radio is powered on, but not yet ready.
1: Radio is powered on, and ready.
2: Radio is powered off.
5 SIM STATUS SIM card status: [0-3]
0: SIM access granted.
1: SIM access denied: PIN required.
2: SIM access denied: PUK required.
3: No SIM card detected.
[6,7] CRC CRC [0x0000 -
0xFFFF]
8 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

36
BitPipe Serial API V1

0x24 - Get IMEI

Allows retrieving the International Mobile Equipment Identity of the BitPipe.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get IMEI 0x24
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get IMEI 0x24
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1,3,4,5]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
3 7 MSG TYPE REPLY 1
[4-18] IMEI International Mobile Equipment Identity ASCII
[19, 20] CRC CRC [0x0000 -
0xFFFF]
21 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

37
BitPipe Serial API V1

0x25 - Get ICCID

Allows retrieving the Integrated Circuit Card Identifier (i.e.: SIM card ID) inserted in the BitPipe.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get ICCID 0x25
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get ICCID 0x25
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1,3,4,5,10]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No SIM card present.
3 7 MSG TYPE REPLY 1
[4-23] ICCID Integrated Circuit Card Identifier ASCII
[24, 25] CRC CRC [0x0000 -
0xFFFF]
26 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

38
BitPipe Serial API V1

0x26 - Get IMSI

Allows retrieving the International Mobile Subscriber Identity using the BitPipe.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get IMSI 0x26
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get IMSI 0x26
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 1, 3, 4, 5,
1: Error; Message malformed. 10-12]
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No SIM card present.
11: Error; SIM access denied: PIN required.
12: Error; SIM access denied: PUK required.
3 7 MSG TYPE REPLY 1
[4-18] IMSI International Mobile Subscriber Identifier ASCII
[19, 20] CRC CRC [0x0000 -
0xFFFF]
21 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

39
BitPipe Serial API V1

0x27 - Get Own Phone Number

Allows retrieving the phone number associated with the SIM card in the BitPipe (I.e.: The BitPipe phone
number).

Important Note: The phone number will only be returned if your mobile operator has provisioned this
information in the SIM card. This is outside the BitPipe control.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Own Phone Number 0x27
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Own Phone Number 0x27
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 1, 3, 4, 5,
1: Error; Message malformed. 10-12]
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No SIM card present.
11: Error; SIM access denied: PIN required.
12: Error; SIM access denied: PUK required.
3 7 MSG TYPE REPLY 1
4 LEN Length, in bytes, of the phone number. [0-25]
[5-...] OWN PHONE Phone Number ASCII
[N-2, N-1] CRC CRC [0x0000 -
www.briowireless.com Copyright 2016 Briowireless inc.
40
BitPipe Serial API V1

0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

41
BitPipe Serial API V1

0x28 - Get APN Configuration

Retrieves the configured APN from the BitPipe.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get APN Configuration 0x28
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get APN Configuration 0x28
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 1, 3, 4, 10]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; Failed to retrieve information from storage.
10: Error; APN not configured.
3 7 MSG TYPE REPLY 1
4 HOST LEN Length, in bytes of the APN hostname. [0-64]
5...X HOST APN hostname. ASCII
X+1 USER NAME Length, in bytes, of the APN user name, for [0-24]
LEN authentication.
X+2...Y USER NAME The APN user name. ASCII
Y+1 PASSWORD Length, in bytes, of the APN password, for [0-24]
LEN authentication.
Y+2...N-3 PASSWORD The APN password. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

42
BitPipe Serial API V1

0x29 - Set APN Configuration

Configures the Access Point Name information to use for bridging the cellular network with the IP
network.

This information is stored in non-volatile memory, and persisted across reboots.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set APN Configuration 0x29
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 HOST LEN Length, in bytes of the APN hostname. [0-64]
5...X HOST APN hostname. ASCII
X+1 USER NAME Length, in bytes, of the APN user name, for [0-24]
LEN authentication.
X+2...Y USER NAME The APN user name. ASCII
Y+1 PASSWORD Length, in bytes, of the APN password, for [0-24]
LEN authentication.
Y+2...N-3 PASSWORD The APN password. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set APN Configruation 0x29
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4]
1: Error; Message malformed.
2: Error; Invalid parameter value.
3: Info; BitPipe is busy. Try again later.
4: Error; Could Not Store APN Info in Non-Volatile
Memory.
3 7 MSG TYPE REPLY 1

www.briowireless.com Copyright 2016 Briowireless inc.

43
BitPipe Serial API V1

[4, 5] CRC CRC [0x0000 -

0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

44
BitPipe Serial API V1

0x2A - Set SIM Access Configuration

Allows configuring the SIM personal identification number, to allow the BitPipe the full use of the Radio
features.
This is only required when the SIM card is locked by a PIN.

Warning: Providing an invalid PIN three times in a row may lock your SIM card. If this happens, the SIM
PIN Unlock Key(SIM PUK) will be required.

This information is stored in non-volatile memory, and persisted across reboots.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set SIM Access Configuration 0x2A
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 HOST LEN Length, in bytes, of the SIM PIN or SIM PUK. [0-20]
5...N-3 SIM PIN SIM PIN - or - SIM PUK. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Set SIM Access Configuration 0x2A
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success; PIN was validated and stored. [0-4,10-13]
1: Error; Message malformed.
2: Error; Invalid parameter value.
3: Info; BitPipe is busy. Try again later.
4: Error; Failed to save information to storage.
10: Error; No SIM card present.
11: Error; Invalid SIM PIN, retry with another PIN.
12: Error; Invalid SIM PIN/PUK. PUK is now required.
13: Error; SIM status is OK: no PIN required.
3 7 MSG TYPE REPLY 1
www.briowireless.com Copyright 2016 Briowireless inc.
45
BitPipe Serial API V1

[4, 5] CRC CRC [0x0000 -

0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

46
BitPipe Serial API V1

0x2B - Get Mobile Connection Status

Retrieves whether or not the BitPipe has mobile connectivity, and is registered to the mobile network.
If it has mobile connectivity, it also retrieves the access technology used (e.g.: GSM, UTRAN, LTE, etc),
and the signal strength.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Mobile Connection Status 0x2B
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Mobile Connection Status 0x2B
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0,1,3,4,5,10-
1: Error; Message malformed. 12]
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No SIM card present.
11: Error; SIM access denied: PIN required. BitPipe
cannot connect to mobile network.
12: Error; SIM access denied: PUK required. BitPipe
cannot connect to mobile network.
3 7 MSG TYPE REPLY 1
4 CONNECTED Connected Indicator: [0-3]
IND 0: Not connected.
1: Camping on a mobile cell; not registered.
www.briowireless.com Copyright 2016 Briowireless inc.
47
BitPipe Serial API V1

2: Registered on home mobile network.

3: Registered on foreign mobile network.
5 LINK Access Technology: [0-3]
TECHNOLOGY 0: Unknown
1: 2G
2: 3G
3: LTE (4G)
[6, 7] NET LAC Network Location Area Code (16-bit value) [0x0000-
0xFFFF]
[8-11] NET CELL ID Network Cell Identifier (32-bit value) [0x00000000-
0xFFFFFFFF]
12 SIGNAL Signal Strength: 2G: [0-63, 255]
STRENGTH 255: Unknown 3G: [0-99, 255]
2G: 0-63, Subtract 110 from this value to have BCCH 4G: [0-96, 255]
value in dBm.
3G: 0-99, Subtract 124 from this value to have RSCP
value in dBm.
4G: 0-96, Subtract 140 from this value to have RSRP
value in dBm.
[13-16] NET MCC Mobile Country Code, ASCII, null-terminated. ASCII
[17-20] NET MNC Mobile Network Code, ASCII, null-terminated ASCII
[21,22] CRC CRC [0x0000 -
0xFFFF]
23 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

48
BitPipe Serial API V1

0x2C - Mobile Connection Status Change Notify

The BitPipe informs the host asynchronously that he connection to the mobile network has changed
(Connected Indicator only).
Information about the access technology and signal strength are also sent.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Mobile Connection Status Change Notify 0x2C
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 CONNECTED Connected Indicator: [0-3]
IND 0: Not connected.
1: Camping on a mobile cell; not registered.
2: Registered on home mobile network.
3: Registered on foreign mobile network.
5 LINK Access Technology: [0-3]
TECHNOLOGY 0: Unknown
1: 2G
2: 3G
3: LTE (4G)
[6, 7] NET LAC Network Location Area Code (16-bit value) [0x0000-
0xFFFF]
[8-11] NET CELL ID Network Cell Identifier (32-bit value) [0x00000000-
0xFFFFFFFF]
[12,13] CRC CRC [0x0000 -
0xFFFF]
14 EOF End-of-frame 0xCE

No Reply Defined

www.briowireless.com Copyright 2016 Briowireless inc.

49
BitPipe Serial API V1

0x2D - Get Mobile Date and Time

Retrieves the mobile network time and date.

The reliability of the time depends on the BitPipe being connected to the mobile network. The returned
time may be invalid until an initial connection to the mobile network is established.

Note: This depends on your mobile operator's support of NITZ time update. If your mobile operator
doesn't support NITZ, the returned time and date will be unreliable.

Request Message Direction

Host → Bitpipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Mobile Date and Time 0x2D
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD Get Mobile Date and Time 0x2D
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 1, 3, 4, 5]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
3 7 MSG TYPE REPLY 1
4 YEAR Current date year, minus 2000. [0 - 255]
Example: 16 = year 2016
5 MONTH Current date month, zero-based. [0 - 11]
Example: 1 = February.
www.briowireless.com Copyright 2016 Briowireless inc.
50
BitPipe Serial API V1

6 DAY Current date day, zero based. [0 - 30]

7 HOUR Current time, in 24 hours format. [0 - 23]
Example: 22 = 10PM
8 MINUTE Current time minute. [0 - 59]
9 SECOND Current time second. [0 - 59]
[10, 11] CRC CRC [0x0000 -
0xFFFF]
12 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

51
BitPipe Serial API V1

3.4. WiFi Status and Information (0x30-0x3F)

<WIP>

www.briowireless.com Copyright 2016 Briowireless inc.

52
BitPipe Serial API V1

3.5. LoRa Status and Information (0x40-0x4F)

<WIP>

www.briowireless.com Copyright 2016 Briowireless inc.

53
BitPipe Serial API V1

3.6. IP Socket (0x80-0x8F)

0x80 - TCP Initiate Connection

The host instructs the BitPipe that an outgoing TCP connection should be initiated to the specified host
and port.

It is possible to enable security at the transport layer using SSL/TLS protocols. The supported security
protocol versions depend on the actual BitPipe product.
Refer to product datasheet for more information on this topic.

There are a limited number of concurrent TCP connections supported. This also depends on the actual
BitPipe product.
Refer to product datasheet for more information on this topic.

The reply message will indicate if connection was successfully initiated through the status code, and if
not, it will describe the error condition.
When a connection is successfully initiated, the reply message will contain a TCP Connection Identifier
that will be used for subsequent TCP operations.

Following a successful connection initiation, the TCP Connection Established Notify or IP Connection
Close Notify message will be sent to the Host to indicate the end result of the actual connection.

When initiating a connection to an unreachable host, the IP Connection Close Notify message with
reason Host Unreachable will be sent after a timeout of 3 minutes. Closing the IP connection before this
timeout has expired is permitted, but internal resources will not be freed before the timeout expires.
Trying to re-initiate a TCP connection while the timeout hasn't expired will result in an error.
Starting with Firmware FW1.1, this timeout has been reduced to 60 seconds.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Initiate Connection 0x80
2 ID Packet ID [0x00 - 0xFF]
3 [0-6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 0 SECURE Security: [0, 1]
0: Non-Secure.
1: Secure (i.e.: SSL/TLS). Security level will be
negotiated between client and server.

www.briowireless.com Copyright 2016 Briowireless inc.

54
BitPipe Serial API V1

4 [1-5] FUTURE Unused 0

4 [6,7] CONN CLASS Connection Class requested: [0-3]
0: Class A - Send buffer of 1400 bytes - Only one
instance permitted.
1,2,3: Reserved for Future Use. Do not use.
5 HOST LEN Length, in bytes of the host to connect to (or IP [0-130]
address).
6..N-7 HOST Host name to connect to (or IP address, in decimal ASCII
dotted notation).
[N-6, N-5] PORT TCP port to connect to [0 - 65535]
[N-4, N-3] TCP Keep-alive interval, in seconds. [0-1800]
0: Disabled
Note: This option may not be available on all
versions of BitPipe.
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Initiate Connection 0x80
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Connection In Progress [0-5, 10-16]
1: Error; Message Malformed
2: Error; Invalid parameter value.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No TCP connection available for
connection class requested.
11: Error; APN not configured.
12: Error; SIM card status is invalid.
13: Error; Transport-layer security was requested,
but is unavailable.
14: Error; TCP keep-alive not supported.
15: Error; No link or bearer available.
16: Error; Generic.
3 7 MSG TYPE REPLY 1
4 TCP CONN TCP Connection Identifier. [0x00 - 0xFF]
ID
www.briowireless.com Copyright 2016 Briowireless inc.
55
BitPipe Serial API V1

[5, 6] CRC CRC [0x0000 -

0xFFFF]
7 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

56
BitPipe Serial API V1

0x81 - TCP Connection Established Notify

The BitPipe informs the Host that the TCP connection initiated previously has completed and was
successful.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Connection Established Notify 0x81
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 TCP CONN TCP Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

57
BitPipe Serial API V1

0x82 - TCP Write Append

Appends a byte array into the BitPipe send buffer.
If the byte array cannot be completely appended to the BitPipe send buffer (because it would overflow),
no byte from the array is appended.

The byte array is not immediately sent on the network. Because of the non-negligible overhead of
Internet protocols (TCP+IP+Ethernet headers), this mechanism allows you to append your data payload
into a buffer on the BitPipe. This way, you maximize your data payload .vs. Internet headers ratio.

Sending this request with a 0-length byte array will clear the BitPipe send buffer, erasing any previously
appended data.

Trigger the actual sending of the buffered data using the TCP Write Send operation.

Prerequisite: You need a valid TCP Connection Identifier, obtained by a successful TCP Initiate
Connection operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Write Append 0x82
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 TCP CONN TCP Connection Identifier. [0x00 - 0xFF]
ID
5 DATA LEN Length, in bytes, of the following data buffer. [0-253]
Sending a data buffer of 0 bytes will CLEAR the
BitPipe send buffer.
6...N-3 Data [0x00 - 0xFF]
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Write Append 0x82
www.briowireless.com Copyright 2016 Briowireless inc.
58
BitPipe Serial API V1

2 ID Packet ID [0x00 - 0xFF]

3 [0 - 6] STATUS 0: Success [0-2, 10-11]
1: Error; Message Malformed
2: Error; Invalid parameter value.
10: Error; Invalid TCP connection identifier
11: Error; Buffer full / cannot append
12: Error; Buffer already in use by SMS Message
Append / Send.
3 7 MSG TYPE REPLY 1
[4, 5] BUFFER Number of bytes in the send buffer of the BitPipe. [0x0000 -
SIZE 0xFFFF]
[6,7] BUFFER Size of the send buffer of the BitPipe. [0x0000 -
SIZE MAX This size is static and cannot be changed. It depends 0xFFFF]
on the version of the BitPipe.
[8, 9] CRC CRC [0x0000 -
0xFFFF]
10 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

59
BitPipe Serial API V1

0x83 - TCP Write Send

Instructs the BitPipe to transmit the contents of the BitPipe send buffer to the remote endpoint.

The reply to this request is sent when the whole send buffer has been transmitted to the remote
endpoint, or earlier, if an I/O error occurs.

Upon an I/O error, the connection may be closed. If this is the case, a IP Connection Close Notify
message will be emitted from the BitPipe.
If the connection remains valid, you may re-issue this operation again to complete transmission of the
send buffer.

Once the operation is successful, the BitPipe send buffer is cleared. You may continue appending data
using the TCP Write Append operation.

Note: The send buffer used by this operation is the same send buffer as the SMS Message Append /
Send operation. If SMS data is presently in the BitPipe send buffer, an error will be indicated in the
status of the reply message.

Prerequisites: (1) You need a valid TCP Connection Identifier, obtained by a successful TCP Initiate
Connection operation.
(2) You need to have appended data in the BitPipe send buffer using the TCP Write Append operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Write Send 0x83
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 TCP CONN TCP Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E

www.briowireless.com Copyright 2016 Briowireless inc.

60
BitPipe Serial API V1

1 CMD TCP Write Send 0x83

2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4, 10-12]
1: Error; Message malformed.
2: Error; Invalid Parameter Value
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid TCP connection identifier.
11: Error; Cannot write: Not ready to send. Retry
later.
12: Error; I/O error while writing.
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

61
BitPipe Serial API V1

0x84 - TCP Rx Notify

The BitPipe forwards incoming data sent from the endpoint to the Host.
This message is sent asynchronously from the BitPipe to the Host whenever data is received from the
remote endpoint.

The request is sent by the BitPipe and MUST be acknowledged by the Host (using the reply message).
The TCP data will be dropped by the BitPipe after the 3rd try without acknowledge.

Prerequisite: You need a valid TCP Connection Identifier, obtained by a successful TCP Initiate
Connection operation.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Rx Notify 0x84
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 TCP CONN TCP Connection Identifier. [0x00 - 0xFF]
ID
5 LEN Length, in bytes, of the following data buffer. [0x00 - 0xFF]
[6..N-3] DATA Received data. [0x00 - 0xFF]
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD TCP Rx Notify 0x84
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

62
BitPipe Serial API V1

0x85 - HTTP Initiate Connection

The host instructs the BitPipe that an outgoing HTTP connection should be initiated to the specified host
and port.

It is possible to enable security at the transport layer using SSL/TLS protocols (i.e.: HTTPS).

There are a limited number of concurrent HTTP connections supported. This also depends on the actual
BitPipe product.
Refer to product datasheet for more information on this topic.

The reply message will indicate if connection was successfully initiated through the status code, and if
not, it will describe the error condition.
When a connection is successfully initiated, the reply message will contain an HTTP Connection
Identifier that will be used for subsequent HTTP operations.

Following a successful connection initiation, the HTTP POST Write Ready Notify, HTTP Rx Notify, or IP
Connection Close Notify message will be sent to the Host to indicate the HTTP protocol state.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP Initiate Connection 0x85
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 0 SECURE Security: [0, 1]
0: Non-Secure; uses HTTP.
1: Secure (i.e.: SSL/TLS); uses HTTPS. Security level
will be negotiated between client and server.
4 [1,2] HTTP Method: [0-2]
0: GET
1: POST
2: HEAD
4 [3-7] FUTURE Unused 0
5 HOST LEN Length, in bytes of the host to connect to (or IP [0-96*]12
address).
6..K HOST Host name to connect to (or IP address, in decimal ASCII
dotted notation).

www.briowireless.com Copyright 2016 Briowireless inc.

63
BitPipe Serial API V1

[K+1, K+2] PORT HTTP port to connect to. Optional. [0 - 65535]

0 indicates to use standard port (HTTP=80,
HTTPS=443).
K+3 PATH+Q LEN Length of the path and query string. [0-160]12
[K+4..L] PATH+Q Path and query part of the HTTP request. The path ASCII
MUST start with a forward slash.
Example:
"/some/path/to/resource?var1=value1&var2=value
2"
L+1 ADD HDRS LEN Length of the additional headers string. BP2G-E: [0-
127]2
Others: [0-
254]2
[L+2, N-7] ADD HDRS Additional headers string. Allows to include custom ASCII
HTTP headers to the request. The format is:
<Header name> ':' *space* <Header value>
Multiple headers can be specified, by separating
each with the following litteral string: "\0d\0a" (not
"\r\n").
Example: "Authorization: Basic
Y3VyaW91czpzbmVhaw==\0d\0aContent-Type:
multipart/form-data"
[N-6..N-3] POST CONT If HTTP method is POST, this is the HTTP content [0 - 2³²-1]
LEN length of the data that will be transmitted in the
request.
Should be set to 0 when using HTTP method GET or
HEAD.
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE
1
: The limits are flexible. A total of 256 bytes is allocated and available for the URL.
2
: The entire message payload MUST not be over the internal BitPipe communications buffer size of 256
bytes.

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP Initiate Connection 0x85
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Connection In Progress [0-5, 10-14]
1: Error; Message Malformed
2: Error; Invalid parameter value.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
www.briowireless.com Copyright 2016 Briowireless inc.
64
BitPipe Serial API V1

Usually due to transient state, e.g.: bad network

coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No more HTTP connections supported.
11: Error; APN not configured.
12: Error; SIM card status is invalid.
13: Error; No link or bearer available.
14: Error; Generic.
3 7 MSG TYPE REPLY 1
4 HTTP CONN HTTP Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

65
BitPipe Serial API V1

0x86 - HTTP POST Write Ready Notify

The BitPipe informs the Host that the HTTP POST request is ready and waiting for the POST data.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Note: This message is only sent to the Host when an HTTP Initiate Connection was requested using
HTTP method 'POST'.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP POST Write Ready Notify 0x86
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 HTTP CONN HTTP Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

66
BitPipe Serial API V1

0x87 - HTTP POST Write

This operation allows the Host to transfer the HTTP POST request payload to the remote server
endpoint.

The Write Operation parameter allows to perform 3 different but related operations:

 Write (append) to buffer: Allows to transfer the data from the Host and cache it on the BitPipe in a
temporary buffer. This buffer size is 1400 bytes;

 Write (append) to buffer and send: Same as above, but also writes it on the HTTP connection to the
server, flushing all the buffer;

 Write (append) to buffer, send and mark as complete: Same as above, but also informs the server
that the entire POST request data is complete and can be processed;

When sending to the HTTP server, always wait for the HTTP POST Write Ready Notify message before
attempting another send.

After the entire HTTP POST data is transferred ("Write to buffer, send and mark as complete" Write
Option), the HTTP server may send you back data, or close the connection.

Upon an I/O error, the connection may be closed. If this is the case, a IP Connection Close Notify
message will be emitted from the BitPipe.

Prerequisites: (1) You need a valid HTTP Connection Identifier, obtained by a successful HTTP Initiate
Connection operation, with method HTTP POST.
(2) You need to have been notified via HTTP POST Write Ready Notify message that the connection is in
the correct state.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP POST Write 0x87
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 HTTP CONN HTTP Connection Identifier. [0x00 - 0xFF]
ID
5 OPER Write Operation: [0-3]
www.briowireless.com Copyright 2016 Briowireless inc.
67
BitPipe Serial API V1

0: Write (append) to buffer;

1: Write (append) to buffer and send;
2: Write (append) to buffer, send and mark as
complete;
6 DATA CHUNK Length, in bytes of the HTTP POST request data [0-255]
LEN chunk.
[7..N-3] DATA CHUNK Data chunk of HTTP POST request. BINARY
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP POST Write 0x87
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4, 10-13]
1: Error; Message malformed.
2: Error; Invalid Parameter Value
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid HTTP connection identifier.
11: Error; Cannot append to write buffer: Internal
buffer is full.
12: Error; Cannot write: Not ready to send. Retry
later.
13: Error; I/O error while writing.
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

68
BitPipe Serial API V1

0x88 - HTTP Rx Notify

The BitPipe forwards incoming data sent from the server endpoint to the Host.
This message is sent asynchronously from the BitPipe to the Host whenever data is received from the
HTTP connection.

The request is sent by the BitPipe and MUST be acknowledged by the Host (using the reply message).
The HTTP data will be dropped by the BitPipe after the 3rd try without acknowledge.

Prerequisite: You need a valid HTTP Connection Identifier, obtained by a successful HTTP Initiate
Connection operation.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP Rx Notify 0x88
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 HTTP CONN HTTP Connection Identifier. [0x00 - 0xFF]
ID
5 LEN Length, in bytes, of the following data buffer. [0x00 - 0xFF]
[6..N-3] DATA Received data. [0x00 - 0xFF]
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD HTTP Rx Notify 0x88
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

69
BitPipe Serial API V1

0x8E - IP Connection Close

Instructs the BitPipe to close the TCP or HTTP connection.
Any unsent data in the BitPipe send buffer is discarded, and any data waiting to be read from the
remote endpoint is flushed.

After a successful IP Connection Close, the Internet Connection Identifier cannot be subsequently used
with another IP SOCKET command.

Prerequisite: You need a valid (TCP/HTTP) Connection Identifier, obtained by a successful TCP Initiate
Connection or HTTP Initiate Connection operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD IP Connection Close 0x8E
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 INET CONN Internet Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD IP Connection Close 0x8E
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 1, 3, 4, 10]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid Internet connection identifier
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
www.briowireless.com Copyright 2016 Briowireless inc.
70
BitPipe Serial API V1

0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

71
BitPipe Serial API V1

0x8F - IP Connection Close Notify

Sent from the BitPipe to inform the Host that the remote endpoint has closed the connection, or that an
error occurred, which triggered the closing of this connection.

The INET Connection Identifier cannot be subsequently used with another TCP or HTTP command.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD IP Connection Close Notify 0x8F
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 INET CONN Internet Connection Identifier. [0x00 - 0xFF]
ID
5 REASON Reason Code: [0-5, 254]
0: Remote Internet endpoint has closed the
connection.
1: Error; SIM deactivated; Bad APN information; Not
registered on the network.
2: Error; Host not found.
3: Error; Host unreachable.
4: Error; Host has reset connection (invalid port/port
not listening).
5: Error; Resource not found (HTTP 404).
254: Error; Generic socket error.
[6, 7] CRC CRC [0x0000 -
0xFFFF]
8 EOF End-of-frame 0xCE

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

72
BitPipe Serial API V1

3.7. MQTT Client API (0x90-0x9F)

The implementation of MQTT in the BitPipe is based on version 3.1.1.

For more information about the MQTT protocol, please refer to http://docs.oasis-
open.org/mqtt/mqtt/v3.1.1/csprd01/mqtt-v3.1.1-csprd01.html

0x90 - MQTT Initiate Connection

The host instructs the BitPipe that an outgoing MQTT connection should be initiated to the MQTT
broker, at the specified host and port.

It is possible to enable security at the transport layer using SSL/TLS protocols.

There are a limited number of concurrent MQTT connections supported. This also depends on the actual
BitPipe product.
Refer to product datasheet for more information on this topic.

The reply message will indicate if connection was successfully initiated through the status code, and if
not, it will describe the error condition.
When a connection is successfully initiated, the reply message will contain an MQTT Connection
Identifier that will be used for subsequent MQTT operations.

Following a successful connection initiation, the MQTT Connection Established Notify or MQTT
Disconnect Notify message will be sent to the Host to indicate the MQTT protocol state.

When initiating a connection to an unreachable host, the IP Connection Close Notify message with
reason Host Unreachable will be sent after a timeout of 3 minutes. Closing the IP connection before this
timeout has expired is permitted, but internal resources will not be freed before the timeout expires.
Trying to re-initiate a TCP connection while the timeout hasn't expired will result in an error.
Starting with Firmware FW1.1, this timeout has been reduced to 60 seconds.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Initiate Connection 0x90
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 0 SECURE Security: [0, 1]
0: Non-Secure.
www.briowireless.com Copyright 2016 Briowireless inc.
73
BitPipe Serial API V1

1: Secure (i.e.: SSL/TLS). Security level will be

negotiated between client and server.
4 1 CLEAN Clean Session Flag: [0, 1]
SESSION 0: False; a persistent session. The broker will store
all subscriptions and all missed messages
1: True; a non-persistent session. The broker will
purge all information from a previous persistent
session.
4 [3-7] FUTURE Unused 0
5 HOST LEN Length, in bytes of the host to connect to (or IP [0-96]
address).
[6..K] HOST Host name to connect to (or IP address, in decimal ASCII
dotted notation).
[K+1, K+2] PORT MQTT port to connect to. Optional. [0 - 65535]
0 indicates to use standard port (TCP port 1883, or
8883 when using TLS/SSL).
K+3 CLIENT ID LEN Length of the client identifier. Cannot be omitted. [1-20]
[K+4..L] CLIENT ID The client identifier string. ASCII
L+1 USER LEN Length of the user name. [0-24]
[L+2..M] USER User Name for authentication. ASCII
[M+1] PASS LEN Length of the password. [0-24]
[M+2..N- PASS Password ASCII
4]
N-3 KA INTERVAL Keep-Alive Interval, in 5 seconds increments. [0, 60 - 240]
Examples:
0: No keep-alive.
60: 300 seconds interval (5 minutes).
...
240: 1200 seconds interval (20 minutes).
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Initiate Connection 0x90
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Connection In Progress [0-5, 10-14]
1: Error; Message Malformed
2: Error; Invalid parameter value.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
www.briowireless.com Copyright 2016 Briowireless inc.
74
BitPipe Serial API V1

Usually due to transient state, e.g.: bad network

coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; No more MQTT connections supported.
11: Error; APN not configured.
12: Error; SIM card status is invalid.
13: Error; Not registered to mobile network.
14: Error; TCP Initiate Connection Failed.
3 7 MSG TYPE REPLY 1
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

75
BitPipe Serial API V1

0x91 - MQTT Connection Established Notify

The BitPipe informs the Host that the MQTT connection initiated previously has completed and was
successful.

This notification means that the network connection was established successfully and that the MQTT
CONNECT phase was successful.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Connection Established Notify 0x91
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

76
BitPipe Serial API V1

0x92 - MQTT Subscribe Topic

This operation allows the Host to subscribe to up to three topics simultaneously on the MQTT broker.

To subscribe to only one topic, you should set Topic 2 Len and Topic 3 Len value to 0. To subscribe to
more than 3 topics, you will need to use this operation more than once.

Upon an I/O error, the connection may be closed. If this is the case, a MQTT Connection Close Notify
message will be emitted from the BitPipe.

Prerequisite: You need a valid MQTT Connection Identifier, obtained by a successful MQTT Initiate
Connection operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Subscribe Topic 0x92
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
5 [0, 1] SUBS QOS 1 QOS requested for subscription of topic #1: [0, 1]
0: QOS 0;
1: QOS 1;
2,3: Reserved.
5 [2, 3] SUBS QOS 2 QOS requested for subscription of topic #2: [0, 1]
0: QOS 0;
1: QOS 1;
2,3: Reserved.
5 [4, 5] SUBS QOS 3 QOS requested for subscription of topic #3: [0, 1]
0: QOS 0;
1: QOS 1;
2,3: Reserved.
6 TOPIC 1 LEN Length of the topic #1 to subscribe to. [0-255]1
[7..K] TOPIC 1 The topic #1 to subscribe to. ASCII
K+1 TOPIC 2 LEN Length of the topic #2 to subscribe to. [0-255]1
[K+2..L] TOPIC 2 The topic #2 to subscribe to. ASCII
L+1 TOPIC 3 LEN Length of the topic #3 to subscribe to. [0-255]1
www.briowireless.com Copyright 2016 Briowireless inc.
77
BitPipe Serial API V1

[L+2..N-3] TOPIC 3 The topic #3 to subscribe to. ASCII

[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE
1
: The entire message payload MUST not be over the internal BitPipe communications buffer size of 256
bytes.

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Subscribe Topic 0x92
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4, 10-13]
1: Error; Message malformed.
2: Error; Invalid Parameter Value
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid MQTT connection identifier.
11: Error; Cannot subscribe: Underlying TCP
connection is not ready.
12: Error; I/O error while writing to the underlying
TCP connection.
13: MQTT protocol error; Subscription not
successful.
3 7 MSG TYPE REPLY 1
4 SUBSCRIPTION Bitfield indicating the subscription status of each [0x00-0x07]
STATUS topic. A value of 0 indicates a failure; a value of 1
indicates success.
Bit 0: Subscription status of topic #1;
Bit 1: Subscription status of topic #2;
Bit 2: Subscription status of topic #3.
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

78
BitPipe Serial API V1

0x93 - MQTT UnSubscribe Topic

This operation allows the Host to unsubscribe from up to three topics simultaneously on the MQTT
broker.

To unsubscribe from only one topic, you should set Topic 2 Len and Topic 3 Len value to 0. To
unsubscribe from more than 3 topics, you will need to use this operation more than once.

Upon an I/O error, the connection may be closed. If this is the case, a MQTT Connection Close Notify
message will be emitted from the BitPipe.

Prerequisite: You need a valid MQTT Connection Identifier, obtained by a successful MQTT Initiate
Connection operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT UnSubscribe Topic 0x93
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
5 TOPIC 1 LEN Length of the topic #1 to unsubscribe from. [0-255]1
[6..K] TOPIC 1 The topic #1 to unsubscribe from. ASCII
K+1 TOPIC 2 LEN Length of the topic #2 to unsubscribe from. [0-255]1
[K+2..L] TOPIC 2 The topic #2 to unsubscribe from. ASCII
L+1 TOPIC 3 LEN Length of the topic #3 to unsubscribe from. [0-255]1
[L+2..N-3] TOPIC 3 The topic #3 to unsubscribe from. ASCII
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE
1
: The entire message payload MUST not be over the internal BitPipe communications buffer size of 256
bytes.

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E

www.briowireless.com Copyright 2016 Briowireless inc.

79
BitPipe Serial API V1

1 CMD MQTT UnSubscribe Topic 0x93

2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4, 10-13]
1: Error; Message malformed.
2: Error; Invalid Parameter Value
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid MQTT connection identifier.
11: Error; Cannot unsubscribe: Underlying TCP
connection is not ready.
12: Error; I/O error while writing to the underlying
TCP connection.
13: MQTT protocol error; Unsubscribe not
successful.
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

80
BitPipe Serial API V1

0x94 - MQTT Publish

This operation allows the Host to publish one message with payload and a given QOS to the MQTT
broker.

To send large payloads, it is possible to chain multiple MQTT Publish operations, by controlling the Send
Indicator parameter. When doing this, do not repeat the topic in subsequent operations, as a non-zero
topic length is interpreted as a new MQTT Publication (i..e: Clears previous message payload).

The published message topic length plus payload length cannot be over 1000 bytes.

The message parameters QOS and Retain Indicator are taken into account on the last message, i.e.:
when the Send Indicator is set.

Upon an I/O error, the connection may be closed. If this is the case, a MQTT Connection Close Notify
message will be emitted from the BitPipe.

Prerequisite: You need a valid MQTT Connection Identifier, obtained by a successful MQTT Initiate
Connection operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Publish 0x94
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
5 [0,1] QOS Message QOS: [0, 1]
0: QOS 0;
1: QOS 1;
2,3: Reserved.
5 2 RETAIN IND Retain Indicator: [0, 1]
0: Message is not retained;
1: Message is retained.
5 [3-6] NOT USED Not used. 0
5 7 SEND IND Send Indicator: [0, 1]
0: Message payload not complete; do not send now;
1: Message payload complete; send MQTT Publish
www.briowireless.com Copyright 2016 Briowireless inc.
81
BitPipe Serial API V1

message.
6 TOPIC LEN Length of the topic. [0-128]
0: Indicates a continuation of the previous MQTT
Publish operation.
Non-zero: Indicates the start of a new MQTT Publish
operation.
7.. TOPIC The topic of the MQTT Publish message. ASCII
MSG CHUNK Length, in bytes, of the message payload chunk. [0-255]1
LEN
[..N-3] MSG CHUNK Message payload chunk. BINARY
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE
1
: The entire message payload MUST not be over the internal BitPipe communications buffer size of 256
bytes.

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Publish 0x94
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-4, 10-14]
1: Error; Message malformed.
2: Error; Invalid Parameter Value
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid MQTT connection identifier.
11: Error; Cannot publish: Underlying TCP
connection is not ready.
12: Error; I/O error while writing to the underlying
TCP connection.
13: MQTT protocol error; Publish not successful.
14: Error; Cannot append to write buffer: Internal
buffer is full.
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

82
BitPipe Serial API V1

0x95 - MQTT Publication Rx Notify

This message is sent asynchronously from the BitPipe to the Host upon reception of a new MQTT
message from the broker.

The request is sent by the BitPipe and MUST be acknowledged by the Host (using the reply message).
The MQTT message data will be dropped by the BitPipe after the 3rd try without acknowledge.

Several instances of this operation can be chained by the BitPipe when the message payload is too long.
Check the Complete Indicator to see if more message data payload will be incoming. The message topic
is only sent on the first instance

Note: Since the topic is sent in the first instance of this message, it MUST fit within the Host maximum
payload size. If the topic length is greater than the Host maximum payload size, it will be truncated.

Prerequisite: You need a valid MQTT Connection Identifier, obtained by a successful MQTT Initiate
Connection operation.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Publication Rx Notify 0x95
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
5 [0, 1] QOS Message QOS: [0, 1]
0: QOS 0;
1: QOS 1;
2,3: Reserved.
5 2 RETAIN IND Retain Indicator: [0, 1]
0: Message is not retained;
1: Message is retained.
5 [3-6] UNUSED Not used. 0
5 7 COMPLETE Message payload complete indicator: [0, 1]
IND 0: Message not yet complete (more message chunk
are coming);
1: Message is complete.
6 TOPIC LEN Length, in bytes, of the message topic: [0-255]
www.briowireless.com Copyright 2016 Briowireless inc.
83
BitPipe Serial API V1

0: indicates a continuation of the previous MQTT Depends on

Publication Rx Notify. the
Non-zero: indicates a new message reception. Host
maximum
payload size.
[7..M] TOPIC The message topic. ASCII
M+1 MSG CHUNK Length, in bytes, of the following message chunk [0x00 - 0xFF]
LEN data.
[M+2..N- MSG CHUNK Received message data payload. BINARY
3] DATA
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Publication Rx Notify 0x95
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

84
BitPipe Serial API V1

0x9E - MQTT Disconnect

Instructs the BitPipe to end the MQTT session with the broker, and close the underlying TCP connection.

After a successful MQTT Disconnect, the MQTT Connection Identifier cannot be subsequently used with
another MQTT operation.

Prerequisite: You need a valid MQTT Connection Identifier, obtained by a successful TCP Initiate
Connection or HTTP Initiate Connection operation.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Disconnect 0x9E
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
[5, 6] CRC CRC [0x0000 -
0xFFFF]
7 EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Disconnect 0x9E
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0, 1, 3, 4, 10]
1: Error; Message malformed.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
10: Error; Invalid MQTT connection identifier
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE
www.briowireless.com Copyright 2016 Briowireless inc.
85
BitPipe Serial API V1

0x9F - MQTT Disconnect Notify

Sent from the BitPipe to inform the Host that the remote endpoint has closed the connection, or that an
error occurred, which triggered the closing of this connection.

The MQTT Connection Identifier cannot be subsequently used with another MQTT operation.

The reception of this notification does not need to be acknowledged, so no reply message is defined.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD MQTT Disconnect Notify 0x9F
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 MQTT CONN MQTT Connection Identifier. [0x00 - 0xFF]
ID
5 REASON Reason Code: [0, 1, 254]
0: MQTT broker has closed the connection.
1: MQTT CONNECT has failed.
...
254: Error; Generic socket error.
[6, 7] CRC CRC [0x0000 -
0xFFFF]
8 EOF End-of-frame 0xCE

No Reply Message Defined

www.briowireless.com Copyright 2016 Briowireless inc.

86
BitPipe Serial API V1

3.8. SMS (0xD0-0xD7)

0xD0 - SMS Setup Transmission

Informs the BitPipe of an upcoming SMS message transmission. This message configures the send
options and the SMS message recipient (Phone Number).

If options and a recipient have been previously configured and don't need to be changed, this operation
can be skipped. However, this information is stored in volatile memory; it doesn't carry across reboots.

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Setup Transmission 0xD0
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 0 CONCAT Concatenated SMS (i.e.: Large SMS) support: [0,1]
SUPPORT 0: Disabled;
1: Enabled.
4 [1,2] ENCODING SMS Encoding used: [0-2]
0: 7 bits, ASCII - (Max 160 characters / SMS);
1: 8 bits, binary - (Max 140 characters / SMS);
2: 16 bits, UCS2 - (Max 70 characters / SMS);
4 [3-7] RESERVED Reserved for future use 0
5 Phone number Number of digits in the phone number. [0-25]
length
[6 - ...] Phone number Phone number of SMS ASCII (digits)
The format is international, without any leading '+'
character.
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Setup Transmission 0xD0
2 ID Packet ID [0x00 - 0xFF]
www.briowireless.com Copyright 2016 Briowireless inc.
87
BitPipe Serial API V1

3 [0 - 6] STATUS 0: Success [0-2]

1: Error; Message malformed.
2: Error; Invalid parameter value.
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

88
BitPipe Serial API V1

0xD1 - SMS Message Append / Send

This message is used by the Host to append an SMS message part to the BitPipe send buffer. If this
message is the last part of the SMS message, the Send Indicator field should have a value of 1 to trigger
the actual send of the SMS message on the mobile network.

Sending this request with a 0-length message part, along with Send Indicator value of 0, will clear the
BitPipe send buffer, erasing any previously appended SMS data.
Sending this request with a 0-length message part, along with Send Indicator value of 1, will re-send the
last message.

When appending with 16-bit encoding, make sure to transfer the characters in big endian.
When appending with 7-bit encoding, transfer the characters in 8-bit binary: The 7-bit encoding will take
place in the BitPipe. Hence, ASCII can be transferred directly.

Note: The send buffer used by this operation is the same send buffer as the TCP Write Append
operation. If TCP data is presently in the BitPipe send buffer, an error will be indicated in the status of
the reply message

Request Message Direction

Host → BitPipe

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Message Append / Send 0xD1
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 Send Indicator Specifies if the SMS message should be sent after [0, 1]
this data:
0: More data will follow.
1: No more data will follow. Send the message.
5 Msg Length Length of the following SMS message part. [0x00-0xFF]
[6 - ...] Message SMS message part (8-bit binary) [0x00-0xFF]
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
www.briowireless.com Copyright 2016 Briowireless inc.
89
BitPipe Serial API V1

1 CMD SMS Message Append / Send 0xD1

2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success [0-5, 10-15]
1: Error; Message malformed.
2: Error; Invalid parameter value.
3: Info; BitPipe is busy. Try again later.
4: Error; BitPipe wireless device command timeout.
Usually due to transient state, e.g.: bad network
coverage.
5: Info; BitPipe wireless device is offline. Cannot
complete request.
10: Error; Network error (Invalid phone number,
etc).
11: Error; No SIM card present, or SIM card status
invalid.
12: Error; No link or bearer available.
13: Error; Buffer already in use by TCP Write
Append.
14: Error; SMS message full (Only with
concatenation support disabled).
15: Error; Buffer full / cannot append (Only with
concatenation support enabled).
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

90
BitPipe Serial API V1

0xD4 - SMS Message Reception Notify

Sent from the BitPipe to inform the Host that an SMS message has been received.

The request is sent by the BitPipe and MUST be acknowledged by the Host (using the reply message).
The SMS information will be dropped by the BitPipe after the 3rd try without acknowledge.

The Host should also expect following SMS Message Part Notify message(s) following this operation.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Message Reception Notify 0xD4
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 ENCODING SMS Encoding used: [0-2]
0: 7 bits;
1: 8 bits;
2: 16 bits;
Note: 7-bit characters are expanded to 8-bit
characters during reception in the BitPipe.
5 YEAR Date year, minus 2000, at which the service center [0 - 255]
received the SMS.
Example: 16 = year 2016
6 MONTH Current date month, zero-based, at which the [0 - 11]
service center received the SMS.
Example: 1 = February.
7 DAY Date day, zero based, at which the service center [0 - 30]
received the SMS.
8 HOUR Time, in 24 hours format, at which the service [0 - 23]
center received the SMS.
Example: 22 = 10PM
9 MINUTE Time minute, at which the service center received [0 - 59]
the SMS.
10 SECOND Time second, at which the service center received [0 - 59]
the SMS.
11 [0 - 6] TZ INFO Timezone information, at which the service center [0-127]
received the SMS.
Specifies the number of quarter-hours added or
www.briowireless.com Copyright 2016 Briowireless inc.
91
BitPipe Serial API V1

removed from GMT.

11 7 TZ INFO Specifies whether the number of TZ INFO minutes is [0,1]
negative (1) or positive (0).
12 MSISDN LEN Length, in bytes(digits), of the following phone [0-25]
number.
[13..N-3] MSISDN Phone number(MSISDN) of SMS sender. ASCII (digits)
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Message Reception Notify 0xD4
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
3 7 MSG TYPE REPLY 1
[4, 5] CRC CRC [0x0000 -
0xFFFF]
6 EOF End-of-frame 0xCE

www.briowireless.com Copyright 2016 Briowireless inc.

92
BitPipe Serial API V1

0xD5 - SMS Message Part Notify

Sent from the BitPipe to the Host to transfer the SMS message part. This message follows the SMS
Message Reception Notify operation.
The Last part indicator field specifies if the message is complete or if more message parts will follow.

The data must be interpreted as indicated by the SMS encoding specified in the SMS Message
Reception Notify message. Please note that 7-bit characters are transformed into 8-bit characters
during reception, so there is no transformation necessary when 7-bit encoding is used by the sender. For
16-bit encoding, the bytes need to be swapped because they will have been transmitted in big endian.

The request is sent by the BitPipe and MUST be acknowledged by the Host (using the reply message).
The SMS message data will be dropped by the BitPipe after the 3rd try without acknowledge.

Request Message Direction

BitPipe → Host

Request
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Message Part Notify 0xD5
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS Unused 0
3 7 MSG TYPE REQUEST 0
4 Last Part Ind Last part indicator: [0, 1]
0: More data will follow.
1: No more data will follow.
5 SMS data Length, in bytes, of the following SMS data. [0x00 - 0xFF]
length
[6 - ...] SMS data SMS message data (8-bit binary). [0x00 - 0xFF]
[N-2, N-1] CRC CRC [0x0000 -
0xFFFF]
N EOF End-of-frame 0xCE

Reply
Byte # Bit # Name Description Value
0 SOF Start-of-frame 0x7E
1 CMD SMS Message Part Notify 0xD5
2 ID Packet ID [0x00 - 0xFF]
3 [0 - 6] STATUS 0: Success 0
3 7 MSG TYPE REPLY 1

www.briowireless.com Copyright 2016 Briowireless inc.

93
BitPipe Serial API V1

[4, 5] CRC CRC [0x0000 -

0xFFFF]
6 EOF End-of-frame 0xCE

Align center

www.briowireless.com Copyright 2016 Briowireless inc.

94