BCX0X Serial API Documentation

For Beacons to Firmare Version 0.6.3

Supported Models

  • BC202 USB Dongle
  • BC103 OEM Board

Table of Contents

  1. Serial Packet Format
  2. Data Types
  3. Serial Configuration
  4. Settings String Configuration
    1. Settings String Format
    2. Updating Settings Command
    3. Confirming Settings
    4. Settings Values
  5. Commands
  6. Events
  7. Examples

Serial Packet Format

Commands are sent from host to USB beacon over a serial connection. For each command, the beacon provides a corresponding response. Each field in the response packet arrives over serial with most significant byte first (big-endian), for easier readability.

Command

Byte Length (bytes) Description
0 1 Message type
1 1 Payload length
2 1 Class ID (0xBC)
3 1 Command ID
4-n 0 to 255 Payload

Response

Byte Length (bytes) Description
0 1 Message type
1 1 Payload length
2 1 Class ID (0xBC)
3 1 Command ID
4-n 0 to 255 Response data or
Response code

back to top

Message Type Field

Value ID
Command or Response 0x00
Event 0x80

back to top

Response Code Field

Command Success:

ID Meaning Description
0x00 Success Command succeeded

Command Errors:

ID Meaning Description
0x01 Busy Previous command needs to complete or be canceled before sending next command.
0x02 Advertising Disabled Send command only when advertising enabled.
0x03 Buffer Overflow Buffer overflowed.
0x04 Remote Hung Up Command not available when no device is connected.
0x05 Gatt Write Failed to write response to BLE data request.
0x06 Invalid Parameter Parameter in command payload is invalid.
0x07 Not Supported Command not supported in this firmware version.
0x08 No Pending Changes Send begin setting update command before end settings update command.

Event Errors:

ID Meaning Description
0x84 Unrecognized Command Command was not recognized.
0x85 Permission Denied Permission has been disabled or rejected for format device.

back to top

Data Types

Type Description Example (Human readable) Example (Hex)
int8 Signed integer stored in one byte 2’s complement form -42 0xD6
uint8 Unsigned integer stored in 1 byte 42 0x2A
uint16 Unsigned integer stored in 2 bytes 1701 0xa5 0x06
uint32 Unsigned integer stored in 4 bytes 1000000 0x40 0x42 0x0f 0x00
uint8array Byte array “Hello” 0x68 0x65 0x6c 0x6c 0x6f

back to top

Serial Configuration

Setting Value
Handshake RequestToSend
BaudRate 115200 baud (BC202)
9600 baud (BC103)
DataBits 8
StopBits One
Parity None

back to top

Settings String Configuration

Settings String Format

A settings string is a line of hex that contain all of a beacon’s settings to be applied. Settings strings start with the total length in bytes and the number of settings. The last setting passed must be the beacon version as this signifies the end of a settings string.

Field (bytes) Total length in bytes (2) Number of Settings (2) Setting 1 Type (2) Setting 1 Length (2) Setting 1 Value (variable) Setting n Type (2) Setting n Length (2) Setting n Value (variable) Last Setting Type (2) Last Setting Length (2) Last Setting Value (variable)
Example 0056 000A 0000 (BEACON_LOUDNESS) 0001 0F 0005 (PROXIMITY_UUID) 0010 61687109-905F-4436-91F8-E602F514C96D 0007 (VERSION) 0001 03

Setting Values

Settings

Setting Setting Value Length in Bytes
BEACON_LOUDNESS 0000 0001
TARGET_SPEED 0001 0002
MEASURED_POWER 0002 0001
BEACON_MAJOR 0003 0002
BEACON_MINOR 0004 0002
PROXIMITY_UUID 0005 0010
PRIVACY_DURATION 0006 0002
VERSION 0007 0001
BEACON_MODE 0008 0001
EDDY_NID 0009 000A
EDDY_IID 000A 0006
EDDY_URL 000B variable
CONNECTABLE 000C 0001
SECURITY_TYPE 000E 0001
KEEPALIVE_PROX_UUID 0018 0010
KEEPALIVE_MAJOR 0019 0002
KEEPALIVE_MINOR 001A 0002
LOCALNAME_SHORT 001B variable

Beacon Modes

Type Value
SECURE_MODE 1
IBEACON_MODE 2
IBEACON_PLUS_SECURE_MODE 3
EDDY_UID_MODE 4
EDDY_URL_MODE 5
NEWBORN_MODE 6
IBEACON_PLUS_UID_MODE 7

