#include "ruuvi_driver_enabled_modules.h"
#include "ruuvi_driver_error.h"
#include "ruuvi_interface_communication.h"
#include "ruuvi_interface_communication_radio.h"
#include <stdint.h>

Data Structures
struct	ri_adv_scan_t

Macros
#define	RUUVI_COMM_BLE_ADV_MAX_LENGTH (RI_COMM_BLE_PAYLOAD_MAX_LENGTH)

#define	RUUVI_COMM_BLE_ADV_SCAN_LENGTH (RUUVI_COMM_BLE_ADV_MAX_LENGTH)

#define	RUUVI_COMM_BLE_ADV_SCAN_BUFFER (RUUVI_COMM_BLE_ADV_MAX_LENGTH)

#define	BLE_MAC_ADDRESS_LENGTH 6

Enumerations
enum	ri_adv_type_t { NONCONNECTABLE_NONSCANNABLE , CONNECTABLE_NONSCANNABLE , CONNECTABLE_SCANNABLE , NONCONNECTABLE_SCANNABLE }
	Allowed advertisement types. More...

Functions
rd_status_t	ri_adv_init (ri_comm_channel_t *const channel)
	Initialize Advertising module and scanning module. More...

void	ri_adv_rx_ble_phy_enabled_set (const bool is_le_1m_phy_enabled, const bool is_le_2m_phy_enabled, const bool is_le_coded_phy_enabled)
	Set BLE PHYs enabled or disabled for scanning. More...

void	ri_adv_rx_set_max_advertisement_data_length (const uint8_t max_adv_length)
	Set maximum advertisement data length. This is used to limit the size of extended advertisement data. More...

rd_status_t	ri_adv_uninit (ri_comm_channel_t *const channel)

rd_status_t	ri_adv_tx_interval_set (const uint32_t ms)

rd_status_t	ri_adv_tx_interval_get (uint32_t *ms)
	Getter for broadcast advertisement interval. More...

rd_status_t	ri_adv_manufacturer_id_set (const uint16_t id)
	Set manufacturer ID of manufacturer specific advertisement. More...

rd_status_t	ri_adv_channels_set (const ri_radio_channels_t channels)
	Set channels to use on radio. This has effect only on BLE advertising. More...

rd_status_t	ri_adv_tx_power_set (int8_t *dbm)
	Set radio TX power. More...

rd_status_t	ri_adv_tx_power_get (int8_t *dbm)
	Get radio TX power. More...

rd_status_t	ri_adv_scan_response_setup (const char *const name, const bool advertise_nus)
	Configure advertising data with a scan response. More...

rd_status_t	ri_adv_type_set (ri_adv_type_t type)
	Configure the type of advertisement. More...

rd_status_t	ri_adv_stop (void)
	Stop ongoing advertisements. More...

rd_status_t	ri_adv_scan_start (const uint32_t window_interval_ms, const uint32_t window_size_ms)
	setup scan window interval and window size. More...

rd_status_t	ri_adv_scan_stop (void)
	Stop ongoing scanning. More...

rd_status_t	ri_adv_channels_enable (const ri_radio_channels_t channel)
	Select active channels. More...

uint16_t	ri_adv_parse_manuid (uint8_t *const data, const size_t data_length)
	Parse Manufacturer ID from given Bluetooth scan data. More...

void	ri_adv_enable_uuid (const bool enable_uuid)
	Set to true to enable advertising 16-bit service UUID in primary advertisement packet. More...

void	ri_adv_set_service_uuid (const uint16_t uuid)
	Configure Bluetooth GATT Service UUID to advertise in primary advertisement packet. More...

Detailed Description

Author: Otso Jousimaa otso@.nosp@m.ojou.nosp@m.sima..nosp@m.net

Date: 2020-03-26

Copyright: Ruuvi Innovations Ltd, license BSD-3-Clause.

Common definitions and functions for all BLE advertising.

Definition in file ruuvi_interface_communication_ble_advertising.h.

Macro Definition Documentation

◆ BLE_MAC_ADDRESS_LENGTH

#define BLE_MAC_ADDRESS_LENGTH 6

