Helper to schedule and construct beacons. More...

#include <nrfcxx/sd/beacon.hpp>

Inheritance diagram for nrfcxx::sd::Beacon:

Data Structures
struct	frame_prefix_s
	Structure providing the prefix for most beacon content. More...

struct	telemetry_state_type
	State retained across resets that is used in telemetry beacons. More...

Public Types
enum	state_e : uint8_t { INVALID = 0, FAILED, INACTIVE, CANCELLED, SCHEDULED_PREPARE, SCHEDULED, READY, ACTIVE }
	Values representing the beacon state. More...

using	crc_type = uint16_t
	Natively-supported checksum is CRC-16/DNP.

Public Member Functions
virtual	~Beacon ()
	The beacon is stopped on destruction.

state_e	state () const
	Return the current beacon state. More...

int	validate () const
	Test whether the beacon is in a valid state. More...

unsigned int	min_interval_utt () const
	Minimum interval between transmissions, in uptime ticks.

unsigned int	interval_utt () const
	Current interval between transmissions, in uptime ticks.

unsigned int	max_interval_utt () const
	Maximum interval between transmissions, in uptime ticks.

unsigned int	prepare_backoff_utt () const
	Duration before beacon transmission that a pre-transmission notification will occur, in uptime ticks.

int	set_interval (unsigned int utt)
	Configure a fixed interval. More...

int	set_interval (unsigned int min_utt, unsigned int max_utt)
	Configure an exponential back-off interval. More...

int	set_prepare_backoff (notifier_type notify, unsigned int backoff_utt)
	Configure notification that a beacon will transmit soon. More...

void	set_tx_notify (notifier_type notify)
	Configure notification that a beacon is being sent. More...

uint8_t	dt_flags () const
	Get the GAP ASD Flags data type value to use in the beacon.

void	dt_flags (uint8_t v)
	Set the GAP ASD Flags data type value to use in the beacon.

int8_t	dt_tx_power () const
	Get the GAP ASD Tx Power data type value to use in the beacon.

void	dt_tx_power (int8_t v)
	Set the GAP ASD Tx Power data type value to use in the beacon.

int	reset_interval ()
	Reset the interval so the beacon is retransmitted as quickly as possible. More...

int	activate ()
	Enable the beacon. More...

int	deactivate ()
	Disable the beacon.

unsigned int	tx_count () const
	Return the number of transmissions since activation.

template<typename FT >
crc_type	update_crc (FT *bp)
	Helper to store a checksum immediately following a frame instance. More...

Static Public Member Functions
static const telemetry_state_type &	telemetry_state ()
	Access the current telemetry state.

static const Beacon *	active ()

static void	set_notify (notifier_type notify)
	Register the notifier that signals application to process a beacon event.

static int	process_event ()
	Method to be invoked by main loop when a beacon-related event occurs.

static int	process_completion ()
	Method to be invoked by main loop when the beacon has been transmitted.

static void	telemetry_state_setup (const systemState::state_type &ss, bool is_reset, bool retained)
	Function to maintain beacon telemetry state across resets. More...

Static Public Attributes
static constexpr size_t	MAX_MSD_LENGTH = 19 + sizeof(crc_type)
	The maximum length of a Manufacturer Specific Data PDU. More...

static constexpr uint16_t	COMPANY_ID = -1
	The value to be used as the company ID for manufacturer specific data. More...

static constexpr uint8_t	APP_FRAME_TYPE_BASE = 0x80
	Minimum value for frame_prefix_s::frame_type available for application beacons. More...

static constexpr uint8_t	APP_FRAME_TYPE_LIMIT = 0xEF
	Maximum value for frame_prefix_s::frame_type available for application beacons. More...

static constexpr uint8_t	FRAME_TYPE_TEST = 0xFF
	Frame type reserved for test applications.

Protected Member Functions
	Beacon ()
	Construct a new beacon.

virtual int	pre_activate_ ()
	Called by activate() to make sure everything needed for activation is present.