Security Types

Type Value Description
NONE 00 no authentication, un-secure settings string
TWOKEY 01 lfsr authentication, secure settings string
PASSCODE 02 8 byte passcode authentication, passcode for secure settings string keys
TRIPLEKEY 03 16 bytes encrypted authentication, secure settings string

Supported Loudness Values

Name Decimal Value
Whisper 0
Mutter 2
Talk 4
Shout 8
Scream 15 (0x0F)

Supported Target Speed Values

Name Decimal Value
Sprint 20 (0x14)

Eddystone-URLs

URL Scheme Prefix

The URL Scheme Prefix byte defines the identifier scheme, an optional prefix and how the remainder of the URL is encoded.

Decimal Hex Expansion
0 0x00 http://www.
1 0x01 https://www.
2 0x02 http://
3 0x03 https://
Top Level Domain Encoding
Decimal Hex Expansion
0 0x00 .com/
1 0x01 .org/
2 0x02 .edu/
3 0x03 .net/
4 0x04 .info/
5 0x05 .biz/
6 0x06 .gov/
7 0x07 .com
8 0x08 .org
9 0x09 .edu
10 0x0a .net
11 0x0b .info
12 0x0c .biz
13 0x0d .gov
Example
Field Value
Length 88
Number of Settings 6
Loudness Talk
Target Speed Sprint
Measured Power -41
Mode Eddystone-URL
URL https://www.bluecats.com
Version 3

Pass the URL scheme prefix as the first value in the url settings. Example string:
00580006000000010800010002001400020001D70008000105000B000A01626C756563617473000007000103

See the Eddystone-URL specification for more information.

Commands

Reset

Reboot or reboot to DFU mode. This will not affect the beacons persistent store.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x00 Command ID
4 uint8 0 : to reboot
1 : to reboot to DFU mode.

Important: Command will execute immediately with no response packet.

back to top

Meow

Send to discover beacons when enumerating serial ports. Beacon will excitedly respond with a hardy ASCII “Meow!”

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x01 Command ID

Table: Response

Byte Value Description
0 0x00 type: command
1 0x05 Payload length
2 0xBC Message ID
3 0x01 Command ID
4 - 8 uint8array Result: 0x4D656F7721 “Meow!”

back to top

Read Beacon Loudness

Read beacon loudness. Value can range from 0x00 to 0x0F.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x05 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x05 Command ID
4 uint8 Value range: 0 - 15.
Example response: 0x0F

back to top

Read Beacon Mode

Read beacon mode. Value range 0x01 to 0x03.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x07 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x07 Command ID
4 uint8 Beacon Mode. Value range: 1-7.
Example Value: 0x01 - Secure Mode

back to top

Read Proximity UUID

Read the beacon Proximity UUID.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x09 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x10 Payload length
2 0xBC Message ID
3 0x09 Command ID
4-19 uint8 Example response: 0x61687109905F443691F8E602F514C96D

back to top

Read Major Value

Read the iBeacon major value from the beacon.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x0B Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x02 Payload length
2 0xBC Message ID
3 0x0B Command ID
4-5 uint16 Example Value: 0x0005

back to top

Read Minor Value

Read the iBeacon Minor value.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x0D Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x02 Payload length
2 0xBC Message ID
3 0x0D Command ID
4-5 uint16 Example result: 0x0012

back to top

Read Advertising Enabled

Read if advertising is enabled.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x13 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x13 Command ID
4 uint8 Example value: 0x00 (No)

Values:

  1. 0x00 - No
  2. 0x01 - Yes

back to top

Write Advertising Enabled

Enables advertising on the beacon.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x14 Command ID
4 uint8 Example value: 0x01 (Yes)

Values:

  1. 0x00 - No
  2. 0x01 - Yes

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x14 Command ID
4 uint8 Response code

back to top

Read Target Speed

Read the beacon target speed.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x15 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x02 Payload length
2 0xBC Message ID
3 0x15 Command ID
4-5 uint8 Example value: 0x0014

Note: Current firmware only supports the Sprint Target Speed.

back to top

Send Data Blocks

Transmits a raw payload of data blocks over BLE advertising mode. Data block advertising can be canceled vie the Cancel Data Blocks command.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 to 0xFF Payload length
2 0xBC Message ID
3 0x17 Command ID
4-n uint8array Payload to be sent

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x17 Command ID
4 uint8 Response code

