Namespace hal

Namespace List > hal

The foundation of libhal containing, interfaces, utilities and soft drivers.

Namespaces

Type	Name
namespace	cortex_m libhal drivers for the ARM Cortex-M series of processors
namespace	error Error objects, templates, and constants.
namespace	esp8266 libhal compatible libraries for the esp8266 device and microcontroller
namespace	literals Namespace containing user defined literals for the hal standard units.
namespace	lpc40 libhal drivers for the lpc40 series of microcontrollers from NXP
namespace	micromod
namespace	mock
namespace	mpl
namespace	rmd
namespace	soft
namespace	stm32f1

Classes

Type	Name
class	accelerometer Acceleration sensing hardware abstraction interface.
class	adc Analog to Digital Converter (ADC) hardware abstraction interface.
class	angular_velocity_sensor angular velocity sensor hardware abstraction interface
struct	bit_limits <BitWidth, int_t> Similar to std::numeric_limits<T> except that this object can give properties of integral types of arbitrary bit widths.
struct	bit_mask Represents a bit mask of contiguous bits.
class	bit_modify <T>
class	bit_value <T>
struct	byte_mask <ByteIndex> Helper for generating byte position masks.
class	can Controller Area Network (CAN bus) hardware abstraction interface.
class	can_router Route CAN messages received on the can bus to callbacks based on ID.
class	current_sensor current sensor hardware abstraction interface
class	dac Digital to Analog Converter (DAC) hardware abstraction interface.
class	distance_sensor Linear distance hardware abstraction interface.
class	gyroscope Angular velocity sensing hardware abstraction interface.
class	i2c Inter-integrated Circuit (I2C) hardware abstract interface.
class	input_pin Digital input pin hardware abstraction interface.
class	interrupt_pin Digital interrupt pin hardware abstraction.
class	magnetometer Magnetic field strength sensing hardware abstraction interface.
class	motor Hardware abstraction for an open loop rotational actuator.
class	move_interceptor <class T> Use this to perform changes on an object its move constructor is executed.
struct	nibble_mask <NibbleIndex> Helper for generating nibble position masks.
class	output_pin Digital output pin hardware abstraction.
class	overflow_counter <CountBitWidth> Extend a counter's count from an arbitrary bit width to 64-bits by detecting overflows in the count. Each detected overflow is added to an overflow counter which is combined with the current count in order create a count up to 64-bits in length.
class	pwm Pulse Width Modulation (PWM) channel hardware abstraction.
class	read_into Non-blocking callable for reading serial data into a buffer.
class	read_uint32 Read bytes from serial port and convert to integer.
class	read_upto Discard received bytes until the sequence is found.
class	rotation_sensor Rotation measuring hardware abstraction interface.
class	serial Hardware abstract interface for the serial communication protocol.
class	servo Hardware abstraction for a closed loop position controlled rotational actuator.
class	skip_past Discard received bytes until the sequence is found.
class	spi Serial peripheral interface (SPI) communication protocol hardware abstract interface.
class	spy_handler <args_t> Helper utility for making mocks for class functions that return status.
class	static_callable <class owner_class, reference_designator, typename signature> General class which will be used to allow for signature to be used and then split by the below class.
class	static_callable< owner_class, reference_designator, return_t(args_t... p_args)> <class owner_class, reference_designator, typename return_t, args_t> Specialization of static_callable with the return type and arguments split up.
class	static_list <class Object> static_list is a non-owning non-allocating doubly linked list container with O(1) memory utilization.
class	steady_clock Hardware abstraction interface for a steady clock mechanism.
class	steady_clock_timeout Timeout object based on hal::steady_clock .
class	stream_fill Non-blocking callable for reading serial data into a buffer.
class	stream_fill_upto Discard received bytes until the sequence is found.
class	stream_find Discard received bytes until the sequence is found.
class	stream_parse <T> Read bytes from stream and convert to integer.
class	stream_skip Skip number of bytes in a byte stream.
class	temperature_sensor Temperature sensing hardware abstraction interface.
class	timer Timer hardware abstraction interface.

Public Types

Type	Name
typedef float	ampere Type for current represented in amps.
typedef std::uint8_t	byte
typedef inplace_function< F, sizeof(std::intptr_t) *2 >	callback Definition of a standard libhal owning callback object.
typedef float	celsius Type for temperature represented in celsius.
typedef float	degrees Type for angle represented in degrees.
typedef void(void)	error_handler
typedef tl::function_ref< F >	function_ref Definition of a non-owning callable object.
typedef float	g_force
typedef float	gauss Type for magnetic field represented in gauss.
typedef float	hertz Type for frequency represented in hertz.
enum	i2c_operation Set of I2C transaction operations.
typedef stdext::inplace_function< F, Capacity >	inplace_function Definition of a owning callable object.
typedef boost::leaf::match< T, value... >	match
typedef float	meters Type for length represented in meters.
enum	pin_resistor Set of possible pin mode resistor settings.
typedef boost::leaf::result< T >	result
typedef float	rpm Type for rotational velocity represented in RPMs.
typedef result< void >	status
typedef std::chrono::nanoseconds	time_duration The standard time durations in libhal std::chrono::nanoseconds.
typedef status(void)	timeout_function Timeout is a callable object or function that signals to a procedure that the procedure has exceeded its time allotment and should return control to the calling function.
typedef float	volts Type for voltage represented in volts.
typedef result< work_state >()	work_function A non-blocking callable that performs work with each call.
enum	work_state Represents the state of a coroutine or resumable callable.

Public Attributes

