MetaWear C++ API  0.20.0
C++ implementation of the MetaWear protocol
Classes | Enumerations | Functions | Variables
settings.h File Reference

Configures Bluetooth Low Energy advertisement and connection settings. More...

#include <stdint.h>
#include "datasignal_fwd.h"
#include "event_fwd.h"
#include "metawearboard_fwd.h"
#include "metawear/platform/dllmarker.h"

Go to the source code of this file.

Classes

struct  MblMwBtleAddress
 BLE MAC Address. More...
 

Enumerations

enum  MblMwWhitelistFilter { MBL_MW_WHITELIST_FILTER_ALLOW_FROM_ANY = 0 , MBL_MW_WHITELIST_FILTER_SCAN_REQUESTS = 1 , MBL_MW_WHITELIST_FILTER_CONNECTION_REQUESTS = 2 , MBL_MW_WHITELIST_FILTER_SCAN_AND_CONNECTION_REQUESTS = 3 }
 Whitelist filter modes.
 
enum  MblMwBleAdType { MBL_MW_BLE_AD_TYPE_CONNECTED_UNDIRECTED = 0 , MBL_MW_BLE_AD_TYPE_CONNECTED_DIRECTED = 1 }
 

Functions

METAWEAR_API MblMwEventmbl_mw_settings_get_disconnect_event (const MblMwMetaWearBoard *board)
 Retrieves an event pointer representing a disconnect event. More...
 
METAWEAR_API MblMwDataSignalmbl_mw_settings_get_battery_state_data_signal (const MblMwMetaWearBoard *board)
 Retrieves the data signal representing battery state. More...
 
METAWEAR_API MblMwDataSignalmbl_mw_settings_get_mac_data_signal (const MblMwMetaWearBoard *board)
 Retrieves the data signal representing the device GAP (MAC) address. More...
 
METAWEAR_API MblMwDataSignalmbl_mw_settings_get_power_status_data_signal (const MblMwMetaWearBoard *board)
 Retrieves the data signal representing the power status. More...
 
METAWEAR_API MblMwDataSignalmbl_mw_settings_get_charge_status_data_signal (const MblMwMetaWearBoard *board)
 Retrieves the data signal representing the charge status. More...
 
METAWEAR_API void mbl_mw_settings_set_device_name (const MblMwMetaWearBoard *board, const uint8_t *device_name, uint8_t len)
 Sets the advertisement name Can be used to rename the device. More...
 
METAWEAR_API void mbl_mw_settings_set_ad_interval (const MblMwMetaWearBoard *board, uint16_t interval, uint8_t timeout)
 
METAWEAR_API void mbl_mw_settings_set_ad_parameters (const MblMwMetaWearBoard *board, uint16_t interval, uint8_t timeout, MblMwBleAdType type)
 Configures Bluetooth LE ad parameters. More...
 
METAWEAR_API void mbl_mw_settings_set_tx_power (const MblMwMetaWearBoard *board, int8_t tx_power)
 Sets advertising transmitting power. More...
 
METAWEAR_API void mbl_mw_settings_start_advertising (const MblMwMetaWearBoard *board)
 Starts advertising. More...
 
METAWEAR_API void mbl_mw_settings_set_scan_response (const MblMwMetaWearBoard *board, const uint8_t *response, uint8_t len)
 Sets scan response. More...
 
METAWEAR_API void mbl_mw_settings_set_connection_parameters (const MblMwMetaWearBoard *board, float min_conn_interval, float max_conn_interval, uint16_t latency, uint16_t timeout)
 Sets connection parameters. More...
 
METAWEAR_API void mbl_mw_settings_add_whitelist_address (const MblMwMetaWearBoard *board, uint8_t index, const MblMwBtleAddress *address)
 Adds MAC Addresses for Whitelist filtering. More...
 
METAWEAR_API MblMwDataSignalmbl_mw_settings_get_whitelist_data_signal (MblMwMetaWearBoard *board, uint8_t index)
 Adds MAC Addresses for Whitelist filtering. More...
 
METAWEAR_API void mbl_mw_settings_set_whitelist_filter_mode (const MblMwMetaWearBoard *board, MblMwWhitelistFilter mode)
 Sets connection parameters. More...
 
METAWEAR_API uint8_t mbl_mw_settings_get_firmware_build_id (const MblMwMetaWearBoard *board)
 Retrieves the firmware build id, used for identifying custom firmware build variants. More...
 
