State machine abstraction for time-delayed transitions and error captures. More...

#include <nrfcxx/lpm.hpp>

Public Types
using	state_type = unsigned int
	Representation for both generic and specific machine state. More...

using	process_flags_type = unsigned int
	Representation for flags returned from lpsm_capable::lpsm_process(). More...

using	error_type = int
	Representation for values stored in error(). More...

Public Member Functions
	state_machine (notifier_type notify)
	Create a state machine that records state and supports delayed transitions. More...

void	reset ()
	Cancel any pending transitions and restore the state to its as-constructed value.

state_type	state () const
	Return the current machine state excluding error/pending flags. More...

state_type	full_state () const
	Return the current machine state including error/pending flags. More...

void	set_state (state_type state, bool post=false)
	Set the machine state. More...

bool	has_error () const
	`true` iff the current state is marked with STATE_HAS_ERROR. More...

void	set_error ()
	Mark the current state with STATE_HAS_ERROR. More...

void	set_error (error_type error)
	Mark the current state with STATE_HAS_ERROR. More...

void	set_lost ()
	Set the current state as MS_LOST and store the unrecognized state in error().

error_type	error () const
	Read the current error code. More...

bool	blocking_alarm_pending () const
	`true` iff the current state is marked with STATE_BLOCKING_ALARM.

bool	fallback_alarm_pending () const
	`true` iff the current state is marked with STATE_FALLBACK_ALARM.

void	post_event ()
	Use the constructor-provided notifier to inform the application that the machine needs to be serviced.

int	deadline () const
	Read the deadline for the most recently scheduled alarm.

void	set_delay (int delay_utt)
	Set an alarm to invoke post_event() after a delay. More...

void	cancel_delay ()
	Cancel any delay initiated by set_delay().

Static Public Attributes
static constexpr state_type	STATE_MASK = ((1U << 24) - 1)
	Mask isolating the bits of state_type that are available to record machine state. More...

static constexpr state_type	STATE_HAS_ERROR = (1U << 24)
	Bit set in state_type when the machine is in an error state. More...

static constexpr state_type	STATE_BLOCKING_ALARM = (1U << 25)
	Bit set in state_type when an alarm guarding entry to the configured state has not yet fired. More...

static constexpr state_type	STATE_FALLBACK_ALARM = (1U << 26)
	Bit set in state_type when an alarm triggering post_event() has not yet fired. More...

static constexpr state_type	STATE_STOP_PENDING = (1U << 26)
	Bit set in state_type when lpsm_capable::lpsm_stop() has been invoked by the application to request a shutdown.

static constexpr state_type	MS_OFF = 0x0000
	State when the machine is off and all resources associated with it are disabled. More...

static constexpr state_type	MS_ENTRY_START = 0x0001
	State indicating the machine should begin automated transitions.

static constexpr state_type	MS_LOST = 0x0003
	State indicating the machine entered processing in a state not supported by the machine. More...

static constexpr state_type	MS_ENTRY_RESET = 0x0010
	State available to indicate that the machine needs to executing an internal reset operation.

static constexpr state_type	MS_EXIT_RESET = 0x0011
	State available to indicate that the machine is waiting to complete an internal reset operation. More...

static constexpr state_type	MS_ENTRY_ERRORED = 0x0012

static constexpr state_type	MS_ERRORED = 0x0013

static constexpr state_type	MS_ENTRY_FAILED = 0x0014

static constexpr state_type	MS_FAILED = 0x0015

static constexpr state_type	MS_ENTRY_STOPPED = 0x0016

static constexpr state_type	MS_ENTRY_SETUP = 0x0020
	States available to guard entry to a setup state. More...

static constexpr state_type	MS_EXIT_SETUP = 0x0030
	States available to guard exit from a setup step. More...

static constexpr state_type	MS_IDLE = 0x0040
	State indicating the machine is in a functional state from which an application signal is required to make further transitions. More...

static constexpr state_type	MS_ENTRY_SAMPLE = 0x0050
	States available to guard entry to a sample state. More...

static constexpr state_type	MS_SAMPLE = 0x0060
	States available to implement a sample state. More...

static constexpr state_type	MS_EXIT_SAMPLE = 0x0070
	States available to guard exit from a sample state. More...

static constexpr state_type	MS_APP_BASE {0x100}
	Base state value available for application-specific states.

static constexpr process_flags_type	PF_OFF = 0x01
	lpsm_capable::lpsm_process() flag bit when the machine is turned off. More...

