SaBLE-x Development with Serial-to-BLE API
This online guide is intended to provide helpful videos and step-by-step tutorials for developers utilizing the SaBLE-x Development Kit (p/n 450-0141) and the Serial-to-BLE API found within the LSR Developer Tool Suite.

Serial-to-BLE Opening the Box

1 Table of Contents
1
Serial-to-BLE Overview
This brief video provides a conceptual overview of how Serial-to-BLE simplifies Bluetooth communication between a Central and Peripheral device. (2:16)
2
NewExploring the API library for Serial-to-BLE
This video provides a walk through explanation of the API library tool for Serial-to-BLE, highlighting how to easily sort and search to find the API command you need. It also details how to download the auto-generated C code for your host MCU from right within the tool. (4:34)
3
Bootloading the SaBLE-x
This video walks through various options for bootloading the SaBLE-x module, including the USB bootloader utility integrated in the Developer Tool Suite from LSR. (5:40)
4
Connecting via USB
This short video reviews the various options and settings related to establishing a connection with your SaBLE-x development board via USB. (2:14)
5
Exploring the PC Host
This video provides an overview of the PC Host for Serial-to-BLE tool, which allows the developer to set up their PC to act as a Host to talk to the SaBLE-x module using the Serial-to-BLE API for evaluating the API and troubleshooting your design. (3:27)
6
Exploring the PC Host Script Tool
This tutorial walks through the powerful PC Host Script Tool, which allows a developer to chain a sequence of commands together, without any time spent coding the host MCU. It also highlights a number of the useful sample scripts that LSR has included with this tool. (16:31)
7
Host Porting Guide
This guide will explain how to use the C code generated for a SaBLE-x host processor. The Developer Tool Suite lets a user export C code for a host processor that includes all commands in the Serial-to-BLE API.
8
Managing Low Power Mode
This video shows how to facilitate Low Power Mode (LPM) settings using commands in the Serial-to-BLE software API. The video walks through several scenarios using the Serial-to-BLE scripting tool with the help of a logic analyzer. (11:06)
9
Monitoring Battery Status
This video walks through the steps to check the status of the battery powering SaBLE-x by utilizing the 'Query Module Sensors Request' and 'Query Module Sensors Response' commands in the Serial-to-BLE API. (1:36)
10
Documentation for Host Examples
This tutorial provides step-by-step instructions for implementing the Serial-to-BLE with specific host MCU examples, including TI MSP430 Experimenter and ST Nucleo development boards.
11
New Calculating Battery Life
This video explores the convenient BLE Configuration tool added to the DTS, which allows you to calculate the battery life of your BLE application based on a straight-forward worksheet of parameters. This tool then also determines your ideal connection parameters and the settings to utilize when implementing Serial-to-BLE to achieve that battery performance. (6:08)
12
Troubleshooting and Support Tips
This short video discusses troubleshooting tips for developing with this serial protocol, as well as detailing how to contact the LSR Technical Support team with questions or issues related to Serial-to-BLE. (3:30)
2 Additional Documentation
Exploring the API library tool for Serial-to-BLE

This video provides a walk through explanation of the API library tool for Serial-to-BLE, highlighting how to easily sort and search to find the API command you need. It also details how to download the auto-generated C code for your host MCU from right within the tool. (4:34)

Next: Bootloading SaBLE-x
Connecting via USB

This short video reviews the various options and settings related to establishing a connection with your SaBLE-x development board via USB. (2:14)

Next: Exploring the PC Host for Serial-to-BLE Tool
Exploring the PC Host for Serial-to-BLE Tool

This video provides an overview of the PC Host for Serial-to-BLE tool, which allows the developer to set up their PC to act as a Host to talk to the SaBLE-x module using the Serial-to-BLE API for evaluating the API and troubleshooting your design. (3:27)

Next: Exploring the PC Host Script Tool
Exploring the PC Host Script Tool

This tutorial walks through the powerful PC Host Script Tool, which allows a developer to chain a sequence of commands together, without any time spent coding the host MCU. It also highlights a number of the useful sample scripts that LSR has included with this tool. (16:31)

1 LSR Provided PC Host Test Scripts

The PC Host Script Tool provides the capability to create scripts combining multiple Serial-to-BLE commands into a specific sequence. The Developer Tool Suite includes over 20 Test Scripts already available. The following table provides a description of those LSR-provided Test Scripts.

Test Scripts can be found within the PC Host Script Tool by clicking on Open, and then following this path:

2 Script Cheat Sheet
Script Name Description Device(s)
SaBLE-x_TestScript_1 Script used to test the advertsing LED behavior. Peripheral only
SaBLE-x_TestScript_2 Script used to test the heartbeat LED behavior. Peripheral only
SaBLE-x_TestScript_3 Script used to test all the set baud rate command. Peripheral & Central
SaBLE-x_TestScript_4 Script used to connect devices at min connection interval. Peripheral & Central
SaBLE-x_TestScript_5 Script used to connect devices at max connection interval. Peripheral & Central
SaBLE-x_TestScript_6 Script used to connect devices at default connection interval. Peripheral & Central
SaBLE-x_TestScript_7 Script used to send OTA data min payload, both hex and ASCII, both directions. Peripheral & Central
SaBLE-x_TestScript_8 Script used to send OTA data max payload, both hex and ASCII, both directions. Peripheral & Central
SaBLE-x_TestScript_9 Script used to test the default settings. Peripheral only
SaBLE-x_TestScript_10 Script used to test minimum values. Peripheral only
SaBLE-x_TestScript_11 Script used to test maximum values. Peripheral only
SaBLE-x_TestScript_12 Script used to test minimum string lengths. Peripheral only
SaBLE-x_TestScript_13 Script used to check for memory leaks on messages that requrie the entire script to be looped. Peripheral only
SaBLE-x_TestScript_14 Script used to test soft reset. Peripheral only
SaBLE-x_TestScript_15 Script used to test wake host option. Peripheral only
SaBLE-x_TestScript_16 Script used to test wake host option. Peripheral only
SaBLE-x_TestScript_17 Script used to check for memory leaks on peripheral only messages. Peripheral only
SaBLE-x_TestScript_18 Script used to check for memory leaks on common messages. Peripheral & Central
SaBLE-x_TestScript_19 Script used to send invalid OTA host messages. Peripheral & Central
SaBLE-x_TestScript_20 Script used to test the UART LED behavior Peripheral only
SaBLE-x_TestScript_21 Script to test if the peripheral sends wake host notifications when receiving OTA data Peripheral & Central
Next: Host Porting Guide
Host Porting Guide

This guide will explain how to use the C code generated for a SaBLE-x host processor. The Developer Tool Suite lets a user export C code for a host processor that includes all commands in the Serial-to-BLE API.

Please see the Serial-to-BLE API Overview in order to gain an understanding of the Serial-to-BLE API and JSON-RPC.

1 Generating the C Code

To generate the C code that should be included in the host processor project, open the Serial-to-BLE API in the Developer Tool Suite, and click the "Generate Host C Code" button.

How to Generate the C Code

The Developer Tool Suite will save all the C files to a folder the user specifies. These C files can then be used in a host processor C project.

2 Using the Generated C Code

First, the generated C code will need to be included in the host processor project.

How to Use the C Code

3 Sending Messages to the SaBLE-x Module

All API messages sent from the host to the module will be found in the C files containing "OutgoingMsg". For example, the QueryFirmwareVersionOut message looks like:

How the QueryFirmwareVersionOut message looks

The JSON library (json.c and json.h) provide functions for building JSON-RPC messages. The auto-generated C code builds the QueryFirmwareVersion message using the json_mkobject, json_append_member and json_stringify methods from the json.c library. All API messages are implemented in the auto-generated C code so the end user does not have to worry about properly formatting and building the JSON-RPC messages.

To finish implementing this function, the user should add some code in between the App Code Start and End comment to send the pTemp char[] out the host processor's UART peripheral. Adding a function to send the null-terminated pTemp string might look like:

Add a function to send the null-terminated pTemp string

Now the QueryFirmwareVersionOut function can be called to send the message to the module.

The UartProcessor_WriteTxMessage function is responsible for adding the CRC to the end of the JSON-RPC message and sending it out the UART. The UartProcessor_WriteTxMessage function might look like:

UartProcessor_WriteTxMessage function

4 Receiving Messages from the SaBLE-x Module

Receiving bytes over the UART and framing a message is handled outside of the C code generated by the Developer Tool Suite. Some example code is provided below to properly frame a JSON-RPC message from a stream of bytes over a UART.

In the example, uartProcessor.c is a FreeRTOS task designed to process data placed into a circular buffer by the MSP430 UART peripheral.

The prvUSCI_A2_ISR() in mspUart.c fires when bytes are received on the MSP430 UART. The bytes are placed into the circular buffer and a notification is posted to the uartProcessor task. The uartProcessor will start the UartProcessorRxStateMachine() when the notification is received to process any bytes in the circular buffer. The UART RX state machine works via function pointers. The RX state machine will follow these steps to frame a JSON-RPC message from the bytes available in the circular buffer:

  • UartProcessor_lookForStartByte
  • UartProcessor_validateHeader
  • UartProcessor_validateTrailer
  • UartProcessor_parseMsg