Definition at line 29 of file ruuvi_interface_communication_ble_advertising.h.

◆ RUUVI_COMM_BLE_ADV_MAX_LENGTH

#define RUUVI_COMM_BLE_ADV_MAX_LENGTH (RI_COMM_BLE_PAYLOAD_MAX_LENGTH)

Definition at line 24 of file ruuvi_interface_communication_ble_advertising.h.

◆ RUUVI_COMM_BLE_ADV_SCAN_BUFFER

#define RUUVI_COMM_BLE_ADV_SCAN_BUFFER (RUUVI_COMM_BLE_ADV_MAX_LENGTH)

Definition at line 26 of file ruuvi_interface_communication_ble_advertising.h.

◆ RUUVI_COMM_BLE_ADV_SCAN_LENGTH

#define RUUVI_COMM_BLE_ADV_SCAN_LENGTH (RUUVI_COMM_BLE_ADV_MAX_LENGTH)

Definition at line 25 of file ruuvi_interface_communication_ble_advertising.h.

Enumeration Type Documentation

◆ ri_adv_type_t

enum ri_adv_type_t

Allowed advertisement types.

Enumerator
NONCONNECTABLE_NONSCANNABLE	Nonconnectable, nonscannable.
CONNECTABLE_NONSCANNABLE	Connectable, nonscannable.
CONNECTABLE_SCANNABLE	Connectable, scannable.
NONCONNECTABLE_SCANNABLE	Nonconnectable, scannable.

Definition at line 32 of file ruuvi_interface_communication_ble_advertising.h.

Function Documentation

◆ ri_adv_channels_enable()

rd_status_t ri_adv_channels_enable ( const ri_radio_channels_t channel )

Select active channels.

If advertisement was configured on repeat, calling this function has no effect to advertisements on send queue.

Return values

RD_SUCCESS if no more advertisements are ongoing.

◆ ri_adv_channels_set()

rd_status_t ri_adv_channels_set ( const ri_radio_channels_t channels )

Set channels to use on radio. This has effect only on BLE advertising.

The function call will not modify already queued advertisements, it will take effect on advertisements queued after this call has finished.

Parameters

[in] channels Channels to advertise on.

Return values

RD_SUCCESS

◆ ri_adv_enable_uuid()

void ri_adv_enable_uuid ( const bool enable_uuid )

Set to true to enable advertising 16-bit service UUID in primary advertisement packet.

Bluetooth Service UUID lets scanner apps note that your firmware is providing a specific service over BLE GATT. Be sure to configure ri_adv_set_service_uuid, otherwise your program violates Bluetooth license terms. You must have the license to use the configured UUID.

When enabled, the field takes 3 bytes of space in advertisement.

Parameters

[in] enable_uuid true to enable Service UUID advertisement, false to disable.

◆ ri_adv_init()

rd_status_t ri_adv_init ( ri_comm_channel_t *const channel )

Initialize Advertising module and scanning module.

Initially channels 37, 38 and 39 are enabled. Modulation is decided by radio initialization. If RI_RADIO_BLE_125KBPS or RI_RADIO_BLE_1MBPS is set, primary phy is the configured one and no secondary PHY is used. If modulation is RI_RADIO_BLE_2MBPS primary PHY is RI_RADIO_BLE_1MBPS and secondary PHY is RI_RADIO_BLE_2MBPS.

Parameters

[out] channel Interface used for communicating through advertisements.

Return values

RD_SUCCESS	on success,
RD_ERROR_NULL	Channel is NULL.
RD_ERROR_INVALID_STATE	if radio is not already initialized.

Note: Modulation used on the advertisement depends on how radio was initialized.

◆ ri_adv_manufacturer_id_set()

rd_status_t ri_adv_manufacturer_id_set ( const uint16_t id )

Set manufacturer ID of manufacturer specific advertisement.

Will take effect on next send. Has no effect on already queued messages.

Parameters

[in] id ID of manufacturer, MSB first. E.g. 0x0499 for Ruuvi Innovations.

Return values

RD_SUCCESS

◆ ri_adv_parse_manuid()