Type	Name
constexpr hal::bit_mask	byte_m = = byte_mask<ByteIndex>::value Shorthand for using hal::byte_mask<N>::value .
concept	convertible_to_bytes = = requires(T a) {
*a.data();
a.size();
}
concept	enumeration = = std::is_enum_v<T> concept for enumeration types
concept	has_work_state = = requires(T a) {
{
a.state()
} -> std::same_as<work_state>;
}
constexpr hal::bit_mask	nibble_m = = nibble_mask<NibbleIndex>::value Shorthand for using hal::nibble_mask<N>::value.
error_handler *	on_error_callback = = nullptr
concept	timeout = = std::convertible_to<T, hal::function_ref<timeout_function>>
concept	worker = = std::convertible_to<T, hal::function_ref<work_function>>

Public Functions

Type	Name
constexpr T	absolute_value (T p_value) Generic absolute value function that works for integer types.
constexpr std::span< const hal::byte >	as_bytes (const T * p_address, size_t p_number_of_elements)
constexpr std::span< const hal::byte >	as_bytes (const convertible_to_bytes auto & p_container)
constexpr std::span< hal::byte >	as_writable_bytes (T * p_address, size_t p_number_of_elements)
constexpr std::span< hal::byte >	as_writable_bytes (convertible_to_bytes auto & p_container)
constexpr auto	attempt (TryBlock && p_try_block, H &&... p_handlers)
constexpr auto	attempt_all (TryBlock && p_try_block, H &&... p_handlers)
constexpr auto	bit_extract (std::unsigned_integral auto p_value)
constexpr auto	bit_extract (bit_mask p_field, std::unsigned_integral auto p_value)
constexpr std::uint16_t	bit_width (const can::settings & p_settings)
steady_clock_timeout	create_timeout (hal::steady_clock & p_steady_clock, hal::time_duration p_duration) Create a timeout object based on hal::steady_clock .
constexpr std::int64_t	cycles_per (hertz p_source, hal::time_duration p_duration) Calculate the number of cycles of this frequency within the time duration. This function is meant for timers to determine how many count cycles are needed to reach a particular time duration at this frequency.
status	delay (timeout auto p_timeout) Delay the execution of the application or thread for a duration of time.
void	delay (hal::steady_clock & p_steady_clock, hal::time_duration p_duration) Delay execution for a duration of time using a hardware steady_clock .
constexpr T	distance (T p_left, T p_right) Calculates the distance between two values (L1 Norm or Manhattan distance), the absolute value of their difference.
constexpr std::make_unsigned_t< T >	distance (T p_left, T p_right) Calculates the distance between two values (L1 Norm or Manhattan distance), the absolute value of their difference.
result< std::chrono::nanoseconds >	duration_from_cycles (hertz p_source, uint32_t p_cycles) Calculate the amount of time it takes a frequency to oscillate a number of cycles.
constexpr bool	failed (work_state p_state)
constexpr bool	failed (has_work_state auto p_worker)
constexpr bool	finished (work_state p_state)
constexpr bool	finished (has_work_state auto p_worker)
std::uint64_t	future_deadline (hal::steady_clock & p_steady_clock, hal::time_duration p_duration) Function to compute a future timestamp in ticks.
consteval T	generate_field_of_ones () Generate a mask of 1s at compile time.
void	halt ()
constexpr bool	in_progress (work_state p_state)
constexpr bool	in_progress (has_work_state auto p_worker)
constexpr std::optional< std::uint32_t >	is_valid (const can::settings & p_settings, hertz p_operating_frequency) Validate configuration settings against an operating frequency.
constexpr float	map (float p_target, std::pair< float, float > p_input_range, std::pair< float, float > p_output_range) Map an target value [x] from an input range [a,b] to an output range [c,d].
result< T >	multiply (T p_lhs, T p_rhs) Perform multiply operation and return an error code std::errc::result_out_of_range if the two values when multiplied would overflow the containing value.
auto	never_timeout () Create a timeout that will never time out.
auto	new_error (Item &&... p_item)
std::basic_ostream< CharT, Traits > &	operator<< (std::basic_ostream< CharT, Traits > & p_ostream, const work_state & p_state)
std::basic_ostream< CharT, Traits > &	operator<< (std::basic_ostream< CharT, Traits > & p_ostream, const hal::byte & p_byte) print byte type using ostreams
constexpr auto	operator== (const can::settings & p_lhs, const can::settings & p_rhs)
constexpr auto	operator== (const can::message_t & p_lhs, const can::message_t & p_rhs)
constexpr auto	operator== (const i2c::settings & p_lhs, const i2c::settings & p_rhs)
constexpr auto	operator== (const input_pin::settings & p_lhs, const input_pin::settings & p_rhs)
constexpr auto	operator== (const interrupt_pin::settings & p_lhs, const interrupt_pin::settings & p_rhs)
constexpr auto	operator== (const output_pin::settings & p_lhs, const output_pin::settings & p_rhs)
constexpr auto	operator== (const serial::settings & p_lhs, const serial::settings & p_rhs)
constexpr auto	operator== (const spi::settings & p_lhs, const spi::settings & p_rhs)
void	print (serial & p_serial, DataArray && p_data) Write data to serial buffer and drop return value.
void	print (serial & p_serial, const char * p_format, Parameters... p_parameters) Write formatted string data to serial buffer and drop return value.
hal::result< hal::i2c::transaction_t >	probe (i2c & p_i2c, hal::byte p_address) probe the i2c bus to see if a device exists
hal::result< hal::i2c::transaction_t >	read (i2c & p_i2c, hal::byte p_address, std::span< hal::byte > p_data_in, timeout auto p_timeout) read bytes from target device on i2c bus
hal::result< hal::i2c::transaction_t >	read (i2c & p_i2c, hal::byte p_address, std::span< hal::byte > p_data_in) read bytes from target device on i2c bus
result< std::array< hal::byte, BytesToRead > >	read (i2c & p_i2c, hal::byte p_address, timeout auto p_timeout) return array of read bytes from target device on i2c bus
result< std::array< hal::byte, BytesToRead > >	read (i2c & p_i2c, hal::byte p_address) return array of read bytes from target device on i2c bus
result< std::span< hal::byte > >	read (serial & p_serial, std::span< hal::byte > p_data_in, timeout auto p_timeout) Read bytes from a serial port.
result< std::array< hal::byte, BytesToRead > >	read (serial & p_serial, timeout auto p_timeout) Read bytes from a serial port and return an array.
result< hal::spi::transfer_t >	read (spi & p_spi, std::span< hal::byte > p_data_in, hal::byte p_filler=spi::default_filler) Read data from the SPI bus.
result< std::array< hal::byte, BytesToRead > >	read (spi & p_spi, hal::byte p_filler=spi::default_filler) Read data from the SPI bus and return a std::array of bytes.
constexpr T	rounding_division (T p_numerator, T p_denominator) Perform integer division and round the value up if the next decimal place is greater than or equal to 0.5.
status	success () a readability function for returning successful results;
constexpr bool	terminated (work_state p_state)
constexpr bool	terminated (has_work_state auto p_worker)
auto	timeout_generator (hal::steady_clock & p_steady_clock) Generates a function that, when passed a duration, returns a timeout.
hal::byte	to_8_bit_address (hal::byte p_address, i2c_operation p_operation) noexcept Convert 7-bit i2c address to an 8-bit address.
constexpr std::array< char, N+1 >	to_array (std::string_view p_view) Convert a string_view into a std::array of N number of characters.
constexpr std::string_view	to_string (work_state p_state)
result< work_state >	try_until (worker auto & p_worker, timeout auto p_timeout) Repeatedly call a worker function until it has reached a terminal state or a timeout has been reached.
result< work_state >	try_until (worker auto && p_worker, timeout auto p_timeout) Repeatedly call a worker function until it has reached a terminal state or a timeout has been reached.
constexpr auto	value (enumeration auto p_enum_value) Helper function to convert an enum to its integral value.
constexpr std::chrono::duration< int64_t, Period >	wavelength (hertz p_source) Calculates and returns the wavelength in seconds.
hal::result< hal::i2c::transaction_t >	write (i2c & p_i2c, hal::byte p_address, std::span< const hal::byte > p_data_out, timeout auto p_timeout) write data to a target device on the i2c bus
hal::result< hal::i2c::transaction_t >	write (i2c & p_i2c, hal::byte p_address, std::span< const hal::byte > p_data_out) write data to a target device on the i2c bus
status	write (serial & p_serial, std::span< const hal::byte > p_data_out) Write bytes to a serial port.
status	write (serial & p_serial, std::string_view p_data_out) Write std::span of const char to a serial port.
result< hal::spi::transfer_t >	write (spi & p_spi, std::span< const hal::byte > p_data_out) Write data to the SPI bus and ignore data sent from peripherals on the bus.
result< serial::write_t >	write_partial (serial & p_serial, std::span< const hal::byte > p_data_out) Write bytes to a serial port.
hal::result< hal::i2c::transaction_t >	write_then_read (i2c & p_i2c, hal::byte p_address, std::span< const hal::byte > p_data_out, std::span< hal::byte > p_data_in, timeout auto p_timeout=hal::never_timeout()) write and then read bytes from target device on i2c bus
hal::result< hal::i2c::transaction_t >	write_then_read (i2c & p_i2c, hal::byte p_address, std::span< const hal::byte > p_data_out, std::span< hal::byte > p_data_in) write and then read bytes from target device on i2c bus
result< std::array< hal::byte, BytesToRead > >	write_then_read (i2c & p_i2c, hal::byte p_address, std::span< const hal::byte > p_data_out, timeout auto p_timeout) write and then return an array of read bytes from target device on i2c bus
result< std::array< hal::byte, BytesToRead > >	write_then_read (i2c & p_i2c, hal::byte p_address, std::span< const hal::byte > p_data_out) write and then return an array of read bytes from target device on i2c bus
result< std::span< hal::byte > >	write_then_read (serial & p_serial, std::span< const hal::byte > p_data_out, std::span< hal::byte > p_data_in, timeout auto p_timeout) Perform a write then read transaction over serial.
result< std::array< hal::byte, BytesToRead > >	write_then_read (serial & p_serial, std::span< const hal::byte > p_data_out, timeout auto p_timeout) Perform a write then read transaction over serial.
result< hal::spi::transfer_t >	write_then_read (spi & p_spi, std::span< const hal::byte > p_data_out, std::span< hal::byte > p_data_in, hal::byte p_filler=spi::default_filler) Write data to the SPI bus and ignore data sent from peripherals on the bus then read data from the SPI and fill the write line with filler bytes.
result< std::array< hal::byte, BytesToRead > >	write_then_read (spi & p_spi, std::span< const hal::byte > p_data_out, hal::byte p_filler=spi::default_filler) Write data to the SPI bus and ignore data sent from peripherals on the bus then read data from the SPI, fill the write line with filler bytes and return an array of bytes.