METAWEAR_API void mbl_mw_settings_read_current_power_status (MblMwMetaWearBoard *board, void *context, MblMwFnBoardPtrInt handler)
 Reads the current power status if available. More...
 
METAWEAR_API void mbl_mw_settings_read_current_charge_status (MblMwMetaWearBoard *board, void *context, MblMwFnBoardPtrInt handler)
 Reads the current charge status. More...
 
METAWEAR_API void mbl_mw_settings_enable_3V_regulator (const MblMwMetaWearBoard *board, uint8_t enable)
 Turns on the 3V regulator Needed if IOs / peripherals need 3V power from the MetaSensor For MMS only, will be ignored for all others. More...
 

Variables

const uint8_t MBL_MW_SETTINGS_BATTERY_VOLTAGE_INDEX = 0
 < Indices for component values of the battery data signal, to be used with mbl_mw_datasignal_get_component
 
const uint8_t MBL_MW_SETTINGS_BATTERY_CHARGE_INDEX = 1
 
const uint8_t MBL_MW_ADDRESS_TYPE_PUBLIC = 0
 Types of BLE addresses.
 
const uint8_t MBL_MW_ADDRESS_TYPE_RANDOM_STATIC = 1
 
const uint8_t MBL_MW_ADDRESS_TYPE_PRIVATE_RESOLVABLE = 2
 
const uint8_t MBL_MW_ADDRESS_TYPE_PRIVATE_NON_RESOLVABLE = 3
 
const int32_t MBL_MW_SETTINGS_POWER_STATUS_UNSUPPORTED = -1
 < Values returned if the power or charge statuses are not supported
 
const int32_t MBL_MW_SETTINGS_CHARGE_STATUS_UNSUPPORTED = -1
 

Detailed Description

Configures Bluetooth Low Energy advertisement and connection settings.

Function Documentation

◆ mbl_mw_settings_add_whitelist_address()

METAWEAR_API void mbl_mw_settings_add_whitelist_address ( const MblMwMetaWearBoard board,
uint8_t  index,
const MblMwBtleAddress address 
)

Adds MAC Addresses for Whitelist filtering.

Parameters
boardBoard to modify
indexWhitelist MAC address in range [1, 8], must start at 1 and go in increasing order
addressAddress to add

◆ mbl_mw_settings_enable_3V_regulator()

METAWEAR_API void mbl_mw_settings_enable_3V_regulator ( const MblMwMetaWearBoard board,
uint8_t  enable 
)

Turns on the 3V regulator Needed if IOs / peripherals need 3V power from the MetaSensor For MMS only, will be ignored for all others.

Parameters
boardBoard to modify
index0: Disable, 1: Enable

◆ mbl_mw_settings_get_battery_state_data_signal()

METAWEAR_API MblMwDataSignal* mbl_mw_settings_get_battery_state_data_signal ( const MblMwMetaWearBoard board)

Retrieves the data signal representing battery state.

Parameters
boardCalling object
Returns
Pointer to the battery state signal

◆ mbl_mw_settings_get_charge_status_data_signal()

METAWEAR_API MblMwDataSignal* mbl_mw_settings_get_charge_status_data_signal ( const MblMwMetaWearBoard board)

Retrieves the data signal representing the charge status.

Parameters
boardCalling object
Returns
Pointer to the charge status signal, nullptr if unsupported

◆ mbl_mw_settings_get_disconnect_event()

METAWEAR_API MblMwEvent* mbl_mw_settings_get_disconnect_event ( const MblMwMetaWearBoard board)

Retrieves an event pointer representing a disconnect event.

Parameters
boardBoard the event is fired on
Returns
Pointer to the disconnect event

◆ mbl_mw_settings_get_firmware_build_id()

METAWEAR_API uint8_t mbl_mw_settings_get_firmware_build_id ( const MblMwMetaWearBoard board)

Retrieves the firmware build id, used for identifying custom firmware build variants.

Parameters
boardCalling object

◆ mbl_mw_settings_get_mac_data_signal()

METAWEAR_API MblMwDataSignal* mbl_mw_settings_get_mac_data_signal ( const MblMwMetaWearBoard board)

Retrieves the data signal representing the device GAP (MAC) address.

Parameters
boardCalling object
Returns
Pointer to the mac signal

◆ mbl_mw_settings_get_power_status_data_signal()

METAWEAR_API MblMwDataSignal* mbl_mw_settings_get_power_status_data_signal ( const MblMwMetaWearBoard board)

Retrieves the data signal representing the power status.

