Bluetooth Low Energy Handshake Sample Code

This topic walks you through sample code that encodes and decodes packets that an Echo device and a gadget exchange during a handshake over Bluetooth Low Energy (BLE). Here we use a C language implementation, but you can extend the concepts to other languages such as Python or Java.

Step 1: Get the resources

The first step is to get the following resources:

  1. Download the nanopb .proto compiler – To use protocol buffers with C, we recommend that you use nanopb. Nanopb is a small code-size protocol buffer implementation in ANSI C. It is especially suitable for use in microcontrollers, but fits any memory-restricted system. To install nanopb, do the following:
    1. Download the latest nanopb version at Nanopb Downloads.
    2. Extract the contents of the nanopb download. The extracted nanopb directory will contain an executable to compile .proto files (that is, get *.c and *.h files). It will also contain helper files that contain functions and data structures to encode and decode any protobuf-encoded data.
  2. Download the Alexa Gadgets sample code repository – Get the Alexa Gadgets Sample Code GitHub repository. This repository contains Alexa Gadget .proto files and sample code.

Step 2: Copy the utility files

Copy the following files from your nanopb directory into the /ConnectionHelpers/BLE/Handshake directory of the Alexa Gadgets repository that you downloaded in the previous step. These files are the utility files that define the methods and the data structures required to encode and decode the protobuf-encoded messages.

  • pb.h
  • pb_common.c
  • pb_common.h
  • pb_decode.c
  • pb_decode.h
  • pb_encode.c
  • pb_encode.h

Step 3: Compile the .proto files

You now need to compile the Alexa Gadgets .proto files into classes that you can reference from your gadget code, as follows:

  1. Navigate to the /ConnectionHelpers/BLE/Handshake directory of the Alexa Gadgets sample code repository that you downloaded.
  2. Open compile_nanos.sh (on Mac or Linux) or compile_nanos.bat (on Windows) and make sure that your nanopb .proto compiler is located at the specified PROTO_COMPILE_PATH.
  3. From the /ConnectionHelpers/BLE/Handshake directory, run compile_nanos.sh (on Mac or Linux) or compile_nanos.bat (on Windows). This compiles all of the .proto files in the Alexa Gadgets sample code repository and puts the resulting C and header source files into the /ConnectionHelpers/BLE/Handshake directory.

Step 4: Compile the sample

From the /ConnectionHelpers/BLE/Handshake directory, compile the code by using the following command:

Copied to clipboard.

gcc -I. -DPB_FIELD_16BIT  *.c -o sample

Step 5: Run the sample

Execute the sample by typing ./sample (on Mac or Linux) or sample.exe (on Windows). This encodes and decodes BLE handshake commands and responses to and from binary format, and prints out the results. The following table shows the functions that the sample code contains.

Function Description
runSampleCreateAdvertisingPacket() Creates a sample advertisement packet.
runSampleProtocolVersionPacket() Creates a sample protocol version packet.
runSample(createCommandGetDeviceInformation()) Creates a DeviceInformation command; emulates a gadget receiving the command and generating a response; emulates an Echo device processing the response.
runSample(createCommandGetDeviceFeatures()) Creates a DeviceFeatures command; emulates a gadget receiving the command and generating a response; emulates an Echo device processing the response.
runSample(createCommandUpdateComponentSegment()) Creates an UpdateComponentSegment command; emulates a gadget receiving the command and generating a response; emulates an Echo device processing the response.
runSample(createCommandApplyFirmware()) Creates an ApplyFirmware command; emulates a gadget receiving the command and generating a response; emulates an Echo device processing the response.
runSample(createAlexaDiscoveryDiscoverDirective()) Creates an Alexa.Discovery.Discover directive; emulates a gadget receiving the command and generating a response; emulates an Echo device processing the response.
runSample(testMyPacketCapturesFromEchoDevice()) Decodes BLE packets that the gadget received from the Echo device.

Output

When you run the sample, you will get the following output:

(Optional) Step 6: Configure the sample code parameters

The sample code uses the configuration declared in config.h, which sets the maximum transaction size and the maximum transmission unit (MTU) size as follows:

#define SAMPLE_MAX_TRANSACTION_SIZE (5000U)
#define SAMPLE_NEGOTIATED_MTU       (128U)

You can modify these configurations and rebuild the sample as needed.

Last updated: Feb 14, 2022