Public Static Functions

Type	Name
constexpr static bool	equals (std::floating_point auto p_value1, std::floating_point auto p_value2, float p_epsilon=1e-9f) Determines if two values are equal within a relative error.

Public Types Documentation

typedef ampere

using hal::ampere = typedef float;

typedef byte

using hal::byte = typedef std::uint8_t;

Standard type for bytes in libhal. hal::byte has a number of annoyances that results in more verbose code without much benefit and thus hal::byte was created.

typedef callback

Definition of a standard libhal owning callback object.

using hal::callback = typedef inplace_function<F, sizeof(std::intptr_t) * 2>;

This is an inplace_function with its capacity set to two pointers. Callable objects must fit within the size of two integers to be able to construct this polymorphic callable object.

Template parameters:

• F - function type or call signature

typedef celsius

using hal::celsius = typedef float;

typedef degrees

using hal::degrees = typedef float;

typedef error_handler

using hal::error_handler = typedef void(void);

typedef function_ref

Definition of a non-owning callable object.

using hal::function_ref = typedef tl::function_ref<F>;

Use this for passing a callable object to a function that the function does not need to store in anyway. Best used for timeouts where a function simply needs the callable during the runtime of the function and when the function is over, the callable is no longer needed.

This function is light weight in comparison to std::function, which is allocating, or inplace_function.

