BLE Services
The Bluetooth GATT (Generic Attribute Profile) governs communication between BLE devices via a dedicated connection.
For GATT documentation, see https://www.bluetooth.org:
- 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 ZentriOS-S 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). However with the ZENTRI-DUAL product, the Zentri BLE device can also act as Central.
A BLE Peripheral can connect to only one Central. A Zentri BLE device Central is restricted to connect to only one Peripheral.
The diagram shows a mobile device, running an app, connecting as a Central to a Zentri Device, acting as a Peripheral.
General BLE issues are discussed in Introduction to BLE below.
Depending on the ZentriOS-S product, ZentriOS-S provides the following services:
- Zentri Streaming Service - provides remote command mode and data streaming
- HID Service - provide HID keyboard and HID consumer support
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 ZentriOS-S 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 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.
Note: To use a ZentriOS-S device as a Central, update to the ZENTRI-DUAL product. You can also use the ZENTRI-TRUCONNECT product, for backward compatibility with earlier TruConnect apps.
The implementation of these procedural steps depends on the Central platform.
Zentri Streaming Service
If the device ZentriOS-S product includes the Zentri Streaming Service feature, the following capabilities are available:
- remote command mode: the Central can connect to a ZentriOS-S module via BLE, and place it in remote command mode. This allows a Central to use the full range of control and monitoring available via ZentriOS-S.
- streaming: The Central can place the ZentriOS-S module in STREAM mode, and send and receive streams of data to and from the device.
Note: The rbmode command is provided with the ZENTRI-DUAL product. You can also use the ZENTRI-TRUCONNECT product, for backward compatibility with earlier TruConnect apps.
The feature is offered with a number of products and provides additional commands and variables for managing streaming and the remote command interface:
Commands
Variables
- bu i - initial bus mode
- bu s c - bus serial control
- bu s s - bus breakout sequence
- sy r e - remote enabled
Products
Zentri Streaming Service Characteristics
Zentri Streaming Service defines a GATT profile consisting of a Zentri Streaming Service and three Characteristics, Rx, Tx and Mode.
A ZentriOS-S device advertises the Zentri Streaming Service on start up according to the advertising variables:
A ZentriOS-S device can be identified by its SERVICE_TRUCONNECT_UUID
. To interact with a ZentriOS-S device as a Peripheral, use the Zentri Streaming Service.
The Rx (receive) and Tx (transmit) Characteristics are named from the point of view of the Peripheral ZentriOS-S 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, read from the Tx Characteristic.
For a ZentriOS-S device, the serial interface Service and Characteristics are as follows:
Service or Characteristic | Abbr | UUID | Values |
---|---|---|---|
SERVICE_TRUCONNECT_UUID | 175f8f23-a570-49bd-9627-815a6a27de2a | - | |
CHARACTERISTIC_TRUCONNECT_PERIPHERAL_RX_UUID | Rx | 1cce1ea8-bd34-4813-a00a-c76e028fadcb | Strings sent to ZentriOS-S serial interface |
CHARACTERISTIC_TRUCONNECT_PERIPHERAL_TX_UUID | Tx | cacc07ff-ffff-4c48-8fae-a9ef71b75e26 | Strings received from ZentriOS-S serial interface |
CHARACTERISTIC_TRUCONNECT_MODE_UUID | Mode | 20b9794f-da1a-4d14-8014-a0fb9cefb2f7 | 1 (STREAM_MODE)2 (LOCAL_COMMAND_MODE)3 (REMOTE_COMMAND_MODE) |
The Abbr column in the table defines abbreviations used in this documentation only.
Zentri Streaming Service Procedures
This section describes connection and communication procedures required to connect to a ZentriOS-S device offering the Zentri Streaming Service.
Specific implementations depend on the Central. Sample iOS procedures, for an Apple mobile device, are documented in the Communicating via BLE application note as described below.
Scan for a ZentriOS-S Device
Scan for the ZentriOS-S Peripheral using the procedure required by the Central platform.
See Scanning for a ZentriOS-S Device.
Accessing and Subscribing to Characteristics of the Zentri Streaming Service
After obtaining the Peripheral's advertising data by scanning, discover the Peripheral's Characteristics and subscribe to the appropriate Characteristics by registering for notification when the value of a Characteristic changes.
Reading from a ZentriOS-S Device Serial Interface
To read from the Peripheral's serial interface, subscribe to the Tx characteristic as described above.
On each notification, a local variable can be set to the value of the Tx characteristic.
Example: Communicating via BLE, iOS, Reading from a ZentriOS-S Device Serial Interface
Writing to a ZentriOS-S Device Serial Interface
To write to the device serial interface, write to the Rx characteristic.
Example: Communicating via BLE, iOS, Writing to a ZentriOS-S Device Serial Interface
Switching to Remote Command Mode or Stream Mode
Only the following command mode transitions are permitted via BLE:
STREAM_MODE
->REMOTE_COMMAND_MODE
REMOTE_COMMAND_MODE
->STREAM_MODE
Note: The ZentriOS-S device must be in STREAM_MODE
before another BLE device can switch it into REMOTE_COMMAND_MODE
.
See Serial Interface for details of serial interface mode operation.
Switch the mode via BLE by writing to the Mode characteristic.
Example: Communicating via BLE, iOS, Switching to Remote Command Mode or Stream Mode
Sending a ZentriOS-S Command
First switch to REMOTE_COMMAND_MODE
as described above.
Then, write the command to the ZentriOS-S Rx characteristic. See Writing to a ZentriOS-S Device Serial Interface above.
Up to 20 bytes can be written to Rx in a single write. Repeated writes are required for longer strings.
Read the response back as described in Reading from a ZentriOS-S Device Serial Interface.
All commands must be terminated by CR-LF (\r\n), adding two bytes to the length.
It may be more convenient to read responses to ZentriOS-S commands if echo is turned off and response headers are turned on.
See Serial Interface for details of response format.
Example: Communicating via BLE, iOS, Sending a ZentriOS-S Command
Sending and Receiving Data in Stream Mode
First switch to STREAM_MODE
as described above.
To stream data to the ZentriOS-S device, write the data to the Rx characteristic. See Writing to a ZentriOS-S Device Serial Interface above.
You can verify that the data is received by connecting a ZentriOS-S terminal to the device. See Getting Started. The data appears on the terminal display.
To stream data to the ZentriOS-S device, read the data from the Tx characteristic. See Reading from a ZentriOS-S Device Serial Interface above.
You can verify that the data is received by connecting a ZentriOS-S terminal to the device. Data sent from the central appears directly on the terminal display.
You can send data by connecting a ZentriOS-S terminal to the device. Type data into the terminal. The data is sent directly to the central.
HID Service
BLE devices can implement the HID (Human Interface Device) service. This enables your device to act as an input device for a host, for example as a keyboard, or as a remote control to play/pause music.
HID controls are organized as usage pages. Each page defines a group of related controls.
For full documentation of usage pages, see: Universal Serial Bus (USB), HID Usage Tables at www.usb.org.
For ZentriOS-S we offer products covering the following usage pages:
- ZENTRI-HIDCN - HID with Consumer page support. See HID Usage Tables, page 75
- ZENTRI-HIDKB - HID with Keyboard page support. See HID Usage Tables, page 53
With both products, the ZentriOS-S device and the mobile or other device connect by BLE pairing.
Typically the mobile device supports BLE pairing and there is no need to create an app for this purpose.
When the devices are in communication, you can use the ZentriOS-S hid command to send codes for keystrokes or button presses from the ZentriOS-S device to the mobile device.
For example, the following command sends key strokes corresponding to typing abc012
on a keyboard:
> hid 1f1e270605040000
The 04
code corresponds to 'a' and the 1f
code corresponds to '2'.
To indicate a final key up, send the null code:
> hid 0000000000000000
For more details, see hid command documentation.