BLE Connections
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
The TruConnect device acts as the Peripheral (GATT server) and a BLE mobile device such as a phone or pad acts as the Central (GATT client).
Once Central can connect to many Peripherals, but each Peripheral may connect to only one Central.
The Central can connect to a TruConnect module via BLE, and place it in remote command mode. This allows the full range of control and monitoring available via TruConnect.
You can also place the TruConnect module in STREAM mode, and send and receive streams of data to and from the device.
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 TruConnect 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.
The implementation of these procedural steps depends on the Central platform.
TruConnect Service and Characteristics
TruConnect defines a GATT profile consisting of a TruConnect Service and three TruConnect Characteristics, Rx, Tx and Mode.
ACKme TruConnect devices advertise the TruConnect Service on start up according to the advertising variables bl v h d, bl v h i, bl v l d & bl v l i.
An ACKme TruConnect device can be identified by its SERVICE_TRUCONNECT_UUID
. To interact with a TruConnect device as a Peripheral, use the TruConnect serial interface service.
The Rx (receive) and Tx (transmit) Characteristics are named from the point of view of the Peripheral TruConnect 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 an ACKme TruConnect 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 TruConnect serial interface |
CHARACTERISTIC_TRUCONNECT_PERIPHERAL_TX_UUID | Tx | cacc07ff-ffff-4c48-8fae-a9ef71b75e26 | Strings received from TruConnect 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.
Interacting with a TruConnect Device
The TruConnect device acts as a Peripheral, and the BLE mobile device acts as a Central.
TruConnect Procedures
This section describes TruConnect connection and communication procedures in general.
Specific implementations are documented in the Communicating via BLE application note as described below.
Scan for a TruConnect Device
Scan for the TruConnect Peripheral using the procedure required by the Central platform.
See Scanning for a TruConnect Device.
Accessing and Subscribing to Characteristics of the TruConnect 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 TruConnect Service
Reading from a TruConnect 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 TruConnect Device Serial Interface
Writing to a TruConnect Device Serial Interface
To write to the device serial interface, write to the Rx characteristic.
Example: Communicating via BLE, iOS, Writing to a TruConnect 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 TruConnect 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 TruConnect Command
First switch to REMOTE_COMMAND_MODE
as described above.
Then, write the command to the TruConnect Rx characteristic. See Writing to a TruConnect 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 TruConnect 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 TruConnect 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 TruConnect Command
Sending and Receiving Data in Stream Mode
First switch to STREAM_MODE
as described above.
To stream data to the TruConnect device, write the data to the TruConnect Rx characteristic. See Writing to a TruConnect Device Serial Interface above.
You can verify that the data is received by connecting a TruConnect terminal to the device. See Getting Started. The data appears on the terminal display.
To stream data to the TruConnect device, read the data from the TruConnect Tx characteristic. See Reading from a TruConnect Device Serial Interface above.
You can verify that the data is received by connecting a TruConnect terminal to the device. Data sent from the central appears directly on the terminal display.
You can send data by connecting a TruConnect terminal to the device. Type data into the terminal. The data is sent directly to the central.