crc_type	update_crc_ (uint8_t *sp, size_t span)
	Function to calculate a checksum and store it after the data. More...

virtual int	populate_ (pabigot::ble::gap::adv_data &ad)
	Function that must be overridden to fill in beacon content. More...

Detailed Description

Helper to schedule and construct beacons.

This is a base class associated with a specific beacon, e.g. sensor values or telemetry. The beacon interval is configured to range from a minimum to a maximum, with exponential back-off until a reset_interval() operation causes the interval to be reduced to its minimum. Prior to transmission an optional callback is invoked to update the beacon content. Beacons can be disabled. Multiple beacons can be active simultaneously.

Subclasses should override populate_(). When designing a beacon payload, consider that the standard BLE 4 advertising packet is 31 octets, which may be used this way:

3 octets FLAG
3 octets TX_POWER (if dt_tx_power() is not zero)
4 octets MFG_DATA header (length, type, company id) or other
19 octets MFG_DATA payload available, starting with frame_prefix_s
2 octets MFG_DATA suffix for CRC-16/DNP provided by update_crc().

Applications must configure the Beacon infrastructure using set_notify(), then invoke process_event() when the corresponding notification event is received. They must also register for soft-device radio notifications and invoke process_completion() when the radio off event is received.

Currently defined infrastructure frame types include

0x00 Telemetry carrying power source voltage, uptime and advertisement count, and information on duty cycle and activity.
0x01 System State carrying material from systemState::state_type including reset reasons and diagnostics, as well as current resource allocations.
0x02 Environmental Sensor carrying temperature, humidity, and related environment measures.
0x03 Application Id carrying the application checksum, soft-device version, processor identification, and related information.
0x04 through 0x7F reserved for common infrastructure use
0x80 through 0xBF available for registered application use
0xC0 through 0xEF available for unregistered application use
0xF0 through 0xFE reserved
0xFF is reserved for test purposes

Registered application beacons supported by various examples include:

0x80 CCS811 status providing CCS811 version information and baseline maintenance status.

Member Enumeration Documentation

◆ state_e

enum nrfcxx::sd::Beacon::state_e : uint8_t

Values representing the beacon state.

Most transitions are performed under application control, either during setup or in response to events. The following transitions will occur asynchronously and may be delayed using nrfcxx::clock::uptime::mutex_type:

SCHEDULED_PREPARE to SCHEDULED
SCHEDULED to READY

Enumerator
INVALID	Indicates that the beacon is unusable. Generally this means some configurable parameter such as interval is not valid. Transition out of this state can only occur if the invalid state is corrected.
FAILED	Indicates that an attempt to transmit the beacon failed. This may be due to invalid parameters or an overflow in packing the beacon content. In either case, transition out of this state is not supported.
INACTIVE	Indicates the beacon is not scheduled to transmit, but may be activated in the future. Transitions to SCHEDULED_PREPARE or SCHEDULED on activate().
CANCELLED	Indicates a beacon that was deactivated while it was active. Transitions to INACTIVE when the transmission completes.
SCHEDULED_PREPARE	Indicates that the beacon is scheduled for a pre-transmission notification. Transitions to INACTIVE on deactivate(), and to SCHEDULED when the alarm fires. Note Transition from SCHEDULED_PREPARE to SCHEDULED will occur asynchronously.
SCHEDULED	Indicates the beacon is scheduled for a future transmission. Transitions to INACTIVE on deactivate(), and to READY when the alarm fires. Note Transition from SCHEDULED to READY will occur asynchronously.
READY	Indicates the beacon should transmit as soon as the radio is available. Transitions to ACTIVE or FAILED when the radio becomes available and all earlier READY beacons complete, and to INACTIVE if cancelled before transmission starts.
ACTIVE	Indicates the beacon is actively transmitting. Transitions to INACTIVE, SCHEDULED_PREPARE, or SCHEDULED when the transmission completes, and to CANCELLED on deactivate().

Member Function Documentation

◆ activate()

int nrfcxx::sd::Beacon::activate ( )