uint16_t ri_adv_parse_manuid	(	uint8_t *const	data,
		const size_t	data_length
	)

Parse Manufacturer ID from given Bluetooth scan data.

Parameters

[in]	data	pointer to data to parse
[in]	data_length	length of data to parse

Return values

0	if argument is NULL of manufacturer ID not found

Returns: BLE Manufacturer ID, e.g. 0x0499 for Ruuvi Innovation

◆ ri_adv_rx_ble_phy_enabled_set()

void ri_adv_rx_ble_phy_enabled_set	(	const bool	is_le_1m_phy_enabled,
		const bool	is_le_2m_phy_enabled,
		const bool	is_le_coded_phy_enabled
	)

Set BLE PHYs enabled or disabled for scanning.

Parameters

[in]	is_le_1m_phy_enabled	True if 1 MBit/s PHY is enabled.
[in]	is_le_2m_phy_enabled	True if 2 MBit/s PHY is enabled.
[in]	is_le_coded_phy_enabled	True if 125 kBit/s PHY is enabled.

◆ ri_adv_rx_set_max_advertisement_data_length()

void ri_adv_rx_set_max_advertisement_data_length ( const uint8_t max_adv_length )

Set maximum advertisement data length. This is used to limit the size of extended advertisement data.

Parameters

[in] max_adv_length Maximum length of advertisement data. If zero, the maximum length is not checked and it is limited by macro RUUVI_COMM_BLE_ADV_SCAN_LENGTH.

◆ ri_adv_scan_response_setup()

rd_status_t ri_adv_scan_response_setup	(	const char *const	name,
		const bool	advertise_nus
	)

Configure advertising data with a scan response.

The scan response must be separately enabled by setting advertisement type as scannable. This setting has effect starting from the next time send is called.

Parameters

[in]	name	Name to advertise, NULL-terminated string. Max 27 characters if not advertising NUS, 10 characters if NUS is advertised. NULL won't be included in advertisement.
[in]	advertise_nus	True to include Nordic UART Service UUID in scan response.

Return values

RD_SUCCESS	on success
RD_ERROR_NULL	if name is NULL
RD_ERROR_DATA_SIZE	if name will be cut. However the abbreviated name will be set.

◆ ri_adv_scan_start()

rd_status_t ri_adv_scan_start	(	const uint32_t	window_interval_ms,
		const uint32_t	window_size_ms
	)

setup scan window interval and window size.

The scan window interval must be larger or equivalent to window size. Example: Interval 1000 ms, window size 100 ms. The scanning will scan 100 ms at channel 37, wait 900 ms, scan 100 ms at channel 38, wait 900 ms, scan 100 ms at channel 39. After scan has finished RI_COMM_TIMEOUT event is triggered if initialized channel has event handler.

Scan is started immediately after calling this function and ended once timeout occurs or ri_adv_scan_stop is called.

Raw scan results are passed to given event handler as on_received events with ri_adv_scan_t as a parameter.

If the message contains Ruuvi-specific advertisement data, the payload is inserted into a ri_comm_message_t with repeat = 0 and it can be read via channel->read

This function is not suitable for establishing connections to peripherals, if central mode is supported in the future a separate connection initialization function is implemented.

Parameters

[in]	window_interval_ms	interval of the windows. At most 10s.
[in]	window_size_ms	window size within interval. Smaller or equal to interval.

Returns: RD_SUCCESS on success.; RD_ERROR_INVALID_STATE If scan is ongoing or if trying to scan on other than 1 MBit / s PHY without extended advertising enabled.; RD_ERROR_INVALID_PARAM if window is larger than interval or values are otherwise invalid.

◆ ri_adv_scan_stop()

rd_status_t ri_adv_scan_stop ( void )

Stop ongoing scanning.

If advertisement was configured on repeat, calling this function stops advertising before the repeat counter has been reached. This function can be safely called even if no advertising is ongoing.

Return values

RD_SUCCESS if no more advertisements are ongoing.

◆ ri_adv_set_service_uuid()

void ri_adv_set_service_uuid ( const uint16_t uuid )