Template parameters:

• F - function type or call signature

typedef g_force

using hal::g_force = typedef float;

Type for acceleration represented in the force applied by gravity at sea level.

typedef gauss

using hal::gauss = typedef float;

typedef hertz

using hal::hertz = typedef float;

enum i2c_operation

enum hal::i2c_operation {
    write = 0,
    read = 1
};

typedef inplace_function

Definition of a owning callable object.

using hal::inplace_function = typedef stdext::inplace_function<F, Capacity>;

Use this instead of function_ref when a callable object needs to be stored.

Template parameters:

• F - function type or call signature
• Capacity - storage capacity of the function in bytes. If a callable object has a size greater than the capacity, then attempting to create an inplace function with it will result in a compiler error.

typedef match

using hal::match = typedef boost::leaf::match<T, value...>;

typedef meters

using hal::meters = typedef float;

enum pin_resistor

Set of possible pin mode resistor settings.

enum hal::pin_resistor {
    none = 0,
    pull_down,
    pull_up
};

See each enumeration to get more details about when and how these should be used.

typedef result

using hal::result = typedef boost::leaf::result<T>;

typedef rpm

using hal::rpm = typedef float;

typedef status

using hal::status = typedef result<void>;

typedef time_duration

using hal::time_duration = typedef std::chrono::nanoseconds;

typedef timeout_function

Timeout is a callable object or function that signals to a procedure that the procedure has exceeded its time allotment and should return control to the calling function.

using hal::timeout_function = typedef status(void);

Exception:

• hal::timeout - when the timeout condition has been met.

Returns:

status - sets error flag set when timeout condition has been met, otherwise returns success.

typedef volts

using hal::volts = typedef float;

typedef work_function

A non-blocking callable that performs work with each call.

using hal::work_function = typedef result<work_state>();

Each call to a work_function will perform a set of work. The worker will return a work_state to indicate its current state. Once the worker reaches a terminal state, it MUST perform no additional work and return the terminal state. For example, if a work function failed, it must always return failure and not interact with hardware or other software from that point on. Same will occur for the "finished" state.

This function can be repeatedly tried until it has reached a terminal state with the try_until() function.

Returns:

result<work_state> - sets error flag set when an error occurs, otherwise returns work_state enum.

enum work_state

enum hal::work_state {
    in_progress,
    failed,
    finished
};

Public Attributes Documentation

variable byte_m

Shorthand for using hal::byte_mask<N>::value .

constexpr hal::bit_mask hal::byte_m;

Template parameters:

• ByteIndex - the byte position to make a mask for

variable convertible_to_bytes

concept hal::convertible_to_bytes;

variable enumeration

concept for enumeration types

concept hal::enumeration;

Template parameters:

• T - enum type

variable has_work_state

concept hal::has_work_state;

variable nibble_m

Shorthand for using hal::nibble_mask<N>::value.

constexpr hal::bit_mask hal::nibble_m;

Template parameters:

• NibbleIndex - the nibble position to make a mask for

variable on_error_callback

error_handler* hal::on_error_callback;

variable timeout

concept hal::timeout;

variable worker

concept hal::worker;

Public Functions Documentation

function absolute_value

Generic absolute value function that works for integer types.

template<typename T typename T>
constexpr T hal::absolute_value (
    T p_value
) 

Preferred this over the C API for rounding numbers such as abs(), labs() and llabs(). This function relieves the need in template code to check the type of the integer and select the correct function to call.

NOTE: If p_value is minimum negative number of type T then the resulting return value will be the maximum positive number represented by T. For example, INT32_MIN is 2147483648 where as INT32_MAX is 2147483647. The absolute value of INT32_MIN is 1 greater than INT32_MAX. To prevent overflow, passing INT32_MIN will simply return back INT32_MAX.

Template parameters:

• T - integral type

Parameters:

• p_value - integer value to be made positive

Returns:

constexpr auto - positive representation of the integer

function as_bytes

template<typename T typename T>
constexpr std::span< const hal::byte > hal::as_bytes (
    const T * p_address,
    size_t p_number_of_elements
) 

function as_bytes

constexpr std::span< const hal::byte > hal::as_bytes (
    const convertible_to_bytes auto & p_container
) 

function as_writable_bytes

template<typename T typename T>
constexpr std::span< hal::byte > hal::as_writable_bytes (
    T * p_address,
    size_t p_number_of_elements
) 

function as_writable_bytes

constexpr std::span< hal::byte > hal::as_writable_bytes (
    convertible_to_bytes auto & p_container
) 

function attempt

template<class TryBlock class TryBlock, class... H>
constexpr auto hal::attempt (
    TryBlock && p_try_block,
    H &&... p_handlers
) 

function attempt_all

template<class TryBlock class TryBlock, class... H>
constexpr auto hal::attempt_all (
    TryBlock && p_try_block,
    H &&... p_handlers
) 

function bit_extract

template<bit_mask field>
constexpr auto hal::bit_extract (
    std::unsigned_integral auto p_value
) 

function bit_extract

constexpr auto hal::bit_extract (
    bit_mask p_field,
    std::unsigned_integral auto p_value
) 

function bit_width

constexpr std::uint16_t hal::bit_width (
    const can::settings & p_settings
) 

function create_timeout

Create a timeout object based on hal::steady_clock .

steady_clock_timeout hal::create_timeout (
    hal::steady_clock & p_steady_clock,
    hal::time_duration p_duration
) 

NOTE: Multiple timeout objects can be made from a single steady_clock without influencing other timeout objects.

Parameters:

• p_steady_clock - hal::steady_clock implementation
• p_duration - amount of time until timeout

Returns:

hal::steady_clock_timeout - timeout object

function cycles_per

Calculate the number of cycles of this frequency within the time duration. This function is meant for timers to determine how many count cycles are needed to reach a particular time duration at this frequency.

constexpr std::int64_t hal::cycles_per (
    hertz p_source,
    hal::time_duration p_duration
) 

Parameters:

• p_source - source frequency
• p_duration - the amount of time to convert to cycles

Returns:

std::int64_t - number of cycles

function delay

Delay the execution of the application or thread for a duration of time.

inline status hal::delay (
    timeout auto p_timeout
) 

Template parameters:

• Timeout - timeout type

Parameters:

• p_timeout - callable timeout object

Returns:

status - success or failure

function delay

Delay execution for a duration of time using a hardware steady_clock .

void hal::delay (
    hal::steady_clock & p_steady_clock,
    hal::time_duration p_duration
) 

Parameters:

• p_steady_clock - steady_clock driver
• p_duration - the amount of time to delay for. Zero or negative time duration will delay for one tick of the p_steady_clock.

function distance

Calculates the distance between two values (L1 Norm or Manhattan distance), the absolute value of their difference.

template<typename T typename T>
constexpr T hal::distance (
    T p_left,
    T p_right
) 

Template parameters:

• T - integral type of the two values

Parameters:

• p_left - the first point of the distance calculation
• p_right - the second point of the distance calculation

Returns:

constexpr T - absolute value of the difference between the two points.

function distance

Calculates the distance between two values (L1 Norm or Manhattan distance), the absolute value of their difference.

template<std::integral T>
constexpr std::make_unsigned_t< T > hal::distance (
    T p_left,
    T p_right
) 

NOTE: Values cannot exceed int32_t.

Template parameters:

• T - integral type of the two values

Parameters:

• p_left - the first point of the distance calculation
• p_right - the second point of the distance calculation

Returns:

constexpr T - absolute value of the difference between the two points.

function duration_from_cycles

Calculate the amount of time it takes a frequency to oscillate a number of cycles.

inline result< std::chrono::nanoseconds > hal::duration_from_cycles (
    hertz p_source,
    uint32_t p_cycles
) 

Parameters:

• p_source - the frequency to compute the cycles from
• p_cycles - number of cycles within the time duration

Returns:

std::chrono::nanoseconds - time duration based on this frequency and the number of cycles

function failed

constexpr bool hal::failed (
    work_state p_state
) 

function failed

constexpr bool hal::failed (
    has_work_state auto p_worker
) 

function finished

constexpr bool hal::finished (
    work_state p_state
) 

function finished

constexpr bool hal::finished (
    has_work_state auto p_worker
) 

function future_deadline

Function to compute a future timestamp in ticks.

inline std::uint64_t hal::future_deadline (
    hal::steady_clock & p_steady_clock,
    hal::time_duration p_duration
) 

This function calculates a future timestamp based on the current uptime of a steady clock and a specified duration.

Parameters:

• p_steady_clock - the steady_clock used to calculate the future duration. Note that this future deadline will only work with this steady clock.
• p_duration The duration for which we need to compute a future timestamp.

Returns:

A 64-bit unsigned integer representing the future timestamp in steady clock ticks. The future timestamp is calculated as the sum of the current number of ticks of the clock and the number of ticks equivalent to the specified duration. If the duration corresponds to a ticks_required value less than or equal to 1, it will be set to 1 to ensure at least one tick is waited.

function generate_field_of_ones

Generate a mask of 1s at compile time.

template<size_t BitWidth, std::integral T>
consteval T hal::generate_field_of_ones () 

Template parameters:

• BitWidth - number of 1s in the mask
• T - the type

Returns:

consteval uint32_t - mask with 1s at the LSB

function halt

inline void hal::halt () 

function in_progress

constexpr bool hal::in_progress (
    work_state p_state
) 

function in_progress

constexpr bool hal::in_progress (
    has_work_state auto p_worker
) 

function is_valid

Validate configuration settings against an operating frequency.

constexpr std::optional< std::uint32_t > hal::is_valid (
    const can::settings & p_settings,
    hertz p_operating_frequency
) 

The settings and frequency must follow the following rules:

• propagation_delay, phase_segment1, phase_segment2 and synchronization_jump_width must be nonzero.
• synchronization_jump_width must be the lesser between phase_segment1 and phase_segment2.
• The total bit width must be equal to or greater than 8 Tq/bit; the sum of sync_segment, propagation_delay, phase_segment1 and phase_segment2.
• The CAN device's operating frequency must be at least 8 times the baud rate to give the minimum.
• The ratio between the CAN device's operating frequency and the bit width must be close enough to an integer to produce a usable baud rate prescaler.

Parameters:

• p_settings - settings object to check
• p_operating_frequency - CAN device operating frequency

Returns:

std::optional<std::uint32_t> - baud rate prescaler

function map

Map an target value [x] from an input range [a,b] to an output range [c,d].

constexpr float hal::map (
    float p_target,
    std::pair< float, float > p_input_range,
    std::pair< float, float > p_output_range
) 

Another term for this is an affine transformation which follows this equation: For example:

let x = 5.0 let input_range = [0.0, 10.0] let output_range = [100.0, 200.0] The result will be 150.0

Parameters:

• p_target - target value within p_input_range to be mapped to the output range.
• p_input_range - the input range of p_target
• p_output_range - the output range to map p_target to

Returns:

constexpr float - value mapped from input range to the output range. The output is clamped to the output range.

function multiply

Perform multiply operation and return an error code std::errc::result_out_of_range if the two values when multiplied would overflow the containing value.

template<typename T typename T>
result< T > hal::multiply (
    T p_lhs,
    T p_rhs
) 

Template parameters:

• T - integer arithmetic type

Parameters:

• p_lhs - left hand side integer
• p_rhs - right hand side integer

Returns:

result<T> - either the resultant or an error std::errc::result_out_of_range

