Infrastructure that starts and stops the soft device and provides a main event loop for the application, exposed through make_setter(). More...

#include <nrfcxx/sd/broadcaster.hpp>

Public Member Functions
	Broadcaster (const systemState &cs)
	Instantiate the broadcaster instance. More...

	~Broadcaster ()
	stop() is invoked when broadcaster is destructed.

notifier_type	make_setter (event_set::event_type bits) const
	Construct a setter for the specified bits. More...

int	start ()
	Start the broadcast infrastructure. More...

void	stop ()
	Stop the broadcast infrastructure. More...

event_set_copy	wait_for_event ()
	Sleep until an event occurs. More...

uint16_t	vdd_mV () const
	Return the most recently read system voltage. More...

int	ram_delta () const
	Get the difference between required and available soft-device RAM. More...

const ble_gap_addr_t &	address () const
	Reference the Bluetooth device address used in GAP.

const ble_version_t &	fwid () const
	Reference the firmware version structure collected during start().

Static Public Member Functions
static void	state_setup (const systemState::state_type &ss, bool is_reset, bool retained)
	Function to maintain broadcaster state across resets. More...

Data Fields
SystemStateBeacon	sys_beacon
	The owned system state beacon.

TelemetryBeacon	tlm_beacon
	The owned telemetry beacon.

ApplicationIdBeacon	appid_beacon
	The owned application identity beacon.

sensor::adc::vdd	vdd_sensor
	A sensor instance that collects Vdd information for TelemetryBeacon. More...

Static Public Attributes
static constexpr event_set::event_type	EVT_SD = 0x0010
	Event informing the application that a soft-device interrupt has occured. More...

static constexpr event_set::event_type	EVT_RADIO_ON = 0x0020
	Event set when the radio has turned on. More...

static constexpr event_set::event_type	EVT_RADIO_OFF = 0x0040
	Event set when the radio has turned off. More...

static constexpr event_set::event_type	EVT_VDD_REQUIRED = 0x0100
	Event set when the broadcaster requires an updated Vdd measurement. More...

static constexpr event_set::event_type	EVT_VDD_UPDATED = 0x0200
	Event set when Vdd_mV() has been updated. More...

static constexpr event_set::event_type	EVT_APP_BASE = 0x1000
	Base event available for application use. More...

Detailed Description

Infrastructure that starts and stops the soft device and provides a main event loop for the application, exposed through make_setter().

It also supplies the maintenance operation for both owned and external beacons, including (in preferred activation order):

The owned beacons are created by the broadcaster, and their configurations may be changed by the application prior to starting the broadcaster. The beacons are not started along with the broadcaster; if the application desires them they should be activated once the broadcaster is running.

Any application-specific beacons may also be activated after start(). These do not need to be registered with the broadcaster.

Once activated the notifications associated with beacon maintenance are processed by the broadcaster's event loop. The application should invoke wait_for_event() in its main loop, to receive any application-specific events that it must process.

All owned beacons are deactivated when the broadcaster is stopped.

Constructor & Destructor Documentation

◆ Broadcaster()

nrfcxx::sd::Broadcaster::Broadcaster ( const systemState & cs )

Instantiate the broadcaster instance.

Warning: Attempts to instantiate a second instance will result in a FailSafeCode::RESOURCE_VIOLATION failsafe.

Parameters

cs	reference to the application-controlled system state. Note that the application must have caused state_setup() to be invoked when this state was initialized.

Member Function Documentation

◆ make_setter()

notifier_type nrfcxx::sd::Broadcaster::make_setter ( event_set::event_type bits ) const

Construct a setter for the specified bits.

Warning: FailSafeCode::API_VIOLATION will occur if bits includes any bits reserved by the Broadcaster instance.

Returns: the setter.

◆ ram_delta()

int nrfcxx::sd::Broadcaster::ram_delta ( ) const

inline

Get the difference between required and available soft-device RAM.

A postive value indicates that the amount of memory available is that much more than is required.

A negative value indicates that the amount of memory available must be increased by the absolute value in order to allow the system to run. In this case start() will fail with NRF_ERROR_NO_MEM.

Note: This value is set by start().

◆ start()

int nrfcxx::sd::Broadcaster::start ( )

Start the broadcast infrastructure.

Note: This simply configures and enables the soft device. Activating any owned beacons is the responsibility of the application.

Returns: Zero on success. A positive value is a Nordic soft-device error code indicating why the broadcaster could not be started; a negative value indicates a failure in the infrastructure startup.