Configure Bluetooth GATT Service UUID to advertise in primary advertisement packet.

Bluetooth Service UUID lets scanner apps note that your firmware is providing a specific service over BLE GATT. Be sure to enable ri_adv_enable_uuid.

When enabled, the field takes 3 bytes of space in advertisement.

Parameters

[in] uuid 16-bit UUID to advertise, e.g. 0xFC98 for "Ruuvi Innovations Sensor Data"

◆ ri_adv_stop()

rd_status_t ri_adv_stop ( void )

Stop ongoing advertisements.

If advertisement was configured on repeat, calling this function stops advertising before the repeat counter has been reached. Any queued advertisements are cancelled. This function can be safely called even if no advertising is ongoing.

Return values

RD_SUCCESS if no more advertisements are ongoing.

◆ ri_adv_tx_interval_get()

rd_status_t ri_adv_tx_interval_get ( uint32_t * ms )

Getter for broadcast advertisement interval.

Parameters

[out] ms Milliseconds between transmission, without the random delay.

Return values

RD_SUCCESS	on success.
RD_ERROR_NULL	If ms is NULL.
RD_ERROR_INVALID_STATE	if advertisement module is not initialized.

◆ ri_adv_tx_interval_set()

rd_status_t ri_adv_tx_interval_set ( const uint32_t ms )

◆ ri_adv_tx_power_get()

rd_status_t ri_adv_tx_power_get ( int8_t * dbm )

Get radio TX power.

Parameters

[out] dbm Radio power.

Return values

RD_SUCCESS	on success
RD_ERROR_NULL	if dbm is NULL.
RD_ERROR_INVALID_STATE	if radio is not initialized.

◆ ri_adv_tx_power_set()

rd_status_t ri_adv_tx_power_set ( int8_t * dbm )

Set radio TX power.

Takes effect on next call to send, messages already in send queue are not affected.

Parameters

[in,out] dbm Radio power. Supported values are board-dependent. Value is interpreted as "at least", power is set to smallest value which satisfies the desired level. Actual value is set to pointed parameter as an output.

Return values

RD_SUCCESS	on success
RD_ERROR_NULL	if dbm is NULL.
RD_ERROR_INVALID_STATE	if radio is not initialized.
RD_ERROR_INVALID_PARAM	if given power level is not supported.

◆ ri_adv_type_set()

rd_status_t ri_adv_type_set ( ri_adv_type_t type )

Configure the type of advertisement.

Advertisement can be connectable, scannable, both or neither: ri_adv_type_t. It is possible to setup scannable advertisement before setting up scan response, in this case scan response will be 0-length and empty until scan resonse if configured. If the advertisement has to be extended type, the implementation will automatically select extended advertisement.

Return values

RD_SUCCESS	on success.
RD_ERROR_INVALID_STATE	if advertisements are not initialized.

◆ ri_adv_uninit()

rd_status_t ri_adv_uninit ( ri_comm_channel_t *const channel )

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ BLE_MAC_ADDRESS_LENGTH

◆ RUUVI_COMM_BLE_ADV_MAX_LENGTH

◆ RUUVI_COMM_BLE_ADV_SCAN_BUFFER

◆ RUUVI_COMM_BLE_ADV_SCAN_LENGTH

Enumeration Type Documentation

◆ ri_adv_type_t

Function Documentation

◆ ri_adv_channels_enable()

◆ ri_adv_channels_set()

◆ ri_adv_enable_uuid()

◆ ri_adv_init()

◆ ri_adv_manufacturer_id_set()

◆ ri_adv_parse_manuid()

◆ ri_adv_rx_ble_phy_enabled_set()

◆ ri_adv_rx_set_max_advertisement_data_length()

◆ ri_adv_scan_response_setup()

◆ ri_adv_scan_start()

◆ ri_adv_scan_stop()

◆ ri_adv_set_service_uuid()

◆ ri_adv_stop()

◆ ri_adv_tx_interval_get()

◆ ri_adv_tx_interval_set()

◆ ri_adv_tx_power_get()

◆ ri_adv_tx_power_set()

◆ ri_adv_type_set()

◆ ri_adv_uninit()