Beacon providing telemetry information. More...

#include <nrfcxx/sd/beacon.hpp>

Inheritance diagram for nrfcxx::sd::TelemetryBeacon:

Data Structures
struct	frame_s
	Frame content for this beacon. More...

Public Types
enum	frame_flag_e : uint8_t { FT_FLAG_MAINS_POWER = 0x01, FT_FLAG_PWR_IS_Vdd = 0x02, FT_FLAG_CHARGING = 0x04, FT_FLAG_AGGREGATE_UPTIME = 0x08, FT_FLAG_HAS_POWER_LEVEL = 0x10, FT_FLAG_HAS_RESET_COUNT = 0x20 }
	Bits used in frame_prefix_s::flags to refine content of the frame. More...

typedef unsigned int(*	power_level_type) (unsigned int)
	Function type for calculating power source level from power voltage. More...

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.

Public Member Functions
	TelemetryBeacon (const systemState &system_state)
	Constructor for beacon requires a systemState reference.

void	update_pwr_mV (uint16_t pwr_mV, bool is_vdd=false)
	Provide a value for pwr_mV to be used in the next beacon. More...

uint8_t	mutate_flags (uint8_t set, uint8_t clear)
	Modify the content of frame_prefix_s::flags. More...

void	power_level (power_level_type fn)
	Provide a function that can estimate power source level from measured voltage. More...

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...

Data Fields
const systemState &	system_state
	The systemState instance from which information is taken.

Static Public Attributes
static constexpr uint8_t	FRAME_TYPE = 0
	frame_prefix_s::frame_type value for this beacon.

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.

Additional Inherited Members
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...

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...

Detailed Description

Beacon providing telemetry information.

This includes estimated battery voltage, number of advertisements sent, total system uptime, and duty cycle information. * This beacon is configured with:

min_interval_utt() set to 1 s
max_interval_utt() set to 5 min

It is not expected that the beacon interval will be reset.

Member Typedef Documentation

◆ power_level_type

typedef unsigned int(* nrfcxx::sd::TelemetryBeacon::power_level_type) (unsigned int)

Function type for calculating power source level from power voltage.

Parameters

pwr_mV the measured power source voltage, in millivolts

Returns: the estimated power source level, in parts per ten thousand.

Member Enumeration Documentation

◆ frame_flag_e

enum nrfcxx::sd::TelemetryBeacon::frame_flag_e : uint8_t

Bits used in frame_prefix_s::flags to refine content of the frame.

Enumerator
FT_FLAG_MAINS_POWER	Set to indicate that the device is being powered by mains. For devices that are permanently mains-powered, e.g. through a USB dongle, this will always be true. In that situation #pwr_mV should always be zero, and FT_FLAG_HAS_POWER_LEVEL should be cleared. For devices that are battery-powered but can be charged in-place this will be true when the charging connector is powered. There #pwr_mV may be provided, but cannot be trusted to actually represent the true level of the battery, and in that situation FT_FLAG_HAS_POWER_LEVEL should be cleared.
FT_FLAG_PWR_IS_Vdd	Set to indicate that frame_s::pwr_mV is a measure of system Vdd rather than a measure of some external power source like a battery.
FT_FLAG_CHARGING	Set to indicate that the battery is being charged.
FT_FLAG_AGGREGATE_UPTIME	Set to indicate that frame_s::adv_cnt and frame_s::sec_cnt are aggregates since installation (or power lost) If cleared these values count since last reset. Deprecated: This feature has been removed. Once the last installation has been updated past 2018-11-09 remove the flag.
FT_FLAG_HAS_POWER_LEVEL	Set to indicate that the fixed content of #frame_s is followed in frame_s::optional by an 8-bit unsigned value that represents the normalized level of the device power source. E.g. 255 indicates 100%, 128 indicates 50.2%, 0 indicates 0% remaining. See comments at FT_FLAG_MAINS_POWER.
FT_FLAG_HAS_RESET_COUNT	Set to indicate that the field formerly used for wfe_cnt carries reset_count instead. Todo: Remove this flag once all firmware that stored `wfe_cnt` where frame_s::reset_cnt is now has been replaced.

Member Function Documentation

◆ mutate_flags()

uint8_t nrfcxx::sd::TelemetryBeacon::mutate_flags	(	uint8_t	set,
		uint8_t	clear
	)

inline

Modify the content of frame_prefix_s::flags.

Parameters

set	values from frame_flag_e that should be set in the flags field.
clear	values from frame_flag_e that should be cleared from the flags field.

Returns: the resulting flags value.

◆ power_level()

void nrfcxx::sd::TelemetryBeacon::power_level ( power_level_type fn )

inline

Provide a function that can estimate power source level from measured voltage.

If this is not provided FT_FLAG_HAS_POWER_LEVEL will never be included in the beacon.

◆ update_pwr_mV()

void nrfcxx::sd::TelemetryBeacon::update_pwr_mV	(	uint16_t	pwr_mV,
		bool	is_vdd = `false`
	)

inline

Provide a value for pwr_mV to be used in the next beacon.

Parameters

pwr_mV	the power source voltage to be recorded
is_vdd	whether FT_FLAG_PWR_IS_Vdd should be set.

Note: The provided value will be used once then cleared. The application is responsible for ensuring a fresh value is made available before the infrastructure invokes populate_(). One way to do that is to use set_prepare_backoff() to be notified of the need to collect or store a new sample.

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

nrfcxx/sd/beacon.hpp

Data Structures

Public Types

Public Member Functions

Data Fields

Static Public Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ power_level_type

Member Enumeration Documentation

◆ frame_flag_e

Member Function Documentation

◆ mutate_flags()

◆ power_level()

◆ update_pwr_mV()