Parameters
boardCalling object
Returns
Pointer to the power status signal, nullptr if unsupported

◆ mbl_mw_settings_get_whitelist_data_signal()

METAWEAR_API MblMwDataSignal* mbl_mw_settings_get_whitelist_data_signal ( MblMwMetaWearBoard board,
uint8_t  index 
)

Adds MAC Addresses for Whitelist filtering.

Parameters
boardBoard to modify
indexWhitelist MAC address in range [1, 8], must start at 1 and go in increasing order
addressAddress to add

◆ mbl_mw_settings_read_current_charge_status()

METAWEAR_API void mbl_mw_settings_read_current_charge_status ( MblMwMetaWearBoard board,
void *  context,
MblMwFnBoardPtrInt  handler 
)

Reads the current charge status.

The callback function will be called with:
1 - battery is charging
0 - battery is not charging
-1 - feature not supported

◆ mbl_mw_settings_read_current_power_status()

METAWEAR_API void mbl_mw_settings_read_current_power_status ( MblMwMetaWearBoard board,
void *  context,
MblMwFnBoardPtrInt  handler 
)

Reads the current power status if available.

The callback function will be called with:
1 - power source is attached
0 - no power source atached
-1 - feature not supported

Parameters
boardCalling object
contextPointer to additional data for the callback function
handlerCallback function that is executed when the task is finished

◆ mbl_mw_settings_set_ad_interval()

METAWEAR_API void mbl_mw_settings_set_ad_interval ( const MblMwMetaWearBoard board,
uint16_t  interval,
uint8_t  timeout 
)
Deprecated:
In v0.14.0, use mbl_mw_settings_set_ad_parameters instead

◆ mbl_mw_settings_set_ad_parameters()

METAWEAR_API void mbl_mw_settings_set_ad_parameters ( const MblMwMetaWearBoard board,
uint16_t  interval,
uint8_t  timeout,
MblMwBleAdType  type 
)

Configures Bluetooth LE ad parameters.

Parameters
boardCalling object
intervalAdvertisement interval, between [0, 65535] milliseconds
timeoutAdvertisement timeout, between [0, 180] seconds where 0 indicates no timeout
typeAdvertisement type, ignored if unsupported on current firmware

◆ mbl_mw_settings_set_connection_parameters()

METAWEAR_API void mbl_mw_settings_set_connection_parameters ( const MblMwMetaWearBoard board,
float  min_conn_interval,
float  max_conn_interval,
uint16_t  latency,
uint16_t  timeout 
)

Sets connection parameters.

Parameters
boardBoard to modify
min_conn_intervalConnection interval lower bound, min 7.5ms
max_conn_intervalConnection interval upper bound, max 4000ms
latencyNumber of connection intervals to skip, betwen [0, 1000]
timeoutMax time between data exchanges until the connection is considered to be lost, between [10, 32000]ms

◆ mbl_mw_settings_set_device_name()

METAWEAR_API void mbl_mw_settings_set_device_name ( const MblMwMetaWearBoard board,
const uint8_t *  device_name,
uint8_t  len 
)

Sets the advertisement name Can be used to rename the device.

Parameters
boardBoard to modify
device_nameByte array containing the device name, max 8 ASCII characters
lenLength of the array

◆ mbl_mw_settings_set_scan_response()

METAWEAR_API void mbl_mw_settings_set_scan_response ( const MblMwMetaWearBoard board,
const uint8_t *  response,
uint8_t  len 
)

Sets scan response.

Parameters
boardBoard to modify
responseScan response as a byte array
lenLength of the array

◆ mbl_mw_settings_set_tx_power()

METAWEAR_API void mbl_mw_settings_set_tx_power ( const MblMwMetaWearBoard board,
int8_t  tx_power 
)

Sets advertising transmitting power.

If a non valid value is set, the nearest valid value will be used instead

Parameters
boardBoard to set the TX power
tx_powerValid values are: 4, 0, -4, -8, -12, -16, -20, -30

◆ mbl_mw_settings_set_whitelist_filter_mode()

METAWEAR_API void mbl_mw_settings_set_whitelist_filter_mode ( const MblMwMetaWearBoard board,
MblMwWhitelistFilter  mode 
)

Sets connection parameters.

Parameters
boardBoard to modify
modeWhitelist filter mode

◆ mbl_mw_settings_start_advertising()

METAWEAR_API void mbl_mw_settings_start_advertising ( const MblMwMetaWearBoard board)

Starts advertising.

Parameters
boardBoard to start btle advertisement