function never_timeout

Create a timeout that will never time out.

inline auto hal::never_timeout () 

Returns:

auto - callable that will never return timeout

function new_error

template<class... Item>
inline auto hal::new_error (
    Item &&... p_item
) 

function operator<<

template<class CharT class CharT, class Traits class Traits>
inline std::basic_ostream< CharT, Traits > & hal::operator<< (
    std::basic_ostream< CharT, Traits > & p_ostream,
    const work_state & p_state
) 

function operator<<

print byte type using ostreams

template<class CharT class CharT, class Traits class Traits>
inline std::basic_ostream< CharT, Traits > & hal::operator<< (
    std::basic_ostream< CharT, Traits > & p_ostream,
    const hal::byte & p_byte
) 

Meant for unit testing, testing and simulation purposes C++ streams, in general, should not be used for any embedded project that will ever have to be used on an MCU due to its memory cost.

Template parameters:

• CharT - character type
• Traits - ostream traits type

Parameters:

• p_ostream - the ostream
• p_byte - object to convert to a string

Returns:

std::basic_ostream<CharT, Traits>& - reference to the ostream

function operator==

constexpr auto hal::operator== (
    const can::settings & p_lhs,
    const can::settings & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const can::message_t & p_lhs,
    const can::message_t & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const i2c::settings & p_lhs,
    const i2c::settings & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const input_pin::settings & p_lhs,
    const input_pin::settings & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const interrupt_pin::settings & p_lhs,
    const interrupt_pin::settings & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const output_pin::settings & p_lhs,
    const output_pin::settings & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const serial::settings & p_lhs,
    const serial::settings & p_rhs
) 

function operator==

constexpr auto hal::operator== (
    const spi::settings & p_lhs,
    const spi::settings & p_rhs
) 

function print

Write data to serial buffer and drop return value.

template<typename DataArray typename DataArray>
void hal::print (
    serial & p_serial,
    DataArray && p_data
) 

Only use this with serial ports with infallible write operations, meaning they will never return an error result.

Template parameters:

• DataArray - data array type

Parameters:

• p_serial - serial port to write data to
• p_data - data to be sent over the serial port

function print

Write formatted string data to serial buffer and drop return value.

template<size_t BufferSize, typename... Parameters>
void hal::print (
    serial & p_serial,
    const char * p_format,
    Parameters... p_parameters
) 

Uses snprintf internally and writes to a local statically allocated an array. This function will never dynamically allocate like how standard std::printf does.

This function does NOT include the NULL character when transmitting the data over the serial port.

Template parameters:

• BufferSize - Size of the buffer to allocate on the stack to store the formatted message.
• Parameters - printf arguments

Parameters:

• p_serial - serial port to write data to
• p_format - printf style null terminated format string
• p_parameters - printf arguments

function probe

probe the i2c bus to see if a device exists

inline hal::result< hal::i2c::transaction_t > hal::probe (
    i2c & p_i2c,
    hal::byte p_address
) 

Parameters:

• p_i2c - i2c driver
• p_address - target address to probe for

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function read

read bytes from target device on i2c bus

inline hal::result< hal::i2c::transaction_t > hal::read (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< hal::byte > p_data_in,
    timeout auto p_timeout
) 

Shorthand for writing i2c.transfer(...) for read only operations

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_in - buffer to read bytes into from target device
• p_timeout - amount of time to execute the transaction

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function read

read bytes from target device on i2c bus

inline hal::result< hal::i2c::transaction_t > hal::read (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< hal::byte > p_data_in
) 

Shorthand for writing i2c.transfer(...) for read only operations, but never times out. Can be used for devices that never perform clock stretching.

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_in - buffer to read bytes into from target device

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function read

return array of read bytes from target device on i2c bus

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::read (
    i2c & p_i2c,
    hal::byte p_address,
    timeout auto p_timeout
) 

Eliminates the need to create a buffer and pass it into the read function.

Template parameters:

• BytesToRead - number of bytes to read

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_timeout - amount of time to execute the transaction

Returns:

result<std::array<hal::byte, BytesToRead>> - array of bytes from target device or an error.

function read

return array of read bytes from target device on i2c bus

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::read (
    i2c & p_i2c,
    hal::byte p_address
) 

Eliminates the need to create a buffer and pass it into the read function. This operation will never time out and should only be used with devices that never perform clock stretching.

Template parameters:

• BytesToRead - number of bytes to read

Parameters:

• p_i2c - i2c driver
• p_address - target address

Returns:

result<std::array<hal::byte, BytesToRead>> - array of bytes from target device or an error.

function read

Read bytes from a serial port.

inline result< std::span< hal::byte > > hal::read (
    serial & p_serial,
    std::span< hal::byte > p_data_in,
    timeout auto p_timeout
) 

Parameters:

• p_serial - the serial port that will be read from
• p_data_in - buffer to have bytes from the serial port read into
• p_timeout - timeout callable that indicates when to bail out of the read operation.

Returns:

result<std::span<hal::byte>> - return an error if a call to serial::read or delay() returns an error from the serial port or a span with the number of bytes read and a pointer to where the read bytes are.

function read

Read bytes from a serial port and return an array.

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::read (
    serial & p_serial,
    timeout auto p_timeout
) 

This call eliminates the boiler plate of creating an array and then passing that to the read function.

Template parameters:

• BytesToRead - the number of bytes to be read from the serial port.

Parameters:

• p_serial - the serial port to be read from
• p_timeout - timeout callable that indicates when to bail out of the read operation.

Returns:

result<std::array<hal::byte, BytesToRead>> - return an error if a call to serial::read or delay() returns an error from the serial port or a span with the number of bytes read and a pointer to where the read bytes are.

function read

Read data from the SPI bus.

inline result< hal::spi::transfer_t > hal::read (
    spi & p_spi,
    std::span< hal::byte > p_data_in,
    hal::byte p_filler=spi::default_filler
) 