Enable the beacon.

Subclasses may override pre_activate_() to confirm that their requirements have been met. Any non-zero value returned from that function will be returned from this function, aborting the activation process.

Returns: zero on successful activation, or a non-zero result if the activation failed (positive only if from pre_activate_()).

◆ populate_()

virtual int nrfcxx::sd::Beacon::populate_ ( pabigot::ble::gap::adv_data & ad )

inlineprotectedvirtual

Function that must be overridden to fill in beacon content.

The return value is interpreted in this way:

A zero value indicates that the beacon content was not populated, e.g. because nothing is available yet. The beacon will not transmit, but it will be immediately rescheduled as if it had. Application or infrastructure should invoke reset_interval() whenever the conditions that are blocking transmission have been resolved.
A negative value indicates that a critical error has been discovered. The beacon will transition into FAILED state.
A positive value indicates that the beacon has been filled and transmission should succeed. If, however, ad is not valid the result will be as if the function had returned -EINVAL and the beacon will be failed.

Parameters

ad	an advertising data structure, with the Flags and (if nonzero) TxPower data items already populated.

Returns: as documented above.

Reimplemented in nrfcxx::sd::GenericBeacon< CONTENT_TYPE, ID >.

◆ reset_interval()

int nrfcxx::sd::Beacon::reset_interval ( )

Reset the interval so the beacon is retransmitted as quickly as possible.

min_interval_utt() still applies: a reset immediately after a transmission will incur a delay of at least min_interval_utt() until the next transmission. A reset at least min_interval_utt() after the last transmission will result in a transmission as soon as the radio is available.

Note: This function is expected to be invoked from the application main loop. Invocation from a FLIH may result in anomalous behavior.

Warning: If this function is invoked on a beacon that has a prepare backoff the prepare notification will not be issued for the first transmission after reset. If a prepare notification had already been emitted the rescheduled transmission may occur before the expected backoff period completes.

Returns: negative if the beacon was not active; positive if a scheduled beacon transmission was cancelled and a new one scheduled. Zero if the beacon was ready to transmit or being transmitted.

◆ set_interval() [1/2]

int nrfcxx::sd::Beacon::set_interval	(	unsigned int	min_utt,
		unsigned int	max_utt
	)

Configure an exponential back-off interval.

Invoking reset_interval() sets the interval back to the minimum and transmits ASAP; afterwards the interval doubles until it reachs the maximum, where it stays until reset again.

Note: This function must be invoked while the beacon is inactive.

Parameters

min_utt	the minimum interval between scheduled beacons, in uptime ticks. The value must be nonzero and strictly greater than prepare_backoff_utt().
max_utt	the maximum interval between scheduled beacons, in uptime ticks. The value must be no less than `min_utt`.

Returns: zero on success, or a negative error code

◆ set_interval() [2/2]

int nrfcxx::sd::Beacon::set_interval ( unsigned int utt )

inline

Configure a fixed interval.

Note: This function must be invoked while the beacon is inactive.

Parameters

utt	the interval between scheduled beacons, in uptime ticks. The value must be nonzero.

Returns: zero on success, or a negative error code

◆ set_prepare_backoff()

int nrfcxx::sd::Beacon::set_prepare_backoff	(	notifier_type	notify,
		unsigned int	backoff_utt
	)

Configure notification that a beacon will transmit soon.

This can be used to collect information for an upcoming beacon, e.g. measuring Vdd just before a telemetry beacon will be generated.

There is no coordination between this notification and the transmission; if the application does not react to the notification in a timely manner the beacon will still transmit on schedule.

Note: This function must be invoked while the beacon is inactive.; See reset_interval() for its impact on prepare notifications.

Parameters

notify	the notifier that the beacon will transmit soon. Pass a null notifier to disable the feature.
backoff_utt	the duration before the next transmission at which the notifier will be invoked. This parameter must be strictly less than min_interval_utt().

Returns: zero on successful disable, positive on successful enable, or a negative error code.

