Development website

General considerations

This section will describe the BLE module API. The functions which manage BLE module belong to the class WaspBLE, and the object created to use them is defined as BLE.

The module talks to Waspmote using a binary protocol through a serial interface. When a command is sent, the module answers back acknowledging the command, and also commands can produce events. The implemented functions manage the commands, answer and events to make easier handling the module. The diagram below shows the described process.

Besides that, the Waspmote API can manage the module to switch between the four device roles defined by the Bluetooth Standard.

  • Advertiser: Broadcast advertisements.

  • Scanner: Listen for advertisements. Can connect to an advertiser.

  • Master (central): Communicates with the device in slave role, defining timings and transmissions.

  • Slave (peripheral): A device connected to a master. Can have only one master at the same time.

Full information is provided in next sections, including some examples of use and some Bluetooth standard concepts necessary to understand the main features of the module. However, if the user requires more information about the Bluetooth standard, please visit the Bluetooth SIG website: www.bluetooth.org.

Waspmote libraries

Waspmote BLE Files

WaspBLE.h; WaspBLE.cpp

It is mandatory to include the BLE library when using this module. So the following line must be added at the beginning of the code:

#include <WaspBLE.h>

Constructor

To start using the Waspmote BLE library, an object from class WaspBLE must be created. This object, called BLE, is already created by default inside Waspmote BLE library. It will be used through this guide to show how Waspmote BLE library works.

When creating this constructor, all the variables are defined with an initial value by default. Some of these variables are:

  • _baudrateBT: specifies the baudrate used to communicate with the module (115200 bps by default)

  • errorCode: saves error codes returned by the module

API functions

Through this guide there are many examples of using functions. In these examples, API functions are called to execute the commands, storing in their related variables the parameter value in each case.

Example of use:

Related variables:

{
    BLE.getOwnMac(); // Get BLE module\'s MAC address
    BLE.getScanningParameters(); // Get current scanning parameters
}

BLE.my_bd_addr → Stores the BLE module MAC address

BLE.GAP_discover_mode → Stores general access profile discover mode

BLE.scan_interval → Stores at what intervals scanner is started

BLE.scan_window → Stores how long to scan at each scan interval

BLE.scan_duplicate_filtering → Stores if active or passive scan is taking process

BLE.TXPower → Stores TX power

When returning from the function BLE.getOwnMac(), the related variable BLE.my_bd_addr will be filled with the appropriate value. Before calling the function, the related variable is created but it is empty or with a default value.

All the functions also return a flag to know if the function called was successful or not. The most common case is to return the BLE.errorCode variable which contains the answer of the module to the command sent. Detailed information about the meaning of each error code can be found in the manufacturer documentation.

API extension

All the relevant and useful functions have been included in the Waspmote BLE API, although any command can be sent directly to the BLE module with the sendCommand() function. The command can be sent as a string or as an array of uint8_t, adding the total length. "Packet mode" is used in Waspmote API, so the first byte must be the command length.

Example of use:

{
    // sending "hello" command
    BLE.sendCommand(\"0400000001\");
    
    // sending the command as an array of uint8_t
    uint8_t command = {0x04, 0x00, 0x00, 0x00, 0x01};
    BLE.sendCommand(command,5);
}

Sending commands example:

https://development.libelium.com/ble-20-sending-custom-commands/

Waspmote reboot

When Waspmote is rebooted the application code will start again, creating all the variables and objects from the beginning.

Constants predefined

There are some constants defined in a file called WaspBLE.h. These constants define some parameters like the baudrate used for serial communication. The most important constants are explained next:

There are other less relevant constants for secondary functions or internal library usage. They can be found at the header file WaspBLE.h.

PreviousHardwareNextInitialization

Last updated