Filler bytes will be placed on the write line.

Parameters:

• p_spi - spi driver
• p_data_in - buffer to receive bytes back from the SPI bus
• p_filler - filler data placed on the bus in place of actual write data.

Returns:

result<hal::spi::transfer_t> - success or failure

function read

Read data from the SPI bus and return a std::array of bytes.

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::read (
    spi & p_spi,
    hal::byte p_filler=spi::default_filler
) 

Filler bytes will be placed on the write line.

Template parameters:

• BytesToRead - Number of bytes to read

Parameters:

• p_spi - spi driver
• p_filler - filler data placed on the bus in place of actual write data.

Returns:

result<std::array<hal::byte, BytesToRead>> - any errors associated with this call

function rounding_division

Perform integer division and round the value up if the next decimal place is greater than or equal to 0.5.

template<typename T typename T>
constexpr T hal::rounding_division (
    T p_numerator,
    T p_denominator
) 

Template parameters:

• T - integral type of the two operands

Parameters:

• p_numerator - the value to be divided
• p_denominator - the value to divide the numerator against

Returns:

constexpr T - rounded quotient between numerator and denominator. Returns 0 if the denominator is greater than the numerator.

function success

a readability function for returning successful results;

inline status hal::success () 

For functions that return status, rather than returning {} to default initialize the status object as "success", use this function to make it more clear to the reader.

EXAMPLE:

Returns:

status - that is always successful

function terminated

constexpr bool hal::terminated (
    work_state p_state
) 

function terminated

constexpr bool hal::terminated (
    has_work_state auto p_worker
) 

function timeout_generator

Generates a function that, when passed a duration, returns a timeout.

inline auto hal::timeout_generator (
    hal::steady_clock & p_steady_clock
) 

Parameters:

• p_steady_clock - steady_clock driver that must out live the lifetime of the returned lambda.

Returns:

auto - a callable that returns a new timeout object each time a time duration is passed to it.

function to_8_bit_address

Convert 7-bit i2c address to an 8-bit address.

inline hal::byte hal::to_8_bit_address (
    hal::byte p_address,
    i2c_operation p_operation
) noexcept

Parameters:

• p_address 7-bit i2c address
• p_operation write or read operation

Returns:

hal::byte - 8-bit i2c address

function to_array

Convert a string_view into a std::array of N number of characters.

template<size_t N>
constexpr std::array< char, N+1 > hal::to_array (
    std::string_view p_view
) 

Will always ensure that the array is null terminated

Template parameters:

• N - Size of the array

Parameters:

• p_view - string to be placed into a char array

Returns:

constexpr std::array<char, N + 1> - the char array object

function to_string

constexpr std::string_view hal::to_string (
    work_state p_state
) 

function try_until

Repeatedly call a worker function until it has reached a terminal state or a timeout has been reached.

inline result< work_state > hal::try_until (
    worker auto & p_worker,
    timeout auto p_timeout
) 

Parameters:

• p_worker - worker function to repeatedly call
• p_timeout - callable timeout object

Returns:

result<work_state> - state of the worker function

function try_until

Repeatedly call a worker function until it has reached a terminal state or a timeout has been reached.

inline result< work_state > hal::try_until (
    worker auto && p_worker,
    timeout auto p_timeout
) 

Parameters:

• p_worker - worker function to repeatedly call
• p_timeout - callable timeout object

Returns:

result<work_state> - state of the worker function

function value

Helper function to convert an enum to its integral value.

constexpr auto hal::value (
    enumeration auto p_enum_value
) 

Parameters:

• p_enum_value - the enumeration you want to convert into an integral value

Returns:

constexpr auto - return the integral value of the enum with the same type as the enumeration.

function wavelength

Calculates and returns the wavelength in seconds.

template<typename Period typename Period>
constexpr std::chrono::duration< int64_t, Period > hal::wavelength (
    hertz p_source
) 

Calculates and returns the wavelength in seconds as a float.

Template parameters:

• Period - desired period (defaults to std::femto for femtoseconds).

Parameters:

• p_source - source frequency to convert to wavelength

Returns:

std::chrono::duration<int64_t, Period> - time based wavelength of the frequency.

Template parameters:

• float_t - float type
• Period - desired period

Parameters:

• p_source - source frequency to convert to wavelength

Returns:

constexpr float - float representation of the time based wavelength of the frequency.

function write

write data to a target device on the i2c bus

inline hal::result< hal::i2c::transaction_t > hal::write (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< const hal::byte > p_data_out,
    timeout auto p_timeout
) 

Shorthand for writing i2c.transfer(...) for write only operations

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_out - buffer of bytes to write to the target device
• p_timeout - amount of time to execute the transaction

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function write

write data to a target device on the i2c bus

inline hal::result< hal::i2c::transaction_t > hal::write (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< const hal::byte > p_data_out
) 

Shorthand for writing i2c.transfer(...) for write only operations, but never times out. Can be used for devices that never perform clock stretching.

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_out - buffer of bytes to write to the target device

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function write

Write bytes to a serial port.

inline status hal::write (
    serial & p_serial,
    std::span< const hal::byte > p_data_out
) 

Parameters:

• p_serial - the serial port that will be written to
• p_data_out - the data to be written out the port

Returns:

status - success or failure

function write

Write std::span of const char to a serial port.

inline status hal::write (
    serial & p_serial,
    std::string_view p_data_out
) 

Parameters:

• p_serial - the serial port that will be written to
• p_data_out - chars to be written out the port

Returns:

status - success or failure

function write

Write data to the SPI bus and ignore data sent from peripherals on the bus.

inline result< hal::spi::transfer_t > hal::write (
    spi & p_spi,
    std::span< const hal::byte > p_data_out
) 

Parameters:

• p_spi - spi driver
• p_data_out - data to be written to the SPI bus

Returns:

result<hal::spi::transfer_t> - success or failure

