User Tools


Link to this comparison view

2.0:ble_connections [2015/09/16 02:00] (current)
Line 1: Line 1:
 +====== 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 [[serial_interface#​stream_mode|STREAM mode]], and send and receive streams of data to and from the device. ​
 +
 +{{./​communicating_via_ble/​communicating_via_ble2.png?​800 }}
 +
 +===== 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|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 [[variables#​bl_v_h_d|bl v h d]], [[variables#​bl_v_h_i|bl v h i]], [[variables#​bl_v_l_d|bl v l d]] & [[variables#​bl_v_l_i|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 [[.apps/​communicating_via_ble|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 [[.apps/​communicating_via_ble#​ios_scan|Scanning for a TruConnect Device]].
 +
 +<​BOOKMARK:​access_subscribe> ​
 +==== 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: [[.apps/​communicating_via_ble#​ios_access_subscribe|Communicating via BLE, iOS, Accessing and Subscribing to Characteristics of the TruConnect Service]]
 +
 +<​BOOKMARK:​reading>​
 +==== 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: [[.apps/​communicating_via_ble#​ios_reading|Communicating via BLE, iOS, Reading from a TruConnect Device Serial Interface]]
 +
 +<​BOOKMARK:​writing>​
 +==== Writing to a TruConnect Device Serial Interface ====
 +
 +To write to the device serial interface, write to the **Rx** characteristic.
 +
 +Example: [[.apps/​communicating_via_ble#​ios_writing|Communicating via BLE, iOS, Writing to a TruConnect Device Serial Interface]]
 +
 +<​BOOKMARK:​switch_command_stream>​
 +==== 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|Serial Interface]] for details of serial interface mode operation. ​
 +
 +Switch the mode via BLE by writing to the **Mode** characteristic. ​
 +
 +Example: [[.apps/​communicating_via_ble#​ios_switch_command_stream|Communicating via BLE, iOS, Switching to Remote Command Mode or Stream Mode]]
 +
 +<​BOOKMARK:​ios_send_command>​
 +==== 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|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|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|Serial Interface]] for details of response format.
 +
 +Example: [[.apps/​communicating_via_ble#​ios_send_command|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|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|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|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. ​
 +
 +
 +
 +
 +