FastArduino  v1.7
C++ library to build fast but small Arduino/AVR projects
utils Namespace Reference

Contains all generic utility methods. More...

Enumerations

enum  UnitPrefix : int8_t {
  GIGA = 9,
  MEGA = 6,
  KILO = 3,
  HECTO = 2,
  DECA = 1,
  NONE = 0,
  DECI = -1,
  CENTI = -2,
  MILLI = -3,
  MICRO = -6,
  NANO = -9
}
 Common prefixes for measurement units. More...
 

Functions

template<typename T >
constexpr T constrain (T value, T min, T max)
 Constrain value to be greater than or equal to min and lower than or equal to max. More...
 
template<typename TI , typename TO >
constexpr TO map (TI value, TI input_min, TI input_max, TO output_min, TO output_max)
 Linearly transform value from range [input_min ; input_max] to range [output_min ; output_max]. More...
 
constexpr uint32_t power_of_10 (int8_t n)
 Calculate a power of 10 at compile-time, provided that n is a constant at call time. More...
 
constexpr int16_t map_raw_to_physical (int16_t value, UnitPrefix prefix, int16_t range, uint8_t precision_bits)
 Convert the raw value, obtained from an electronics device, using precision_bit number of bits (that defines the input range) into a physical measure for which range defines the complete output range for such value, adjusted according to the unit prefix that we want in the resulting measure. More...
 
constexpr int16_t map_physical_to_raw (int16_t value, UnitPrefix prefix, int16_t range, uint8_t precision_bits)
 Convert an absolute physical value, expressed in some given measurement unit, scaled with prefix, into a raw measurement as if obtained from a electronics device, using precision_bit number of bits (that defines the device raw measure range); for this device, physical measures are within range. More...
 
constexpr uint8_t low_byte (uint16_t word)
 Extract the low order byte of a 16-bits word.
 
constexpr uint8_t high_byte (uint16_t word)
 Extract the high order byte of a 16-bits word.
 
constexpr uint16_t as_uint16_t (uint8_t high, uint8_t low)
 Convert 2 bytes into an unsigned int. More...
 
template<typename T >
constexpr T is_zero (T value, T default_value)
 Replace value by default_value if not "true" (also known as "Elvis operator"). More...
 
template<typename T >
void set_mask (volatile T &reg, T mask, T value)
 Common utility to force a part of the value of a register, designated by a bit mask. More...
 
template<typename T >
constexpr bool is_mask_equal (T actual, T mask, T expected)
 Common utility to check if 2 values are equal according to a mask. More...
 
uint8_t bcd_to_binary (uint8_t bcd)
 Convert Binary-coded decimal byte (each nibble is a digit from 0 to 9) into a natural byte. More...
 
uint8_t binary_to_bcd (uint8_t binary)
 Convert a natural integers to a BCD byte (2 digits). More...
 
void swap_bytes (uint16_t &value)
 Swap 2 bytes of a 2-bytes integer. More...
 
void swap_bytes (int16_t &value)
 Swap 2 bytes of a 2-bytes integer. More...
 
template<typename T >
constexpr uint8_t as_uint8_t (T input)
 Cast a one byte long bit-fields struct into a byte. More...
 
template<typename T , typename U = uint8_t[sizeof(T)]>
constexpr void as_array (const T &input, U output)
 Cast an instance of type T to an array of uint8_t of the size of T. More...
 
constexpr uint8_t calculate_delay1_count (float time_us)
 Calculate the count to pass to delay1() in order to reach time_us microseconds delay. More...
 
constexpr uint8_t num_bits (uint8_t mask, uint8_t num=0)
 Calculate the number of 1 bits in a byte. More...
 

Detailed Description

Contains all generic utility methods.

Enumeration Type Documentation

◆ UnitPrefix

enum utils::UnitPrefix : int8_t
strong

Common prefixes for measurement units.

Used by map_raw_to_physical() and map_physical_to_raw() for units conversion. To avoid large arithmetic calculation, we limit these prefixes to power of 10 that can hold within 32 bits; this is why TERA or PICO are absent.

Definition at line 101 of file utilities.h.