back to top

Respond to BLE Data Request

Send response, over a BLE connection, to the data request from a mobile device.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 to 0xFF Payload length
2 0xBC Message ID
3 0x18 Command ID
4-n uint8array Value: A custom payload user defined data bytes

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x18 Command ID
4 uint8 Response code

back to top

Cancel Data Blocks

Cancel transmission of data blocks over BLE advertising mode, initiated via the Send Data Blocks command.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x19 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x19 Command ID
4 uint8 Response code

back to top

Read Crash Report

Read the status of a crash report. Crash report is saved to persistent store after a crash. Crash report will be reset to a value of 0x00 upon the next beacon reset/shutdown.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x1A Command ID
4 uint8 Value: Version to write

Table: Response

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x1A Command ID
4 uint8 Response code

back to top

Read Events Enabled

This command returns true if events have been enabled. Events are asynchronous messages that can come from the beacon at any time. These messages pass on info like if the beacon initiated a Bluetooth BLE connection, system failures, data requests from a mobile device, etc. It is recommended that host applications enable events as soon as they have confirmation of being attached to the USB beacon. This setting is non-persistent, so must be enabled each time the beacon is powered and attached to host.

Values:

  1. 0x00 - No (startup default)
  2. 0x01 - Yes

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x1B Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x1B Command ID
4 uint8 Response code

back to top

Write Events Enabled

This command enables the receiving of event notifications from the beacon. It is recommended to enable events immediately after the beacon has successfully been connected and attached to a host application.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x1C Command ID
4 uint8 Example value: 0x01 (Yes)

Values:

  1. 0x01 - Yes
  2. 0x00 - No

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x1C Command ID
4 uint8 Response code

back to top

Read Privacy Duration

Reads the beacon’s privacy duration in minutes.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x1F Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x02 Payload length
2 0xBC Message ID
3 0x1F Command ID
4 uint8 Example value: 0x05A8 (1448)

back to top

Write Settings String

Writes the beacon’s new settings.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x0A - 0xFB Payload length
2 0xBC Message ID
3 0x25 Command ID
4-255 Setting String Example value: 0x00440003000000010F0005001061687109905F443691F8E602F514C96D0007000103

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x25 Command ID
4 uint8 Response code

back to top

Read Status String

Reads the beacon’s status string.

Table: Command

Byte Value Description
0 0x00 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x26 Command ID

Table: Response

Byte Value Description
0 0x00 Message type
1 0x10 Payload length
2 0xBC Message ID
3 0x26 Command ID
4+ Start of Status String Fields  
Status String Fields
Length Field Example
6 MAC Address 0780D0765858
2 Model Number 202A
2 Firmware Version 0062
1 Settings Version 06
1 Measured Power B5
1 Power Level 64
1+ Footer BCBCBC

back to top

Prepare Future Settings

Writes the beacon’s future settings

Table: Command

Byte Value Description
0 0x00 Message type
1 0x0A - 0xFB Payload length
2 0xBC Message ID
3 0x27 Command ID
4-255   Example value: 0x0056000A000000010F0005001061687109905F443691F8E602F514C96D0007000103

Table: Response

Byte Value Description
0 0x00 Message type
1 0x01 Payload length
2 0xBC Message ID
3 0x27 Command ID
4 uint8 Response code

back to top

##Events

Note: Events are not enabled by default. You must write events enabled before receiving event notifications.

BLE Connect

A BLE mobile device connected to the beacon.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x01 Event ID

back to top

BLE Disconnect

A BLE mobile device disconnected from the beacon.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x02 Event ID

back to top

BLE Authentication Succeeded

A BLE mobile device authenticated with the beacon. Mobile devices with BlueCats SDK enabled apps receive the ability to authenticate with a beacon. Once authenticated, the app can perform various tasks over BLE connection like settings updates, firmware updates, etc.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x04 Event ID

back to top

BLE Authentication Failed

A BLE mobile device failed to authenticate with the beacon.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x05 Event ID

back to top

Error

An error occurred in beacon.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC or 0x00 Message ID
3 0x06 Event ID
4 uint8 Response code
5 0x01 constant value

Message ID Values:

  1. 0xBC - BlueCats error
  2. 0x00 - Underlying hardware manufacturer specific error

back to top

Settings Saved

Event indicates a successful settings commit to the beacon’s persistent store via a call to the End Settings Update command. Also triggered when beacon is updated over BLE connection.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x07 Event ID

