Apis

Arduino library for the Apis board, which manages a LiDAR Lite unit (roll/pitch, firmware lock/reset, power supply). More…

#include <Apis.h>

Public Functions

	Name
	Apis(uint16_t nRangeReadings =1, bool rangeStats =false, uint16_t nOrientReadings =1, bool orientStats =false) Instantiate Apis object.
bool	begin(uint8_t address =ADR_DEFAULT, SensitivityMode sensitivity =SENSITIVITY_BALANCED) Begin communications with the Apis using a prescribed address.
void	setNRangeReadings(uint16_t n) Set number of range readings to average.
void	setRangeStats(bool enable) Enable or disable range std and sterr in getString().
void	setNOrientReadings(uint16_t n) Set number of orientation readings to average.
void	setOrientStats(bool enable) Enable or disable orientation std and sterr in getString().
void	setRangefinderSensitivity(SensitivityMode mode) Change the rangefinder sensitivity mode after begin().
void	setI2CAddress(uint8_t newAddress) Write a new I2C address to the device.
bool	updateRange() Measure range [cm] only, without reading the accelerometer. Intended for rapid repeated range readings (e.g. for averaging). Also updates the cached signal strength (see getSignalStrength()). Returns false if the sensor returns an error value.
bool	updateOrientation() Measure pitch [deg] and roll [deg] only, without ranging. Intended for rapid repeated orientation readings (e.g. for averaging). FIX: Independent readings require firmware support; current firmware caches accelerometer values each loop (~200 ms). Returns false if the sensor returns an error value.
bool	updateMeasurements() Measure range [cm], roll [deg] and pitch [deg]. Uses Welford’s online algorithm to compute mean, std, and sterr over nRangeReadings and nOrientReadings respectively. Returns false if any sensor returns an error value.
int16_t	getRange() Return range mean [cm], rounded to nearest cm.
float	getRoll() Return roll mean [deg].
float	getPitch() Return pitch mean [deg].
uint8_t	getSignalStrength() Return the most recently cached LiDAR Lite signal strength.
float	getRangeMean() Return range mean [cm] as float.
float	getRangeStd() Return range standard deviation [cm].
float	getRangeSterr() Return range standard error [cm].
float	getPitchStd() Return pitch standard deviation [deg].
float	getPitchSterr() Return pitch standard error [deg].
float	getRollStd() Return roll standard deviation [deg].
float	getRollSterr() Return roll standard error [deg].
String	getHeader() Return a comma-separated header matching getString() output. Includes statistics columns when rangeStats or orientStats are enabled and nReadings > 1.
String	getString(bool takeNewReadings =true) Return comma-separated data values.
void	beginRawReadings(uint8_t component =NW_READING_ALL) Prepare for raw reading collection.
uint16_t	takeRawReading(char * buf, uint16_t offset) Take one raw reading and write CSV data into buf at offset. Writes: range [cm] for RANGE; pitch [deg], roll [deg] for ORIENT; range, pitch, roll for ALL. Each value followed by a comma. Max bytes written per call: 7 (RANGE), 18 (ORIENT), 25 (ALL).
void	endRawReadings() End raw reading collection.

Detailed Description

class Apis;

Arduino library for the Apis board, which manages a LiDAR Lite unit (roll/pitch, firmware lock/reset, power supply).

Library to communicate with the Apis module, which connects to a LiDAR Lite rangefinder. The Apis is equipped with capacitors to handle the large burst power draw from the LiDAR Lite, a MEMS accelerometer to note its orientation, a magnet to note a known orientation (often, but not necessarily, horizontal) and the ability to absorb occasional firmware issues that lead to system hangs. The leveling helps the user to calculate, for example, a water level when the sensor is placed on a cliff or a tree next to the river but does not have water below it. The level loses absolute accuracy when near plumb, so a Hall-effect sensor connected to the magnet allows the user to set a zero value, thereby correcting for this. Managing failures of the LiDAR Lite within the Apis is essential, and the Apis therefore acts as a buffer to protect the data logger from raw sensor failures.

Public Functions Documentation

function Apis

Apis(
    uint16_t nRangeReadings =1,
    bool rangeStats =false,
    uint16_t nOrientReadings =1,
    bool orientStats =false
)

Instantiate Apis object.

Parameters:

• nRangeReadings Number of range readings to average (default 1). Paul et al. (2020, WRR, doi:10.1029/2019WR026810) found ~1000 readings needed for stable mean convergence under field conditions. Uses Welford’s online algorithm: O(1) memory regardless of count. FIX: Independent readings require firmware support for on-demand triggering; current firmware caches the value each loop (~200 ms).
• rangeStats If true, getString() includes range std and sterr. Only meaningful when nRangeReadings > 1.
• nOrientReadings Number of orientation readings to average (default 1). FIX: Independent readings require firmware support; current firmware caches accelerometer values each loop (~200 ms).
• orientStats If true, getString() includes orientation std and sterr. Only meaningful when nOrientReadings > 1.

function begin

bool begin(
    uint8_t address =ADR_DEFAULT,
    SensitivityMode sensitivity =SENSITIVITY_BALANCED
)

Begin communications with the Apis using a prescribed address.

Parameters:

