General considerations
Last updated
Last updated
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.
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>
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
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.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.
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 commands example:
https://development.libelium.com/ble-20-sending-custom-commands/
When Waspmote is rebooted the application code will start again, creating all the variables and objects from the beginning.
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.