Function Documentation

◆ constrain()

template<typename T >
constexpr T utils::constrain ( value,
min,
max 
)
constexpr

Constrain value to be greater than or equal to min and lower than or equal to max.

Template Parameters
Tthe type of value (must be comparable: int, float...)
Parameters
valuethe value to constrain
minthe minimum allowed value
maxthe maximum allowed value
Returns
the value constrained to be between min and max

Definition at line 62 of file utilities.h.

◆ map()

template<typename TI , typename TO >
constexpr TO utils::map ( TI  value,
TI  input_min,
TI  input_max,
TO  output_min,
TO  output_max 
)
constexpr

Linearly transform value from range [input_min ; input_max] to range [output_min ; output_max].

Note that the transformed value is not explicitly constrained to range [output_min ; output_max], hence if you want it to be with that range, you should also use constrain() on the returned value.

Template Parameters
T0the type of the target range and value
T1the type of the source range and value
Parameters
valuethe value to transform
input_minthe minimum value of the input range
input_maxthe maximum value of the input range
output_minthe minimum value of the output range
output_maxthe maximum value of the output range
Returns
transformed value

Definition at line 89 of file utilities.h.

◆ power_of_10()

constexpr uint32_t utils::power_of_10 ( int8_t  n)
constexpr

Calculate a power of 10 at compile-time, provided that n is a constant at call time.

This is to avoid dragging huge mathematics libraries if this can be avoided.

Parameters
nthe power of exponent to apply to 10; if negative, then its absolute value is used instead.
Returns
10 ^ |n|

Definition at line 124 of file utilities.h.

◆ map_raw_to_physical()

constexpr int16_t utils::map_raw_to_physical ( int16_t  value,
UnitPrefix  prefix,
int16_t  range,
uint8_t  precision_bits 
)
constexpr

Convert the raw value, obtained from an electronics device, using precision_bit number of bits (that defines the input range) into a physical measure for which range defines the complete output range for such value, adjusted according to the unit prefix that we want in the resulting measure.

This is useful when you need to display real measurement from raw values provided by a sensor. Note however, that in most cases, this method will be evaluated at runtime only, and thus will drag all arithmetic computation libraries. If you need to know the physical measure from a raw value, only to compare it against some constant physical value, then it is preferable to convert the latter, with map_raw_to_physical() which will be evaluated at compile time, and only compare raw values in your program: that will help decrease code size and improve code speed (no runtime conversions needed).

// This sample code use MPU6050 (accelerometer-gyroscope) support
using namespace devices::magneto;
using namespace utils;
// These are the accel and gyro ranges used in this code
static constexpr const GyroRange GYRO_RANGE = GyroRange::RANGE_250;
static constexpr const AccelRange ACCEL_RANGE = AccelRange::RANGE_2G;
// This function converts a raw gyro axis measure into centi-degrees per second
// so that it can be displayed to an LCD.
inline int16_t gyro(int16_t value)
{
// GYRO_RANGE_DPS calculates the gyro maximum range (in degrees per second)
// 15 is the number of bits of precision (on positive range only).
return map_raw_to_physical(value, UnitPrefix::CENTI, GYRO_RANGE_DPS(GYRO_RANGE), 15);
}
// This function converts a raw accelerometer axis measure into milli-g
// so that it can be displayed to an LCD.
inline int16_t accel(int16_t value)
{
// ACCEL_RANGE_G calculates the accel maximum range (in g)
// 15 is the number of bits of precision (on positive range only).
return map_raw_to_physical(value, UnitPrefix::MILLI, ACCEL_RANGE_G(ACCEL_RANGE), 15);
}
Parameters
valuethe raw value to convert
prefixthe unit scale prefix to use to compute the physical value
rangethe physical measure matching the maximum raw value
precision_bitsthe number of significant bits of the raw value; only positive values are accounted, hence if a raw measure can be any value in [-32768;+32767], then precision_bits is 15.
Returns
the physical value calculated from value, scaled according to prefix
See also
map_physical_to_raw()

Definition at line 187 of file utilities.h.

◆ map_physical_to_raw()