back to top

BLE Data Requested

A BLE data request has been received. Data requests can be initiated by remote BLE devices running an app that utilizes the BlueCats SDK. The remote device is able to send a BLE data request with user defined message data to the beacon. The request and message are forwarded on to the host with this event. The host can then parse the message to determine the nature of the data being requested by the remote device and send its response with the Respond to BLE DataRequest command. If the data was successfully received by the remote device, a BLE Data Indicated event will be received.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 to 0xFF Payload length
2 0xBC Message ID
3 0x08 Event ID
4-n uint8array Value: A user defined payload of bytes

back to top

Data Blocks Sent

Event fired upon completion of data block transmission over BLE advertising mode using the Send Data Blocks command.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x09 Event ID

back to top

BLE Data Indicated

Event occurs as part of a data request transaction indicating that the remote BLE device received it’s requested data.

Table: Event

Byte Value Description
0 0x80 Message type
1 0x00 Payload length
2 0xBC Message ID
3 0x0A Event ID

back to top

Examples

Change the Proximity UUID

Sets the Beacon’s Proximity UUID to AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA

  COMMAND                 HOST (hex)         BEACON (hex)       RESPONSE / EVENT
 ----------------------- ------------------ ------------------ -----------------------
| WriteEventsEnabled    | 0001BC1C01       |                  |                       |
|                       |                  | 0001BC1C00       | Success               |
|                       |                  |                  |                       |
| WriteSettingsString   | 001DBC25001D0003 |                  |                       |
|   * proximity uuid    | 00050010AAAAAAAA |                  |                       |
|                       | AAAAAAAAAAAAAAAA |                  |                       |
|                       | AAAAAAAA00070001 |                  |                       |
|                       | 02               |                  |                       |
|                       |                  | 0001BC2500       | Success               |
|                       |                  |                  |                       |
|                       |                  | 8000BC07         | SettingsSaved Event   |
|                       |                  |                  |                       |
| ReadProximityUUID     | 0000BC09         |                  |                       |
|                       |                  | AAAAAAAAAAAAAAAA | ProximityUUID:        |
|                       |                  | AAAAAAAAAAAAAAAA | AAAAAAAA-AAAA-AAAA-   |
|                       |                  | AAAAAAAA         | AAAA-AAAAAAAAAAAA     |
 ----------------------- ------------------ ------------------ -----------------------

Change Proximity UUID Settings Packet
--------------------------------------
header   len  cnt  prox len  value                            ver  len  value
001DBC25 001D 0003 0005 0010 AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA 0007 0001 02

back to top

Change the Loudness and Measured Power

Set Bluetooth radio’s transmit Loudness and Measured Power to highest level. For eachpower level (loudness), there is a respective measured power setting that must also be set.

  COMMAND                 HOST (hex)         BEACON (hex)       RESPONSE / EVENT
 ----------------------- ------------------ ------------------ -----------------------
| WriteEventsEnabled    | 0001BC1C01       |                  |                       |
|                       |                  | 0001BC1C00       | Success               |
|                       |                  |                  |                       |
| WriteSettingsString   | 0013BC2500130003 |                  |                       |
|   * loudness          | 000000010F000200 |                  |                       |
|   * measured power    | 01C10007000102   |                  |                       |
|                       |                  | 0001BC2500       | Success               |
|                       |                  |                  |                       |
|                       |                  | 8000BC07         | SettingsSaved Event   |
|                       |                  |                  |                       |
| ReadBeaconLoudness    | 0000BC05         |                  |                       |
|                       |                  | 0001BC050F       | BeaconLoudness:       |
|                       |                  |                  | 0x0F = "Scream"       |
 ----------------------- ------------------ ------------------ -----------------------

Loudness Levels                Measured Power @ One Meter
-----------------              --------------------------
 Whisper 0x00          ->       Whisper (-89 dBm) 0xA7
  Mutter 0x02          ->        Mutter (-85 dBm) 0xAB
    Talk 0x04          ->          Talk (-82 dBm) 0xAE
   Shout 0x08          ->         Shout (-75 dBm) 0xB5
  Scream 0x0F          ->        Scream (-63 dBm) 0xC1

Change Loudness and Measured Power Settings Packet
---------------------------------------------------
header   len  cnt  loud len  va  mpwr len va ver  len  va
0013BC25 0013 0003 0000 0001 0F 0002 0001 C1 0007 0001 02  

back to top