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:

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:

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.

Peripherals offer Services, which consist of Characteristics. Services and Characteristics are distinguished by universally unique identifiers, or UUIDs.

Peripherals advertise, by broadcasting some services and characteristics. This allows them to be discovered by Centrals.

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.

Connecting to a Peripheral

The general procedure for using a Central to interact with a Peripheral is as follows:

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:

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

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 CharacteristicAbbrUUIDValues
SERVICE_TRUCONNECT_UUID175f8f23-a570-49bd-9627-815a6a27de2a-
CHARACTERISTIC_TRUCONNECT_PERIPHERAL_RX_UUIDRx1cce1ea8-bd34-4813-a00a-c76e028fadcbStrings sent to ZentriOS-S serial interface
CHARACTERISTIC_TRUCONNECT_PERIPHERAL_TX_UUIDTxcacc07ff-ffff-4c48-8fae-a9ef71b75e26Strings received from ZentriOS-S serial interface
CHARACTERISTIC_TRUCONNECT_MODE_UUIDMode20b9794f-da1a-4d14-8014-a0fb9cefb2f71 (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.

Example: Communicating via BLE, iOS, Accessing and Subscribing to Characteristics of the Zentri Streaming Service

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:

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:

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.