• address I2C address (default ADR_DEFAULT = 0x50).
• sensitivity One of the SensitivityMode values (default SENSITIVITY_BALANCED). Written to REG_CONFIG (0x0B) and applied each firmware loop() iteration. See SensitivityMode for descriptions of each mode.

Return: true if the device acknowledges and reports correct firmware; false otherwise.

Checks that the device acknowledges on I2C, verifies that the firmware reports the “Apis” device name at registers 0x01–0x04 (indicating firmware v0.2.0+ with the current register map), and writes the initial sensitivity mode to REG_CONFIG (0x0B). Returns false if: (a) no I2C ACK, or (b) name mismatch (old firmware). The minimum firmware version policy beyond that name check is TBD.

function setNRangeReadings

void setNRangeReadings(
    uint16_t n
)

Set number of range readings to average.

function setRangeStats

void setRangeStats(
    bool enable
)

Enable or disable range std and sterr in getString().

function setNOrientReadings

void setNOrientReadings(
    uint16_t n
)

Set number of orientation readings to average.

function setOrientStats

void setOrientStats(
    bool enable
)

Enable or disable orientation std and sterr in getString().

function setRangefinderSensitivity

void setRangefinderSensitivity(
    SensitivityMode mode
)

Change the rangefinder sensitivity mode after begin().

Parameters:

• mode One of the SensitivityMode values.

Writes the new mode to REG_CONFIG (0x0B); the firmware applies it on the next loop() iteration via InitLiDAR(). Must be called after begin(); if called before, Wire is uninitialised and the transmission fails silently.

function setI2CAddress

void setI2CAddress(
    uint8_t newAddress
)

Write a new I2C address to the device.

Parameters:

• newAddress The 7-bit I2C address to persist.

The firmware saves it to EEPROM byte 6 and uses it on the next boot; the current session continues on the old address. Falls back to 0x50 if EEPROM byte 6 is 0xFF (erased).

function updateRange

bool updateRange()

Measure range [cm] only, without reading the accelerometer. Intended for rapid repeated range readings (e.g. for averaging). Also updates the cached signal strength (see getSignalStrength()). Returns false if the sensor returns an error value.

function updateOrientation

bool updateOrientation()

Measure pitch [deg] and roll [deg] only, without ranging. Intended for rapid repeated orientation readings (e.g. for averaging). FIX: Independent readings require firmware support; current firmware caches accelerometer values each loop (~200 ms). Returns false if the sensor returns an error value.

function updateMeasurements

bool updateMeasurements()

Measure range [cm], roll [deg] and pitch [deg]. Uses Welford’s online algorithm to compute mean, std, and sterr over nRangeReadings and nOrientReadings respectively. Returns false if any sensor returns an error value.

function getRange

int16_t getRange()

Return range mean [cm], rounded to nearest cm.

function getRoll

float getRoll()

Return roll mean [deg].

function getPitch

float getPitch()

Return pitch mean [deg].

function getSignalStrength

uint8_t getSignalStrength()

Return the most recently cached LiDAR Lite signal strength.

Updated by every call to updateRange() or updateMeasurements(). Returns 0 before the first measurement.

function getRangeMean

float getRangeMean()

Return range mean [cm] as float.

function getRangeStd

float getRangeStd()

Return range standard deviation [cm].

function getRangeSterr

float getRangeSterr()

Return range standard error [cm].

function getPitchStd

float getPitchStd()

Return pitch standard deviation [deg].

function getPitchSterr

float getPitchSterr()

Return pitch standard error [deg].

function getRollStd

float getRollStd()

Return roll standard deviation [deg].

function getRollSterr

float getRollSterr()

Return roll standard error [deg].

function getHeader

String getHeader()

Return a comma-separated header matching getString() output. Includes statistics columns when rangeStats or orientStats are enabled and nReadings > 1.

function getString

String getString(
    bool takeNewReadings =true
)

Return comma-separated data values.

Parameters:

• takeNewReadings if true, run updateMeasurements() before returning values. Otherwise, return stored values.

This is the most likely function (alongside getHeader) for an end user to use. Always includes: Range [cm], Pitch [deg], Roll [deg]. Appends range std and sterr when rangeStats is true and nRangeReadings > 1. Appends orientation std and sterr when orientStats is true and nOrientReadings > 1. Error values are APIS_ERROR (-9999) for sensor errors and APIS_NOT_MEASURED (-9998) when no measurement has yet been taken.

function beginRawReadings

void beginRawReadings(
    uint8_t component =NW_READING_ALL
)

Prepare for raw reading collection.

Parameters:

• component NW_READING_ALL, NW_READING_RANGE (primary), or NW_READING_ORIENT (secondary).

function takeRawReading

uint16_t takeRawReading(
    char * buf,
    uint16_t offset
)

Take one raw reading and write CSV data into buf at offset. Writes: range [cm] for RANGE; pitch [deg], roll [deg] for ORIENT; range, pitch, roll for ALL. Each value followed by a comma. Max bytes written per call: 7 (RANGE), 18 (ORIENT), 25 (ALL).

Parameters:

• buf Caller-managed destination buffer.
• offset Starting write position in buf.

Return: New offset after writing.

function endRawReadings

void endRawReadings()

End raw reading collection.

---

Updated on 2026-05-14 at 20:14:00 +0000