constexpr int16_t utils::map_physical_to_raw ( int16_t  value,
UnitPrefix  prefix,
int16_t  range,
uint8_t  precision_bits 
)
constexpr

Convert an absolute physical value, expressed in some given measurement unit, scaled with prefix, into a raw measurement as if obtained from a electronics device, using precision_bit number of bits (that defines the device raw measure range); for this device, physical measures are within range.

Computations done by this method will be performed at compile-time as long as all provided arguments are constants; this is important as this will help optimize code size and execution time. This is useful when you want to compare physical values against meaningful limits, and perform actions based on these comparisons; instead of always converting measured raw values into physical ones and then compare with a physical limit, you do the opposite, compare the measured raw values against the raw limits (converted, at compile-time, from physical limits constants).

// This sample code use MPU6050 (accelerometer-gyroscope) support
using namespace devices::magneto;
using namespace utils;
// These is the accelerometer range used in this code
static constexpr const AccelRange ACCEL_RANGE = AccelRange::RANGE_2G;
static constexpr const uint16_t ACCEL_RANGE_IN_G = ACCEL_RANGE_G(ACCEL_RANGE);
// These are specific threshold values for acceleration
static constexpr const int16_t ACCEL_1 = map_physical_to_raw(500, UnitPrefix::MILLI, ACCEL_RANGE_IN_G, 15);
static constexpr const int16_t ACCEL_2 = map_physical_to_raw(1000, UnitPrefix::MILLI, ACCEL_RANGE_IN_G, 15);
// This function performs an action based on current accelerometer value.
void check_accel(int16_t raw)
{
// We consider accelerations the same whatever the sign
if (raw < 0) raw = -raw;
if (raw < ACCEL_1)
act_when_low_accel();
else if (raw < ACCEL_2)
act_when_mid_accel();
else if (raw < ACCEL_2)
act_when_high_accel();
}
Parameters
valuethe physical value to convert
prefixthe unit scale prefix in which value is expressed
rangethe physical measure matching the maximum raw value
precision_bitsthe number of significant bits of the raw value; only positive values are accounted, hence if a raw measure can be any value in [-32768;+32767], then precision_bits is 15.
Returns
the raw value calculated from value, as if directly returned by the device sensor
See also
map_raw_to_physical()

Definition at line 260 of file utilities.h.

◆ as_uint16_t()

constexpr uint16_t utils::as_uint16_t ( uint8_t  high,
uint8_t  low 
)
constexpr

Convert 2 bytes into an unsigned int.

Parameters
highthe high byte
lowthe low byte
Returns
the unsigned integer computed from high and low

Definition at line 295 of file utilities.h.

◆ is_zero()

template<typename T >
constexpr T utils::is_zero ( value,
default_value 
)
constexpr

Replace value by default_value if not "true" (also known as "Elvis operator").

Parameters
valuethe value to check
default_valuethe value to replace 0
Returns
value if value is not false (or 0) otherwise default_value

Definition at line 307 of file utilities.h.

◆ set_mask()

template<typename T >
void utils::set_mask ( volatile T &  reg,
mask,
value 
)

Common utility to force a part of the value of a register, designated by a bit mask.

Template Parameters
Tthe type of values to handle
Parameters
regthe value to change part of
maskthe bit mask indicating which bits shall change
valuethe new value for reg

Definition at line 320 of file utilities.h.

◆ is_mask_equal()

template<typename T >
constexpr bool utils::is_mask_equal ( actual,
mask,
expected 
)
constexpr

Common utility to check if 2 values are equal according to a mask.

Template Parameters
Tthe type of values to compare
Parameters
actualthe actual value to compare
maskthe bit mask indicating which bits shall change
expectedthe expected value

Definition at line 332 of file utilities.h.

◆ bcd_to_binary()

uint8_t utils::bcd_to_binary ( uint8_t  bcd)
inline

Convert Binary-coded decimal byte (each nibble is a digit from 0 to 9) into a natural byte.

Parameters
bcdthe input using BCD format
Returns
bcd converted to natural integer

Definition at line 343 of file utilities.h.

◆ binary_to_bcd()

