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.

Figure: Serial communication between Waspmote and BLE module

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.

Figure: Device roles and relationship between them

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:

Constant	Default value	Description
BLE_DEBUG	0	Debug mode label. Possible values are: 0 = no debug messages will be printed 1 = some debug messages will be printed 2 = all messages of internal communication will be printed
ENABLE_EEPROM_SAVING	1	Comment this line to avoid using EEPROM with this library
BT_BLUEGIGA_RATE	115200	Baudrate used for serial communication between Waspmote and BLE module.
MAX_PACKET_SIZE	65	Maximum packet size allowed by the protocol
DEFAULT_SCAN_TIME	30	Default scanning time when it is not specified.
TX_POWER_MAX	15	TX power range from 0 to 15, equivalent to power from -23 to +3 dBm

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