◆ set_tx_notify()

void nrfcxx::sd::Beacon::set_tx_notify ( notifier_type notify )

inline

Configure notification that a beacon is being sent.

notify will be invoked when the soft-device is successfully invoked to transmit the beacon.

Parameters

notify the notifier that the beacon will transmit soon.

◆ state()

state_e nrfcxx::sd::Beacon::state ( ) const

inline

Return the current beacon state.

Note: If the returned state is SCHEDULED the actual state may be updated to READY asynchronously by the alarm infrastructure. See clock::alarm::mutex_type.

◆ telemetry_state_setup()

static void nrfcxx::sd::Beacon::telemetry_state_setup	(	const systemState::state_type &	ss,
		bool	is_reset,
		bool	retained
	)

static

Function to maintain beacon telemetry state across resets.

This must be invoked from the application's systemState app_handler to ensure beacon telemetry state is properly managed.

◆ update_crc()

template<typename FT >

crc_type nrfcxx::sd::Beacon::update_crc ( FT * bp )

inline

Helper to store a checksum immediately following a frame instance.

This calculates a CRC-16/DNP checksum over the entire value of a (packed) structure, and stores it in residue-compatible format immediately following the data.

Template Parameters

FT	a structure containing beacon data, often within a Manufacturer Specific Data block that's allocated to hold the structure plus the checksum.

Parameters

bp	pointer to the prepared beacon data. The checksum will be stored immediate after object.

◆ update_crc_()

crc_type nrfcxx::sd::Beacon::update_crc_	(	uint8_t *	sp,
		size_t	span
	)

protected

Function to calculate a checksum and store it after the data.

Parameters

sp	pointer to a block of data
span	the number of octets at `sp` to be covered by the checksum

Returns: the checksum that was stored at sp + span.

◆ validate()

int nrfcxx::sd::Beacon::validate ( ) const

Test whether the beacon is in a valid state.

This should return 0 if the configuration would allow the beacon to be activated, and a negative error code if they do not. External users should see a non-zero value only if state() is INVALID or FAILED.

Field Documentation

◆ APP_FRAME_TYPE_BASE

constexpr uint8_t nrfcxx::sd::Beacon::APP_FRAME_TYPE_BASE = 0x80

staticconstexpr

Minimum value for frame_prefix_s::frame_type available for application beacons.

Values less than this are reserved for infrastructure-defined beacons.

◆ APP_FRAME_TYPE_LIMIT

constexpr uint8_t nrfcxx::sd::Beacon::APP_FRAME_TYPE_LIMIT = 0xEF

staticconstexpr

Maximum value for frame_prefix_s::frame_type available for application beacons.

Values less than this are reserved for infrastructure-defined beacons.

◆ COMPANY_ID

constexpr uint16_t nrfcxx::sd::Beacon::COMPANY_ID = -1

staticconstexpr

The value to be used as the company ID for manufacturer specific data.

The standard beacons convey information in an MSD data instance, where the first two octets correspond to frame_prefix_s.

◆ MAX_MSD_LENGTH

constexpr size_t nrfcxx::sd::Beacon::MAX_MSD_LENGTH = 19 + sizeof(crc_type)

staticconstexpr

The maximum length of a Manufacturer Specific Data PDU.

This excludes the the length, flag, and company id, but includes the terminating CRC-16/DNP present in some beacon payloads.

The documentation for this class was generated from the following file:

nrfcxx/sd/beacon.hpp

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ state_e

Member Function Documentation

◆ activate()

◆ populate_()

◆ reset_interval()

◆ set_interval() [1/2]

◆ set_interval() [2/2]

◆ set_prepare_backoff()

◆ set_tx_notify()

◆ state()

◆ telemetry_state_setup()

◆ update_crc()

◆ update_crc_()

◆ validate()

Field Documentation

◆ APP_FRAME_TYPE_BASE

◆ APP_FRAME_TYPE_LIMIT

◆ COMPANY_ID

◆ MAX_MSD_LENGTH