uint8_t utils::binary_to_bcd ( uint8_t  binary)
inline

Convert a natural integers to a BCD byte (2 digits).

Behavior is undefined if binary >99.

Parameters
binarythe natural integer value to convert to BCD; must be in range [0..99]
Returns
binary converted to BCD

Definition at line 357 of file utilities.h.

◆ swap_bytes() [1/2]

void utils::swap_bytes ( uint16_t &  value)
inline

Swap 2 bytes of a 2-bytes integer.

Useful to convert from big-endian to small-endian (AVR).

Parameters
valuevalue to convert in place (reference)

Definition at line 373 of file utilities.h.

◆ swap_bytes() [2/2]

void utils::swap_bytes ( int16_t &  value)
inline

Swap 2 bytes of a 2-bytes integer.

Useful to convert from big-endian to small-endian (AVR).

Parameters
valuevalue to convert in place (reference)

Definition at line 383 of file utilities.h.

◆ as_uint8_t()

template<typename T >
constexpr uint8_t utils::as_uint8_t ( input)
constexpr

Cast a one byte long bit-fields struct into a byte.

Useful when dealing with devices registers (bytes) where each bit has a specific meaning which you want to clarify through a bitfield struct.

Parameters
inputthe bit field struct value to convert
Returns
input casted as a byte

Definition at line 412 of file utilities.h.

◆ as_array()

template<typename T , typename U = uint8_t[sizeof(T)]>
constexpr void utils::as_array ( const T &  input,
output 
)
constexpr

Cast an instance of type T to an array of uint8_t of the size of T.

Template Parameters
Tthe type of input
Parameters
inputa constant reference to the instance to cast to an array
outputa pointer to an array of the size of T

Definition at line 424 of file utilities.h.

◆ calculate_delay1_count()

constexpr uint8_t utils::calculate_delay1_count ( float  time_us)
constexpr

Calculate the count to pass to delay1() in order to reach time_us microseconds delay.

Calculation is performed at compile-time, provided that time_us is a constant when the method is called. This is to avoid dragging huge mathematics libraries if it can be avoided.

Parameters
time_usthe time to reach through delay1() AVR function
Returns
the count to pass to delay1() AVR function

Definition at line 437 of file utilities.h.

◆ num_bits()

constexpr uint8_t utils::num_bits ( uint8_t  mask,
uint8_t  num = 0 
)
constexpr

Calculate the number of 1 bits in a byte.

Calculation is performed at compile-time, provided that mask is a constant when the method is called.

Parameters
maskthe byte which you want to count the number of 1 bits

Definition at line 447 of file utilities.h.

utils::map_raw_to_physical
constexpr int16_t map_raw_to_physical(int16_t value, UnitPrefix prefix, int16_t range, uint8_t precision_bits)
Convert the raw value, obtained from an electronics device, using precision_bit number of bits (that ...
Definition: utilities.h:187
devices::magneto::ACCEL_RANGE_G
static constexpr uint16_t ACCEL_RANGE_G(AccelRange range)
Convert an AccelRange constant to the real accelerometer range in g.
Definition: mpu6050.h:78
devices::magneto
Defines API for magnetic sensors for direction, speed and acceleration properties.
Definition: common_magneto.h:32
devices::magneto::GyroRange
GyroRange
The full-scale range of the gyroscope in dps (datasheet §6.1).
Definition: mpu6050.h:43
devices::magneto::AccelRange
AccelRange
The full-scale range of the accelerometer in g (datasheet §6.2).
Definition: mpu6050.h:68
utils::map_physical_to_raw
constexpr int16_t map_physical_to_raw(int16_t value, UnitPrefix prefix, int16_t range, uint8_t precision_bits)
Convert an absolute physical value, expressed in some given measurement unit, scaled with prefix,...
Definition: utilities.h:260
devices::magneto::GYRO_RANGE_DPS
static constexpr uint16_t GYRO_RANGE_DPS(GyroRange range)
Convert a GyroRange constant to the real gyroscope range in dps.
Definition: mpu6050.h:53
utils
Contains all generic utility methods.
Definition: utilities.h:52