Infrastructure to manage a beacon with a fixed payload. More...

#include <nrfcxx/sd/beacon.hpp>

Inheritance diagram for nrfcxx::sd::GenericBeacon< CONTENT_TYPE, ID >:

Data Structures
struct	frame_s
	Frame content for this beacon is the first #content_span octets of a #content_type instance. More...

Public Types
using	content_type = CONTENT_TYPE

Public Types inherited from nrfcxx::sd::Beacon
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.

Data Fields
content_type	content {}
	The content that will be copied into the beacon by populate_().

uint8_t	flags = 0
	The flags that will be used by populate_().

bool	ready = false
	Set to `true` when content has been updated. More...

Static Public Attributes
static constexpr uint8_t	FRAME_TYPE = ID

static constexpr size_t	content_span = CONTENT_TYPE::SPAN

Static Public Attributes inherited from nrfcxx::sd::Beacon
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
int	populate_ (pabigot::ble::gap::adv_data &ad) override
	Function that must be overridden to fill in beacon content. More...

Protected Member Functions inherited from nrfcxx::sd::Beacon
	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...

Additional Inherited Members
Public Member Functions inherited from nrfcxx::sd::Beacon
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 inherited from nrfcxx::sd::Beacon
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...

Detailed Description

template<typename CONTENT_TYPE, uint8_t ID>
class nrfcxx::sd::GenericBeacon< CONTENT_TYPE, ID >

Infrastructure to manage a beacon with a fixed payload.

In simple situations the post-prefix frame content has a fixed layout that corresponds a natively-aligned structure, with at most some padding required at its end. Some boilerplate can be eliminated by using this class to maintain a copy of the data to be transmitted.

Template Parameters

CONTENT_TYPE	the native structure carrying the frame content. This must have a constexpr static `size_t` member named `SPAN` that provides the number of octets that contain transmittable data. This may differ from `sizeof(CONTENT_TYPE)` in the case where the structure has trailing padding to support alignment of consecutive instances, a requirement not relevant to this use.
ID	the Beacon::FRAME_TYPE value to use.

Member Function Documentation

◆ populate_()

template<typename CONTENT_TYPE , uint8_t ID>

int nrfcxx::sd::GenericBeacon< CONTENT_TYPE, ID >::populate_ ( pabigot::ble::gap::adv_data & ad )

inlineoverrideprotectedvirtual

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 from nrfcxx::sd::Beacon.

Field Documentation

◆ ready

template<typename CONTENT_TYPE , uint8_t ID>

bool nrfcxx::sd::GenericBeacon< CONTENT_TYPE, ID >::ready = false

Set to true when content has been updated.

When false (default) populate_() will return zero, inhibiting transmission of the beacon while leaving it enabled.

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

nrfcxx/sd/beacon.hpp

Data Structures

Public Types

Data Fields

Static Public Attributes

Protected Member Functions