Once a complete message is validated in the UartProcessor_parseMsg() function, the corresponding API function can be called via function pointers provided in the auto generated code. For example, once a Query Firmware Version Response is received the QueryFirmwareVersionIn function can be called.

Query Firmware Version Response

Again, functions in the JSON library are included in the auto-generated code to extract the relevant data from the JSON-RPC Serial-to-BLE API message. Application specific code can be added between the App Code Start and End comments to perform useful operations on the data received.

Next: Managing Low Power Mode
Managing Low Power Mode

This video shows how to facilitate Low Power Mode (LPM) settings using commands in the Serial-to-BLE software API. The video walks through several scenarios using the Serial-to-BLE scripting tool with the help of a logic analyzer. (11:06)

Next: Monitoring Battery Status
Monitoring Battery Status

This video walks through the steps to check the status of the battery powering SaBLE-x by utilizing the 'Query Module Sensors Request' and 'Query Module Sensors Response' commands in the Serial-to-BLE API. (1:36)

Next: Host Code Documentaton
Host Code Documentation

The ST Nucleo-L152RE and Texas Instruments MSP-EXP430F5438 SaBLE-x Host demos both use FreeRTOS. They were both based off the demos provided by FreeRTOS.org.

Both demos incorporate low power management.

At its core, there are four components: An application task, UART processor Task, UART driver, and JSON library. Both demos rely on queues and notifications so tasks and processes can communicate with each other.

1 Application Task

The application task is responsible for setting up the SaBLE-x peripheral, deciding what to do with received over the air data, orchestrating over the air transmissions, and telling the system when it is okay to enter low power mode.

2 UART Processor Task

The UART processor task is responsible for framing and parsing valid JSON messages. This includes stripping off the message's CRC_CCITT 16 and verifying it against the message. It is also responsible for packing outgoing messages with a CRC-CCITT 16.

3 UART Driver

The UART driver is responsible for setting up the UART upon boot, disabling the UART for low power mode, and re-enabling the UART upon wakeup. It also notifies the UART processor when bytes have been received so it can begin processing them. Lastly, it allows the UART processor to pass off outgoing messages for transmission.

4 JSON Library

The JSON library is used to pack and unpack JSON messages. For incoming messages the UART processor calls into this library to decipher the data. After the data is unpacked an event is added to the application task with the applicable data. For outgoing messages, generally propagated by the application task, this library is called to pack the data. Once the data is packed and converted to a string, this library will call into the UART processor to add the CRC-CCITT 16 to the message.

Figure 1 - SaBLE-x Host Core Components Interfacing with Each Other

5 What you will need

MSP-EXP430F5438 Host Example

ST Micro Nucleo-L152RE Host Example

  • Nucleo-L152RE (1)
  • SaBLE-x Dev Board Arduino Adapter (1)
  • SaBLE-x Dev Board (2)
  • IAR Embedded Workbench for ARM 7.40.3.8938
Next: BLE Configuration for Calculating Battery Life
MSP-EXP430F5438 Host Example
1 Download Project Files

Project for TI MSP430F5438 Experimenter Board Host Example

Note: The TI MSP430F5438 Experimenter board uses IAR v.6.30.2 for MSP430.

2 Hardware Setup

Select the power input on the MSP-EXP430F5438 to be FET POWER

Figure 2 - Power Selection of the MSP-EXP430F5438

Place the adapter block on the MSP-EXP430F5438 RF3. Make sure the square pad is on pin 1

Figure 3 - Placement of Adapter Block

Place the TI EM Adapter on the MSP-EXP430F5438

Figure 4 - Placement of TI Adapter

Ensure that the switch states of the development board loaded with the Simple Hosted Peripheral are in the following states (red indicates on)

Figure 5 - Peripheral SaBLE-x Development Board Switch States

Place the Peripheral SaBLE-x development board loaded on the TI EM Adapter

Figure 6 - Placement of SaBLE-x Development Board

Attach the MSP-FET430UIF to the MSP-EXP430F5438

Figure 7 - Connecting the MSP-FET430UIF to the MSP-EXP430F5438

3 Running the Demo

Open the project in IAR and select "Download and Debug"

Figure 8 - Loading the MSP430 SaBLE-x Host firmware

Click go and the demo will start running

Figure 9 - Run the application

The host code will now be running on the MSP430. All development board LEDs are configured to as follows:

  • Any valid UART message received or transmitted will generate a red LED pulse
  • The heartbeat LED (green) will pulse every 3 seconds
  • On boot the device will be advertising; the advertising LED (blue) will pulse every second.

After clicking go you should see the red LED on the SaBLE-x Development Board pulse a few times, then once the host is done configuring the heartbeat LED and advertising LED should be pulsing.

Connect the other SaBLE-x development board to the PC and connect to it with the Developer Tool Suite

