BLE Services
The Bluetooth GATT (Generic Attribute Profile) governs communication between BLE devices via a dedicated connection.
For GATT documentation, see Bluetooth Core Standard version 4, Vol 3, Parts F and G.
When two BLE devices interact, one acts as a Peripheral, offering GATT Services, and the other acts as a Central, consuming Services. Services are defined in the GATT as collections of characteristics and relationships to other services.
The BGX device typically acts as the Peripheral (GATT server) and a BLE mobile device such as a phone or pad acts as the Central (GATT client). The BGX device can also act as Central.
A BLE Peripheral can connect to only one Central. A BGX device Central is restricted to connect to only one Peripheral.
General BLE issues are discussed in Introduction to BLE below.
The BGX device offers a Streaming Service - provides remote command mode and data streaming.
Introduction to BLE
This section introduces a few terms necessary for later discussion. These terms have a specific meaning in the BLE context.
BLE devices operate in two broad classifications: Central and Peripheral.
- Central - A Central typically uses the information served by a Peripheral, like a client in the client/server communication model.
- Peripheral - A Peripheral typically supplies data required by other devices, like a server in the client/server communication model.
Peripherals offer Services, which consist of Characteristics. Services and Characteristics are distinguished by universally unique identifiers, or UUIDs.
- Service - A collection of data
- Characteristic - An item of data within a service
- UUID - the universal unique identifier of a service or characteristic. All BGX UUIDs are 128 bit (16 octets).
Peripherals advertise, by broadcasting some services and characteristics. This allows them to be discovered by Centrals.
- Advertising - Broadcasting by a Peripheral of a subset of the available Services and Characteristics. See BLE Advertising
- Discovery - Scanning by a Central for advertising Peripherals and identifying them by their advertised Services and Characteristics.
After discovering a Peripheral of interest, a Central requests a connection to the Peripheral. After connecting, the Central can discover the Peripheral's Services, and within those Services the Peripheral's Characteristics. The Central can read the value of Characteristics, subscribe to the value of Characteristics, and in some cases write the value of the Characteristic back to the Peripheral.
To subscribe to a Characteristic, the BLE mechanism is to register for notification when that Characteristic is changed, and provide a callback to be called on each notification. Typically the callback reads the Characteristic value and takes any action required.
- Subscription - Registering for notification when the value of a Characteristic is changed.
- Notification - An event such as a change to the value of a Characteristic registered for notification.
- Callback - A function or procedure invoked in response to an event, such as a notification.
Connecting to a Peripheral
The general procedure for using a Central to interact with a Peripheral is as follows:
- Start the Central.
- Scan for Peripheral's advertising services.
- After finding the desired Peripheral, stop scanning.
- Request a connection to the Peripheral.
- Discover its Services.
- After finding a desired Service, discover its Characteristics
- For desired Characteristics, perform the desired read, subscribe and write operations.
The implementation of these procedural steps depends on the Central platform.
Xpress Streaming Service
In a BGX device, the following capabilities are available:
- remote command mode: the Central can connect to a BGX device via BLE, and place it in remote command mode. This allows a Central to use the full range of control and monitoring available.
- streaming: The Central can place the BGX module in STREAM mode , and send and receive streams of data to and from the device.
Additional commands and variables for managing streaming and the remote command interface are listed below:
Commands
Variables
- bu i - initial bus mode
- bu s c - bus serial control
- bu s s - bus breakout sequence
- sy r e - remote enabled
Xpress Streaming Service Characteristics
Xpress Streaming Service defines a GATT profile consisting of a Xpress Streaming Service and three Characteristics, Rx , Tx and Mode .
A BGX device advertises the Xpress Streaming Service on start up according to the advertising variables:
A BGX device can be identified by its Xpress Streaming Service UUID. To interact with a BGX device as a Peripheral, use the Xpress Streaming Service.
Xpress Streaming Service UUID:
331a36f5-2459-45ea-9d95-6142f0c4b307
The Rx (receive) and Tx (transmit) Characteristics are named from the point of view of the Peripheral BGX device.
To send a string to be received by the Peripheral serial interface, write to the Rx Characteristic.
To read a string transmitted from the Peripheral serial interface, enable Notifications or Indications from the Tx Characteristic then wait for subsequent Notification or Indication Events to occur.
The BGX Xpress Streaming Service provides the following characteristics:
Characteristic | UUID | Length | Properties |
---|---|---|---|
Peripheral Receive ( Rx ) |
a9da6040-0823-4995-94ec-9ce41ca28833
|
1-250 bytes |
Write, Write without response, Notify (
1.2.2045.0
and later)
|
Peripheral Transmit ( Tx ) |
a73e9a10-628f-4494-a099-12efaf72258f
|
1-250 bytes |
Notify, Indicate, Write without Response (
1.2.2045.0
and later)
|
Stream Mode ( Mode ) |
75a9f022-af03-4e41-b4bc-9de90a47d50b
|
1-18 bytes | Read, Write, Write without response, Notify, Indicate |
Stream Mode Settings
Mode Value | Description |
---|---|
1
|
Streaming Mode |
2
|
Local Command Mode |
3
|
Remote Command Mode |
Xpress Streaming Service Flow Control
Legacy Flow Control
In firmware versions prior to
1.2.2045.0
, flow control is implemented by
sending Xpress Streaming Service data via Notifications (Peripheral-to-Central)
and Write operations (Central-to-Peripheral). Notification and Write operations
require the receiving device to send an acknowledgement before another operation
can occur. This allows the receiving device to delay its acknowledgement until
it has freed up enough internal buffer space to hold the next incoming packet
of data. This approach greatly reduces throughput, however, because a
Notification or Write can happen at most once every two connection intervals.
Fast-Ack Flow Control
Starting with firmware version
1.2.2045.0
, a Streaming Control Channel is
available that is used to transmit Streaming Control Messages between two
connected devices. These Control Messages contain buffer status information that
can be used to ensure that no Xpress Streaming Service data is dropped, allowing
the devices to achieve high throughput while still guaranteeing data integrity.
Flow control implemented over the Streaming Control Channel is referred to as
Fast-Ack Flow Control, or just Fast-Ack.
Streaming Control Messages are sent from the Peripheral to the Central via Notifications on the Rx characteristic.
Streaming Control Messages are sent from the Central to the Peripheral via Write without Response operations on the Tx characteristic.
Streaming Control Messages are three bytes long and take the following format:
Byte 0 | Bytes 1 - 2 |
---|---|
Opcode | Data |
The Data field is Little Endian (i.e., Byte 1 is the LSB and Byte 2 is the MSB).
The table below describes the Streaming Control Opcodes available.
Streaming Control Opcode | Description |
---|---|
0x00: Initial Buffer Size | The Data field represents the total number of bytes the device can hold in its internal buffer. |
0x01: Buffer Bytes Freed | The Data field represents the number of bytes that have been freed from the device's internal buffers. |
Xpress Streaming Service flow control is implemented on the Central device by the following procedure:
- After initially connecting, the Central enables Notifications on the Rx characteristic.
- The Peripheral responds by transmitting the number of bytes it can buffer internally via an Initial Buffer Size Control Message. The Central must save this value. This value will be referred to as Transmit Byte Available (TBA) for the remainder of this procedure.
- The Central then transmits the number of bytes it can buffer internally via an Initial Buffer Size Control Message.
- At this point the devices are ready to exchange Xpress Streaming Service data. The Central may send up to TBA bytes to the Peripheral without receiving any kind of response from the Peripheral. Data should be transmitted via Write without Response operations. Each time it transmits data to the Peripheral, the Central must subtract the number of bytes transmitted from the TBA.
- As the Peripheral frees up internal buffer space, it will periodically send Buffer Bytes Freed Control Messages to the Central. Each time the Central receives a Buffer Bytes Freed Control Message, it must add the number of bytes freed to the TBA.
- As the Central receives and consumes data from the Peripheral, it should transmit Buffer Bytes Freed Control Messages to the Peripheral. The determination of when buffer space has been freed is application-specific and is left up to the application developer.
Backwards Compatibility
Firmware version
1.2.2045.0
and later can still operate in Legacy Flow Control
mode, if desired. In order to operate in legacy flow control mode, the Central
should
not
enable Notifications on the
Rx
characteristric and should use
Write operations to transmit data on the
Rx
characteristric.
Mode Characteristic
The Mode characteristic is used by a central device to put a peripheral BGX into Streaming or Remote Command Mode. A central device (BGX or mobile device) can write the Mode characteristic of a peripheral BGX, but a peripheral BGX cannot write the Mode characteristic of a central device.
To put a peripheral into Streaming Mode, write a single byte value of 0x01 to the Mode characteristic.
To put a peripheral BGX into Remote Command Mode:
- If the peripheral BGX remote command interface is not password-protected ( sy r p = none ), write a single byte value of 0x03 to the Mode characteristic.
- If the peripheral BGX remote command interface is password-protected, perform a single write operation to the Mode characteristic, where the first byte is 0x03, and the subsequent bytes are the null-terminated password.
Example
If the password is 123456, write the following to the Mode characteristic:
0x03 0x31 0x32 0x33 0x34 0x35 0x36 0x00
Notes:
- The Mode characteristic is 18 bytes long to accomodate the longest possible password (16 bytes plus null-terminator).
- If Remote Command Mode is password-protected and the central writes an incorrect password, the BGX will send ATT_ERROR_STREAMING_SERVICE_INVALID_PASSWORD (0x4FE). This response code will be received if the Central used a normal Write Request to write to the Mode characteristic. If the Central used a Write Without Response Request, it will not receive a response. It is recommended to use normal Write Requests so that the response can be verified.
- There must be at least one second between a failed write attempt to the Mode characteristic and the next write attempt. If a write attempt is made before 1 second has elapsed since the previous failed write attempt, the BGX will return ATT_ERROR_STREAMING_SERVICE_PASSWORD_ATTEMPT_TIMING (0x4FD).
Using Xpress Streaming Service From Another Device
Silicon Labs provides libraries and frameworks for using the BGX Xpress Streaming Service from Android or iOS mobile devices.
For more information, see BGXpress Host Software