◆ state_setup()

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

static

Function to maintain broadcaster state across resets.

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

◆ stop()

void nrfcxx::sd::Broadcaster::stop ( )

Stop the broadcast infrastructure.

All owned beacons are deactivated during this process.

◆ vdd_mV()

uint16_t nrfcxx::sd::Broadcaster::vdd_mV ( ) const

inline

Return the most recently read system voltage.

The value will be zero until the first sample of vdd_sensor completes. EVT_VDD_UPDATED is generated when the value changes.

Note: The value stored here remains set until updated by another sample. However, each new value will be used only once once in a telemetry beacon. Respect EVT_VDD_REQUIRED.

Returns: the most recently read system voltage, in millivolts.

◆ wait_for_event()

event_set_copy nrfcxx::sd::Broadcaster::wait_for_event ( )

Sleep until an event occurs.

This checks for pending events, and if none are available drops to the lowest power mode available and waits for an event. When an event is received the set of events is captured, all internal events are processed, and the remaining events are returned to the caller for processing.

Note: The returned event set may be empty.

Field Documentation

◆ EVT_APP_BASE

constexpr event_set::event_type nrfcxx::sd::Broadcaster::EVT_APP_BASE = 0x1000

staticconstexpr

Base event available for application use.

The application may define and set events at or higher than this bit. For example:

#define EVT_SAMPLE (Broadcaster::EVT_APP_BASE << 0)
#define EVT_PROCESS (Broadcaster::EVT_APP_BASE << 1)

◆ EVT_RADIO_OFF

constexpr event_set::event_type nrfcxx::sd::Broadcaster::EVT_RADIO_OFF = 0x0040

staticconstexpr

Event set when the radio has turned off.

The application may ignore this event if it is not relevant.

◆ EVT_RADIO_ON

constexpr event_set::event_type nrfcxx::sd::Broadcaster::EVT_RADIO_ON = 0x0020

staticconstexpr

Event set when the radio has turned on.

The application may ignore this event if it is not relevant.

◆ EVT_SD

constexpr event_set::event_type nrfcxx::sd::Broadcaster::EVT_SD = 0x0010

staticconstexpr

Event informing the application that a soft-device interrupt has occured.

Such events are not expected for broadcasters, but probably should be handled anyway.

◆ EVT_VDD_REQUIRED

constexpr event_set::event_type nrfcxx::sd::Broadcaster::EVT_VDD_REQUIRED = 0x0100

staticconstexpr

Event set when the broadcaster requires an updated Vdd measurement.

This event should be expected to fire shortly (nominally, 500 ms) before a TelemetryBeacon is transmitted. Inspect tlm_beacon for transmission rates.

The application should initiate a sample using vdd_sensor as soon as feasible after the event is received.

Alternatively the application may calculate the voltage of the system power source (Vbatt, by preference) through other means and provide it to tlm_beacon via TelemetryBeacon::update_pwr_mV().

If no power source voltage has been provided by the time the beacon content is formed the beacon will transmit a zero value.

◆ EVT_VDD_UPDATED

constexpr event_set::event_type nrfcxx::sd::Broadcaster::EVT_VDD_UPDATED = 0x0200

staticconstexpr

Event set when Vdd_mV() has been updated.

This event will be provided after the application successfully initiates a sample on vdd_sensor.

◆ vdd_sensor

sensor::adc::vdd nrfcxx::sd::Broadcaster::vdd_sensor

A sensor instance that collects Vdd information for TelemetryBeacon.

If this sensor is not used and the source voltage not provided through some other mechanism telemetry beacons will not provide source voltage.

The application is responsible for provisioning, enabling, and calibrating periph::ADC, and claiming and releasing the client in response to EVT_VDD_REQUIRED events.

Note: EVT_VDD_UPDATED will be issued whenever this sensor completes a sample.

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

nrfcxx/sd/broadcaster.hpp

Public Member Functions

Static Public Member Functions

Data Fields

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Broadcaster()

Member Function Documentation

◆ make_setter()

◆ ram_delta()

◆ start()

◆ state_setup()

◆ stop()

◆ vdd_mV()

◆ wait_for_event()

Field Documentation

◆ EVT_APP_BASE

◆ EVT_RADIO_OFF

◆ EVT_RADIO_ON

◆ EVT_SD

◆ EVT_VDD_REQUIRED

◆ EVT_VDD_UPDATED

◆ vdd_sensor