function write_partial

Write bytes to a serial port.

inline result< serial::write_t > hal::write_partial (
    serial & p_serial,
    std::span< const hal::byte > p_data_out
) 

Parameters:

• p_serial - the serial port that will be written to
• p_data_out - the data to be written out the port

Returns:

result<serial::write_t> - get the results of the uart port write operation.

function write_then_read

write and then read bytes from target device on i2c bus

inline hal::result< hal::i2c::transaction_t > hal::write_then_read (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< const hal::byte > p_data_out,
    std::span< hal::byte > p_data_in,
    timeout auto p_timeout=hal::never_timeout ()
) 

This API simply calls transaction. This API is here for consistency across the other other communication protocols such as SPI and serial.

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_out - buffer of bytes to write to the target device
• p_data_in - buffer to read bytes into from target device
• p_timeout - amount of time to execute the transaction

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function write_then_read

write and then read bytes from target device on i2c bus

inline hal::result< hal::i2c::transaction_t > hal::write_then_read (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< const hal::byte > p_data_out,
    std::span< hal::byte > p_data_in
) 

This API simply calls transaction. This API is here for consistency across the other other communication protocols such as SPI and serial.

This operation will never time out and should only be used with devices that never perform clock stretching.

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_out - buffer of bytes to write to the target device
• p_data_in - buffer to read bytes into from target device

Returns:

hal::result<hal::i2c::transaction_t> - success or failure

function write_then_read

write and then return an array of read bytes from target device on i2c bus

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::write_then_read (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< const hal::byte > p_data_out,
    timeout auto p_timeout
) 

Eliminates the need to create a buffer and pass it into the read function.

Template parameters:

• BytesToRead - number of bytes to read after write

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_out - buffer of bytes to write to the target device
• p_timeout - amount of time to execute the transaction

Returns:

result<std::array<hal::byte, BytesToRead>>

function write_then_read

write and then return an array of read bytes from target device on i2c bus

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::write_then_read (
    i2c & p_i2c,
    hal::byte p_address,
    std::span< const hal::byte > p_data_out
) 

Eliminates the need to create a buffer and pass it into the read function.

Template parameters:

• BytesToRead - number of bytes to read after write

Parameters:

• p_i2c - i2c driver
• p_address - target address
• p_data_out - buffer of bytes to write to the target device

Returns:

result<std::array<hal::byte, BytesToRead>>

function write_then_read

Perform a write then read transaction over serial.

inline result< std::span< hal::byte > > hal::write_then_read (
    serial & p_serial,
    std::span< const hal::byte > p_data_out,
    std::span< hal::byte > p_data_in,
    timeout auto p_timeout
) 

This is especially useful for devices that use a command and response method of communication.

Parameters:

• p_serial - the serial port to have the transaction occur on
• p_data_out - the data to be written to the port
• p_data_in - a buffer to receive the bytes back from the port
• p_timeout - timeout callable that indicates when to bail out of the read operation.

Returns:

status - success or failure or serial::write() returns an error from the serial port or success.

function write_then_read

Perform a write then read transaction over serial.

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::write_then_read (
    serial & p_serial,
    std::span< const hal::byte > p_data_out,
    timeout auto p_timeout
) 

This is especially useful for devices that use a command and response method of communication.

Template parameters:

• BytesToRead - the number of bytes to read back

Parameters:

• p_serial - the serial port to have the transaction occur on
• p_data_out - the data to be written to the port
• p_timeout - timeout callable that indicates when to bail out of the read operation.

Returns:

result<std::array<hal::byte, BytesToRead>> - return an error if a call to serial::read or serial::write() returns an error from the serial port or an array of read bytes.

function write_then_read

Write data to the SPI bus and ignore data sent from peripherals on the bus then read data from the SPI and fill the write line with filler bytes.

inline result< hal::spi::transfer_t > hal::write_then_read (
    spi & p_spi,
    std::span< const hal::byte > p_data_out,
    std::span< hal::byte > p_data_in,
    hal::byte p_filler=spi::default_filler
) 

This utility function that fits the use case of many SPI devices where a transaction is not full duplex. In many spi devices, full duplex means that as data is being written to the SPI bus, the peripheral device is sending data back on the read line. In most cases, the protocol is to write data to the bus, and ignore the read line because the peripheral is not writing anything meaningful to that line, then reading from SPI bus and writing nothing meaningful to the write line as the peripheral is ignoring that line.

Parameters:

• p_spi - spi driver
• p_data_out - bytes to write to the bus
• p_data_in - buffer to receive bytes back from the SPI bus
• p_filler - filler data placed on the bus when the read operation begins.

Returns:

result<hal::spi::transfer_t> - success or failure

function write_then_read

Write data to the SPI bus and ignore data sent from peripherals on the bus then read data from the SPI, fill the write line with filler bytes and return an array of bytes.

template<size_t BytesToRead>
result< std::array< hal::byte , BytesToRead > > hal::write_then_read (
    spi & p_spi,
    std::span< const hal::byte > p_data_out,
    hal::byte p_filler=spi::default_filler
) 

Template parameters:

• BytesToRead - Number of bytes to read from the bus

Parameters:

• p_spi - spi driver
• p_data_out - bytes to write to the bus
• p_filler - filler data placed on the bus when the read operation begins.

Returns:

result<std::array<hal::byte, BytesToRead>>

Public Static Functions Documentation

function equals

Determines if two values are equal within a relative error.

static constexpr static bool hal::equals (
    std::floating_point auto p_value1,
    std::floating_point auto p_value2,
    float p_epsilon=1e-9f
) 

Parameters:

• p_value1 - First value to compare.
• p_value2 - Second value to compare.
• p_epsilon - Error margin that the difference is compared to.

Returns:

true - difference is less than epsilon

Returns:

false - difference is more than epsilon

---

The documentation for this class was generated from the following file libraries/include/libhal/accelerometer.hpp