TruConnect is designed to reduce time to market by simplifying development.

You 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 a TruConnect terminal connection.

You can also place the TruConnect module in stream mode, and send and receive streams of data to and from the device.

Screenshot on tablet is the yACKme BLE app available in the App Store

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

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.
• Discovery - Scanning 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 its services, and within those services its 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:

• Scan for peripherals 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 desired read, subscribe and write operations.

The implementation of these procedural steps depends on the platform.

Code examples are provided below in Objective C, used in Apple iOS BLE development.

TruConnect Services and Characteristics

Interacting with a TruConnect Device

//TruConnect
#define SERVICE_TRUCONNECT_UUID                        @"175f8f23-a570-49bd-9627-815a6a27de2a"
#define CHARACTERISTIC_TRUCONNECT_PERIPHERAL_RX_UUID   @"1cce1ea8-bd34-4813-a00a-c76e028fadcb"
#define CHARACTERISTIC_TRUCONNECT_PERIPHERAL_TX_UUID   @"cacc07ff-ffff-4c48-8fae-a9ef71b75e26"
#define CHARACTERISTIC_TRUCONNECT_MODE_UUID            @"20b9794f-da1a-4d14-8014-a0fb9cefb2f7"
#define STREAM_MODE          1
#define LOCAL_COMMAND_MODE   2
#define REMOTE_COMMAND_MODE  3
 
CBCharacteristic *rxChar;   // corresponds to Rx characteristic
CBCharacteristic *txChar;   // corresponds to Tx characteristic
CBCharacteristic *modeChar; // corresponds to Mode characteristic

Scanning for a TruConnect Device

[manager scanForPeripheralsWithServices:@[[CBUUID UUIDWithString:SERVICE_TRUCONNECT_UUID]] options:nil ];

Accessing and Subscribing to Characteristics of the TruConnect Service

The code below assumes a peripheral object has been obtained by scanning. It loops through the peripheral services, and if is the TruConnect service, it sets local variables to point to the corresponding characteristics and subscribes to the appropriate characteristics by registering for notification when their values change. The callback function for all changed value notifications is

didUpdateValueForCharacteristic

.

- (void)peripheral:(CBPeripheral *)aPeripheral \
didUpdateValueForCharacteristic:(CBCharacteristic *)characteristic error:(NSError *)error
/* callback function, called for each notification of a change to a subscribed characteristic */
{    if ([characteristic.UUID
          isEqual:[CBUUID UUIDWithString:CHARACTERISTIC_TRUCONNECT_PERIPHERAL_TX_UUID]])
     {
          NSString *response = [[NSString alloc]
               initWithBytes:[characteristic.value bytes]
               length:characteristic.value.length
               encoding:NSUTF8StringEncoding];
     } else if ([characteristic.UUID
          isEqual:[CBUUID UUIDWithString:CHARACTERISTIC_TRUCONNECT_MODE_UUID]])
     {
          NSString *mode = [[NSString alloc]
               initWithBytes:[characteristic.value bytes]
               length:characteristic.value.length
               encoding:NSUTF8StringEncoding];
     } }
 
/* Loop through services */
for (CBService *service in peripheral.services)
{
     if([service.UUID isEqual:[CBUUID UUIDWithString:SERVICE_TRUCONNECT_UUID]])
     {
          for (CBCharacteristic *characteristic in service.characteristics)
          {
               if ([characteristic.UUID
                    isEqual:[CBUUID UUIDWithString:CHARACTERISTIC_TRUCONNECT_PERIPHERAL_RX_UUID]])
               {
                    rxChar = characteristic;
               }
               else if ([characteristic.UUID
                    isEqual:[CBUUID UUIDWithString:CHARACTERISTIC_TRUCONNECT_PERIPHERAL_TX_UUID]])
               {
                    txChar = characteristic;
                    [peripheral setNotifyValue:YES forCharacteristic:characteristic]; // subscribe
               }
               else if ([characteristic.UUID
                    isEqual:[CBUUID UUIDWithString:CHARACTERISTIC_TRUCONNECT_MODE_UUID]])
               { modeChar = characteristic; [peripheral setNotifyValue:YES forCharacteristic:characteristic]; // subscribe
               }
          }
     }
}

Reading from a TruConnect Device Serial Interface

To read from the device serial interface, read the Tx characteristic:

NSString *str = [[NSString alloc] initWithBytes:[txChar.value bytes]
     length:txChar.value.length encoding:NSUTF8StringEncoding];

Writing to a TruConnect Device Serial Interface

To write to the device serial interface, write to the Rx characteristic:

[peripheral writeValue:[stringToWriteToDevice dataUsingEncoding:NSUTF8StringEncoding]
     forCharacteristic:rxChar
     type:CBCharacteristicWriteWithResponse];

Switching to Remote Command Mode or Stream Mode

• 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.

The following code demonstrates switching to REMOTE_COMMAND_MODE.

The following code demonstrates switching to STREAM_MODE.

Check that the mode was changed successfully by reading back the modeChar characteristic's value:

new_mode = REMOTE_COMMAND_MODE;
[peripheral writeValue:[NSData dataWithBytes:&new_mode length:1]
     forCharacteristic:modeChar type:CBCharacteristicWriteWithResponse];

new_mode = STREAM_MODE;
[peripheral writeValue:[NSData dataWithBytes:&new_mode length:1]
     forCharacteristic:modeChar type:CBCharacteristicWriteWithResponse];

{
     NSString *modeRead = [[NSString alloc] initWithBytes:[modeChar.value bytes]
          length:modeChar.value.length encoding:NSUTF8StringEncoding];
     if *modeRead != new_mode
     {
          //...error handling...
     }
}

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.

The code below shows how to create the command string to turn echo off:

The code below shows how to create the command string to turn headers on:

NSString *commandEchoOff = @"set sy c e 0\r\n";

NSString *commandResponseHeadersOn = @"set sy c h 1\r\n";

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 Rxcharacteristic. 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 Txcharacteristic. 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.

For more information on TruConnect visit:                https://truconnect.ack.me
For more information on ACKme modules visit:        https://ack.me