Figure 10 - Select the Central API and Click Connect

Select the COM port and Click OK

Figure 11 - Select the COM port and Click OK

Scan for the other advertising SaBLE-x development board

Figure 12 - Scan for the Advertising SaBLE-x Development Board

Connect to the advertising SaBLE-x development board

Figure 13 - Connect to the Advertising SaBLE-x Development Board

Wait for the Developer Tool Suite to come back with a Link Status of "1"

Figure 14 - Link Status Notification of 1

The MSP-EXP430F5438 will now indicate via the LCD that it is connected

Figure 15 - MSP-EXP430F5438 Connected

Press the joystick on the MSP-EXP430F5438 multiple times

Figure 16 - MSP-EXP430F5438 Joystick

On the Developer Tool Suite you will see inbound over the air messages alternate between sending light, temperature, and tilt data from the SaBLE-x Development Board's sensors

Figure 17 - Reception of Over the Air Data

Furthermore, the MSP-EXP430F5438's LCD will indicate the write was successful or not

Figure 18 - Indication of Over the Air Transmission Pass or Fail

Now using the Developer Tool Suite send ASCII data to the peripheral

Figure 19 - Sending ASCII Data to the Peripheral

The MSP-EXP430F5438 will now display the data it received

Figure 20 - Reception of ASCII Over the Air Data

Now using the Developer Tool Suite send HEX data to the peripheral

Figure 21 - Reception of HEX Over the Air Data

The MSP-EXP430F5438 will now display the data it received

Figure 22 - Reception of HEX Over the Air Data

ST Micro Nucleo-L152RE Host Example
1 Download Project Files

Project for ST Nucleo-L152RE Board Host Example

Note: The ST Nucleo-L152RE board uses IAR v.7.40.3 for ARM.

2 Hardware Setup

Place the Arduino Adapter on the Nucleo-L152RE

Figure 23 - Placement Arduino Adapter

Ensure that the switch states of the development board loaded with the Simple Hosted Peripheral are in the following states (red indicates on)

Figure 24 - Peripheral SaBLE-x Development Board Switch States

Place the Peripheral SaBLE-x Development Board on the Arduino Adapter

Figure 25 - Placement of SaBLE-x Development Board

3 Running the Demo

Open the project in IAR and select "Download and Debug"

Figure 26 - Loading the MSP430 SaBLE-x Host firmware

Click go and the demo will start running

Figure 27 - Run the application

The host code will now be running on the Nucleo-L152RE. All development board LEDs are configured to as follows:

  • Any valid UART message received or transmitted will generate a red LED pulse
  • The heartbeat LED (green) will pulse every 3 seconds
  • On boot the device will be advertising; the advertising LED (blue) will pulse every second.

After clicking go you should see the red LED on the SaBLE-x Development Board pulse a few times, then once the host is done configuring the heartbeat LED and advertising LED should be pulsing.

Connect the other SaBLE-x development board to the PC and connect to it with the Developer Tool Suite

Figure 28 - Select the Central API and Click Connect

Select the COM port and Click OK

Figure 29 - Select the COM port and Click OK

Scan for the other advertising SaBLE-x development board

Figure 30 - Scan for the Advertising SaBLE-x Development Board

Connect to the advertising SaBLE-x development board

Figure 31 - Connect to the Advertising SaBLE-x Development Board

Wait for the Developer Tool Suite to come back with a Link Status of "1"

Figure 32 - Link Status Notification of 1

Once connected we can query the peripheral SaBLE-x Development board's sensors by sending over the air ASCII commands from the central. The following commands are supported

  • light
  • temp
  • tilt

Send the "light" command

Figure 33 - Sending the light Command

Reception of Light Data in LUX

Figure 34 - Reception of Light Data in LUX

Send the "temp" command

Figure 35 - Sending the temp Command

Reception of Light Data in C

Figure 36 - Reception of Light Data in C

Send the "tilt" command

Figure 37 - Sending the tilt Command

Reception of Tilt Data; refer to the API for definition of bitmask

Figure 38 - Reception of Tilt Data; refer to the API for definition of bitmask

BLE Configuration for Calculating Battery Life

This video explores the convenient BLE Configuration tool added to the DTS, which allows you to calculate the battery life of your BLE application based on a straight-forward worksheet of parameters. This tool then also determines your ideal connection parameters and the settings to utilize when implementing Serial-to-BLE to achieve that battery performance. (6:08)

Next: Troubleshooting and Support Tips
Troubleshooting and Support Tips

This short video discusses troubleshooting tips for developing with this serial protocol, as well as detailing how to contact the LSR Technical Support team with questions or issues related to Serial-to-BLE. (3:30)

Back to the TOC