static constexpr process_flags_type	PF_STARTED = 0x02
	lpsm_capable::lpsm_process() flag bit when the machine is ready to provide observations. More...

static constexpr process_flags_type	PF_RESET = 0x04
	lpsm_capable::lpsm_process() flag bit when the machine has initiated a peripheral reset. More...

static constexpr process_flags_type	PF_FAILED = 0x08
	Bit set in non-negative lpsm_capable::lpsm_process() result when the machine is in an unrecoverable failed state. More...

static constexpr process_flags_type	PF_STOPPED = 0x10

static constexpr process_flags_type	PF_OBSERVATION = 0x20
	lpsm_capable::lpsm_process() flag bit when a new observation is available.

static constexpr process_flags_type	PF_APP_BASE = 0x100
	First lpsm_capable::lpsm_process() flag bit available for application-specific result code bits. More...

Static Protected Member Functions
static bool	alarm_callback_ (clock::alarm &alarm)

Detailed Description

State machine abstraction for time-delayed transitions and error captures.

An instance of this can be used to coordinate multi-step processes that are often executed in the background. A 24-bit task-specific state is retained by the instance. Bits in the state indicate whether the process has an error and whether it is blocked waiting for an alarm.

An uptime-based alarm infrastructure is also maintained, using nrfcxx::event_set to notify the application when the alarm has completed. Fact-of a pending alarm is recorded in the state value, allowing premature entry into the state transition manager to be ignored by the manager.

A 32-bit error code can be set in the state machine. A cooperative manager will respect the error and wait until reset() is invoked before taking steps to restart the machine.

Member Typedef Documentation

◆ error_type

using nrfcxx::lpm::state_machine::error_type = int

Representation for values stored in error().

Error values are simply negative values returned by lpsm_capable::lpsm_process_().

◆ process_flags_type

using nrfcxx::lpm::state_machine::process_flags_type = unsigned int

Representation for flags returned from lpsm_capable::lpsm_process().

Flags at and above PF_APP_BASE are available to the application.

◆ state_type

using nrfcxx::lpm::state_machine::state_type = unsigned int

Representation for both generic and specific machine state.

The low 24 bits of this are available for specific machines to use to encode their state. The upper 8 bits are reserved for infrastructure support such as error markers and delayed transitions.

Constructor & Destructor Documentation

◆ state_machine()

nrfcxx::lpm::state_machine::state_machine ( notifier_type notify )

inline

Create a state machine that records state and supports delayed transitions.

Parameters

notify the event setter through which the application is notified of transitions.

Member Function Documentation

◆ error()

error_type nrfcxx::lpm::state_machine::error ( ) const

inline

Read the current error code.

Error values are most often negative values returned by the machine-specific lpsm_capable::lpsm_process_(). The specific interpretation is not generally defined, but in many cases these will indicate a TWI/SPI error.

Error values may also be set in context with MS_LOST, where the value is the erroneous state.

Specific machines may also indicate other problems through setting an error. Again, the interpretation is not specified.

The error value is cleared on reset(), and set by lpsm_capable::lpsm_process() through set_error(error_type).

◆ full_state()

state_type nrfcxx::lpm::state_machine::full_state ( ) const

inline

Return the current machine state including error/pending flags.

This is appropriate for testing whether invocation of lpsm_capable::lpsm_process() had any machine-visible side effects (e.g., setting an alarm).

On construction the state is zero.

◆ has_error()

bool nrfcxx::lpm::state_machine::has_error ( ) const

inline

true iff the current state is marked with STATE_HAS_ERROR.

This method should be invoked after any call to lpsm_capable::lpsm_process() to determine whether the machine has recorded an error state.

◆ set_delay()

void nrfcxx::lpm::state_machine::set_delay ( int delay_utt )

Set an alarm to invoke post_event() after a delay.

Parameters

delay the duration to wait. A positive value indicates a blocking alarm. A negative value indicates a fallback alarm. In either case the absolute value of the delay will be used as the parameter to clock::alarm::schedule_offset().

◆ set_error() [1/2]

void nrfcxx::lpm::state_machine::set_error ( )

inline

Mark the current state with STATE_HAS_ERROR.

This API does not change the value stored in error().

◆ set_error() [2/2]

void nrfcxx::lpm::state_machine::set_error ( error_type error )

inline

Mark the current state with STATE_HAS_ERROR.

Parameters

error the error code to be stored.

◆ set_state()

