BLE Scanner Library
Description
This library provides functions to access the BLE Scanner App. The BLE Scanner App is a firmware developed by Microtronics that is installed on BLE modules integrated in Microtronics devices. It provides a set of AT commands for BLE functionality (e.g. 'at+scan' to scan for BLE Peripherals).
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT (i.e. myDatalogEASY IoT)
- rapidM2M BLEGW (i.e. BLE & 3G Gateway, BLE Gateway)
- rapidM2M M2 (BLE module is connected via UART)
- rapidM2M M23 (BLE module is connected via UART)
- rapidM2M NRF91 (BLE module is connected via UART)
Overview
M22X:
Abstract:
This library provides functions to access the BLE Scanner App. The BLE Scanner App is a firmware developed by Microtronics that is
installed on BLE modules integrated in Microtronics devices. It provides
a set of AT commands for BLE functionality (e.g. 'at+scan' to scan for BLE Peripherals).
Some rapidM2M hardware platforms provide native firmware API commands to access the
BLE Scanner App (e.g. rapidM2M EasyIoT), on some HW boards (e.g. PoC Shields with
rapidM2M M2xx module such as the rapidM2M PoC BLE/WiFi) the BLE module is connected
through generic rM2M UART interface.
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT:
- Firmware: 01v018 and higher
- BLE Scanner App: 01v008 and higher
- rapidM2M BLEGW:
- Firmware: 01v020 and higher
- BLE Scanner App: 01v001 and higher
- rapidM2M M2 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M M23 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M NRF91 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.
Config:
To enable the BLE Scanner Library, add the following macro to the main.dde file.BleApp_EvtDevinfo() BleApp_EvtError()
This macro must be defined in order to use the library.
/**
* Use this macro to enable the callback functions for the features which you want to use:
*
* BLE Central Mode Callbacks
* 0: Disables all callback functions for this mode
* 1: Scanning for devices in advertising mode
* 2: Connecting to peripheral devices and read/write data
* 3: Using Notifications
* 4: Raw access to the AT-interface of the BLE Scanner App (rapidM2M EasyIoT only)
*
* BLE Peripheral Mode (rapidM2M M2 or rapidM2M M23 only)
* 0: Disables all callback functions for this mode
* 1: Advertising
* 2: Detection that a connection has been established, add primary services
* and characteristics, detection that data has been received
* 3: Currently not supported by any of the hardware platforms
*/
#define BLEAPP_CENTRAL_CB 0 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Mandatory Callbacks
BLE Central Mode Callbacks
A BLE Central scans for advertisements from BLE peripherals and initiates connections.
BLEAPP_CENTRAL_CB >=1BleApp_EvtScan() BleApp_EvtScanDone()
BLEAPP_CENTRAL_CB >=2BleApp_EvtConnect() BleApp_EvtRead() BleApp_EvtReadResult() BleApp_EvtWriteResult()
BLEAPP_CENTRAL_CB >=3BleApp_EvtNotify()
BLEAPP_CENTRAL_CB >=4BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
BLEAPP_CENTRAL_CB >=5BleApp_EvtRSSI BleApp_EvtRSSIResult
BLE Peripheral Mode Callbacks
A BLE Peripheral sends out advertisements to inform BLE central devices that it is ready for connection.
BLEAPP_PERIPHERAL_CB >=1BleApp_EvtAdvertise()
BLEAPP_PERIPHERAL_CB >=2BleApp_EvtConnected() BleApp_EvtPrimaryServiceAdded() BleApp_EvtCharAdded() BleApp_EvtWritten()
BLEAPP_PERIPHERAL_CB >=3 (Currently not supported)BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
Detailed explanation
Most of the commands used in this library are working in non-blocking mode. If a command response is available it is provided to the user application
through configurable callback functions. These callbacks are divided into
three main groups:Mandatory Callbacks BLE Central Mode Callbacks BLE Peripheral Mode Callbacks
BLE Peripheral Mode is currently only supported by rapidM2M M2 or rapidM2M M23
The BLE Central Mode Callbacks and the BLE Peripheral Mode Callbacks are divided into further subgroups. Depending on what functionality is needed,
this subgroups of callbacks can be switched on and off. The subgroups are
sorted in ascending order. If a subgroup is activated, all callbacks of
the subgroups below must also be implemented by the user (i.e. if subgroup
3 is activated, all callbacks of subgroups 1 and 2 must also be implemented).
The mandatory callbacks need to be implemented by the user in any case
and cannot be switched off.
- BLE Central Mode Callbacks
- Scanning for devices in advertising mode
- Connecting to peripheral devices and read/write data
- Using Notifications
- Raw access to the AT-interface of the BLE Scanner App (only supported by rapidM2M EasyIoT)
- BLE Peripheral Mode Callbacks
- Advertising
- Detection that a connection has been established, add primary services and characteristics, detection that data has been received
Interface Selection:
Depending on the device profile (i.e. the rapidM2M hardware platform used) you have selected in the project settings different interfaces are supported.
The interface can be selected by calling the BleApp_Init() function. This function must be called only once for a specific interface and prepares the handle for later
use (i.e. inits the handle for a BLE Scanner App interface of the device).
rapidM2M EasyIoT or rapidM2M BLEGW:
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the Firmware interface is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_FIRMWARE) < OK)
{
// Error, selected interface probably not available on this device
}
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the first UART interface (UART0) is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_UART0) < OK)
{
// Error, selected interface probably not available on this device
}
Enable Interface:
The BLE Scanner App interface of the device must be enabled through BleApp_Enable() before use. If it is not required anymore, it is recommended
to call BleApp_Disable().
The handle for the BLE Scanner App interface must be initialized using BleApp_Init() before calling BleApp_Enable().
rapidM2M EasyIoT or rapidM2M BLEGW:
Calling BleApp_Enable() initializes communication with the BLE module integrated in devices.
BleApp_Enable(hBle);
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
Calling BleApp_Enable() initializes the UART interface connected to the BLE module.
It is recommended, first to call BleApp_Enable() and then power-on/enable the BLE module. If the BLE Scanner App interface is not required anymore, it is recommended to call
BleApp_Disable() and power-off/disable the BLE module afterwards.
BleApp_Enable(hBle);
// place code for powering/enabling BLE module here.
// :
How to use:
/* Hardware setup */
const
{
APP_INTERFACE = 0, // The first BLE Scanner App interface should be used.
// Alternatively use:
// BLEAPP_INTERFACE_FIRMWARE (rapidM2M EasyIoT and rapidM2M BLEGW)
// BLEAPP_INTERFACE_UART0 (rapidM2M M2 and rapidM2M M23)
}
// Handle for a BLE Scanner App interface of the device
new hBle;
static iScanFound; // Number of BLE peripherals found
// 1 sec. timer is used for the general program sequence
#callback Timer1s()
{
static bleStateLast = -1; // Last determined operation state
new bleState; // Temporary memory for the current operation state
bleState = BleApp_GetState(hBle); // Gets current operation state of a BLE Scanner App interface
if(bleState != bleStateLast) // If the operation state has changed ->
{
#watch("BLE State=%d", bleState); // Issues current operation state via the watch panel
bleStateLast = bleState; // Copies current operation state to the variable for the last determined state
}
if(bleState == BLEAPP_STATE_READY) // If the BLE Scanner App interface is ready ->
{
catch(BleApp_Scan(hBle)); // Initiates the Scan for BLE peripherals
}
}
// Device has been prepared for Application start by "salve" function
#callback appInit()
{
// Initializes handle for a BLE Scanner App interface
catch(BleApp_Init(hBle, APP_INTERFACE));
//Enables a BLE Scanner App interface
catch(BleApp_Enable(hBle));
// Power-on/enable BLE module (Only for rapidM2M M2 and rapidM2M M23)
// Initialisation of a cyclic sec. timer
setInterval(Timer1s, 1000);
}
// Application entry point
main() {
salve( appInit);
}
// "BLE module information available" - Callback
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{})
{
// Issues BLE module information via the console
#log("BLE_EvtDevinfo: %d, %s, %s, %s, %s, %02X:%02X:%02X:%02X:%02X:%02X", handle, chipname, appname, hwrev, fwrev, addr{0},addr{1},addr{2},addr{3},addr{4},addr{5});
}
// "Internal error has occured" - Callback
BleApp_EvtError(handle, iError)
{
// Inspect Error Codes
switch(iError)
{
case BLE_ERROR_UNKNOWN:
{
// Unspecified internal error
}
case BLE_ERROR_INIT:
{
// Error during initialization (e.g chip not responding)
}
case BLE_ERROR_IO:
{
// Error IO communication
}
case BLE_ERROR_RESTART:
{
// Automatic restart due to error
}
case BLE_ERROR_FORCED_DISC:
{
// Error on BLE-connection-handling (disconnect forced)
// Only available on rapidM2M EasyIoT
}
case BLE_ERROR_TIMEOUT:
{
// Internal communication timeout
// Only available on rapidM2M M2, rapidM2M M23 and BLEGW.
}
}
// 1. Reset BLE module
BleApp_Disable(handle); // Disables a BLE Scanner App interface
// 1a. Power-off/disable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
// 1b. Wait 500ms // (Only for rapidM2M M2 and rapidM2M M23)
// 2. Reset all applicative BLE relevant libraries and variables
// 3. Power-on/enable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
BleApp_Enable(handle); // Enables a BLE Scanner App interface
// 4. Optionally, write an log message to indicate an error has occured
// #log("ble-scanner-app-mt - error %d", iError);
}
// "BLE peripheral was found" - Callback
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
#pragma unused handle
#pragma unused type
//Issues the infos of the scan response (Device name, received signal strength, HW adress and adress type) via the console
#log("BLE: %s, %d, %02X:%02X:%02X:%02X:%02X:%02X, %d", sScan.name, sScan.rssi, sScan.addr{0}, sScan.addr{1}, sScan.addr{2}, sScan.addr{3},sScan.addr{4},sScan.addr{5},sScan.addr_type);
iScanFound++; //Increases number of BLE peripherals found
}
// "Scan operation has finished" - Callback
BleApp_EvtScanDone(handle, iResult)
{
// Issues handle of the BLE Scanner App interface and result of the scan operation via the console
#log("BLE_EvtScanDone %d %s", handle, errorToStr(iResult));
#watch("BLE Scan Count=%d", iScanFound); // Issues the number of BLE peripherals found via the watch panel
iScanFound = 0; // Resets the number of BLE peripherals found
}
M23X:
Abstract:
This library provides functions to access the BLE Scanner App. The BLE Scanner App is a firmware developed by Microtronics that is
installed on BLE modules integrated in Microtronics devices. It provides
a set of AT commands for BLE functionality (e.g. 'at+scan' to scan for BLE Peripherals).
Some rapidM2M hardware platforms provide native firmware API commands to access the
BLE Scanner App (e.g. rapidM2M EasyIoT), on some HW boards (e.g. PoC Shields with
rapidM2M M2xx module such as the rapidM2M PoC BLE/WiFi) the BLE module is connected
through generic rM2M UART interface.
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT:
- Firmware: 01v018 and higher
- BLE Scanner App: 01v008 and higher
- rapidM2M BLEGW:
- Firmware: 01v020 and higher
- BLE Scanner App: 01v001 and higher
- rapidM2M M2 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M M23 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M NRF91 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.
Config:
To enable the BLE Scanner Library, add the following macro to the main.dde file.BleApp_EvtDevinfo() BleApp_EvtError()
This macro must be defined in order to use the library.
/**
* Use this macro to enable the callback functions for the features which you want to use:
*
* BLE Central Mode Callbacks
* 0: Disables all callback functions for this mode
* 1: Scanning for devices in advertising mode
* 2: Connecting to peripheral devices and read/write data
* 3: Using Notifications
* 4: Raw access to the AT-interface of the BLE Scanner App (rapidM2M EasyIoT only)
*
* BLE Peripheral Mode (rapidM2M M2 or rapidM2M M23 only)
* 0: Disables all callback functions for this mode
* 1: Advertising
* 2: Detection that a connection has been established, add primary services
* and characteristics, detection that data has been received
* 3: Currently not supported by any of the hardware platforms
*/
#define BLEAPP_CENTRAL_CB 0 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Mandatory Callbacks
BLE Central Mode Callbacks
A BLE Central scans for advertisements from BLE peripherals and initiates connections.
BLEAPP_CENTRAL_CB >=1BleApp_EvtScan() BleApp_EvtScanDone()
BLEAPP_CENTRAL_CB >=2BleApp_EvtConnect() BleApp_EvtRead() BleApp_EvtReadResult() BleApp_EvtWriteResult()
BLEAPP_CENTRAL_CB >=3BleApp_EvtNotify()
BLEAPP_CENTRAL_CB >=4BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
BLEAPP_CENTRAL_CB >=5BleApp_EvtRSSI BleApp_EvtRSSIResult
BLE Peripheral Mode Callbacks
A BLE Peripheral sends out advertisements to inform BLE central devices that it is ready for connection.
BLEAPP_PERIPHERAL_CB >=1BleApp_EvtAdvertise()
BLEAPP_PERIPHERAL_CB >=2BleApp_EvtConnected() BleApp_EvtPrimaryServiceAdded() BleApp_EvtCharAdded() BleApp_EvtWritten()
BLEAPP_PERIPHERAL_CB >=3 (Currently not supported)BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
Detailed explanation
Most of the commands used in this library are working in non-blocking mode. If a command response is available it is provided to the user application
through configurable callback functions. These callbacks are divided into
three main groups:Mandatory Callbacks BLE Central Mode Callbacks BLE Peripheral Mode Callbacks
BLE Peripheral Mode is currently only supported by rapidM2M M2 or rapidM2M M23
The BLE Central Mode Callbacks and the BLE Peripheral Mode Callbacks are divided into further subgroups. Depending on what functionality is needed,
this subgroups of callbacks can be switched on and off. The subgroups are
sorted in ascending order. If a subgroup is activated, all callbacks of
the subgroups below must also be implemented by the user (i.e. if subgroup
3 is activated, all callbacks of subgroups 1 and 2 must also be implemented).
The mandatory callbacks need to be implemented by the user in any case
and cannot be switched off.
- BLE Central Mode Callbacks
- Scanning for devices in advertising mode
- Connecting to peripheral devices and read/write data
- Using Notifications
- Raw access to the AT-interface of the BLE Scanner App (only supported by rapidM2M EasyIoT)
- BLE Peripheral Mode Callbacks
- Advertising
- Detection that a connection has been established, add primary services and characteristics, detection that data has been received
Interface Selection:
Depending on the device profile (i.e. the rapidM2M hardware platform used) you have selected in the project settings different interfaces are supported.
The interface can be selected by calling the BleApp_Init() function. This function must be called only once for a specific interface and prepares the handle for later
use (i.e. inits the handle for a BLE Scanner App interface of the device).
rapidM2M EasyIoT or rapidM2M BLEGW:
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the Firmware interface is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_FIRMWARE) < OK)
{
// Error, selected interface probably not available on this device
}
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the first UART interface (UART0) is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_UART0) < OK)
{
// Error, selected interface probably not available on this device
}
Enable Interface:
The BLE Scanner App interface of the device must be enabled through BleApp_Enable() before use. If it is not required anymore, it is recommended
to call BleApp_Disable().
The handle for the BLE Scanner App interface must be initialized using BleApp_Init() before calling BleApp_Enable().
rapidM2M EasyIoT or rapidM2M BLEGW:
Calling BleApp_Enable() initializes communication with the BLE module integrated in devices.
BleApp_Enable(hBle);
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
Calling BleApp_Enable() initializes the UART interface connected to the BLE module.
It is recommended, first to call BleApp_Enable() and then power-on/enable the BLE module. If the BLE Scanner App interface is not required anymore, it is recommended to call
BleApp_Disable() and power-off/disable the BLE module afterwards.
BleApp_Enable(hBle);
// place code for powering/enabling BLE module here.
// :
How to use:
/* Hardware setup */
const
{
APP_INTERFACE = 0, // The first BLE Scanner App interface should be used.
// Alternatively use:
// BLEAPP_INTERFACE_FIRMWARE (rapidM2M EasyIoT and rapidM2M BLEGW)
// BLEAPP_INTERFACE_UART0 (rapidM2M M2 and rapidM2M M23)
}
// Handle for a BLE Scanner App interface of the device
new hBle;
static iScanFound; // Number of BLE peripherals found
// 1 sec. timer is used for the general program sequence
#callback Timer1s()
{
static bleStateLast = -1; // Last determined operation state
new bleState; // Temporary memory for the current operation state
bleState = BleApp_GetState(hBle); // Gets current operation state of a BLE Scanner App interface
if(bleState != bleStateLast) // If the operation state has changed ->
{
#watch("BLE State=%d", bleState); // Issues current operation state via the watch panel
bleStateLast = bleState; // Copies current operation state to the variable for the last determined state
}
if(bleState == BLEAPP_STATE_READY) // If the BLE Scanner App interface is ready ->
{
catch(BleApp_Scan(hBle)); // Initiates the Scan for BLE peripherals
}
}
// Device has been prepared for Application start by "salve" function
#callback appInit()
{
// Initializes handle for a BLE Scanner App interface
catch(BleApp_Init(hBle, APP_INTERFACE));
//Enables a BLE Scanner App interface
catch(BleApp_Enable(hBle));
// Power-on/enable BLE module (Only for rapidM2M M2 and rapidM2M M23)
// Initialisation of a cyclic sec. timer
setInterval(Timer1s, 1000);
}
// Application entry point
main() {
salve( appInit);
}
// "BLE module information available" - Callback
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{})
{
// Issues BLE module information via the console
#log("BLE_EvtDevinfo: %d, %s, %s, %s, %s, %02X:%02X:%02X:%02X:%02X:%02X", handle, chipname, appname, hwrev, fwrev, addr{0},addr{1},addr{2},addr{3},addr{4},addr{5});
}
// "Internal error has occured" - Callback
BleApp_EvtError(handle, iError)
{
// Inspect Error Codes
switch(iError)
{
case BLE_ERROR_UNKNOWN:
{
// Unspecified internal error
}
case BLE_ERROR_INIT:
{
// Error during initialization (e.g chip not responding)
}
case BLE_ERROR_IO:
{
// Error IO communication
}
case BLE_ERROR_RESTART:
{
// Automatic restart due to error
}
case BLE_ERROR_FORCED_DISC:
{
// Error on BLE-connection-handling (disconnect forced)
// Only available on rapidM2M EasyIoT
}
case BLE_ERROR_TIMEOUT:
{
// Internal communication timeout
// Only available on rapidM2M M2, rapidM2M M23 and BLEGW.
}
}
// 1. Reset BLE module
BleApp_Disable(handle); // Disables a BLE Scanner App interface
// 1a. Power-off/disable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
// 1b. Wait 500ms // (Only for rapidM2M M2 and rapidM2M M23)
// 2. Reset all applicative BLE relevant libraries and variables
// 3. Power-on/enable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
BleApp_Enable(handle); // Enables a BLE Scanner App interface
// 4. Optionally, write an log message to indicate an error has occured
// #log("ble-scanner-app-mt - error %d", iError);
}
// "BLE peripheral was found" - Callback
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
#pragma unused handle
#pragma unused type
//Issues the infos of the scan response (Device name, received signal strength, HW adress and adress type) via the console
#log("BLE: %s, %d, %02X:%02X:%02X:%02X:%02X:%02X, %d", sScan.name, sScan.rssi, sScan.addr{0}, sScan.addr{1}, sScan.addr{2}, sScan.addr{3},sScan.addr{4},sScan.addr{5},sScan.addr_type);
iScanFound++; //Increases number of BLE peripherals found
}
// "Scan operation has finished" - Callback
BleApp_EvtScanDone(handle, iResult)
{
// Issues handle of the BLE Scanner App interface and result of the scan operation via the console
#log("BLE_EvtScanDone %d %s", handle, errorToStr(iResult));
#watch("BLE Scan Count=%d", iScanFound); // Issues the number of BLE peripherals found via the watch panel
iScanFound = 0; // Resets the number of BLE peripherals found
}
M2BLEGW:
Abstract:
This library provides functions to access the BLE Scanner App. The BLE Scanner App is a firmware developed by Microtronics that is
installed on BLE modules integrated in Microtronics devices. It provides
a set of AT commands for BLE functionality (e.g. 'at+scan' to scan for BLE Peripherals).
Some rapidM2M hardware platforms provide native firmware API commands to access the
BLE Scanner App (e.g. rapidM2M EasyIoT), on some HW boards (e.g. PoC Shields with
rapidM2M M2xx module such as the rapidM2M PoC BLE/WiFi) the BLE module is connected
through generic rM2M UART interface.
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT:
- Firmware: 01v018 and higher
- BLE Scanner App: 01v008 and higher
- rapidM2M BLEGW:
- Firmware: 01v020 and higher
- BLE Scanner App: 01v001 and higher
- rapidM2M M2 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M M23 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M NRF91 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.
Config:
To enable the BLE Scanner Library, add the following macro to the main.dde file.BleApp_EvtDevinfo() BleApp_EvtError()
This macro must be defined in order to use the library.
/**
* Use this macro to enable the callback functions for the features which you want to use:
*
* BLE Central Mode Callbacks
* 0: Disables all callback functions for this mode
* 1: Scanning for devices in advertising mode
* 2: Connecting to peripheral devices and read/write data
* 3: Using Notifications
* 4: Raw access to the AT-interface of the BLE Scanner App (rapidM2M EasyIoT only)
*
* BLE Peripheral Mode (rapidM2M M2 or rapidM2M M23 only)
* 0: Disables all callback functions for this mode
* 1: Advertising
* 2: Detection that a connection has been established, add primary services
* and characteristics, detection that data has been received
* 3: Currently not supported by any of the hardware platforms
*/
#define BLEAPP_CENTRAL_CB 0 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Mandatory Callbacks
BLE Central Mode Callbacks
A BLE Central scans for advertisements from BLE peripherals and initiates connections.
BLEAPP_CENTRAL_CB >=1BleApp_EvtScan() BleApp_EvtScanDone()
BLEAPP_CENTRAL_CB >=2BleApp_EvtConnect() BleApp_EvtRead() BleApp_EvtReadResult() BleApp_EvtWriteResult()
BLEAPP_CENTRAL_CB >=3BleApp_EvtNotify()
BLEAPP_CENTRAL_CB >=4BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
BLEAPP_CENTRAL_CB >=5BleApp_EvtRSSI BleApp_EvtRSSIResult
BLE Peripheral Mode Callbacks
A BLE Peripheral sends out advertisements to inform BLE central devices that it is ready for connection.
BLEAPP_PERIPHERAL_CB >=1BleApp_EvtAdvertise()
BLEAPP_PERIPHERAL_CB >=2BleApp_EvtConnected() BleApp_EvtPrimaryServiceAdded() BleApp_EvtCharAdded() BleApp_EvtWritten()
BLEAPP_PERIPHERAL_CB >=3 (Currently not supported)BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
Detailed explanation
Most of the commands used in this library are working in non-blocking mode. If a command response is available it is provided to the user application
through configurable callback functions. These callbacks are divided into
three main groups:Mandatory Callbacks BLE Central Mode Callbacks BLE Peripheral Mode Callbacks
BLE Peripheral Mode is currently only supported by rapidM2M M2 or rapidM2M M23
The BLE Central Mode Callbacks and the BLE Peripheral Mode Callbacks are divided into further subgroups. Depending on what functionality is needed,
this subgroups of callbacks can be switched on and off. The subgroups are
sorted in ascending order. If a subgroup is activated, all callbacks of
the subgroups below must also be implemented by the user (i.e. if subgroup
3 is activated, all callbacks of subgroups 1 and 2 must also be implemented).
The mandatory callbacks need to be implemented by the user in any case
and cannot be switched off.
- BLE Central Mode Callbacks
- Scanning for devices in advertising mode
- Connecting to peripheral devices and read/write data
- Using Notifications
- Raw access to the AT-interface of the BLE Scanner App (only supported by rapidM2M EasyIoT)
- BLE Peripheral Mode Callbacks
- Advertising
- Detection that a connection has been established, add primary services and characteristics, detection that data has been received
Interface Selection:
Depending on the device profile (i.e. the rapidM2M hardware platform used) you have selected in the project settings different interfaces are supported.
The interface can be selected by calling the BleApp_Init() function. This function must be called only once for a specific interface and prepares the handle for later
use (i.e. inits the handle for a BLE Scanner App interface of the device).
rapidM2M EasyIoT or rapidM2M BLEGW:
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the Firmware interface is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_FIRMWARE) < OK)
{
// Error, selected interface probably not available on this device
}
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the first UART interface (UART0) is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_UART0) < OK)
{
// Error, selected interface probably not available on this device
}
Enable Interface:
The BLE Scanner App interface of the device must be enabled through BleApp_Enable() before use. If it is not required anymore, it is recommended
to call BleApp_Disable().
The handle for the BLE Scanner App interface must be initialized using BleApp_Init() before calling BleApp_Enable().
rapidM2M EasyIoT or rapidM2M BLEGW:
Calling BleApp_Enable() initializes communication with the BLE module integrated in devices.
BleApp_Enable(hBle);
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
Calling BleApp_Enable() initializes the UART interface connected to the BLE module.
It is recommended, first to call BleApp_Enable() and then power-on/enable the BLE module. If the BLE Scanner App interface is not required anymore, it is recommended to call
BleApp_Disable() and power-off/disable the BLE module afterwards.
BleApp_Enable(hBle);
// place code for powering/enabling BLE module here.
// :
How to use:
/* Hardware setup */
const
{
APP_INTERFACE = 0, // The first BLE Scanner App interface should be used.
// Alternatively use:
// BLEAPP_INTERFACE_FIRMWARE (rapidM2M EasyIoT and rapidM2M BLEGW)
// BLEAPP_INTERFACE_UART0 (rapidM2M M2 and rapidM2M M23)
}
// Handle for a BLE Scanner App interface of the device
new hBle;
static iScanFound; // Number of BLE peripherals found
// 1 sec. timer is used for the general program sequence
#callback Timer1s()
{
static bleStateLast = -1; // Last determined operation state
new bleState; // Temporary memory for the current operation state
bleState = BleApp_GetState(hBle); // Gets current operation state of a BLE Scanner App interface
if(bleState != bleStateLast) // If the operation state has changed ->
{
#watch("BLE State=%d", bleState); // Issues current operation state via the watch panel
bleStateLast = bleState; // Copies current operation state to the variable for the last determined state
}
if(bleState == BLEAPP_STATE_READY) // If the BLE Scanner App interface is ready ->
{
catch(BleApp_Scan(hBle)); // Initiates the Scan for BLE peripherals
}
}
// Device has been prepared for Application start by "salve" function
#callback appInit()
{
// Initializes handle for a BLE Scanner App interface
catch(BleApp_Init(hBle, APP_INTERFACE));
//Enables a BLE Scanner App interface
catch(BleApp_Enable(hBle));
// Power-on/enable BLE module (Only for rapidM2M M2 and rapidM2M M23)
// Initialisation of a cyclic sec. timer
setInterval(Timer1s, 1000);
}
// Application entry point
main() {
salve( appInit);
}
// "BLE module information available" - Callback
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{})
{
// Issues BLE module information via the console
#log("BLE_EvtDevinfo: %d, %s, %s, %s, %s, %02X:%02X:%02X:%02X:%02X:%02X", handle, chipname, appname, hwrev, fwrev, addr{0},addr{1},addr{2},addr{3},addr{4},addr{5});
}
// "Internal error has occured" - Callback
BleApp_EvtError(handle, iError)
{
// Inspect Error Codes
switch(iError)
{
case BLE_ERROR_UNKNOWN:
{
// Unspecified internal error
}
case BLE_ERROR_INIT:
{
// Error during initialization (e.g chip not responding)
}
case BLE_ERROR_IO:
{
// Error IO communication
}
case BLE_ERROR_RESTART:
{
// Automatic restart due to error
}
case BLE_ERROR_FORCED_DISC:
{
// Error on BLE-connection-handling (disconnect forced)
// Only available on rapidM2M EasyIoT
}
case BLE_ERROR_TIMEOUT:
{
// Internal communication timeout
// Only available on rapidM2M M2, rapidM2M M23 and BLEGW.
}
}
// 1. Reset BLE module
BleApp_Disable(handle); // Disables a BLE Scanner App interface
// 1a. Power-off/disable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
// 1b. Wait 500ms // (Only for rapidM2M M2 and rapidM2M M23)
// 2. Reset all applicative BLE relevant libraries and variables
// 3. Power-on/enable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
BleApp_Enable(handle); // Enables a BLE Scanner App interface
// 4. Optionally, write an log message to indicate an error has occured
// #log("ble-scanner-app-mt - error %d", iError);
}
// "BLE peripheral was found" - Callback
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
#pragma unused handle
#pragma unused type
//Issues the infos of the scan response (Device name, received signal strength, HW adress and adress type) via the console
#log("BLE: %s, %d, %02X:%02X:%02X:%02X:%02X:%02X, %d", sScan.name, sScan.rssi, sScan.addr{0}, sScan.addr{1}, sScan.addr{2}, sScan.addr{3},sScan.addr{4},sScan.addr{5},sScan.addr_type);
iScanFound++; //Increases number of BLE peripherals found
}
// "Scan operation has finished" - Callback
BleApp_EvtScanDone(handle, iResult)
{
// Issues handle of the BLE Scanner App interface and result of the scan operation via the console
#log("BLE_EvtScanDone %d %s", handle, errorToStr(iResult));
#watch("BLE Scan Count=%d", iScanFound); // Issues the number of BLE peripherals found via the watch panel
iScanFound = 0; // Resets the number of BLE peripherals found
}
M2EASYIOT:
Abstract:
This library provides functions to access the BLE Scanner App. The BLE Scanner App is a firmware developed by Microtronics that is
installed on BLE modules integrated in Microtronics devices. It provides
a set of AT commands for BLE functionality (e.g. 'at+scan' to scan for BLE Peripherals).
Some rapidM2M hardware platforms provide native firmware API commands to access the
BLE Scanner App (e.g. rapidM2M EasyIoT), on some HW boards (e.g. PoC Shields with
rapidM2M M2xx module such as the rapidM2M PoC BLE/WiFi) the BLE module is connected
through generic rM2M UART interface.
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT:
- Firmware: 01v018 and higher
- BLE Scanner App: 01v008 and higher
- rapidM2M BLEGW:
- Firmware: 01v020 and higher
- BLE Scanner App: 01v001 and higher
- rapidM2M M2 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M M23 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M NRF91 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.
Config:
To enable the BLE Scanner Library, add the following macro to the main.dde file.BleApp_EvtDevinfo() BleApp_EvtError()
This macro must be defined in order to use the library.
/**
* Use this macro to enable the callback functions for the features which you want to use:
*
* BLE Central Mode Callbacks
* 0: Disables all callback functions for this mode
* 1: Scanning for devices in advertising mode
* 2: Connecting to peripheral devices and read/write data
* 3: Using Notifications
* 4: Raw access to the AT-interface of the BLE Scanner App (rapidM2M EasyIoT only)
*
* BLE Peripheral Mode (rapidM2M M2 or rapidM2M M23 only)
* 0: Disables all callback functions for this mode
* 1: Advertising
* 2: Detection that a connection has been established, add primary services
* and characteristics, detection that data has been received
* 3: Currently not supported by any of the hardware platforms
*/
#define BLEAPP_CENTRAL_CB 0 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Mandatory Callbacks
BLE Central Mode Callbacks
A BLE Central scans for advertisements from BLE peripherals and initiates connections.
BLEAPP_CENTRAL_CB >=1BleApp_EvtScan() BleApp_EvtScanDone()
BLEAPP_CENTRAL_CB >=2BleApp_EvtConnect() BleApp_EvtRead() BleApp_EvtReadResult() BleApp_EvtWriteResult()
BLEAPP_CENTRAL_CB >=3BleApp_EvtNotify()
BLEAPP_CENTRAL_CB >=4BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
BLEAPP_CENTRAL_CB >=5BleApp_EvtRSSI BleApp_EvtRSSIResult
BLE Peripheral Mode Callbacks
A BLE Peripheral sends out advertisements to inform BLE central devices that it is ready for connection.
BLEAPP_PERIPHERAL_CB >=1BleApp_EvtAdvertise()
BLEAPP_PERIPHERAL_CB >=2BleApp_EvtConnected() BleApp_EvtPrimaryServiceAdded() BleApp_EvtCharAdded() BleApp_EvtWritten()
BLEAPP_PERIPHERAL_CB >=3 (Currently not supported)BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
Detailed explanation
Most of the commands used in this library are working in non-blocking mode. If a command response is available it is provided to the user application
through configurable callback functions. These callbacks are divided into
three main groups:Mandatory Callbacks BLE Central Mode Callbacks BLE Peripheral Mode Callbacks
BLE Peripheral Mode is currently only supported by rapidM2M M2 or rapidM2M M23
The BLE Central Mode Callbacks and the BLE Peripheral Mode Callbacks are divided into further subgroups. Depending on what functionality is needed,
this subgroups of callbacks can be switched on and off. The subgroups are
sorted in ascending order. If a subgroup is activated, all callbacks of
the subgroups below must also be implemented by the user (i.e. if subgroup
3 is activated, all callbacks of subgroups 1 and 2 must also be implemented).
The mandatory callbacks need to be implemented by the user in any case
and cannot be switched off.
- BLE Central Mode Callbacks
- Scanning for devices in advertising mode
- Connecting to peripheral devices and read/write data
- Using Notifications
- Raw access to the AT-interface of the BLE Scanner App (only supported by rapidM2M EasyIoT)
- BLE Peripheral Mode Callbacks
- Advertising
- Detection that a connection has been established, add primary services and characteristics, detection that data has been received
Interface Selection:
Depending on the device profile (i.e. the rapidM2M hardware platform used) you have selected in the project settings different interfaces are supported.
The interface can be selected by calling the BleApp_Init() function. This function must be called only once for a specific interface and prepares the handle for later
use (i.e. inits the handle for a BLE Scanner App interface of the device).
rapidM2M EasyIoT or rapidM2M BLEGW:
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the Firmware interface is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_FIRMWARE) < OK)
{
// Error, selected interface probably not available on this device
}
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the first UART interface (UART0) is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_UART0) < OK)
{
// Error, selected interface probably not available on this device
}
Enable Interface:
The BLE Scanner App interface of the device must be enabled through BleApp_Enable() before use. If it is not required anymore, it is recommended
to call BleApp_Disable().
The handle for the BLE Scanner App interface must be initialized using BleApp_Init() before calling BleApp_Enable().
rapidM2M EasyIoT or rapidM2M BLEGW:
Calling BleApp_Enable() initializes communication with the BLE module integrated in devices.
BleApp_Enable(hBle);
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
Calling BleApp_Enable() initializes the UART interface connected to the BLE module.
It is recommended, first to call BleApp_Enable() and then power-on/enable the BLE module. If the BLE Scanner App interface is not required anymore, it is recommended to call
BleApp_Disable() and power-off/disable the BLE module afterwards.
BleApp_Enable(hBle);
// place code for powering/enabling BLE module here.
// :
How to use:
/* Hardware setup */
const
{
APP_INTERFACE = 0, // The first BLE Scanner App interface should be used.
// Alternatively use:
// BLEAPP_INTERFACE_FIRMWARE (rapidM2M EasyIoT and rapidM2M BLEGW)
// BLEAPP_INTERFACE_UART0 (rapidM2M M2 and rapidM2M M23)
}
// Handle for a BLE Scanner App interface of the device
new hBle;
static iScanFound; // Number of BLE peripherals found
// 1 sec. timer is used for the general program sequence
#callback Timer1s()
{
static bleStateLast = -1; // Last determined operation state
new bleState; // Temporary memory for the current operation state
bleState = BleApp_GetState(hBle); // Gets current operation state of a BLE Scanner App interface
if(bleState != bleStateLast) // If the operation state has changed ->
{
#watch("BLE State=%d", bleState); // Issues current operation state via the watch panel
bleStateLast = bleState; // Copies current operation state to the variable for the last determined state
}
if(bleState == BLEAPP_STATE_READY) // If the BLE Scanner App interface is ready ->
{
catch(BleApp_Scan(hBle)); // Initiates the Scan for BLE peripherals
}
}
// Device has been prepared for Application start by "salve" function
#callback appInit()
{
// Initializes handle for a BLE Scanner App interface
catch(BleApp_Init(hBle, APP_INTERFACE));
//Enables a BLE Scanner App interface
catch(BleApp_Enable(hBle));
// Power-on/enable BLE module (Only for rapidM2M M2 and rapidM2M M23)
// Initialisation of a cyclic sec. timer
setInterval(Timer1s, 1000);
}
// Application entry point
main() {
salve( appInit);
}
// "BLE module information available" - Callback
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{})
{
// Issues BLE module information via the console
#log("BLE_EvtDevinfo: %d, %s, %s, %s, %s, %02X:%02X:%02X:%02X:%02X:%02X", handle, chipname, appname, hwrev, fwrev, addr{0},addr{1},addr{2},addr{3},addr{4},addr{5});
}
// "Internal error has occured" - Callback
BleApp_EvtError(handle, iError)
{
// Inspect Error Codes
switch(iError)
{
case BLE_ERROR_UNKNOWN:
{
// Unspecified internal error
}
case BLE_ERROR_INIT:
{
// Error during initialization (e.g chip not responding)
}
case BLE_ERROR_IO:
{
// Error IO communication
}
case BLE_ERROR_RESTART:
{
// Automatic restart due to error
}
case BLE_ERROR_FORCED_DISC:
{
// Error on BLE-connection-handling (disconnect forced)
// Only available on rapidM2M EasyIoT
}
case BLE_ERROR_TIMEOUT:
{
// Internal communication timeout
// Only available on rapidM2M M2, rapidM2M M23 and BLEGW.
}
}
// 1. Reset BLE module
BleApp_Disable(handle); // Disables a BLE Scanner App interface
// 1a. Power-off/disable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
// 1b. Wait 500ms // (Only for rapidM2M M2 and rapidM2M M23)
// 2. Reset all applicative BLE relevant libraries and variables
// 3. Power-on/enable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
BleApp_Enable(handle); // Enables a BLE Scanner App interface
// 4. Optionally, write an log message to indicate an error has occured
// #log("ble-scanner-app-mt - error %d", iError);
}
// "BLE peripheral was found" - Callback
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
#pragma unused handle
#pragma unused type
//Issues the infos of the scan response (Device name, received signal strength, HW adress and adress type) via the console
#log("BLE: %s, %d, %02X:%02X:%02X:%02X:%02X:%02X, %d", sScan.name, sScan.rssi, sScan.addr{0}, sScan.addr{1}, sScan.addr{2}, sScan.addr{3},sScan.addr{4},sScan.addr{5},sScan.addr_type);
iScanFound++; //Increases number of BLE peripherals found
}
// "Scan operation has finished" - Callback
BleApp_EvtScanDone(handle, iResult)
{
// Issues handle of the BLE Scanner App interface and result of the scan operation via the console
#log("BLE_EvtScanDone %d %s", handle, errorToStr(iResult));
#watch("BLE Scan Count=%d", iScanFound); // Issues the number of BLE peripherals found via the watch panel
iScanFound = 0; // Resets the number of BLE peripherals found
}
NRF91:
Abstract:
This library provides functions to access the BLE Scanner App. The BLE Scanner App is a firmware developed by Microtronics that is
installed on BLE modules integrated in Microtronics devices. It provides
a set of AT commands for BLE functionality (e.g. 'at+scan' to scan for BLE Peripherals).
Some rapidM2M hardware platforms provide native firmware API commands to access the
BLE Scanner App (e.g. rapidM2M EasyIoT), on some HW boards (e.g. PoC Shields with
rapidM2M M2xx module such as the rapidM2M PoC BLE/WiFi) the BLE module is connected
through generic rM2M UART interface.
Supported rapidM2M hardware platforms:
- rapidM2M EasyIoT:
- Firmware: 01v018 and higher
- BLE Scanner App: 01v008 and higher
- rapidM2M BLEGW:
- Firmware: 01v020 and higher
- BLE Scanner App: 01v001 and higher
- rapidM2M M2 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M M23 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
- rapidM2M NRF91 (BLE module is connected via UART)
- BLE Scanner App: 01v008 and higher
- Required Interface: 1x UART
If you use this library in your IoT app, you should specify the minimum required version of the firmware under "required HW & FW" in the project settings.
Config:
To enable the BLE Scanner Library, add the following macro to the main.dde file.BleApp_EvtDevinfo() BleApp_EvtError()
This macro must be defined in order to use the library.
/**
* Use this macro to enable the callback functions for the features which you want to use:
*
* BLE Central Mode Callbacks
* 0: Disables all callback functions for this mode
* 1: Scanning for devices in advertising mode
* 2: Connecting to peripheral devices and read/write data
* 3: Using Notifications
* 4: Raw access to the AT-interface of the BLE Scanner App (rapidM2M EasyIoT only)
*
* BLE Peripheral Mode (rapidM2M M2 or rapidM2M M23 only)
* 0: Disables all callback functions for this mode
* 1: Advertising
* 2: Detection that a connection has been established, add primary services
* and characteristics, detection that data has been received
* 3: Currently not supported by any of the hardware platforms
*/
#define BLEAPP_CENTRAL_CB 0 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Mandatory Callbacks
BLE Central Mode Callbacks
A BLE Central scans for advertisements from BLE peripherals and initiates connections.
BLEAPP_CENTRAL_CB >=1BleApp_EvtScan() BleApp_EvtScanDone()
BLEAPP_CENTRAL_CB >=2BleApp_EvtConnect() BleApp_EvtRead() BleApp_EvtReadResult() BleApp_EvtWriteResult()
BLEAPP_CENTRAL_CB >=3BleApp_EvtNotify()
BLEAPP_CENTRAL_CB >=4BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
BLEAPP_CENTRAL_CB >=5BleApp_EvtRSSI BleApp_EvtRSSIResult
BLE Peripheral Mode Callbacks
A BLE Peripheral sends out advertisements to inform BLE central devices that it is ready for connection.
BLEAPP_PERIPHERAL_CB >=1BleApp_EvtAdvertise()
BLEAPP_PERIPHERAL_CB >=2BleApp_EvtConnected() BleApp_EvtPrimaryServiceAdded() BleApp_EvtCharAdded() BleApp_EvtWritten()
BLEAPP_PERIPHERAL_CB >=3 (Currently not supported)BleApp_EvtRawCmd() BleApp_EvtRawCmdResult()
Detailed explanation
Most of the commands used in this library are working in non-blocking mode. If a command response is available it is provided to the user application
through configurable callback functions. These callbacks are divided into
three main groups:Mandatory Callbacks BLE Central Mode Callbacks BLE Peripheral Mode Callbacks
BLE Peripheral Mode is currently only supported by rapidM2M M2 or rapidM2M M23
The BLE Central Mode Callbacks and the BLE Peripheral Mode Callbacks are divided into further subgroups. Depending on what functionality is needed,
this subgroups of callbacks can be switched on and off. The subgroups are
sorted in ascending order. If a subgroup is activated, all callbacks of
the subgroups below must also be implemented by the user (i.e. if subgroup
3 is activated, all callbacks of subgroups 1 and 2 must also be implemented).
The mandatory callbacks need to be implemented by the user in any case
and cannot be switched off.
- BLE Central Mode Callbacks
- Scanning for devices in advertising mode
- Connecting to peripheral devices and read/write data
- Using Notifications
- Raw access to the AT-interface of the BLE Scanner App (only supported by rapidM2M EasyIoT)
- BLE Peripheral Mode Callbacks
- Advertising
- Detection that a connection has been established, add primary services and characteristics, detection that data has been received
Interface Selection:
Depending on the device profile (i.e. the rapidM2M hardware platform used) you have selected in the project settings different interfaces are supported.
The interface can be selected by calling the BleApp_Init() function. This function must be called only once for a specific interface and prepares the handle for later
use (i.e. inits the handle for a BLE Scanner App interface of the device).
rapidM2M EasyIoT or rapidM2M BLEGW:
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the Firmware interface is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_FIRMWARE) < OK)
{
// Error, selected interface probably not available on this device
}
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
new hBle;
/* Inits the handle for a BLEAPP_INTERFACE of the device.
In this case the first UART interface (UART0) is used */
if(BleApp_Init(&hBle, BLEAPP_INTERFACE_UART0) < OK)
{
// Error, selected interface probably not available on this device
}
Enable Interface:
The BLE Scanner App interface of the device must be enabled through BleApp_Enable() before use. If it is not required anymore, it is recommended
to call BleApp_Disable().
The handle for the BLE Scanner App interface must be initialized using BleApp_Init() before calling BleApp_Enable().
rapidM2M EasyIoT or rapidM2M BLEGW:
Calling BleApp_Enable() initializes communication with the BLE module integrated in devices.
BleApp_Enable(hBle);
rapidM2M M2 or rapidM2M M23 (BLE module is connected via UART):
Calling BleApp_Enable() initializes the UART interface connected to the BLE module.
It is recommended, first to call BleApp_Enable() and then power-on/enable the BLE module. If the BLE Scanner App interface is not required anymore, it is recommended to call
BleApp_Disable() and power-off/disable the BLE module afterwards.
BleApp_Enable(hBle);
// place code for powering/enabling BLE module here.
// :
How to use:
/* Hardware setup */
const
{
APP_INTERFACE = 0, // The first BLE Scanner App interface should be used.
// Alternatively use:
// BLEAPP_INTERFACE_FIRMWARE (rapidM2M EasyIoT and rapidM2M BLEGW)
// BLEAPP_INTERFACE_UART0 (rapidM2M M2 and rapidM2M M23)
}
// Handle for a BLE Scanner App interface of the device
new hBle;
static iScanFound; // Number of BLE peripherals found
// 1 sec. timer is used for the general program sequence
#callback Timer1s()
{
static bleStateLast = -1; // Last determined operation state
new bleState; // Temporary memory for the current operation state
bleState = BleApp_GetState(hBle); // Gets current operation state of a BLE Scanner App interface
if(bleState != bleStateLast) // If the operation state has changed ->
{
#watch("BLE State=%d", bleState); // Issues current operation state via the watch panel
bleStateLast = bleState; // Copies current operation state to the variable for the last determined state
}
if(bleState == BLEAPP_STATE_READY) // If the BLE Scanner App interface is ready ->
{
catch(BleApp_Scan(hBle)); // Initiates the Scan for BLE peripherals
}
}
// Device has been prepared for Application start by "salve" function
#callback appInit()
{
// Initializes handle for a BLE Scanner App interface
catch(BleApp_Init(hBle, APP_INTERFACE));
//Enables a BLE Scanner App interface
catch(BleApp_Enable(hBle));
// Power-on/enable BLE module (Only for rapidM2M M2 and rapidM2M M23)
// Initialisation of a cyclic sec. timer
setInterval(Timer1s, 1000);
}
// Application entry point
main() {
salve( appInit);
}
// "BLE module information available" - Callback
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{})
{
// Issues BLE module information via the console
#log("BLE_EvtDevinfo: %d, %s, %s, %s, %s, %02X:%02X:%02X:%02X:%02X:%02X", handle, chipname, appname, hwrev, fwrev, addr{0},addr{1},addr{2},addr{3},addr{4},addr{5});
}
// "Internal error has occured" - Callback
BleApp_EvtError(handle, iError)
{
// Inspect Error Codes
switch(iError)
{
case BLE_ERROR_UNKNOWN:
{
// Unspecified internal error
}
case BLE_ERROR_INIT:
{
// Error during initialization (e.g chip not responding)
}
case BLE_ERROR_IO:
{
// Error IO communication
}
case BLE_ERROR_RESTART:
{
// Automatic restart due to error
}
case BLE_ERROR_FORCED_DISC:
{
// Error on BLE-connection-handling (disconnect forced)
// Only available on rapidM2M EasyIoT
}
case BLE_ERROR_TIMEOUT:
{
// Internal communication timeout
// Only available on rapidM2M M2, rapidM2M M23 and BLEGW.
}
}
// 1. Reset BLE module
BleApp_Disable(handle); // Disables a BLE Scanner App interface
// 1a. Power-off/disable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
// 1b. Wait 500ms // (Only for rapidM2M M2 and rapidM2M M23)
// 2. Reset all applicative BLE relevant libraries and variables
// 3. Power-on/enable BLE module // (Only for rapidM2M M2 and rapidM2M M23)
BleApp_Enable(handle); // Enables a BLE Scanner App interface
// 4. Optionally, write an log message to indicate an error has occured
// #log("ble-scanner-app-mt - error %d", iError);
}
// "BLE peripheral was found" - Callback
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
#pragma unused handle
#pragma unused type
//Issues the infos of the scan response (Device name, received signal strength, HW adress and adress type) via the console
#log("BLE: %s, %d, %02X:%02X:%02X:%02X:%02X:%02X, %d", sScan.name, sScan.rssi, sScan.addr{0}, sScan.addr{1}, sScan.addr{2}, sScan.addr{3},sScan.addr{4},sScan.addr{5},sScan.addr_type);
iScanFound++; //Increases number of BLE peripherals found
}
// "Scan operation has finished" - Callback
BleApp_EvtScanDone(handle, iResult)
{
// Issues handle of the BLE Scanner App interface and result of the scan operation via the console
#log("BLE_EvtScanDone %d %s", handle, errorToStr(iResult));
#watch("BLE Scan Count=%d", iScanFound); // Issues the number of BLE peripherals found via the watch panel
iScanFound = 0; // Resets the number of BLE peripherals found
}
Migration Guide V1 to V2
M22X:
Callbacks:
With version 1 of the library, each required callback had to be activated by setting a define specified by the library. This allowed the name of the callback
to be freely chosen, but the type and number of parameters were specified by the library.
A collected list of possible defines for the callbacks was not available. Although
all defines were described in the help, they were distributed over the individual sections.
With version 2 the callbacks are combined in groups. These can be activated via a macro (see Config). When a group has been activated, the compiler results window immediately indicates which callbacks
still need to be defined. The names of the callbacks can no longer be freely chosen. Since the
names of the callbacks are fixed, the context-sensitive help is now able to display the appropriate
help for the callback functions.
Migrating from "V1" to "V2"
Search your project for all defines that have activated a callback function. Below you will find a list of all possible defines.
//Mandatory Callbacks
#define BLEAPP_DEVINFO_CALLBACK My_Own_BleApp_EvtDevinfo
#define BLEAPP_ERROR_CALLBACK My_Own_BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
#define BLEAPP_CONNECT_CALLBACK My_Own_BleApp_EvtConnect
#define BLEAPP_READ_CALLBACK My_Own_BleApp_EvtRead
#define BLEAPP_READ_RESULT_CALLBACK My_Own_BleApp_EvtReadResult
#define BLEAPP_WRITE_RESULT_CALLBACK My_Own_BleApp_EvtWriteResult
//Using Notifications
#define BLEAPP_NOTIFY_CALLBACK My_Own_BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
#define BLEAPP_ADVERTISE_CALLBACK My_Own_BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
#define BLEAPP_CONNECTED_CALLBACK My_Own_BleApp_EvtConnected
#define BLEAPP_ADDPRIMSRVC_CALLBACK My_Own_BleApp_EvtPrimaryServiceAdded
#define BLEAPP_ADDCHAR_CALLBACK My_Own_BleApp_EvtCharAdded
#define BLEAPP_WRITTEN_CALLBACK My_Own_BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
Compare the callbacks you have activated with the groups of callbacks described under Config. Define BLEAPP_CENTRAL_CB and BLEAPP_PERIPHERAL_CB with the appropriate
values.
If you have defined e.g. BLEAPP_SCAN_CALLBACK and BLEAPP_SCAN_FINISHED_CALLBACK in your project, you must define BLEAPP_CENTRAL_CB with "1" (i.e. you must add the
followig line to the main.dde)
#define BLEAPP_CENTRAL_CB 1 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Remove the defines and rename your callbacks according to the specifications of the library. In the following you will find an overview of how the callback
functions must be named
//Lib V1 Lib V2
//Mandatory Callbacks
My_Own_BleApp_EvtDevinfo BleApp_EvtDevinfo
My_Own_BleApp_EvtError BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
My_Own_BleApp_EvtScan BleApp_EvtScan
My_Own_BleApp_EvtScanDone BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
My_Own_BleApp_EvtConnect BleApp_EvtConnect
My_Own_BleApp_EvtRead BleApp_EvtRead
My_Own_BleApp_EvtReadResult BleApp_EvtReadResult
My_Own_BleApp_EvtWriteResult BleApp_EvtWriteResult
//Using Notifications
My_Own_BleApp_EvtNotify BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
My_Own_BleApp_EvtAdvertise BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
My_Own_BleApp_EvtConnected BleApp_EvtConnected
My_Own_BleApp_EvtPrimaryServiceAdded BleApp_EvtPrimaryServiceAdded
My_Own_BleApp_EvtCharAdded BleApp_EvtCharAdded
My_Own_BleApp_EvtWritten BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
Example: Migrating from V1 Scan Callbacks to V2
V1:
//In file included via #preinclude directive:
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
// In main application:
My_Own_BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
My_Own_BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
V2:
//In DDE:
#define BLEAPP_CENTRAL_CB 1
//In main application:
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
BLEAPP_STATE:
To harmonize the various implementations of different hardware platforms, BLEAPP_STATE_TIMEOUT has been removed from the list of possible results of
the BleApp_GetState() function. Instead, the callback function BleApp_EvtError()
is called with the parameter "error" set by the system to "BLE_ERROR_TIMEOUT".
The function BleApp_EvtError() is a mandatory function.
If you have implemented some code to reset the BLE Scanner App interface in the case of an timeout, you need to transfer your implementation of the reset routine
in the callback function BleApp_EvtError(). Here's an example:
V1:
new iBleState = BleApp_GetState();
if(iBleState == BLEAPP_STATE_TIMEOUT)
{
//... do something
}
V2:
BleApp_EvtError(iError)
{
switch(iError)
{
//...
case BLE_ERROR_TIMEOUT:
{
// ... do something
}
}
}
M23X:
Callbacks:
With version 1 of the library, each required callback had to be activated by setting a define specified by the library. This allowed the name of the callback
to be freely chosen, but the type and number of parameters were specified by the library.
A collected list of possible defines for the callbacks was not available. Although
all defines were described in the help, they were distributed over the individual sections.
With version 2 the callbacks are combined in groups. These can be activated via a macro (see Config). When a group has been activated, the compiler results window immediately indicates which callbacks
still need to be defined. The names of the callbacks can no longer be freely chosen. Since the
names of the callbacks are fixed, the context-sensitive help is now able to display the appropriate
help for the callback functions.
Migrating from "V1" to "V2"
Search your project for all defines that have activated a callback function. Below you will find a list of all possible defines.
//Mandatory Callbacks
#define BLEAPP_DEVINFO_CALLBACK My_Own_BleApp_EvtDevinfo
#define BLEAPP_ERROR_CALLBACK My_Own_BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
#define BLEAPP_CONNECT_CALLBACK My_Own_BleApp_EvtConnect
#define BLEAPP_READ_CALLBACK My_Own_BleApp_EvtRead
#define BLEAPP_READ_RESULT_CALLBACK My_Own_BleApp_EvtReadResult
#define BLEAPP_WRITE_RESULT_CALLBACK My_Own_BleApp_EvtWriteResult
//Using Notifications
#define BLEAPP_NOTIFY_CALLBACK My_Own_BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
#define BLEAPP_ADVERTISE_CALLBACK My_Own_BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
#define BLEAPP_CONNECTED_CALLBACK My_Own_BleApp_EvtConnected
#define BLEAPP_ADDPRIMSRVC_CALLBACK My_Own_BleApp_EvtPrimaryServiceAdded
#define BLEAPP_ADDCHAR_CALLBACK My_Own_BleApp_EvtCharAdded
#define BLEAPP_WRITTEN_CALLBACK My_Own_BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
Compare the callbacks you have activated with the groups of callbacks described under Config. Define BLEAPP_CENTRAL_CB and BLEAPP_PERIPHERAL_CB with the appropriate
values.
If you have defined e.g. BLEAPP_SCAN_CALLBACK and BLEAPP_SCAN_FINISHED_CALLBACK in your project, you must define BLEAPP_CENTRAL_CB with "1" (i.e. you must add the
followig line to the main.dde)
#define BLEAPP_CENTRAL_CB 1 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Remove the defines and rename your callbacks according to the specifications of the library. In the following you will find an overview of how the callback
functions must be named
//Lib V1 Lib V2
//Mandatory Callbacks
My_Own_BleApp_EvtDevinfo BleApp_EvtDevinfo
My_Own_BleApp_EvtError BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
My_Own_BleApp_EvtScan BleApp_EvtScan
My_Own_BleApp_EvtScanDone BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
My_Own_BleApp_EvtConnect BleApp_EvtConnect
My_Own_BleApp_EvtRead BleApp_EvtRead
My_Own_BleApp_EvtReadResult BleApp_EvtReadResult
My_Own_BleApp_EvtWriteResult BleApp_EvtWriteResult
//Using Notifications
My_Own_BleApp_EvtNotify BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
My_Own_BleApp_EvtAdvertise BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
My_Own_BleApp_EvtConnected BleApp_EvtConnected
My_Own_BleApp_EvtPrimaryServiceAdded BleApp_EvtPrimaryServiceAdded
My_Own_BleApp_EvtCharAdded BleApp_EvtCharAdded
My_Own_BleApp_EvtWritten BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
Example: Migrating from V1 Scan Callbacks to V2
V1:
//In file included via #preinclude directive:
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
// In main application:
My_Own_BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
My_Own_BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
V2:
//In DDE:
#define BLEAPP_CENTRAL_CB 1
//In main application:
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
BLEAPP_STATE:
To harmonize the various implementations of different hardware platforms, BLEAPP_STATE_TIMEOUT has been removed from the list of possible results of
the BleApp_GetState() function. Instead, the callback function BleApp_EvtError()
is called with the parameter "error" set by the system to "BLE_ERROR_TIMEOUT".
The function BleApp_EvtError() is a mandatory function.
If you have implemented some code to reset the BLE Scanner App interface in the case of an timeout, you need to transfer your implementation of the reset routine
in the callback function BleApp_EvtError(). Here's an example:
V1:
new iBleState = BleApp_GetState();
if(iBleState == BLEAPP_STATE_TIMEOUT)
{
//... do something
}
V2:
BleApp_EvtError(iError)
{
switch(iError)
{
//...
case BLE_ERROR_TIMEOUT:
{
// ... do something
}
}
}
M2BLEGW:
Callbacks:
With version 1 of the library, each required callback had to be activated by setting a define specified by the library. This allowed the name of the callback
to be freely chosen, but the type and number of parameters were specified by the library.
A collected list of possible defines for the callbacks was not available. Although
all defines were described in the help, they were distributed over the individual sections.
With version 2 the callbacks are combined in groups. These can be activated via a macro (see Config). When a group has been activated, the compiler results window immediately indicates which callbacks
still need to be defined. The names of the callbacks can no longer be freely chosen. Since the
names of the callbacks are fixed, the context-sensitive help is now able to display the appropriate
help for the callback functions.
Migrating from "V1" to "V2"
Search your project for all defines that have activated a callback function. Below you will find a list of all possible defines.
//Mandatory Callbacks
#define BLEAPP_DEVINFO_CALLBACK My_Own_BleApp_EvtDevinfo
#define BLEAPP_ERROR_CALLBACK My_Own_BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
#define BLEAPP_CONNECT_CALLBACK My_Own_BleApp_EvtConnect
#define BLEAPP_READ_CALLBACK My_Own_BleApp_EvtRead
#define BLEAPP_READ_RESULT_CALLBACK My_Own_BleApp_EvtReadResult
#define BLEAPP_WRITE_RESULT_CALLBACK My_Own_BleApp_EvtWriteResult
//Using Notifications
#define BLEAPP_NOTIFY_CALLBACK My_Own_BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
#define BLEAPP_ADVERTISE_CALLBACK My_Own_BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
#define BLEAPP_CONNECTED_CALLBACK My_Own_BleApp_EvtConnected
#define BLEAPP_ADDPRIMSRVC_CALLBACK My_Own_BleApp_EvtPrimaryServiceAdded
#define BLEAPP_ADDCHAR_CALLBACK My_Own_BleApp_EvtCharAdded
#define BLEAPP_WRITTEN_CALLBACK My_Own_BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
Compare the callbacks you have activated with the groups of callbacks described under Config. Define BLEAPP_CENTRAL_CB and BLEAPP_PERIPHERAL_CB with the appropriate
values.
If you have defined e.g. BLEAPP_SCAN_CALLBACK and BLEAPP_SCAN_FINISHED_CALLBACK in your project, you must define BLEAPP_CENTRAL_CB with "1" (i.e. you must add the
followig line to the main.dde)
#define BLEAPP_CENTRAL_CB 1 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Remove the defines and rename your callbacks according to the specifications of the library. In the following you will find an overview of how the callback
functions must be named
//Lib V1 Lib V2
//Mandatory Callbacks
My_Own_BleApp_EvtDevinfo BleApp_EvtDevinfo
My_Own_BleApp_EvtError BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
My_Own_BleApp_EvtScan BleApp_EvtScan
My_Own_BleApp_EvtScanDone BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
My_Own_BleApp_EvtConnect BleApp_EvtConnect
My_Own_BleApp_EvtRead BleApp_EvtRead
My_Own_BleApp_EvtReadResult BleApp_EvtReadResult
My_Own_BleApp_EvtWriteResult BleApp_EvtWriteResult
//Using Notifications
My_Own_BleApp_EvtNotify BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
My_Own_BleApp_EvtAdvertise BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
My_Own_BleApp_EvtConnected BleApp_EvtConnected
My_Own_BleApp_EvtPrimaryServiceAdded BleApp_EvtPrimaryServiceAdded
My_Own_BleApp_EvtCharAdded BleApp_EvtCharAdded
My_Own_BleApp_EvtWritten BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
Example: Migrating from V1 Scan Callbacks to V2
V1:
//In file included via #preinclude directive:
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
// In main application:
My_Own_BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
My_Own_BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
V2:
//In DDE:
#define BLEAPP_CENTRAL_CB 1
//In main application:
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
BLEAPP_STATE:
To harmonize the various implementations of different hardware platforms, BLEAPP_STATE_TIMEOUT has been removed from the list of possible results of
the BleApp_GetState() function. Instead, the callback function BleApp_EvtError()
is called with the parameter "error" set by the system to "BLE_ERROR_TIMEOUT".
The function BleApp_EvtError() is a mandatory function.
If you have implemented some code to reset the BLE Scanner App interface in the case of an timeout, you need to transfer your implementation of the reset routine
in the callback function BleApp_EvtError(). Here's an example:
V1:
new iBleState = BleApp_GetState();
if(iBleState == BLEAPP_STATE_TIMEOUT)
{
//... do something
}
V2:
BleApp_EvtError(iError)
{
switch(iError)
{
//...
case BLE_ERROR_TIMEOUT:
{
// ... do something
}
}
}
M2EASYIOT:
Callbacks:
With version 1 of the library, each required callback had to be activated by setting a define specified by the library. This allowed the name of the callback
to be freely chosen, but the type and number of parameters were specified by the library.
A collected list of possible defines for the callbacks was not available. Although
all defines were described in the help, they were distributed over the individual sections.
With version 2 the callbacks are combined in groups. These can be activated via a macro (see Config). When a group has been activated, the compiler results window immediately indicates which callbacks
still need to be defined. The names of the callbacks can no longer be freely chosen. Since the
names of the callbacks are fixed, the context-sensitive help is now able to display the appropriate
help for the callback functions.
Migrating from "V1" to "V2"
Search your project for all defines that have activated a callback function. Below you will find a list of all possible defines.
//Mandatory Callbacks
#define BLEAPP_DEVINFO_CALLBACK My_Own_BleApp_EvtDevinfo
#define BLEAPP_ERROR_CALLBACK My_Own_BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
#define BLEAPP_CONNECT_CALLBACK My_Own_BleApp_EvtConnect
#define BLEAPP_READ_CALLBACK My_Own_BleApp_EvtRead
#define BLEAPP_READ_RESULT_CALLBACK My_Own_BleApp_EvtReadResult
#define BLEAPP_WRITE_RESULT_CALLBACK My_Own_BleApp_EvtWriteResult
//Using Notifications
#define BLEAPP_NOTIFY_CALLBACK My_Own_BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
#define BLEAPP_ADVERTISE_CALLBACK My_Own_BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
#define BLEAPP_CONNECTED_CALLBACK My_Own_BleApp_EvtConnected
#define BLEAPP_ADDPRIMSRVC_CALLBACK My_Own_BleApp_EvtPrimaryServiceAdded
#define BLEAPP_ADDCHAR_CALLBACK My_Own_BleApp_EvtCharAdded
#define BLEAPP_WRITTEN_CALLBACK My_Own_BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
Compare the callbacks you have activated with the groups of callbacks described under Config. Define BLEAPP_CENTRAL_CB and BLEAPP_PERIPHERAL_CB with the appropriate
values.
If you have defined e.g. BLEAPP_SCAN_CALLBACK and BLEAPP_SCAN_FINISHED_CALLBACK in your project, you must define BLEAPP_CENTRAL_CB with "1" (i.e. you must add the
followig line to the main.dde)
#define BLEAPP_CENTRAL_CB 1 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Remove the defines and rename your callbacks according to the specifications of the library. In the following you will find an overview of how the callback
functions must be named
//Lib V1 Lib V2
//Mandatory Callbacks
My_Own_BleApp_EvtDevinfo BleApp_EvtDevinfo
My_Own_BleApp_EvtError BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
My_Own_BleApp_EvtScan BleApp_EvtScan
My_Own_BleApp_EvtScanDone BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
My_Own_BleApp_EvtConnect BleApp_EvtConnect
My_Own_BleApp_EvtRead BleApp_EvtRead
My_Own_BleApp_EvtReadResult BleApp_EvtReadResult
My_Own_BleApp_EvtWriteResult BleApp_EvtWriteResult
//Using Notifications
My_Own_BleApp_EvtNotify BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
My_Own_BleApp_EvtAdvertise BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
My_Own_BleApp_EvtConnected BleApp_EvtConnected
My_Own_BleApp_EvtPrimaryServiceAdded BleApp_EvtPrimaryServiceAdded
My_Own_BleApp_EvtCharAdded BleApp_EvtCharAdded
My_Own_BleApp_EvtWritten BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
Example: Migrating from V1 Scan Callbacks to V2
V1:
//In file included via #preinclude directive:
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
// In main application:
My_Own_BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
My_Own_BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
V2:
//In DDE:
#define BLEAPP_CENTRAL_CB 1
//In main application:
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
BLEAPP_STATE:
To harmonize the various implementations of different hardware platforms, BLEAPP_STATE_TIMEOUT has been removed from the list of possible results of
the BleApp_GetState() function. Instead, the callback function BleApp_EvtError()
is called with the parameter "error" set by the system to "BLE_ERROR_TIMEOUT".
The function BleApp_EvtError() is a mandatory function.
If you have implemented some code to reset the BLE Scanner App interface in the case of an timeout, you need to transfer your implementation of the reset routine
in the callback function BleApp_EvtError(). Here's an example:
V1:
new iBleState = BleApp_GetState();
if(iBleState == BLEAPP_STATE_TIMEOUT)
{
//... do something
}
V2:
BleApp_EvtError(iError)
{
switch(iError)
{
//...
case BLE_ERROR_TIMEOUT:
{
// ... do something
}
}
}
NRF91:
Callbacks:
With version 1 of the library, each required callback had to be activated by setting a define specified by the library. This allowed the name of the callback
to be freely chosen, but the type and number of parameters were specified by the library.
A collected list of possible defines for the callbacks was not available. Although
all defines were described in the help, they were distributed over the individual sections.
With version 2 the callbacks are combined in groups. These can be activated via a macro (see Config). When a group has been activated, the compiler results window immediately indicates which callbacks
still need to be defined. The names of the callbacks can no longer be freely chosen. Since the
names of the callbacks are fixed, the context-sensitive help is now able to display the appropriate
help for the callback functions.
Migrating from "V1" to "V2"
Search your project for all defines that have activated a callback function. Below you will find a list of all possible defines.
//Mandatory Callbacks
#define BLEAPP_DEVINFO_CALLBACK My_Own_BleApp_EvtDevinfo
#define BLEAPP_ERROR_CALLBACK My_Own_BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
#define BLEAPP_CONNECT_CALLBACK My_Own_BleApp_EvtConnect
#define BLEAPP_READ_CALLBACK My_Own_BleApp_EvtRead
#define BLEAPP_READ_RESULT_CALLBACK My_Own_BleApp_EvtReadResult
#define BLEAPP_WRITE_RESULT_CALLBACK My_Own_BleApp_EvtWriteResult
//Using Notifications
#define BLEAPP_NOTIFY_CALLBACK My_Own_BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
#define BLEAPP_ADVERTISE_CALLBACK My_Own_BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
#define BLEAPP_CONNECTED_CALLBACK My_Own_BleApp_EvtConnected
#define BLEAPP_ADDPRIMSRVC_CALLBACK My_Own_BleApp_EvtPrimaryServiceAdded
#define BLEAPP_ADDCHAR_CALLBACK My_Own_BleApp_EvtCharAdded
#define BLEAPP_WRITTEN_CALLBACK My_Own_BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
#define BLEAPP_RAW_CMD_CALLBACK My_Own_BleApp_EvtRawCmd
#define BLEAPP_RAW_CMD_RESULT_CALLBACK My_Own_BleApp_EvtRawCmdResult
Compare the callbacks you have activated with the groups of callbacks described under Config. Define BLEAPP_CENTRAL_CB and BLEAPP_PERIPHERAL_CB with the appropriate
values.
If you have defined e.g. BLEAPP_SCAN_CALLBACK and BLEAPP_SCAN_FINISHED_CALLBACK in your project, you must define BLEAPP_CENTRAL_CB with "1" (i.e. you must add the
followig line to the main.dde)
#define BLEAPP_CENTRAL_CB 1 // BLE Central Mode
#define BLEAPP_PERIPHERAL_CB 0 // BLE Peripheral Mode
Remove the defines and rename your callbacks according to the specifications of the library. In the following you will find an overview of how the callback
functions must be named
//Lib V1 Lib V2
//Mandatory Callbacks
My_Own_BleApp_EvtDevinfo BleApp_EvtDevinfo
My_Own_BleApp_EvtError BleApp_EvtError
/* BLE Central Mode Callbacks */
//Scanning for devices in advertising mode
My_Own_BleApp_EvtScan BleApp_EvtScan
My_Own_BleApp_EvtScanDone BleApp_EvtScanDone
//Connecting to peripheral devices and read/write data
My_Own_BleApp_EvtConnect BleApp_EvtConnect
My_Own_BleApp_EvtRead BleApp_EvtRead
My_Own_BleApp_EvtReadResult BleApp_EvtReadResult
My_Own_BleApp_EvtWriteResult BleApp_EvtWriteResult
//Using Notifications
My_Own_BleApp_EvtNotify BleApp_EvtNotify
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
/* BLE Peripheral Mode Callbacks */
//Advertising
My_Own_BleApp_EvtAdvertise BleApp_EvtAdvertise
//Detection that a connection has been established, add primary services
//and characteristics, detection that data has been received
My_Own_BleApp_EvtConnected BleApp_EvtConnected
My_Own_BleApp_EvtPrimaryServiceAdded BleApp_EvtPrimaryServiceAdded
My_Own_BleApp_EvtCharAdded BleApp_EvtCharAdded
My_Own_BleApp_EvtWritten BleApp_EvtWritten
//Raw access to the AT-interface of the BLE Scanner App
My_Own_BleApp_EvtRawCmd BleApp_EvtRawCmd
My_Own_BleApp_EvtRawCmdResult BleApp_EvtRawCmdResult
Example: Migrating from V1 Scan Callbacks to V2
V1:
//In file included via #preinclude directive:
#define BLEAPP_SCAN_CALLBACK My_Own_BleApp_EvtScan
#define BLEAPP_SCAN_FINISHED_CALLBACK My_Own_BleApp_EvtScanDone
// In main application:
My_Own_BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
My_Own_BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
V2:
//In DDE:
#define BLEAPP_CENTRAL_CB 1
//In main application:
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
{
/* user implementation */
}
BleApp_EvtScanDone( handle, iResult)
{
/* user implementation */
}
BLEAPP_STATE:
To harmonize the various implementations of different hardware platforms, BLEAPP_STATE_TIMEOUT has been removed from the list of possible results of
the BleApp_GetState() function. Instead, the callback function BleApp_EvtError()
is called with the parameter "error" set by the system to "BLE_ERROR_TIMEOUT".
The function BleApp_EvtError() is a mandatory function.
If you have implemented some code to reset the BLE Scanner App interface in the case of an timeout, you need to transfer your implementation of the reset routine
in the callback function BleApp_EvtError(). Here's an example:
V1:
new iBleState = BleApp_GetState();
if(iBleState == BLEAPP_STATE_TIMEOUT)
{
//... do something
}
V2:
BleApp_EvtError(iError)
{
switch(iError)
{
//...
case BLE_ERROR_TIMEOUT:
{
// ... do something
}
}
}
Basic
M22X:
BleApp_Init(&handle, iInterface = -1)
Initializes the handle for a BLE Scanner App interface of the device
(see Interface Selection for more details)
handle : s32 - Empty handle for a BLE Scanner App interface of the device
iInterface : s32 - BLE Scanner App interface that should be used (use BLEAPP_INTERFACE_x)
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Enable(handle)
Enables a BLE Scanner App interface
(see Enable Interface for more details)
rapidM2M EasyIoT or rapidM2M BLEGW:
Initializes communication with the BLE module integrated in the device
rapidM2M M2 or rapidM2M M23:
Initializes the UART interface connected to the BLE module
It is recommended first to call BleApp_Enable() and then power-on/enable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Disable(handle)
Disables a BLE Scanner App interface
(see Enable Interface for more details)
For rapidM2M M2 or rapidM2M M23 only:
It is recommended to call BleApp_Disable() before power-off/disable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_GetState(handle)
Get current operation state of a BLE Scanner App interface
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : BLEAPP_STATE_x - Current operation state of the interface
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{6})
BLE module information available
This function will be called unsolicited when the BLE module is ready.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
chipname : astr - Ascii, chipname (e.g. NRF52)
appname : astr - Ascii, name of the application (e.g.ScannerApp)
hwrev : astr - Ascii, HW revision (e.g. "01v001")
fwrev : astr - Ascii, FW revision (e.g. "02v000")
addr{6} : u8 - HW Address - all bytes zero if not available
BleApp_EvtError(handle, error)
Called if an internal error has occured
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
error : BLE_EVENT_ERROR_x - Errorcode
M23X:
BleApp_Init(&handle, iInterface = -1)
Initializes the handle for a BLE Scanner App interface of the device
(see Interface Selection for more details)
handle : s32 - Empty handle for a BLE Scanner App interface of the device
iInterface : s32 - BLE Scanner App interface that should be used (use BLEAPP_INTERFACE_x)
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Enable(handle)
Enables a BLE Scanner App interface
(see Enable Interface for more details)
rapidM2M EasyIoT or rapidM2M BLEGW:
Initializes communication with the BLE module integrated in the device
rapidM2M M2 or rapidM2M M23:
Initializes the UART interface connected to the BLE module
It is recommended first to call BleApp_Enable() and then power-on/enable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Disable(handle)
Disables a BLE Scanner App interface
(see Enable Interface for more details)
For rapidM2M M2 or rapidM2M M23 only:
It is recommended to call BleApp_Disable() before power-off/disable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_GetState(handle)
Get current operation state of a BLE Scanner App interface
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : BLEAPP_STATE_x - Current operation state of the interface
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{6})
BLE module information available
This function will be called unsolicited when the BLE module is ready.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
chipname : astr - Ascii, chipname (e.g. NRF52)
appname : astr - Ascii, name of the application (e.g.ScannerApp)
hwrev : astr - Ascii, HW revision (e.g. "01v001")
fwrev : astr - Ascii, FW revision (e.g. "02v000")
addr{6} : u8 - HW Address - all bytes zero if not available
BleApp_EvtError(handle, error)
Called if an internal error has occured
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
error : BLE_EVENT_ERROR_x - Errorcode
M2BLEGW:
BleApp_Init(&handle, iInterface = -1)
Initializes the handle for a BLE Scanner App interface of the device
(see Interface Selection for more details)
handle : s32 - Empty handle for a BLE Scanner App interface of the device
iInterface : s32 - BLE Scanner App interface that should be used (use BLEAPP_INTERFACE_x)
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Enable(handle)
Enables a BLE Scanner App interface
(see Enable Interface for more details)
rapidM2M EasyIoT or rapidM2M BLEGW:
Initializes communication with the BLE module integrated in the device
rapidM2M M2 or rapidM2M M23:
Initializes the UART interface connected to the BLE module
It is recommended first to call BleApp_Enable() and then power-on/enable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Disable(handle)
Disables a BLE Scanner App interface
(see Enable Interface for more details)
For rapidM2M M2 or rapidM2M M23 only:
It is recommended to call BleApp_Disable() before power-off/disable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_GetState(handle)
Get current operation state of a BLE Scanner App interface
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : BLEAPP_STATE_x - Current operation state of the interface
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{6})
BLE module information available
This function will be called unsolicited when the BLE module is ready.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
chipname : astr - Ascii, chipname (e.g. NRF52)
appname : astr - Ascii, name of the application (e.g.ScannerApp)
hwrev : astr - Ascii, HW revision (e.g. "01v001")
fwrev : astr - Ascii, FW revision (e.g. "02v000")
addr{6} : u8 - HW Address - all bytes zero if not available
BleApp_EvtError(handle, error)
Called if an internal error has occured
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
error : BLE_EVENT_ERROR_x - Errorcode
M2EASYIOT:
BleApp_Init(&handle, iInterface = -1)
Initializes the handle for a BLE Scanner App interface of the device
(see Interface Selection for more details)
handle : s32 - Empty handle for a BLE Scanner App interface of the device
iInterface : s32 - BLE Scanner App interface that should be used (use BLEAPP_INTERFACE_x)
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Enable(handle)
Enables a BLE Scanner App interface
(see Enable Interface for more details)
rapidM2M EasyIoT or rapidM2M BLEGW:
Initializes communication with the BLE module integrated in the device
rapidM2M M2 or rapidM2M M23:
Initializes the UART interface connected to the BLE module
It is recommended first to call BleApp_Enable() and then power-on/enable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Disable(handle)
Disables a BLE Scanner App interface
(see Enable Interface for more details)
For rapidM2M M2 or rapidM2M M23 only:
It is recommended to call BleApp_Disable() before power-off/disable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_GetState(handle)
Get current operation state of a BLE Scanner App interface
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : BLEAPP_STATE_x - Current operation state of the interface
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{6})
BLE module information available
This function will be called unsolicited when the BLE module is ready.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
chipname : astr - Ascii, chipname (e.g. NRF52)
appname : astr - Ascii, name of the application (e.g.ScannerApp)
hwrev : astr - Ascii, HW revision (e.g. "01v001")
fwrev : astr - Ascii, FW revision (e.g. "02v000")
addr{6} : u8 - HW Address - all bytes zero if not available
BleApp_EvtError(handle, error)
Called if an internal error has occured
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
error : BLE_EVENT_ERROR_x - Errorcode
NRF91:
BleApp_Init(&handle, iInterface = -1)
Initializes the handle for a BLE Scanner App interface of the device
(see Interface Selection for more details)
handle : s32 - Empty handle for a BLE Scanner App interface of the device
iInterface : s32 - BLE Scanner App interface that should be used (use BLEAPP_INTERFACE_x)
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Enable(handle)
Enables a BLE Scanner App interface
(see Enable Interface for more details)
rapidM2M EasyIoT or rapidM2M BLEGW:
Initializes communication with the BLE module integrated in the device
rapidM2M M2 or rapidM2M M23:
Initializes the UART interface connected to the BLE module
It is recommended first to call BleApp_Enable() and then power-on/enable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_Disable(handle)
Disables a BLE Scanner App interface
(see Enable Interface for more details)
For rapidM2M M2 or rapidM2M M23 only:
It is recommended to call BleApp_Disable() before power-off/disable the BLE module.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : s32
OK - if successful
ERROR - If an error occurs
BleApp_GetState(handle)
Get current operation state of a BLE Scanner App interface
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
returns : BLEAPP_STATE_x - Current operation state of the interface
BleApp_EvtDevinfo(handle, chipname{}, appname{}, hwrev{}, fwrev{}, addr{6})
BLE module information available
This function will be called unsolicited when the BLE module is ready.
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
chipname : astr - Ascii, chipname (e.g. NRF52)
appname : astr - Ascii, name of the application (e.g.ScannerApp)
hwrev : astr - Ascii, HW revision (e.g. "01v001")
fwrev : astr - Ascii, FW revision (e.g. "02v000")
addr{6} : u8 - HW Address - all bytes zero if not available
BleApp_EvtError(handle, error)
Called if an internal error has occured
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
error : BLE_EVENT_ERROR_x - Errorcode
BLE Central
M22X:
BleApp_Scan(handle, timeout=10, flags=BLEAPP_SCAN_PASSIVE)
Initiates the Scan for BLE peripherals
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
timeout : s32 - Max. Scan Duration [s]
flags : BLEAPP_SCAN_x - Type of the BLE scan
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtScan() is called every time a BLE peripheral was found. Callback function BleApp_EvtScanDone() is called when the scan operation has
finished (i.e. scan duration has expired). When the scan operation has finished the BleApp_GetState()
function returns "BLEAPP_STATE_READY" instead of "BLEAPP_STATE_BUSY" again.
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
Called every time a BLE peripheral was found.
handle : s32 - Handle of a specific BLE Scanner App interface
type : BLEAPP_SCAN_x - Used BLE scan type
sScan : TBleApp_Scan - BLE scan information
BLEAPP_SCAN_x:
Types for BLE scan
BLEAPP_SCAN_PASSIVE - 0 Passive scan (most power efficient)
BLEAPP_SCAN_ACTIVE - 1 Active scan (Scan Request)
BLEAPP_ADDR_x:
BLE address types
BLEAPP_ADDR_PUBLIC - 0 public address
BLEAPP_ADDR_RANDOM_STATIC - 1 Random static address
BLEAPP_ADDR_RANDOM_PRIV_R - 2 Random private resolvable address
BLEAPP_ADDR_RANDOM_PRIV_NR - 3 Random private non-resolvable address
TBleApp_Scan:
BLE scan information
addr_type : BLEAPP_ADDR_x - Address type
addr{6} : u8 - HW address
rssi : s32 - Signal strength [dBm]
name{32+1} : astr - Peripheral advertising name
msd_len : s32 - Number of bytes stored within .msd{}
msd{32} : u8 - Manufacturer specific data
BleApp_EvtScanDone(handle, iResult)
Called when the scan operation has finished
handle : s32 - Handle of a specific BLE Scanner App interface
iResult
OK - Scan operation has finished
ERROR - Scan operation could not be started
BleApp_Connect(handle, addr{6}, itv = -1)
Initiates the connection to a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
addr{6} : u8 - HW address of the BLE peripheral with which the connection is to be established.
itv - BLE connection interval (i.e. interval in which the data is exchanged)
-1 - Use default interval (i.e. 1000ms)
>=8 - BLE connection interval [ms] (min = 8, max = 1000)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_Disconnect(handle, connhandle)
Initiates the disconnection from a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
ERROR-1 - If BLE is busy because of background connection (not available for rapidM2M M2 and rapidM2M M23)
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_EvtConnect(handle, connhandle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of the BLE peripheral
connected : s32 - State of the connection
0 - DISCONNECTED
1 - CONNECTED
< 0 - ERROR (not available for rapidM2M M2 and rapidM2M M23)
addr{6} : u8 - HW address of the BLE peripheral
This function will be called after BleApp_Connect() and unsolicited if BLE disconnect was detected (i.e. an existing connection was interrupted).
BleApp_Write(handle, connhandle, charhandle, data{}, len)
Writes data to a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
data{} : u8 - Data buffer to write
len : s32 - Number of bytes to write
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtWriteResult() is called when the data has been successfully written to the characteristic of
the BLE peripheral or an error has occurred while writing the data.
BleApp_EvtWriteResult(handle, connhandle, charhandle, result, len)
Called when data has been successfully written to the characteristic of a BLE peripheral or an error has occurred while writing the data.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - Data has been successfully written
ERROR - Error or Timeout has occurred while writing the data
len : s32 - Number of bytes written if successful
BleApp_Read(handle, connhandle, charhandle)
Reads data from a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRead() is called when a block of the requested data has been received. If all requested data has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtReadResult() is called
BleApp_EvtRead(handle, connhandle, charhandle, offset, data{}, len)
Called when a block of the requested data has been received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
offset : s32 - Offset of the data
data{} : u8 - Data buffer with available read data
len : s32 - Number of bytes available within data buffer
BleApp_EvtReadResult(handle, connhandle, charhandle, result)
Called if all requested data has been received or if an error has occurred while reading the data (i.e. Read command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_GetRSSI(handle, connhandle)
Gets the BLE RSSI of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRSSI() is called when a block of the requested data has been received. If all RSSI has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtRSSIResult() is called
BleApp_EvtRSSI(handle, connhandle, rssi)
Called when a BLE RSSI has received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
rssi : s8 - BLE RSSI of a specific BLE peripheral
BleApp_EvtRSSIResult(handle, connhandle, result)
Called if BLERSSIhas been received or if an error has occurred while reading the data (i.e. GetRSSI command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_EvtNotify(handle, connhandle, charhandle, data{}, len)
Called when the software of the BLE peripheral changes the content of a characteristic for which notification was enabled previously.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
data{} : u8 - Data buffer with available notification data
len : s32 - Number of bytes available within data buffer
In order to enable the notification for the desired BLE characteristic, the corresponding configuration characteristic must be written using the
BleApp_Write() function.
BleApp_GetConnState(handle, connhandle)
Get connection state for a specific BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
0 - DISCONNECTED
> 0 - CONNECTED
ERROR - if an error occurs
BleApp_ChgConItv(handle, connhandle, conitv)
Change connection intervall
Device must be already connected
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
conitv : s32 - Connection interval in [ms] (valid 8..1000)
returns : s32
OK - if successful
ERROR - if an error occurs
ERROR-1 - if BLE is busy because of background connection
BleApp_GetId(handle, &FWVersion)
Retrieve identification of BLE chip
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
FWVersion : s32 - Value for storing the firmware version of BLE chip (i.e.ScannerApp version)
Minor version is stored in byte 0, major version in byte 1 (.FWVersion >> 8).
Example "01v003": Major version = 1, Minor version = 3
returns : s32
OK - if successful
ERROR - if an error occurs
M23X:
BleApp_Scan(handle, timeout=10, flags=BLEAPP_SCAN_PASSIVE)
Initiates the Scan for BLE peripherals
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
timeout : s32 - Max. Scan Duration [s]
flags : BLEAPP_SCAN_x - Type of the BLE scan
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtScan() is called every time a BLE peripheral was found. Callback function BleApp_EvtScanDone() is called when the scan operation has
finished (i.e. scan duration has expired). When the scan operation has finished the BleApp_GetState()
function returns "BLEAPP_STATE_READY" instead of "BLEAPP_STATE_BUSY" again.
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
Called every time a BLE peripheral was found.
handle : s32 - Handle of a specific BLE Scanner App interface
type : BLEAPP_SCAN_x - Used BLE scan type
sScan : TBleApp_Scan - BLE scan information
BLEAPP_SCAN_x:
Types for BLE scan
BLEAPP_SCAN_PASSIVE - 0 Passive scan (most power efficient)
BLEAPP_SCAN_ACTIVE - 1 Active scan (Scan Request)
BLEAPP_ADDR_x:
BLE address types
BLEAPP_ADDR_PUBLIC - 0 public address
BLEAPP_ADDR_RANDOM_STATIC - 1 Random static address
BLEAPP_ADDR_RANDOM_PRIV_R - 2 Random private resolvable address
BLEAPP_ADDR_RANDOM_PRIV_NR - 3 Random private non-resolvable address
TBleApp_Scan:
BLE scan information
addr_type : BLEAPP_ADDR_x - Address type
addr{6} : u8 - HW address
rssi : s32 - Signal strength [dBm]
name{32+1} : astr - Peripheral advertising name
msd_len : s32 - Number of bytes stored within .msd{}
msd{32} : u8 - Manufacturer specific data
BleApp_EvtScanDone(handle, iResult)
Called when the scan operation has finished
handle : s32 - Handle of a specific BLE Scanner App interface
iResult
OK - Scan operation has finished
ERROR - Scan operation could not be started
BleApp_Connect(handle, addr{6}, itv = -1)
Initiates the connection to a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
addr{6} : u8 - HW address of the BLE peripheral with which the connection is to be established.
itv - BLE connection interval (i.e. interval in which the data is exchanged)
-1 - Use default interval (i.e. 1000ms)
>=8 - BLE connection interval [ms] (min = 8, max = 1000)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_Disconnect(handle, connhandle)
Initiates the disconnection from a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
ERROR-1 - If BLE is busy because of background connection (not available for rapidM2M M2 and rapidM2M M23)
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_EvtConnect(handle, connhandle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of the BLE peripheral
connected : s32 - State of the connection
0 - DISCONNECTED
1 - CONNECTED
< 0 - ERROR (not available for rapidM2M M2 and rapidM2M M23)
addr{6} : u8 - HW address of the BLE peripheral
This function will be called after BleApp_Connect() and unsolicited if BLE disconnect was detected (i.e. an existing connection was interrupted).
BleApp_Write(handle, connhandle, charhandle, data{}, len)
Writes data to a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
data{} : u8 - Data buffer to write
len : s32 - Number of bytes to write
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtWriteResult() is called when the data has been successfully written to the characteristic of
the BLE peripheral or an error has occurred while writing the data.
BleApp_EvtWriteResult(handle, connhandle, charhandle, result, len)
Called when data has been successfully written to the characteristic of a BLE peripheral or an error has occurred while writing the data.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - Data has been successfully written
ERROR - Error or Timeout has occurred while writing the data
len : s32 - Number of bytes written if successful
BleApp_Read(handle, connhandle, charhandle)
Reads data from a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRead() is called when a block of the requested data has been received. If all requested data has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtReadResult() is called
BleApp_EvtRead(handle, connhandle, charhandle, offset, data{}, len)
Called when a block of the requested data has been received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
offset : s32 - Offset of the data
data{} : u8 - Data buffer with available read data
len : s32 - Number of bytes available within data buffer
BleApp_EvtReadResult(handle, connhandle, charhandle, result)
Called if all requested data has been received or if an error has occurred while reading the data (i.e. Read command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_GetRSSI(handle, connhandle)
Gets the BLE RSSI of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRSSI() is called when a block of the requested data has been received. If all RSSI has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtRSSIResult() is called
BleApp_EvtRSSI(handle, connhandle, rssi)
Called when a BLE RSSI has received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
rssi : s8 - BLE RSSI of a specific BLE peripheral
BleApp_EvtRSSIResult(handle, connhandle, result)
Called if BLERSSIhas been received or if an error has occurred while reading the data (i.e. GetRSSI command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_EvtNotify(handle, connhandle, charhandle, data{}, len)
Called when the software of the BLE peripheral changes the content of a characteristic for which notification was enabled previously.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
data{} : u8 - Data buffer with available notification data
len : s32 - Number of bytes available within data buffer
In order to enable the notification for the desired BLE characteristic, the corresponding configuration characteristic must be written using the
BleApp_Write() function.
BleApp_GetConnState(handle, connhandle)
Get connection state for a specific BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
0 - DISCONNECTED
> 0 - CONNECTED
ERROR - if an error occurs
BleApp_ChgConItv(handle, connhandle, conitv)
Change connection intervall
Device must be already connected
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
conitv : s32 - Connection interval in [ms] (valid 8..1000)
returns : s32
OK - if successful
ERROR - if an error occurs
ERROR-1 - if BLE is busy because of background connection
BleApp_GetId(handle, &FWVersion)
Retrieve identification of BLE chip
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
FWVersion : s32 - Value for storing the firmware version of BLE chip (i.e.ScannerApp version)
Minor version is stored in byte 0, major version in byte 1 (.FWVersion >> 8).
Example "01v003": Major version = 1, Minor version = 3
returns : s32
OK - if successful
ERROR - if an error occurs
M2BLEGW:
BleApp_Scan(handle, timeout=10, flags=BLEAPP_SCAN_PASSIVE)
Initiates the Scan for BLE peripherals
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
timeout : s32 - Max. Scan Duration [s]
flags : BLEAPP_SCAN_x - Type of the BLE scan
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtScan() is called every time a BLE peripheral was found. Callback function BleApp_EvtScanDone() is called when the scan operation has
finished (i.e. scan duration has expired). When the scan operation has finished the BleApp_GetState()
function returns "BLEAPP_STATE_READY" instead of "BLEAPP_STATE_BUSY" again.
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
Called every time a BLE peripheral was found.
handle : s32 - Handle of a specific BLE Scanner App interface
type : BLEAPP_SCAN_x - Used BLE scan type
sScan : TBleApp_Scan - BLE scan information
BLEAPP_SCAN_x:
Types for BLE scan
BLEAPP_SCAN_PASSIVE - 0 Passive scan (most power efficient)
BLEAPP_SCAN_ACTIVE - 1 Active scan (Scan Request)
BLEAPP_ADDR_x:
BLE address types
BLEAPP_ADDR_PUBLIC - 0 public address
BLEAPP_ADDR_RANDOM_STATIC - 1 Random static address
BLEAPP_ADDR_RANDOM_PRIV_R - 2 Random private resolvable address
BLEAPP_ADDR_RANDOM_PRIV_NR - 3 Random private non-resolvable address
TBleApp_Scan:
BLE scan information
addr_type : BLEAPP_ADDR_x - Address type
addr{6} : u8 - HW address
rssi : s32 - Signal strength [dBm]
name{32+1} : astr - Peripheral advertising name
msd_len : s32 - Number of bytes stored within .msd{}
msd{32} : u8 - Manufacturer specific data
BleApp_EvtScanDone(handle, iResult)
Called when the scan operation has finished
handle : s32 - Handle of a specific BLE Scanner App interface
iResult
OK - Scan operation has finished
ERROR - Scan operation could not be started
BleApp_Connect(handle, addr{6}, itv = -1)
Initiates the connection to a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
addr{6} : u8 - HW address of the BLE peripheral with which the connection is to be established.
itv - BLE connection interval (i.e. interval in which the data is exchanged)
-1 - Use default interval (i.e. 1000ms)
>=8 - BLE connection interval [ms] (min = 8, max = 1000)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_Disconnect(handle, connhandle)
Initiates the disconnection from a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
ERROR-1 - If BLE is busy because of background connection (not available for rapidM2M M2 and rapidM2M M23)
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_EvtConnect(handle, connhandle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of the BLE peripheral
connected : s32 - State of the connection
0 - DISCONNECTED
1 - CONNECTED
< 0 - ERROR (not available for rapidM2M M2 and rapidM2M M23)
addr{6} : u8 - HW address of the BLE peripheral
This function will be called after BleApp_Connect() and unsolicited if BLE disconnect was detected (i.e. an existing connection was interrupted).
BleApp_Write(handle, connhandle, charhandle, data{}, len)
Writes data to a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
data{} : u8 - Data buffer to write
len : s32 - Number of bytes to write
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtWriteResult() is called when the data has been successfully written to the characteristic of
the BLE peripheral or an error has occurred while writing the data.
BleApp_EvtWriteResult(handle, connhandle, charhandle, result, len)
Called when data has been successfully written to the characteristic of a BLE peripheral or an error has occurred while writing the data.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - Data has been successfully written
ERROR - Error or Timeout has occurred while writing the data
len : s32 - Number of bytes written if successful
BleApp_Read(handle, connhandle, charhandle)
Reads data from a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRead() is called when a block of the requested data has been received. If all requested data has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtReadResult() is called
BleApp_EvtRead(handle, connhandle, charhandle, offset, data{}, len)
Called when a block of the requested data has been received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
offset : s32 - Offset of the data
data{} : u8 - Data buffer with available read data
len : s32 - Number of bytes available within data buffer
BleApp_EvtReadResult(handle, connhandle, charhandle, result)
Called if all requested data has been received or if an error has occurred while reading the data (i.e. Read command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_GetRSSI(handle, connhandle)
Gets the BLE RSSI of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRSSI() is called when a block of the requested data has been received. If all RSSI has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtRSSIResult() is called
BleApp_EvtRSSI(handle, connhandle, rssi)
Called when a BLE RSSI has received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
rssi : s8 - BLE RSSI of a specific BLE peripheral
BleApp_EvtRSSIResult(handle, connhandle, result)
Called if BLERSSIhas been received or if an error has occurred while reading the data (i.e. GetRSSI command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_EvtNotify(handle, connhandle, charhandle, data{}, len)
Called when the software of the BLE peripheral changes the content of a characteristic for which notification was enabled previously.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
data{} : u8 - Data buffer with available notification data
len : s32 - Number of bytes available within data buffer
In order to enable the notification for the desired BLE characteristic, the corresponding configuration characteristic must be written using the
BleApp_Write() function.
BleApp_GetConnState(handle, connhandle)
Get connection state for a specific BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
0 - DISCONNECTED
> 0 - CONNECTED
ERROR - if an error occurs
BleApp_ChgConItv(handle, connhandle, conitv)
Change connection intervall
Device must be already connected
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
conitv : s32 - Connection interval in [ms] (valid 8..1000)
returns : s32
OK - if successful
ERROR - if an error occurs
ERROR-1 - if BLE is busy because of background connection
BleApp_GetId(handle, &FWVersion)
Retrieve identification of BLE chip
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
FWVersion : s32 - Value for storing the firmware version of BLE chip (i.e.ScannerApp version)
Minor version is stored in byte 0, major version in byte 1 (.FWVersion >> 8).
Example "01v003": Major version = 1, Minor version = 3
returns : s32
OK - if successful
ERROR - if an error occurs
M2EASYIOT:
BleApp_Scan(handle, timeout=10, flags=BLEAPP_SCAN_PASSIVE)
Initiates the Scan for BLE peripherals
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
timeout : s32 - Max. Scan Duration [s]
flags : BLEAPP_SCAN_x - Type of the BLE scan
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtScan() is called every time a BLE peripheral was found. Callback function BleApp_EvtScanDone() is called when the scan operation has
finished (i.e. scan duration has expired). When the scan operation has finished the BleApp_GetState()
function returns "BLEAPP_STATE_READY" instead of "BLEAPP_STATE_BUSY" again.
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
Called every time a BLE peripheral was found.
handle : s32 - Handle of a specific BLE Scanner App interface
type : BLEAPP_SCAN_x - Used BLE scan type
sScan : TBleApp_Scan - BLE scan information
BLEAPP_SCAN_x:
Types for BLE scan
BLEAPP_SCAN_PASSIVE - 0 Passive scan (most power efficient)
BLEAPP_SCAN_ACTIVE - 1 Active scan (Scan Request)
BLEAPP_ADDR_x:
BLE address types
BLEAPP_ADDR_PUBLIC - 0 public address
BLEAPP_ADDR_RANDOM_STATIC - 1 Random static address
BLEAPP_ADDR_RANDOM_PRIV_R - 2 Random private resolvable address
BLEAPP_ADDR_RANDOM_PRIV_NR - 3 Random private non-resolvable address
TBleApp_Scan:
BLE scan information
addr_type : BLEAPP_ADDR_x - Address type
addr{6} : u8 - HW address
rssi : s32 - Signal strength [dBm]
name{32+1} : astr - Peripheral advertising name
msd_len : s32 - Number of bytes stored within .msd{}
msd{32} : u8 - Manufacturer specific data
BleApp_EvtScanDone(handle, iResult)
Called when the scan operation has finished
handle : s32 - Handle of a specific BLE Scanner App interface
iResult
OK - Scan operation has finished
ERROR - Scan operation could not be started
BleApp_Connect(handle, addr{6}, itv = -1)
Initiates the connection to a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
addr{6} : u8 - HW address of the BLE peripheral with which the connection is to be established.
itv - BLE connection interval (i.e. interval in which the data is exchanged)
-1 - Use default interval (i.e. 1000ms)
>=8 - BLE connection interval [ms] (min = 8, max = 1000)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_Disconnect(handle, connhandle)
Initiates the disconnection from a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
ERROR-1 - If BLE is busy because of background connection (not available for rapidM2M M2 and rapidM2M M23)
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_EvtConnect(handle, connhandle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of the BLE peripheral
connected : s32 - State of the connection
0 - DISCONNECTED
1 - CONNECTED
< 0 - ERROR (not available for rapidM2M M2 and rapidM2M M23)
addr{6} : u8 - HW address of the BLE peripheral
This function will be called after BleApp_Connect() and unsolicited if BLE disconnect was detected (i.e. an existing connection was interrupted).
BleApp_Write(handle, connhandle, charhandle, data{}, len)
Writes data to a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
data{} : u8 - Data buffer to write
len : s32 - Number of bytes to write
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtWriteResult() is called when the data has been successfully written to the characteristic of
the BLE peripheral or an error has occurred while writing the data.
BleApp_EvtWriteResult(handle, connhandle, charhandle, result, len)
Called when data has been successfully written to the characteristic of a BLE peripheral or an error has occurred while writing the data.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - Data has been successfully written
ERROR - Error or Timeout has occurred while writing the data
len : s32 - Number of bytes written if successful
BleApp_Read(handle, connhandle, charhandle)
Reads data from a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRead() is called when a block of the requested data has been received. If all requested data has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtReadResult() is called
BleApp_EvtRead(handle, connhandle, charhandle, offset, data{}, len)
Called when a block of the requested data has been received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
offset : s32 - Offset of the data
data{} : u8 - Data buffer with available read data
len : s32 - Number of bytes available within data buffer
BleApp_EvtReadResult(handle, connhandle, charhandle, result)
Called if all requested data has been received or if an error has occurred while reading the data (i.e. Read command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_GetRSSI(handle, connhandle)
Gets the BLE RSSI of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRSSI() is called when a block of the requested data has been received. If all RSSI has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtRSSIResult() is called
BleApp_EvtRSSI(handle, connhandle, rssi)
Called when a BLE RSSI has received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
rssi : s8 - BLE RSSI of a specific BLE peripheral
BleApp_EvtRSSIResult(handle, connhandle, result)
Called if BLERSSIhas been received or if an error has occurred while reading the data (i.e. GetRSSI command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_EvtNotify(handle, connhandle, charhandle, data{}, len)
Called when the software of the BLE peripheral changes the content of a characteristic for which notification was enabled previously.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
data{} : u8 - Data buffer with available notification data
len : s32 - Number of bytes available within data buffer
In order to enable the notification for the desired BLE characteristic, the corresponding configuration characteristic must be written using the
BleApp_Write() function.
BleApp_GetConnState(handle, connhandle)
Get connection state for a specific BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
0 - DISCONNECTED
> 0 - CONNECTED
ERROR - if an error occurs
BleApp_ChgConItv(handle, connhandle, conitv)
Change connection intervall
Device must be already connected
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
conitv : s32 - Connection interval in [ms] (valid 8..1000)
returns : s32
OK - if successful
ERROR - if an error occurs
ERROR-1 - if BLE is busy because of background connection
BleApp_GetId(handle, &FWVersion)
Retrieve identification of BLE chip
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
FWVersion : s32 - Value for storing the firmware version of BLE chip (i.e.ScannerApp version)
Minor version is stored in byte 0, major version in byte 1 (.FWVersion >> 8).
Example "01v003": Major version = 1, Minor version = 3
returns : s32
OK - if successful
ERROR - if an error occurs
NRF91:
BleApp_Scan(handle, timeout=10, flags=BLEAPP_SCAN_PASSIVE)
Initiates the Scan for BLE peripherals
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
timeout : s32 - Max. Scan Duration [s]
flags : BLEAPP_SCAN_x - Type of the BLE scan
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtScan() is called every time a BLE peripheral was found. Callback function BleApp_EvtScanDone() is called when the scan operation has
finished (i.e. scan duration has expired). When the scan operation has finished the BleApp_GetState()
function returns "BLEAPP_STATE_READY" instead of "BLEAPP_STATE_BUSY" again.
BleApp_EvtScan(handle, type, sScan[TBleApp_Scan])
Called every time a BLE peripheral was found.
handle : s32 - Handle of a specific BLE Scanner App interface
type : BLEAPP_SCAN_x - Used BLE scan type
sScan : TBleApp_Scan - BLE scan information
BLEAPP_SCAN_x:
Types for BLE scan
BLEAPP_SCAN_PASSIVE - 0 Passive scan (most power efficient)
BLEAPP_SCAN_ACTIVE - 1 Active scan (Scan Request)
BLEAPP_ADDR_x:
BLE address types
BLEAPP_ADDR_PUBLIC - 0 public address
BLEAPP_ADDR_RANDOM_STATIC - 1 Random static address
BLEAPP_ADDR_RANDOM_PRIV_R - 2 Random private resolvable address
BLEAPP_ADDR_RANDOM_PRIV_NR - 3 Random private non-resolvable address
TBleApp_Scan:
BLE scan information
addr_type : BLEAPP_ADDR_x - Address type
addr{6} : u8 - HW address
rssi : s32 - Signal strength [dBm]
name{32+1} : astr - Peripheral advertising name
msd_len : s32 - Number of bytes stored within .msd{}
msd{32} : u8 - Manufacturer specific data
BleApp_EvtScanDone(handle, iResult)
Called when the scan operation has finished
handle : s32 - Handle of a specific BLE Scanner App interface
iResult
OK - Scan operation has finished
ERROR - Scan operation could not be started
BleApp_Connect(handle, addr{6}, itv = -1)
Initiates the connection to a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
addr{6} : u8 - HW address of the BLE peripheral with which the connection is to be established.
itv - BLE connection interval (i.e. interval in which the data is exchanged)
-1 - Use default interval (i.e. 1000ms)
>=8 - BLE connection interval [ms] (min = 8, max = 1000)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_Disconnect(handle, connhandle)
Initiates the disconnection from a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
ERROR-1 - If BLE is busy because of background connection (not available for rapidM2M M2 and rapidM2M M23)
Command works in non-blocking mode. Callback function BleApp_EvtConnect() is called when:the connection to a BLE peripheral could be established, an existing connection was interrupted or an error occurred while establishing a connection.
BleApp_EvtConnect(handle, connhandle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of the BLE peripheral
connected : s32 - State of the connection
0 - DISCONNECTED
1 - CONNECTED
< 0 - ERROR (not available for rapidM2M M2 and rapidM2M M23)
addr{6} : u8 - HW address of the BLE peripheral
This function will be called after BleApp_Connect() and unsolicited if BLE disconnect was detected (i.e. an existing connection was interrupted).
BleApp_Write(handle, connhandle, charhandle, data{}, len)
Writes data to a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
data{} : u8 - Data buffer to write
len : s32 - Number of bytes to write
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtWriteResult() is called when the data has been successfully written to the characteristic of
the BLE peripheral or an error has occurred while writing the data.
BleApp_EvtWriteResult(handle, connhandle, charhandle, result, len)
Called when data has been successfully written to the characteristic of a BLE peripheral or an error has occurred while writing the data.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - Data has been successfully written
ERROR - Error or Timeout has occurred while writing the data
len : s32 - Number of bytes written if successful
BleApp_Read(handle, connhandle, charhandle)
Reads data from a specific characteristic of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
charhandle : s32 - Handle of a specific BLE characteristic (Must currently be determined externally)
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRead() is called when a block of the requested data has been received. If all requested data has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtReadResult() is called
BleApp_EvtRead(handle, connhandle, charhandle, offset, data{}, len)
Called when a block of the requested data has been received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
offset : s32 - Offset of the data
data{} : u8 - Data buffer with available read data
len : s32 - Number of bytes available within data buffer
BleApp_EvtReadResult(handle, connhandle, charhandle, result)
Called if all requested data has been received or if an error has occurred while reading the data (i.e. Read command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_GetRSSI(handle, connhandle)
Gets the BLE RSSI of a BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRSSI() is called when a block of the requested data has been received. If all RSSI has been
received or if an error has occurred while reading the data, the callback function
BleApp_EvtRSSIResult() is called
BleApp_EvtRSSI(handle, connhandle, rssi)
Called when a BLE RSSI has received.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
rssi : s8 - BLE RSSI of a specific BLE peripheral
BleApp_EvtRSSIResult(handle, connhandle, result)
Called if BLERSSIhas been received or if an error has occurred while reading the data (i.e. GetRSSI command has been finished)
handle : s32 - Handle of a specific BLE Scanner App interface
result : s32 - Resultcode
OK - The requested data could be read successfully
ERROR - Error or Timeout has occurred while reading the data
BleApp_EvtNotify(handle, connhandle, charhandle, data{}, len)
Called when the software of the BLE peripheral changes the content of a characteristic for which notification was enabled previously.
handle : s32 - Handle of a specific BLE Scanner App interface
connhandle : s32 - Connection handle of a specific BLE peripheral
charhandle : s32 - Handle of a specific BLE characteristic
data{} : u8 - Data buffer with available notification data
len : s32 - Number of bytes available within data buffer
In order to enable the notification for the desired BLE characteristic, the corresponding configuration characteristic must be written using the
BleApp_Write() function.
BleApp_GetConnState(handle, connhandle)
Get connection state for a specific BLE peripheral
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
returns : s32
0 - DISCONNECTED
> 0 - CONNECTED
ERROR - if an error occurs
BleApp_ChgConItv(handle, connhandle, conitv)
Change connection intervall
Device must be already connected
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
connhandle : s32 - Connection handle of a specific BLE peripheral (Received via BleApp_EvtConnect())
conitv : s32 - Connection interval in [ms] (valid 8..1000)
returns : s32
OK - if successful
ERROR - if an error occurs
ERROR-1 - if BLE is busy because of background connection
BleApp_GetId(handle, &FWVersion)
Retrieve identification of BLE chip
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
FWVersion : s32 - Value for storing the firmware version of BLE chip (i.e.ScannerApp version)
Minor version is stored in byte 0, major version in byte 1 (.FWVersion >> 8).
Example "01v003": Major version = 1, Minor version = 3
returns : s32
OK - if successful
ERROR - if an error occurs
BLE Peripheral
M22X:
BleApp_AddPrimSrvc(handle, szUUID{})
Adds a primary service
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
szUUID{16+1} : astr - Vendor specific 128-bit UUID in hex string format (freely selectable)
The hex string can be provided in big endian and will be converted to little endian internally.
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtPrimaryServiceAdded() is called when the primary service has been successfully added.
BleApp_EvtPrimaryServiceAdded(handle, srvchandle, szUUID{})
Called when the primary service has been successfully added and returns the service handle of the added primary service
handle : s32 - Handle of a specific BLE Scanner App interface
srvchandle : s32 - Service handle of the added primary service
szUUID{16+1} : astr - Vendor specific 128-bit UUID in hex string format of the primary service
The hex string will be returned in big endian format.
BLEAPP_CHAR_FLAGS_x:
Possible characteristic flags
BLEAPP_CHAR_FLAG_NOTIFY - 0x01 Notification characteristic
BLEAPP_CHAR_FLAG_VLEN - 0x02 Variable length characteristic
BleApp_AddChar(handle, srvchandle, uuid, flags=BLEAPP_CHAR_FLAG_VLEN)
Adds a R/W characteristic
Before a characteristic can be created, a primary service must be created using the function BleApp_AddPrimSrvc().
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
srvchandle : s32 - Service handle of the primary service to which the characteristic should be added to (Received via BleApp_EvtPrimaryServiceAdded())
uuid : u16 - Characteristic UUID in decimal format (freely selectable)
flags : BLEAPP_CHAR_FLAGS_x - Optional characteristic flags
It is recommended to use the variable length (BLEAPP_CHAR_FLAG_VLEN) in anycase (normal and notification characteristic).
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtCharAdded() is called when the characteristic has been successfully added.
BleApp_EvtCharAdded(handle, srvchandle, charhandle, uuid)
Called when the characteristic has been successfully added and returns the handle of the added characteristic
handle : s32 - Handle of a specific BLE Scanner App interface
srvchandle : s32 - Service handle of the primary service
charhandle : s32 - Handle of the added characteristic
uuid : u16 - Characteristic UUID of the added characteristic in decimal format
BleApp_SetChar(handle, charhandle, data{}, len)
Sets the content of a characteristic characteristic
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
charhandle : s32 - Handle of a specific BLE characteristic (Received via BleApp_EvtCharAdded())
data{} : u8 - Data to write
len : s32 - Length of the data
returns : s32
OK - If successful
ERROR - If an error occurs
TBleApp_Adv:
BLE advertising configuration
name{31+1} : astr - Advertising name
itv : s32 - Advertising interval [ms] (min = 20, max = 1024)
type : BLEAPP_ADV_TYPES_x - Advertising type
company_id : s32 - Bluetooth SIG company ID
A valid company ID must be specified. For internal testing a company ID of 0xFFFF can be used, but this value must not be present on shipping end products!
For more information please refer to the Company Identifiers Specification.
adv_buf{23} : u8 - Advertising data (Response to a passive scan, see BleApp_Scan() )
adv_buflen : s32 - Advertising data length
sr_buf{23} : u8 - Scan response data (Response to a active scan, see BleApp_Scan() )
sr_buflen : s32 - Scan response data length
BLEAPP_ADV_TYPES_x:
Possible advertising types
BLEAPP_ADV_TYPE_NONE = -1 - Incorrect type specified
BLEAPP_ADV_TYPE_IND = 0 - Connectable undirected
BLEAPP_ADV_TYPE_DIRECT_IND = 1 - Connectable directed
BLEAPP_ADV_TYPE_SCAN_IND = 2 - Scannable undirected
BLEAPP_ADV_TYPE_NONCONN_IND = 3 - Non connectable undirected
BleApp_Advertise(handle, enable, sAdv[TBleApp_Adv]=[0])
Start advertising
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
enable : s32 - Set advertising state
0 - disabled
1 - enabled
sAdv : TBleApp_Adv - BLE advertising configuration
returns : s32
OK - If command accepted
ERROR - if one of the following errors occurs:
< OK - if another error occurs
Command works in non-blocking mode. Callback function BleApp_EvtAdvertise() is called when start advertising command has been processed.
BleApp_EvtAdvertise(handle, status)
Called when start advertising command has been processed.
handle : s32 - Handle of a specific BLE Scanner App interface
status : s32 - Advertising status
0 - no advertising,
1 - advertising active
BleApp_EvtConnected(handle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connected : s32 - Connection state
0 - disconnected
1 - connected
addr{6} : u8 - HW address of the BLE central device
This function will be called unsolicited if a BLE central device has established a connection (see BleApp_EvtConnect()) or an existing connection was interrupted.
BleApp_EvtWritten(handle, charhandle, data{}, len)
Called when data has been written to a characteristic by a BLE central device.
handle : s32 - Handle of a specific BLE Scanner App interface
charhandle : s32 - Handle of the characteristic that was written to by the BLE device
data{} : u8 - Data that was written
len : s32 - Length of the data that was written
This function will be called unsolicited if a BLE central device has written to a characteristic by a BLE central device (see BleApp_Write()).
M23X:
BleApp_AddPrimSrvc(handle, szUUID{})
Adds a primary service
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
szUUID{16+1} : astr - Vendor specific 128-bit UUID in hex string format (freely selectable)
The hex string can be provided in big endian and will be converted to little endian internally.
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtPrimaryServiceAdded() is called when the primary service has been successfully added.
BleApp_EvtPrimaryServiceAdded(handle, srvchandle, szUUID{})
Called when the primary service has been successfully added and returns the service handle of the added primary service
handle : s32 - Handle of a specific BLE Scanner App interface
srvchandle : s32 - Service handle of the added primary service
szUUID{16+1} : astr - Vendor specific 128-bit UUID in hex string format of the primary service
The hex string will be returned in big endian format.
BLEAPP_CHAR_FLAGS_x:
Possible characteristic flags
BLEAPP_CHAR_FLAG_NOTIFY - 0x01 Notification characteristic
BLEAPP_CHAR_FLAG_VLEN - 0x02 Variable length characteristic
BleApp_AddChar(handle, srvchandle, uuid, flags=BLEAPP_CHAR_FLAG_VLEN)
Adds a R/W characteristic
Before a characteristic can be created, a primary service must be created using the function BleApp_AddPrimSrvc().
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
srvchandle : s32 - Service handle of the primary service to which the characteristic should be added to (Received via BleApp_EvtPrimaryServiceAdded())
uuid : u16 - Characteristic UUID in decimal format (freely selectable)
flags : BLEAPP_CHAR_FLAGS_x - Optional characteristic flags
It is recommended to use the variable length (BLEAPP_CHAR_FLAG_VLEN) in anycase (normal and notification characteristic).
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtCharAdded() is called when the characteristic has been successfully added.
BleApp_EvtCharAdded(handle, srvchandle, charhandle, uuid)
Called when the characteristic has been successfully added and returns the handle of the added characteristic
handle : s32 - Handle of a specific BLE Scanner App interface
srvchandle : s32 - Service handle of the primary service
charhandle : s32 - Handle of the added characteristic
uuid : u16 - Characteristic UUID of the added characteristic in decimal format
BleApp_SetChar(handle, charhandle, data{}, len)
Sets the content of a characteristic characteristic
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
charhandle : s32 - Handle of a specific BLE characteristic (Received via BleApp_EvtCharAdded())
data{} : u8 - Data to write
len : s32 - Length of the data
returns : s32
OK - If successful
ERROR - If an error occurs
TBleApp_Adv:
BLE advertising configuration
name{31+1} : astr - Advertising name
itv : s32 - Advertising interval [ms] (min = 20, max = 1024)
type : BLEAPP_ADV_TYPES_x - Advertising type
company_id : s32 - Bluetooth SIG company ID
A valid company ID must be specified. For internal testing a company ID of 0xFFFF can be used, but this value must not be present on shipping end products!
For more information please refer to the Company Identifiers Specification.
adv_buf{23} : u8 - Advertising data (Response to a passive scan, see BleApp_Scan() )
adv_buflen : s32 - Advertising data length
sr_buf{23} : u8 - Scan response data (Response to a active scan, see BleApp_Scan() )
sr_buflen : s32 - Scan response data length
BLEAPP_ADV_TYPES_x:
Possible advertising types
BLEAPP_ADV_TYPE_NONE = -1 - Incorrect type specified
BLEAPP_ADV_TYPE_IND = 0 - Connectable undirected
BLEAPP_ADV_TYPE_DIRECT_IND = 1 - Connectable directed
BLEAPP_ADV_TYPE_SCAN_IND = 2 - Scannable undirected
BLEAPP_ADV_TYPE_NONCONN_IND = 3 - Non connectable undirected
BleApp_Advertise(handle, enable, sAdv[TBleApp_Adv]=[0])
Start advertising
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
enable : s32 - Set advertising state
0 - disabled
1 - enabled
sAdv : TBleApp_Adv - BLE advertising configuration
returns : s32
OK - If command accepted
ERROR - if one of the following errors occurs:
< OK - if another error occurs
Command works in non-blocking mode. Callback function BleApp_EvtAdvertise() is called when start advertising command has been processed.
BleApp_EvtAdvertise(handle, status)
Called when start advertising command has been processed.
handle : s32 - Handle of a specific BLE Scanner App interface
status : s32 - Advertising status
0 - no advertising,
1 - advertising active
BleApp_EvtConnected(handle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connected : s32 - Connection state
0 - disconnected
1 - connected
addr{6} : u8 - HW address of the BLE central device
This function will be called unsolicited if a BLE central device has established a connection (see BleApp_EvtConnect()) or an existing connection was interrupted.
BleApp_EvtWritten(handle, charhandle, data{}, len)
Called when data has been written to a characteristic by a BLE central device.
handle : s32 - Handle of a specific BLE Scanner App interface
charhandle : s32 - Handle of the characteristic that was written to by the BLE device
data{} : u8 - Data that was written
len : s32 - Length of the data that was written
This function will be called unsolicited if a BLE central device has written to a characteristic by a BLE central device (see BleApp_Write()).
NRF91:
BleApp_AddPrimSrvc(handle, szUUID{})
Adds a primary service
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
szUUID{16+1} : astr - Vendor specific 128-bit UUID in hex string format (freely selectable)
The hex string can be provided in big endian and will be converted to little endian internally.
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtPrimaryServiceAdded() is called when the primary service has been successfully added.
BleApp_EvtPrimaryServiceAdded(handle, srvchandle, szUUID{})
Called when the primary service has been successfully added and returns the service handle of the added primary service
handle : s32 - Handle of a specific BLE Scanner App interface
srvchandle : s32 - Service handle of the added primary service
szUUID{16+1} : astr - Vendor specific 128-bit UUID in hex string format of the primary service
The hex string will be returned in big endian format.
BLEAPP_CHAR_FLAGS_x:
Possible characteristic flags
BLEAPP_CHAR_FLAG_NOTIFY - 0x01 Notification characteristic
BLEAPP_CHAR_FLAG_VLEN - 0x02 Variable length characteristic
BleApp_AddChar(handle, srvchandle, uuid, flags=BLEAPP_CHAR_FLAG_VLEN)
Adds a R/W characteristic
Before a characteristic can be created, a primary service must be created using the function BleApp_AddPrimSrvc().
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
srvchandle : s32 - Service handle of the primary service to which the characteristic should be added to (Received via BleApp_EvtPrimaryServiceAdded())
uuid : u16 - Characteristic UUID in decimal format (freely selectable)
flags : BLEAPP_CHAR_FLAGS_x - Optional characteristic flags
It is recommended to use the variable length (BLEAPP_CHAR_FLAG_VLEN) in anycase (normal and notification characteristic).
returns : s32
OK - If command accepted
ERROR - If an error occurs
Command works in non-blocking mode. Callback function BleApp_EvtCharAdded() is called when the characteristic has been successfully added.
BleApp_EvtCharAdded(handle, srvchandle, charhandle, uuid)
Called when the characteristic has been successfully added and returns the handle of the added characteristic
handle : s32 - Handle of a specific BLE Scanner App interface
srvchandle : s32 - Service handle of the primary service
charhandle : s32 - Handle of the added characteristic
uuid : u16 - Characteristic UUID of the added characteristic in decimal format
BleApp_SetChar(handle, charhandle, data{}, len)
Sets the content of a characteristic characteristic
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
charhandle : s32 - Handle of a specific BLE characteristic (Received via BleApp_EvtCharAdded())
data{} : u8 - Data to write
len : s32 - Length of the data
returns : s32
OK - If successful
ERROR - If an error occurs
TBleApp_Adv:
BLE advertising configuration
name{31+1} : astr - Advertising name
itv : s32 - Advertising interval [ms] (min = 20, max = 1024)
type : BLEAPP_ADV_TYPES_x - Advertising type
company_id : s32 - Bluetooth SIG company ID
A valid company ID must be specified. For internal testing a company ID of 0xFFFF can be used, but this value must not be present on shipping end products!
For more information please refer to the Company Identifiers Specification.
adv_buf{23} : u8 - Advertising data (Response to a passive scan, see BleApp_Scan() )
adv_buflen : s32 - Advertising data length
sr_buf{23} : u8 - Scan response data (Response to a active scan, see BleApp_Scan() )
sr_buflen : s32 - Scan response data length
BLEAPP_ADV_TYPES_x:
Possible advertising types
BLEAPP_ADV_TYPE_NONE = -1 - Incorrect type specified
BLEAPP_ADV_TYPE_IND = 0 - Connectable undirected
BLEAPP_ADV_TYPE_DIRECT_IND = 1 - Connectable directed
BLEAPP_ADV_TYPE_SCAN_IND = 2 - Scannable undirected
BLEAPP_ADV_TYPE_NONCONN_IND = 3 - Non connectable undirected
BleApp_Advertise(handle, enable, sAdv[TBleApp_Adv]=[0])
Start advertising
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
enable : s32 - Set advertising state
0 - disabled
1 - enabled
sAdv : TBleApp_Adv - BLE advertising configuration
returns : s32
OK - If command accepted
ERROR - if one of the following errors occurs:
< OK - if another error occurs
Command works in non-blocking mode. Callback function BleApp_EvtAdvertise() is called when start advertising command has been processed.
BleApp_EvtAdvertise(handle, status)
Called when start advertising command has been processed.
handle : s32 - Handle of a specific BLE Scanner App interface
status : s32 - Advertising status
0 - no advertising,
1 - advertising active
BleApp_EvtConnected(handle, connected, addr{6})
Called when:
handle : s32 - Handle of a specific BLE Scanner App interface
connected : s32 - Connection state
0 - disconnected
1 - connected
addr{6} : u8 - HW address of the BLE central device
This function will be called unsolicited if a BLE central device has established a connection (see BleApp_EvtConnect()) or an existing connection was interrupted.
BleApp_EvtWritten(handle, charhandle, data{}, len)
Called when data has been written to a characteristic by a BLE central device.
handle : s32 - Handle of a specific BLE Scanner App interface
charhandle : s32 - Handle of the characteristic that was written to by the BLE device
data{} : u8 - Data that was written
len : s32 - Length of the data that was written
This function will be called unsolicited if a BLE central device has written to a characteristic by a BLE central device (see BleApp_Write()).
TYPES
M22X:
BLEAPP_INTERFACE_x: s32
BLE Scanner App interfaces available for the selected device profile.
BLEAPP_INTERFACE_NONE = -1 - No interface
BLEAPP_INTERFACE_UART0 = 0 - UART0 interface (see TrM2M_UART_PORT)
BLEAPP_INTERFACE_UART1 = 1 - UART1 interface (see TrM2M_UART_PORT)
BLEAPP_STATE_x: s32
Possible operation state of a BLE Scanner App interface
BLEAPP_STATE_OFF = 0 - Interface currently OFF
BLEAPP_STATE_INIT = 1 - Init sequence active, not (yet) ready
BLEAPP_STATE_READY = 2 - Ready for receiving commands
BLEAPP_STATE_BUSY = 3 - Command currently active
BLE_EVENT_ERROR_x: s32
Internal error codes
BLE_ERROR_UNKNOWN = 0 - unspecified internal error
BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
BLE_ERROR_TIMEOUT = 4 - Internal communication timeout
M23X:
BLEAPP_INTERFACE_x: s32
BLE Scanner App interfaces available for the selected device profile.
BLEAPP_INTERFACE_NONE = -1 - No interface
BLEAPP_INTERFACE_UART0 = 0 - UART0 interface (see TrM2M_UART_PORT)
BLEAPP_INTERFACE_UART1 = 1 - UART1 interface (see TrM2M_UART_PORT)
BLEAPP_STATE_x: s32
Possible operation state of a BLE Scanner App interface
BLEAPP_STATE_OFF = 0 - Interface currently OFF
BLEAPP_STATE_INIT = 1 - Init sequence active, not (yet) ready
BLEAPP_STATE_READY = 2 - Ready for receiving commands
BLEAPP_STATE_BUSY = 3 - Command currently active
BLE_EVENT_ERROR_x: s32
Internal error codes
BLE_ERROR_UNKNOWN = 0 - unspecified internal error
BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
BLE_ERROR_TIMEOUT = 4 - Internal communication timeout
M2BLEGW:
BLEAPP_INTERFACE_x: s32
BLE Scanner App interfaces available for the selected device profile.
BLEAPP_INTERFACE_NONE = -1 - No interface
BLEAPP_INTERFACE_FIRMWARE = 0 - Firmware interface
BLEAPP_STATE_x: s32
Possible operation state of a BLE Scanner App interface
BLEAPP_STATE_OFF = 0 - Interface currently OFF
BLEAPP_STATE_INIT = 1 - Init sequence active, not (yet) ready
BLEAPP_STATE_READY = 2 - Ready for receiving commands
BLEAPP_STATE_BUSY = 3 - Command currently active
BLE_EVENT_ERROR_x: s32
Internal error codes
BLE_ERROR_UNKNOWN = 0 - Unspecified internal error
BLE_ERROR_INIT = 1 - Error during initialization (e.g chip not responding)
BLE_ERROR_IO = 2 - Error IO communication
BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
BLE_ERROR_TIMEOUT = 4 - Internal communication timeout
M2EASYIOT:
BLEAPP_INTERFACE_x: s32
BLE Scanner App interfaces available for the selected device profile.
BLEAPP_INTERFACE_NONE = -1 - No interface
BLEAPP_INTERFACE_FIRMWARE = 0 - Firmware interface
BLEAPP_STATE_x: s32
Possible operation state of a BLE Scanner App interface
BLEAPP_STATE_OFF = 0 - Interface currently OFF
BLEAPP_STATE_INIT = 1 - Init sequence active, not (yet) ready
BLEAPP_STATE_READY = 2 - Ready for receiving commands
BLEAPP_STATE_BUSY = 3 - Command currently active
BLE_EVENT_ERROR_x: s32
Internal error codes
BLE_ERROR_UNKNOWN = 0 - Unspecified internal error
BLE_ERROR_INIT = 1 - Error during initialization (e.g chip not responding)
BLE_ERROR_IO = 2 - Error IO communication
BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
NRF91:
BLEAPP_INTERFACE_x: s32
BLE Scanner App interfaces available for the selected device profile.
BLEAPP_INTERFACE_NONE = -1 - No interface
BLEAPP_INTERFACE_UART0 = 0 - UART0 interface (see TrM2M_UART_PORT)
BLEAPP_INTERFACE_UART1 = 1 - UART1 interface (see TrM2M_UART_PORT)
BLEAPP_STATE_x: s32
Possible operation state of a BLE Scanner App interface
BLEAPP_STATE_OFF = 0 - Interface currently OFF
BLEAPP_STATE_INIT = 1 - Init sequence active, not (yet) ready
BLEAPP_STATE_READY = 2 - Ready for receiving commands
BLEAPP_STATE_BUSY = 3 - Command currently active
BLE_EVENT_ERROR_x: s32
Internal error codes
BLE_ERROR_UNKNOWN = 0 - unspecified internal error
BLE_ERROR_RESTART = 3 - Automatic restart detected/forced
BLE_ERROR_TIMEOUT = 4 - Internal communication timeout
Expert
M22X:
Advanced Config:
The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings
add the following macro to the main.dde file.
/**
* Use this macro to adapt the advanced configuration settings:
*
*/
#define BLE_APP_MAX_CONNECTIONS 5 // Max. Number of simultaneous BLE connections (max. 5)
#define BLE_APP_MAX_SIZE_QUEUE 10 // Max. Number of queue entries for the command queue
#define BLE_APP_MAX_CMD_SIZE 128 // Max. size of one command queue entry
// Note:
// - Only necessary if UART buffers > 256 bytes are required.
// - If used, both settings (RX and TX) must be set.
//#define BLEAPP_AT_UART_RX_LEN 512 // Size of the UART RX buffer
//#define BLEAPP_AT_UART_TX_LEN 512 // Size of the UART TX buffer
#define BLEAPP_AT_LEN_CMD_QUEUE 5 // Max. number of pending commands
#define BLEAPP_AT_LINE_SIZE 128 // ASCII line size buffer for receive (i.e. Cmd rx buffer)
#define BLEAPP_AT_CMD_MAXLEN 128 // Number of characters within ASCII command buffer (i.e. Cmd tx buffer)
#define BLEAPP_AT_READ_DATA_SIZE 32 // Max. BLEAPP_READ_CALLBACK data size
#define BLEAPP_AT_NOTIFY_DATA_SIZE 32 // Max. BLEAPP_NOTIFY_CALLBACK data size
#define BLEAPP_AT_CMD_TO_DEFAULT 5000 // Default command timeout [ms], except for connect, disconnect and scan
#define BLEAPP_AT_CMD_TO_CONNECT 10000 // Default connect and disconnect timeout [ms]
#define BLEAPP_AT_CMD_TO_SCAN 30000 // Default scan timeout [ms]
#define BLEAPP_AT_CMD_TO_ECHO 3000 // Timeout until command must be echoed [ms]
BLE_APP_MAX_CONNECTIONS -
Max. Number of simultaneous BLE connections (Default = 5)
Values from 1 to 5 are valid
BLE_APP_MAX_SIZE_QUEUE -
Max. Number of queue entries for the command queue (Default = 10)
Set to 0 to disable queuing. The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
Disabling the queue can lead to BLE commands being lost and therefore is not recommended.
BLE_APP_MAX_CMD_SIZE -
Max. size of one queue entry (Default = 128).
The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
BLEAPP_AT_UART_x:
UART buffer settings
These defines only have to be set if the 256 byte buffers integrated in the firmware are insufficient. When using these defines, a switch is made from the buffers
integrated in the firmware to buffers from the RAM area reserved for the device logic.
However, both defines must always be set together in order to provide the BLE Scanner App
interface with larger buffers.
BLEAPP_AT_UART_RX_LEN - Size of the UART RX buffer
BLEAPP_AT_UART_TX_LEN - Size of the UART TX buffer
BLEAPP_AT_LEN_CMD_QUEUE -
Max. number of pending commands (Default = 5)
All commands are processed in non-blocking mode. Every command is added to an internal queue of BLEAPP_AT_LEN_CMD_QUEUE size and is processed if
the previous command has finished.
BLEAPP_AT_LINE_SIZE -
ASCII line size buffer for receive. (Default = 128)
This is the buffer in which data received from the BLE module (commando responses, unsolicited notifications) are stored before they are processed.
BLEAPP_AT_CMD_MAXLEN -
Number of characters within ASCII command buffer (Default = 128)
This is the buffer in which the commands to be sent to the BLE module are assembled.
The UART TX buffer must be greater than or equal to this buffer. If BLEAPP_AT_UART_TX_LEN was not defined, the UART TX buffer is 256 bytes
BLEAPP_AT_READ_DATA_SIZE -
Max. BLEAPP_READ_CALLBACK data size (Default = 32)
BLEAPP_AT_NOTIFY_DATA_SIZE -
Max. BLEAPP_NOTIFY_CALLBACK data size (Default = 32)
BLEAPP_AT_CMD_TO_DEFAULT -
Default command timeout [ms], except for connect, disconnect and scan (Default = 5000)
BLEAPP_AT_CMD_TO_CONNECT -
Default connect and disconnect timeout [ms] (Default = 10000)
BLEAPP_AT_CMD_TO_SCAN -
Default scan timeout (Default = 30000)
BLEAPP_AT_CMD_TO_ECHO -
Timeout until command must be echoed [ms] (Default = 3000)
M23X:
Advanced Config:
The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings
add the following macro to the main.dde file.
/**
* Use this macro to adapt the advanced configuration settings:
*
*/
#define BLE_APP_MAX_CONNECTIONS 5 // Max. Number of simultaneous BLE connections (max. 5)
#define BLE_APP_MAX_SIZE_QUEUE 10 // Max. Number of queue entries for the command queue
#define BLE_APP_MAX_CMD_SIZE 128 // Max. size of one command queue entry
// Note:
// - Only necessary if UART buffers > 256 bytes are required.
// - If used, both settings (RX and TX) must be set.
//#define BLEAPP_AT_UART_RX_LEN 512 // Size of the UART RX buffer
//#define BLEAPP_AT_UART_TX_LEN 512 // Size of the UART TX buffer
#define BLEAPP_AT_LEN_CMD_QUEUE 5 // Max. number of pending commands
#define BLEAPP_AT_LINE_SIZE 128 // ASCII line size buffer for receive (i.e. Cmd rx buffer)
#define BLEAPP_AT_CMD_MAXLEN 128 // Number of characters within ASCII command buffer (i.e. Cmd tx buffer)
#define BLEAPP_AT_READ_DATA_SIZE 32 // Max. BLEAPP_READ_CALLBACK data size
#define BLEAPP_AT_NOTIFY_DATA_SIZE 32 // Max. BLEAPP_NOTIFY_CALLBACK data size
#define BLEAPP_AT_CMD_TO_DEFAULT 5000 // Default command timeout [ms], except for connect, disconnect and scan
#define BLEAPP_AT_CMD_TO_CONNECT 10000 // Default connect and disconnect timeout [ms]
#define BLEAPP_AT_CMD_TO_SCAN 30000 // Default scan timeout [ms]
#define BLEAPP_AT_CMD_TO_ECHO 3000 // Timeout until command must be echoed [ms]
BLE_APP_MAX_CONNECTIONS -
Max. Number of simultaneous BLE connections (Default = 5)
Values from 1 to 5 are valid
BLE_APP_MAX_SIZE_QUEUE -
Max. Number of queue entries for the command queue (Default = 10)
Set to 0 to disable queuing. The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
Disabling the queue can lead to BLE commands being lost and therefore is not recommended.
BLE_APP_MAX_CMD_SIZE -
Max. size of one queue entry (Default = 128).
The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
BLEAPP_AT_UART_x:
UART buffer settings
These defines only have to be set if the 256 byte buffers integrated in the firmware are insufficient. When using these defines, a switch is made from the buffers
integrated in the firmware to buffers from the RAM area reserved for the device logic.
However, both defines must always be set together in order to provide the BLE Scanner App
interface with larger buffers.
BLEAPP_AT_UART_RX_LEN - Size of the UART RX buffer
BLEAPP_AT_UART_TX_LEN - Size of the UART TX buffer
BLEAPP_AT_LEN_CMD_QUEUE -
Max. number of pending commands (Default = 5)
All commands are processed in non-blocking mode. Every command is added to an internal queue of BLEAPP_AT_LEN_CMD_QUEUE size and is processed if
the previous command has finished.
BLEAPP_AT_LINE_SIZE -
ASCII line size buffer for receive. (Default = 128)
This is the buffer in which data received from the BLE module (commando responses, unsolicited notifications) are stored before they are processed.
BLEAPP_AT_CMD_MAXLEN -
Number of characters within ASCII command buffer (Default = 128)
This is the buffer in which the commands to be sent to the BLE module are assembled.
The UART TX buffer must be greater than or equal to this buffer. If BLEAPP_AT_UART_TX_LEN was not defined, the UART TX buffer is 256 bytes
BLEAPP_AT_READ_DATA_SIZE -
Max. BLEAPP_READ_CALLBACK data size (Default = 32)
BLEAPP_AT_NOTIFY_DATA_SIZE -
Max. BLEAPP_NOTIFY_CALLBACK data size (Default = 32)
BLEAPP_AT_CMD_TO_DEFAULT -
Default command timeout [ms], except for connect, disconnect and scan (Default = 5000)
BLEAPP_AT_CMD_TO_CONNECT -
Default connect and disconnect timeout [ms] (Default = 10000)
BLEAPP_AT_CMD_TO_SCAN -
Default scan timeout (Default = 30000)
BLEAPP_AT_CMD_TO_ECHO -
Timeout until command must be echoed [ms] (Default = 3000)
M2BLEGW:
Advanced Config:
The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings
add the following macro to the main.dde file.
/**
* Use this macro to adapt the advanced configuration settings:
*
*/
#define BLE_APP_MAX_CONNECTIONS 3 // Max. Number of simultaneous BLE connections (max. 3)
#define BLE_APP_MAX_SIZE_QUEUE 10 // Max. Number of queue entries for the command queue
#define BLE_APP_MAX_CMD_SIZE 128 // Max. size of one command queue entry
BLE_APP_MAX_CONNECTIONS -
Max. Number of simultaneous BLE connections (Default = 3)
Values from 1 to 3 are valid
BLE_APP_MAX_SIZE_QUEUE -
Max. Number of queue entries for the command queue (Default = 10)
Set to 0 to disable queuing. The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
Disabling the queue can lead to BLE commands being lost and therefore is not recommended.
BLE_APP_MAX_CMD_SIZE -
Max. size of one queue entry (Default = 128).
The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
M2EASYIOT:
Advanced Config:
The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings
add the following macro to the main.dde file.
/**
* Use this macro to adapt the advanced configuration settings:
*
*/
#define BLE_APP_MAX_CONNECTIONS 5 // Max. Number of simultaneous BLE connections (max. 5)
#define BLE_APP_MAX_SIZE_QUEUE 10 // Max. Number of queue entries for the command queue
#define BLE_APP_MAX_CMD_SIZE 128 // Max. size of one command queue entry
BLE_APP_MAX_CONNECTIONS -
Max. Number of simultaneous BLE connections (Default = 5)
Values from 1 to 5 are valid
BLE_APP_MAX_SIZE_QUEUE -
Max. Number of queue entries for the command queue (Default = 10)
Set to 0 to disable queuing. The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
Disabling the queue can lead to BLE commands being lost and therefore is not recommended.
BLE_APP_MAX_CMD_SIZE -
Max. size of one queue entry (Default = 128).
The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
BleApp_SendRawCmd(handle, cmd{}, cmdlen, timeout = 0)
Sends RAW AT-commands to BLE module
A RAW AT-command is directly routed to the BLE module. The Application is responsible for building proper AT-commands for the
BLE module linked to the used BLE Scanner App interface.
E.g. Stop advertising on NRF5x Scanner App: "at+advertise=0\r\n"
handle : s32 - Handle of a specific BLE Scanner App interface (Initialized by BleApp_Init() )
cmd{} : astr - RAW AT-Command
cmdlen : s32 - Number of command bytes.
The terminating '\0' after the command must be added
timeout : s32 - Response timeout
0 - use internal default timeout
> 0 - Response timeout in [ms]
returns : s32
OK - If command accepted
ERROR - if an error occurs
Command works in non-blocking mode. The callback function BleApp_EvtRawCmd() is called when a block of STRING/ASCII response data has been received. If all STRING/ASCII response
data has been received or if an error has occurred, the callback function BleApp_EvtRawCmdResult()
is called
BleApp_EvtRawCmd(handle, data{}, len)
Called when a block of STRING/ASCII response data has been received.
handle : s32 - Handle of a specific BLE Scanner App interface
data{} : astr - Data buffer with available response data
len : s32 - Number of bytes available within data buffer
BleApp_EvtRawCmdResult(handle, result, data{}, len)
Called if all STRING/ASCII response data has been received (i.e. AT-Command finished successfully) or if an error has occurred (i.e. AT-Command failed)
handle : s32 - Handle of a specific BLE Scanner App interface
result : s32
OK - command finished successfully
ERROR - command failed
data{} : astr - Data buffer with available response data
len : s32 - Number of bytes available within data buffer
NRF91:
Advanced Config:
The settings mentioned in this chapter should only be changed if really required (e.g. memory saving required). To adapt the settings
add the following macro to the main.dde file.
/**
* Use this macro to adapt the advanced configuration settings:
*
*/
#define BLE_APP_MAX_CONNECTIONS 5 // Max. Number of simultaneous BLE connections (max. 5)
#define BLE_APP_MAX_SIZE_QUEUE 10 // Max. Number of queue entries for the command queue
#define BLE_APP_MAX_CMD_SIZE 128 // Max. size of one command queue entry
// Note:
// - Only necessary if UART buffers > 256 bytes are required.
// - If used, both settings (RX and TX) must be set.
//#define BLEAPP_AT_UART_RX_LEN 512 // Size of the UART RX buffer
//#define BLEAPP_AT_UART_TX_LEN 512 // Size of the UART TX buffer
#define BLEAPP_AT_LEN_CMD_QUEUE 5 // Max. number of pending commands
#define BLEAPP_AT_LINE_SIZE 128 // ASCII line size buffer for receive (i.e. Cmd rx buffer)
#define BLEAPP_AT_CMD_MAXLEN 128 // Number of characters within ASCII command buffer (i.e. Cmd tx buffer)
#define BLEAPP_AT_READ_DATA_SIZE 32 // Max. BLEAPP_READ_CALLBACK data size
#define BLEAPP_AT_NOTIFY_DATA_SIZE 32 // Max. BLEAPP_NOTIFY_CALLBACK data size
#define BLEAPP_AT_CMD_TO_DEFAULT 5000 // Default command timeout [ms], except for connect, disconnect and scan
#define BLEAPP_AT_CMD_TO_CONNECT 10000 // Default connect and disconnect timeout [ms]
#define BLEAPP_AT_CMD_TO_SCAN 30000 // Default scan timeout [ms]
#define BLEAPP_AT_CMD_TO_ECHO 3000 // Timeout until command must be echoed [ms]
BLE_APP_MAX_CONNECTIONS -
Max. Number of simultaneous BLE connections (Default = 5)
Values from 1 to 5 are valid
BLE_APP_MAX_SIZE_QUEUE -
Max. Number of queue entries for the command queue (Default = 10)
Set to 0 to disable queuing. The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
Disabling the queue can lead to BLE commands being lost and therefore is not recommended.
BLE_APP_MAX_CMD_SIZE -
Max. size of one queue entry (Default = 128).
The required memory for the command queue is defined by BLE_APP_MAX_SIZE_QUEUE * BLE_APP_MAX_CMD_SIZE
BLEAPP_AT_UART_x:
UART buffer settings
These defines only have to be set if the 256 byte buffers integrated in the firmware are insufficient. When using these defines, a switch is made from the buffers
integrated in the firmware to buffers from the RAM area reserved for the device logic.
However, both defines must always be set together in order to provide the BLE Scanner App
interface with larger buffers.
BLEAPP_AT_UART_RX_LEN - Size of the UART RX buffer
BLEAPP_AT_UART_TX_LEN - Size of the UART TX buffer
BLEAPP_AT_LEN_CMD_QUEUE -
Max. number of pending commands (Default = 5)
All commands are processed in non-blocking mode. Every command is added to an internal queue of BLEAPP_AT_LEN_CMD_QUEUE size and is processed if
the previous command has finished.
BLEAPP_AT_LINE_SIZE -
ASCII line size buffer for receive. (Default = 128)
This is the buffer in which data received from the BLE module (commando responses, unsolicited notifications) are stored before they are processed.
BLEAPP_AT_CMD_MAXLEN -
Number of characters within ASCII command buffer (Default = 128)
This is the buffer in which the commands to be sent to the BLE module are assembled.
The UART TX buffer must be greater than or equal to this buffer. If BLEAPP_AT_UART_TX_LEN was not defined, the UART TX buffer is 256 bytes
BLEAPP_AT_READ_DATA_SIZE -
Max. BLEAPP_READ_CALLBACK data size (Default = 32)
BLEAPP_AT_NOTIFY_DATA_SIZE -
Max. BLEAPP_NOTIFY_CALLBACK data size (Default = 32)
BLEAPP_AT_CMD_TO_DEFAULT -
Default command timeout [ms], except for connect, disconnect and scan (Default = 5000)
BLEAPP_AT_CMD_TO_CONNECT -
Default connect and disconnect timeout [ms] (Default = 10000)
BLEAPP_AT_CMD_TO_SCAN -
Default scan timeout (Default = 30000)
BLEAPP_AT_CMD_TO_ECHO -
Timeout until command must be echoed [ms] (Default = 3000)