void nrfcxx::lpm::state_machine::set_state	(	state_type	state,
		bool	post = `false`
	)

inline

Set the machine state.

Parameters

state	the state of the machine. In most cases the value should not include any error/alarm/pending flags.
post	if `true` invoke post_event() immediately.

◆ state()

state_type nrfcxx::lpm::state_machine::state ( ) const

inline

Return the current machine state excluding error/pending flags.

This is appropriate for comparing against specific states.

On construction the state is zero.

Field Documentation

◆ MS_ENTRY_SAMPLE

constexpr state_type nrfcxx::lpm::state_machine::MS_ENTRY_SAMPLE = 0x0050

staticconstexpr

States available to guard entry to a sample state.

For example, when waiting for a signal that a sampling resource is available. Pairs with the MS_SAMPLE instance sharing a low nybble.

◆ MS_ENTRY_SETUP

constexpr state_type nrfcxx::lpm::state_machine::MS_ENTRY_SETUP = 0x0020

staticconstexpr

States available to guard entry to a setup state.

For example when MS_ENTRY_START initiates a peripheral configuration that requires a 10 ms delay, MS_ENTRY_SETUP might be used as the target to initiate a second configuration step.

Up to 15 additional instances may be defined by the application to support complex setup processes that require multiple guarded entry conditions.

◆ MS_EXIT_RESET

constexpr state_type nrfcxx::lpm::state_machine::MS_EXIT_RESET = 0x0011

staticconstexpr

State available to indicate that the machine is waiting to complete an internal reset operation.

This is likely to follow MS_ENTRY_RESET after a delay. Concurrent with transition from this state PF_RESET should be returned from lpsm_capable::lpsm_process().

◆ MS_EXIT_SAMPLE

constexpr state_type nrfcxx::lpm::state_machine::MS_EXIT_SAMPLE = 0x0070

staticconstexpr

States available to guard exit from a sample state.

Similar to MS_ENTRY_SAMPLE in cases where the operation is more clearly associated with the source state. For example, when waiting for a result to become available.

Pairs with the MS_SAMPLE instance sharing a low nybble.

◆ MS_EXIT_SETUP

constexpr state_type nrfcxx::lpm::state_machine::MS_EXIT_SETUP = 0x0030

staticconstexpr

States available to guard exit from a setup step.

Similar to MS_ENTRY_SETUP or MS_ENTRY_SAMPLE in cases where the operation is more clearly associated with the source state. Pairs with MS_ENTRY_SETUP with same low nybble.

◆ MS_IDLE

constexpr state_type nrfcxx::lpm::state_machine::MS_IDLE = 0x0040

staticconstexpr

State indicating the machine is in a functional state from which an application signal is required to make further transitions.

Generally you'd use this if the machine does not internally initiate new observations. Up to 15 additional instances may be defined by the application to support multiple idle states; these are generally paired with the MS_SAMPLE instance sharing a low nybble.

◆ MS_LOST

constexpr state_type nrfcxx::lpm::state_machine::MS_LOST = 0x0003

staticconstexpr

State indicating the machine entered processing in a state not supported by the machine.

This should be invoked in the default case of a switch statement processed in lpsm_capable::lpsm_process_(). The effect includes use of set_error() to record the unrecognized state.

◆ MS_OFF

constexpr state_type nrfcxx::lpm::state_machine::MS_OFF = 0x0000

staticconstexpr

State when the machine is off and all resources associated with it are disabled.

Transition from this state is performed by invoking lpsm_capable::lpsm_start(). The destination state is MS_ENTRY_START.

◆ MS_SAMPLE

constexpr state_type nrfcxx::lpm::state_machine::MS_SAMPLE = 0x0060

staticconstexpr

States available to implement a sample state.

A machine is in a sample state when it has initiated an observation.

Up to 15 additional instances may be defined by the application to support multiple sample states.

◆ PF_APP_BASE

constexpr process_flags_type nrfcxx::lpm::state_machine::PF_APP_BASE = 0x100

staticconstexpr

First lpsm_capable::lpsm_process() flag bit available for application-specific result code bits.

If multiple result codes are needed shift each one left by one more bit.

◆ PF_FAILED

constexpr process_flags_type nrfcxx::lpm::state_machine::PF_FAILED = 0x08

staticconstexpr

Bit set in non-negative lpsm_capable::lpsm_process() result when the machine is in an unrecoverable failed state.

Presence of this is sticky, and the system should mark the sensor as nonfunctional.

◆ PF_OFF

constexpr process_flags_type nrfcxx::lpm::state_machine::PF_OFF = 0x01

staticconstexpr

lpsm_capable::lpsm_process() flag bit when the machine is turned off.

This is set in any condition when, on exit from lpsm_capable::lpsm_process(), the machine is in state MS_OFF.

◆ PF_RESET

constexpr process_flags_type nrfcxx::lpm::state_machine::PF_RESET = 0x04

staticconstexpr

lpsm_capable::lpsm_process() flag bit when the machine has initiated a peripheral reset.

For example a CCS811 found to be operating in the wrong drive mode needs a clean reset before programming. This bit indicates that the reset is in progress.

This is so the application can track such resets, which may result in delays before valid observations are received or discontinuous observation curves. The process of reset completion is managed by the machine.

◆ PF_STARTED

constexpr process_flags_type nrfcxx::lpm::state_machine::PF_STARTED = 0x02

staticconstexpr

lpsm_capable::lpsm_process() flag bit when the machine is ready to provide observations.

This should be emitted once per start, on successful completion of all setup steps performed by the machine.

An application that maintains a persisted dynamic calibration might use this as a cue to when the calibration should be made available to the machine, or installed in the sensor.

◆ STATE_BLOCKING_ALARM

constexpr state_type nrfcxx::lpm::state_machine::STATE_BLOCKING_ALARM = (1U << 25)

staticconstexpr

Bit set in state_type when an alarm guarding entry to the configured state has not yet fired.

A blocking alarm should be used when there is a required delay before the machine can progress with the configured state. An example would be when processing #EXIT_RESET after a hardware reset: the machine should take no action until the required reset backoff has passed. Invocation of lpsm_capable::lpsm_process() while the alarm is still pending will return a diagnostic error.

This bit will be set by lpsm_capable::lpsm_process() when delay has been set to a positive value by lpsm_capable::lpsm_process_().

◆ STATE_FALLBACK_ALARM

constexpr state_type nrfcxx::lpm::state_machine::STATE_FALLBACK_ALARM = (1U << 26)

staticconstexpr

Bit set in state_type when an alarm triggering post_event() has not yet fired.

A fallback alarm should be used when a normal cue to process the machine state may be missed, e.g. a device that normally signals data ready through a GPIO signal, but where that signal may not be available. On expiration of the alarm post_event() will be invoked. Invocation of lpsm_capable::lpsm_process() while the alarm is still pending will cause the alarm to be cancelled, and the machine will process. If the machine determines that it cannot proceed yet, it may set another alarm to try again.

This bit will be set by lpsm_capable::lpsm_process() when delay has been set to a positive value by lpsm_capable::lpsm_process_().

◆ STATE_HAS_ERROR

constexpr state_type nrfcxx::lpm::state_machine::STATE_HAS_ERROR = (1U << 24)

staticconstexpr

Bit set in state_type when the machine is in an error state.

This bit may be set in combination with any state. When in an error state the controlling code should invoke reset() to restore the state. If this bit is set invocation of lpsm_capable::lpsm_process() will return zero without invoking to lpsm_capable::lpsm_process_().

◆ STATE_MASK

constexpr state_type nrfcxx::lpm::state_machine::STATE_MASK = ((1U << 24) - 1)

staticconstexpr

Mask isolating the bits of state_type that are available to record machine state.

Bits outside this range are reserved for shared machine operations.

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

nrfcxx/lpm.hpp

Public Types

Public Member Functions

Static Public Attributes

Static Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ error_type

◆ process_flags_type

◆ state_type

Constructor & Destructor Documentation

◆ state_machine()

Member Function Documentation

◆ error()

◆ full_state()

◆ has_error()

◆ set_delay()

◆ set_error() [1/2]

◆ set_error() [2/2]

◆ set_state()

◆ state()

Field Documentation

◆ MS_ENTRY_SAMPLE

◆ MS_ENTRY_SETUP

◆ MS_EXIT_RESET

◆ MS_EXIT_SAMPLE

◆ MS_EXIT_SETUP

◆ MS_IDLE

◆ MS_LOST

◆ MS_OFF

◆ MS_SAMPLE

◆ PF_APP_BASE

◆ PF_FAILED

◆ PF_OFF

◆ PF_RESET

◆ PF_STARTED

◆ STATE_BLOCKING_ALARM

◆ STATE_FALLBACK_ALARM

◆ STATE_HAS_ERROR

◆ STATE_MASK