Apis

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

#include <Apis.h>

Inherits from NW_Sensor

Public Types

	Name
enum uint8_t	Component { RANGE = 0x01, ORIENT = 0x02, ALL = 0x03} Measurement group: which on-board chip a reading covers.

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 =DEFAULT_ADDRESS, SensitivityMode sensitivity =SENSITIVITY_BALANCED) Begin communications with the Apis using a prescribed address.
uint8_t	getHardwareMajor() Hardware version major, from Page 0 (valid after begin()).
uint8_t	getHardwareMinor() Hardware version minor, from Page 0 (valid after begin()).
uint8_t	getFirmwareVersion() Firmware patch version, from Page 0 (valid after begin(), even when it refused).
uint16_t	setDistanceReadings(uint16_t n) Set the number of range readings taken per updateMeasurements() (statistics are computed over them). Clamped to APIS_RANGE_CAPACITY.
void	setDistanceStats(bool enable) Enable or disable range std and sterr in printDataRow().
uint16_t	setOrientationReadings(uint16_t n) Set the number of orientation readings per updateMeasurements(). Clamped to APIS_ORIENT_CAPACITY.
void	setAccelerationColumns(bool enable) Include the g vector’s X, Y and Z columns in printDataRow() and printDataHeader(). Off by default.
void	setMagnitudeColumns(bool enable) Include the acceleration magnitude column, and its statistics when orientation statistics are on. Off by default.
void	setTiltColumns(bool enable) Include the tilt column, and its statistics when orientation statistics are on. Off by default.
void	setOrientationStats(bool enable) Enable or disable orientation std and sterr in printDataRow().
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	ready() True when the status byte’s ready bit is set: the data registers hold a complete reading.
bool	newReading() True when the device’s reading counter has advanced since this library last stored a reading, i.e. a reading is available that has not been read yet. Does not acquire.
bool	requestReading(uint8_t component =ALL) Ask the device for a reading now, of the selected chips. Writes the control register: trigger bit plus the chip-select bits for the component. The device clears ready, measures, and sets ready again with the counter incremented. A write to control also clears the report byte (acknowledgement).
bool	faulted(uint8_t chip) True if the given chip (0 = LiDAR, 1 = accelerometer) was faulted in the status byte of the last reading taken.
bool	anyFault() True if any chip was faulted in the last reading (status pan-fault bit).
uint8_t	reportChip() Chip index of the most recent report (0 LiDAR, 1 accelerometer, 7 the unit itself), from the Report register read with the last reading; meaningful only when reportKind() != 0.
uint8_t	reportKind() Kind of the most recent report, per the spec’s table: 0 none, 1 no-acknowledge, 2 timeout, 3 checksum, 4 out of range, 5 not initialised, 6 reset since the controller last wrote control, 7 configuration rejected, 8 supply fault, 16–31 device-specific. The device clears it on the next control write (requestReading()).
size_t	printReport(Print & out) Print the report as text, e.g. “LiDAR: timeout” or “unit: restarted since configured”; prints “none” when there is no fault.
size_t	printStatus(Print & out, bool boot =false) override The report as one word for a data-table note column, chip then kind: “LiDARTimeout”, “AccelNotAnswering”, “UnitRestarted”; “UnitNone” when there is no fault (check anyFault() first).
const char *	name() const override
bool	reportIsFault() override
uint8_t	bootReportKind() override
void	clearBootReport() override
bool	updateDistance() Why the last begin() refused, as one word: “NotAnswering”, “NotSchema1”, “WrongName”, “OldFirmware”, “ReadFailed”; “None” after a successful begin().
bool	updateOrientation() Take one orientation reading: request it, wait for the counter to advance, then read the accelerometer and offsets and compute pitch [deg] and roll [deg]. Each call is a distinct acquisition. Returns false on timeout, bus error, or the accelerometer failure signature.
bool	updateMeasurements(uint8_t component =ALL) Take a reading: measure range [cm], roll [deg] and pitch [deg], or one chip’s measurements alone. Uses Welford’s online algorithm to compute mean, std, and sterr over nRangeReadings and nOrientReadings respectively.
uint16_t	getDistanceCount() Number of valid range readings in the last updateMeasurements() call (0 to nRangeReadings). The statistics are computed over these.
uint16_t	getOrientationCount() Number of valid orientation readings in the last updateMeasurements().
float	getDistance() Distance [cm] as logged: the mean over the burst, or the single reading when no burst ran. A float like every other measurement getter, so the burst mean keeps its fraction; the device itself resolves whole centimetres. The same number as getDistanceMean() when a burst ran.
float	getRoll() Return roll mean [deg].
float	getPitch() Return pitch mean [deg].
float	getAccelerationX() Acceleration along the accelerometer X axis [m/s^2].
float	getAccelerationY() Acceleration along the accelerometer Y axis [m/s^2]; see getAccelerationX().
float	getAccelerationZ() Acceleration along the accelerometer Z axis [m/s^2]; see getAccelerationX().
float	getAccelerationMagnitude() Magnitude of the acceleration vector [m/s^2], mean over the burst.
float	getTilt() Angle between the housing and its reference [deg], mean over the burst.
uint8_t	getSignalStrength() Return the most recently cached LiDAR Lite signal strength.
int16_t	getAccelerometerTemperatureADC() The accelerometer’s own temperature at the last orientation reading, in the LIS3DH’s relative digits (1 per degree C, no absolute reference; firmware patch 3). Logged beside pitch and roll so that a per-unit drift correction can be fitted later; APIS_NOT_MEASURED before the first reading.
float	getAccelerometerTemperatureChange() Accelerometer temperature change [C] since the zero was stored.
int16_t	getZeroTemperatureADC() The same digit at the moment the Hall-effect zero was taken (Page 1).
uint16_t	getZeroGeneration() How many zeros the unit has stored since manufacture (0 = never), from the copy the reading carries (0x58–0x59, firmware patch 5). Read with the axes, so it belongs to the last orientation reading; the value seen at begin() before then.
bool	zeroChanged() True when the last orientation reading’s generation differs from the one seen at the reading before it, or at begin(), which reads Page 1’s generation once: the unit has stored a new zero.
size_t	dumpZeros(Print & out) Print the record of zeros from Page 1: the current zero and the two before it, newest first, one line each as generation,X,Y,Z,T (offsets in counts; T the temperature digit at the zero). Zeros never stored print nothing, so a unit zeroed once prints one line. Reads calibration, not a reading: no acquisition.
float	getDistanceMean() Return range mean [cm] as float.
float	getDistanceMedian() Return the median range [cm] of the stored readings (nearest cm for odd N; mean of the middle pair otherwise).
float	getAccelerationMagnitudeMedian() Acceleration magnitude median [m/s^2].
float	getTiltMedian() Tilt median [deg].
float	getPitchMedian() Return the median pitch [deg] of the stored readings.
float	getRollMedian() Return the median roll [deg] of the stored readings.
float	getDistanceStd() Return range standard deviation [cm].
float	getDistanceSterr() Return range standard error [cm].
float	getAccelerationMagnitudeStd() Acceleration magnitude standard deviation [m/s^2].
float	getAccelerationMagnitudeSterr() Acceleration magnitude standard error [m/s^2].
float	getTiltStd() Tilt standard deviation [deg].
float	getTiltSterr() Tilt standard error [deg].
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].
size_t	printDataHeader(Print & out) override Print the summary columns a logger writes: the means, with the statistics columns each chip group has enabled.
size_t	printDataRow(Print & out) override Print one summary row, in printDataHeader()’s column order.
uint8_t	defaultAddress() const override Come back on the bus after the logger cut the sensor rail to sleep.
bool	wake(uint8_t address) override
bool	acquire() override Take this row’s readings and store them, for printDataRow() to print.
size_t	printNote(Print & out, bool beginFailed =false) override Print one word for the logger’s Note column, with no comma.
size_t	printHeader(Print & out) Print the header matching printReading(): column names with units, each followed by a comma, for the chips selected by beginReadings(). No statistics columns: one reading has none.
size_t	printReading(Print & out) Print the stored reading of the selected chips, each value followed by a comma. Does not acquire: call updateDistance(), updateOrientation(), or updateMeasurements() first, or use logReading(). Writes: range [cm] for RANGE; pitch [deg], roll [deg] for ORIENT; range, pitch, roll for ALL.
size_t	logReading(Print & out) Take ONE reading of the selected chips and print it: the one-reading primitive for collecting many readings to a file. Uses updateDistance()/updateOrientation(), not updateMeasurements(), so each call is a single acquisition regardless of nRangeReadings.
void	beginReadings(uint8_t component =ALL, uint16_t n =0) Begin a run of readings, selecting which chips they cover.
void	endReadings() End a run of readings.
void	beginRawReadings(uint8_t component =ALL)
uint16_t	takeRawReading(char * buf, uint16_t offset)
void	endRawReadings()

Public Attributes

	Name
constexpr uint8_t	DEFAULT_ADDRESS Default I2C address: NW-Device-Specification Schema 1 ‘A’ (0x41). Firmware v0.1.x used 0x50.

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 Types Documentation

enum Component

Enumerator	Value	Description
RANGE	0x01	LiDAR Lite only (chip 0: the control chip-select bit).
ORIENT	0x02	Accelerometer only (chip 1).
ALL	0x03	Every chip: range, then pitch and roll.

Measurement group: which on-board chip a reading covers.

One group per chip, in the order the NW-Device-Specification Apis appendix numbers them: 0 = LiDAR Lite (range, signal strength), 1 = LIS3DH accelerometer (pitch, roll). ALL selects every chip. Written as Apis::RANGE etc. at the call site.

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, printDataRow() 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, printDataRow() includes orientation std and sterr. Only meaningful when nOrientReadings > 1.

function begin

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

Begin communications with the Apis using a prescribed address.

Parameters:

• address I2C address (default DEFAULT_ADDRESS = 0x41).
• sensitivity One of the SensitivityMode values (default SENSITIVITY_BALANCED). See SensitivityMode.

Return: true if the device acknowledges and passes all three checks; false otherwise. Call getFirmwareVersion() after a refusal to see what the device reported (0 if unreadable).

Checks that the device acknowledges on I2C, then reads Page 0 Blocks 0–1 and requires: schema byte 0x01 (Schema 1); the name “Apis”; a firmware patch of at least APIS_FW_MIN_PATCH. Stores the hardware and firmware versions for the getters below, and writes the initial sensitivity mode to REG_CONFIG (0x46).

function getHardwareMajor

uint8_t getHardwareMajor()

Hardware version major, from Page 0 (valid after begin()).

function getHardwareMinor

uint8_t getHardwareMinor()

Hardware version minor, from Page 0 (valid after begin()).

function getFirmwareVersion

uint8_t getFirmwareVersion()

Firmware patch version, from Page 0 (valid after begin(), even when it refused).

function setDistanceReadings

uint16_t setDistanceReadings(
    uint16_t n
)

Set the number of range readings taken per updateMeasurements() (statistics are computed over them). Clamped to APIS_RANGE_CAPACITY.

Return: The number actually set.

function setDistanceStats

void setDistanceStats(
    bool enable
)

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

function setOrientationReadings

uint16_t setOrientationReadings(
    uint16_t n
)

Set the number of orientation readings per updateMeasurements(). Clamped to APIS_ORIENT_CAPACITY.

function setAccelerationColumns

void setAccelerationColumns(
    bool enable
)

Include the g vector’s X, Y and Z columns in printDataRow() and printDataHeader(). Off by default.

function setMagnitudeColumns

void setMagnitudeColumns(
    bool enable
)

Include the acceleration magnitude column, and its statistics when orientation statistics are on. Off by default.

function setTiltColumns

void setTiltColumns(
    bool enable
)

Include the tilt column, and its statistics when orientation statistics are on. Off by default.

function setOrientationStats

void setOrientationStats(
    bool enable
)

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

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 (0x46); 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 persists it in Page 0 byte 0x1F and uses it on the next boot; the current session continues on the old address. Falls back to 0x41 if that byte is 0xFF (unprogrammed).

function ready

bool ready()

True when the status byte’s ready bit is set: the data registers hold a complete reading.

function newReading

bool newReading()

True when the device’s reading counter has advanced since this library last stored a reading, i.e. a reading is available that has not been read yet. Does not acquire.

function requestReading

bool requestReading(
    uint8_t component =ALL
)

Ask the device for a reading now, of the selected chips. Writes the control register: trigger bit plus the chip-select bits for the component. The device clears ready, measures, and sets ready again with the counter incremented. A write to control also clears the report byte (acknowledgement).

Return: true if the device acknowledged the write.

function faulted

bool faulted(
    uint8_t chip
)

True if the given chip (0 = LiDAR, 1 = accelerometer) was faulted in the status byte of the last reading taken.

function anyFault

bool anyFault()

True if any chip was faulted in the last reading (status pan-fault bit).

function reportChip

uint8_t reportChip()

Chip index of the most recent report (0 LiDAR, 1 accelerometer, 7 the unit itself), from the Report register read with the last reading; meaningful only when reportKind() != 0.

function reportKind

uint8_t reportKind()

Kind of the most recent report, per the spec’s table: 0 none, 1 no-acknowledge, 2 timeout, 3 checksum, 4 out of range, 5 not initialised, 6 reset since the controller last wrote control, 7 configuration rejected, 8 supply fault, 16–31 device-specific. The device clears it on the next control write (requestReading()).

function printReport

size_t printReport(
    Print & out
)

Print the report as text, e.g. “LiDAR: timeout” or “unit: restarted since configured”; prints “none” when there is no fault.

Return: Bytes written.

function printStatus

size_t printStatus(
    Print & out,
    bool boot =false
) override

The report as one word for a data-table note column, chip then kind: “LiDARTimeout”, “AccelNotAnswering”, “UnitRestarted”; “UnitNone” when there is no fault (check anyFault() first).

Print one status line for a logger’s status file: name, serial, versions, the last report (code and note), and Pages 0, 1 and 2 (identity, calibration, data) in hex, comma separated, no newline. The logger prints its timestamp first. Three page reads, no write: the report is not acknowledged.

function name

inline const char * name() const override

function reportIsFault

bool reportIsFault() override

function bootReportKind

uint8_t bootReportKind() override

function clearBootReport

void clearBootReport() override

function updateDistance

bool updateDistance()

Why the last begin() refused, as one word: “NotAnswering”, “NotSchema1”, “WrongName”, “OldFirmware”, “ReadFailed”; “None” after a successful begin().

Take one range reading [cm]: request it, wait for the device’s reading counter to advance (up to the timeout), then read range and signal strength. Each call is a distinct acquisition, so repeated calls give independent readings for statistics. Returns false on timeout, bus error, or a negative (error) range.

function updateOrientation

bool updateOrientation()

Take one orientation reading: request it, wait for the counter to advance, then read the accelerometer and offsets and compute pitch [deg] and roll [deg]. Each call is a distinct acquisition. Returns false on timeout, bus error, or the accelerometer failure signature.

function updateMeasurements

bool updateMeasurements(
    uint8_t component =ALL
)

Take a reading: measure range [cm], roll [deg] and pitch [deg], or one chip’s measurements alone. Uses Welford’s online algorithm to compute mean, std, and sterr over nRangeReadings and nOrientReadings respectively.

Parameters:

• component Apis::ALL (default), Apis::RANGE, or Apis::ORIENT: which chip(s) to read. Fields of a chip not selected are left as they were.

Return: false if any selected chip returned only error values.

function getDistanceCount

uint16_t getDistanceCount()

Number of valid range readings in the last updateMeasurements() call (0 to nRangeReadings). The statistics are computed over these.

function getOrientationCount

uint16_t getOrientationCount()

Number of valid orientation readings in the last updateMeasurements().

function getDistance

float getDistance()

Distance [cm] as logged: the mean over the burst, or the single reading when no burst ran. A float like every other measurement getter, so the burst mean keeps its fraction; the device itself resolves whole centimetres. The same number as getDistanceMean() when a burst ran.

function getRoll

float getRoll()

Return roll mean [deg].

function getPitch

float getPitch()

Return pitch mean [deg].

function getAccelerationX

float getAccelerationX()

Acceleration along the accelerometer X axis [m/s^2].

The last reading rather than a burst mean, as getSignalStrength() is: the three components carry no statistics columns. getAccelerationMagnitude() is a burst mean, so it does not equal the magnitude of these three when more than one reading was taken. APIS_NOT_MEASURED before the first reading, APIS_ERROR when it failed.

function getAccelerationY

float getAccelerationY()

Acceleration along the accelerometer Y axis [m/s^2]; see getAccelerationX().

function getAccelerationZ

float getAccelerationZ()

Acceleration along the accelerometer Z axis [m/s^2]; see getAccelerationX().

function getAccelerationMagnitude

float getAccelerationMagnitude()

Magnitude of the acceleration vector [m/s^2], mean over the burst.

Reads 9.81 whenever the unit is static, so a departure means the Apis moved or the accelerometer is faulted. Pitch and roll cannot report that: a wrong g vector still yields plausible angles.

function getTilt

float getTilt()

Angle between the housing and its reference [deg], mean over the burst.

Measured from the stored zero when one has been taken, and from vertical when none has, which is the same branch getPitch() and getRoll() take. One number for a levelling correction; pitch and roll stay, because recovering the direction of tilt needs both.

function getSignalStrength

uint8_t getSignalStrength()

Return the most recently cached LiDAR Lite signal strength.

Updated by every call to updateDistance() or updateMeasurements(). Returns 0 before the first measurement. It is a column of its own (Andy, 2026-10-01), beside the distance it qualifies: a weak return explains a bad range, and a reader with only the range cannot tell a poor target from a moved one. One byte, not averaged, so it carries the bare standard name rather than a mean_of_ form. A failed reading leaves 0, which is also what the firmware writes when the LiDAR will not power up; a uint8_t cannot carry the -9999 sentinel.

function getAccelerometerTemperatureADC

int16_t getAccelerometerTemperatureADC()

The accelerometer’s own temperature at the last orientation reading, in the LIS3DH’s relative digits (1 per degree C, no absolute reference; firmware patch 3). Logged beside pitch and roll so that a per-unit drift correction can be fitted later; APIS_NOT_MEASURED before the first reading.

function getAccelerometerTemperatureChange

float getAccelerometerTemperatureChange()

Accelerometer temperature change [C] since the zero was stored.

The LIS3DH measures change, not temperature: its Table 5 specifies only the output change versus temperature, 1 digit per degree C and not guaranteed, with no offset and no reference point. So this is a departure from the temperature at which the Hall-effect zero was taken, which is what the drift correction wants, and it is APIS_NOT_MEASURED when no zero has ever been stored, because there is then nothing to be a change from.

function getZeroTemperatureADC

int16_t getZeroTemperatureADC()

The same digit at the moment the Hall-effect zero was taken (Page 1).

function getZeroGeneration

uint16_t getZeroGeneration()

How many zeros the unit has stored since manufacture (0 = never), from the copy the reading carries (0x58–0x59, firmware patch 5). Read with the axes, so it belongs to the last orientation reading; the value seen at begin() before then.

It is a column of its own (Andy, 2026-10-01), last in the row beside the accelerometer temperature change, which is the other zero-relative fact. Pitch, roll and tilt are all measured against a stored zero, and a re-zero mid-deployment silently changes what every later angle means. The generation in each row is what lets an analyst segment the record: equal generation means comparable angles. The firmware anticipates this by mirroring the Page 1 value into Page 2 at 0x58 and serving it with every reading.

function zeroChanged

bool zeroChanged()

True when the last orientation reading’s generation differs from the one seen at the reading before it, or at begin(), which reads Page 1’s generation once: the unit has stored a new zero.

function dumpZeros

size_t dumpZeros(
    Print & out
)

Print the record of zeros from Page 1: the current zero and the two before it, newest first, one line each as generation,X,Y,Z,T (offsets in counts; T the temperature digit at the zero). Zeros never stored print nothing, so a unit zeroed once prints one line. Reads calibration, not a reading: no acquisition.

Return: Bytes written.

function getDistanceMean

float getDistanceMean()

Return range mean [cm] as float.

function getDistanceMedian

float getDistanceMedian()

Return the median range [cm] of the stored readings (nearest cm for odd N; mean of the middle pair otherwise).

function getAccelerationMagnitudeMedian

float getAccelerationMagnitudeMedian()

Acceleration magnitude median [m/s^2].

function getTiltMedian

float getTiltMedian()

Tilt median [deg].

function getPitchMedian

float getPitchMedian()

Return the median pitch [deg] of the stored readings.

function getRollMedian

float getRollMedian()

Return the median roll [deg] of the stored readings.

function getDistanceStd

float getDistanceStd()

Return range standard deviation [cm].

function getDistanceSterr

float getDistanceSterr()

Return range standard error [cm].

function getAccelerationMagnitudeStd

float getAccelerationMagnitudeStd()

Acceleration magnitude standard deviation [m/s^2].

function getAccelerationMagnitudeSterr

float getAccelerationMagnitudeSterr()

Acceleration magnitude standard error [m/s^2].

function getTiltStd

float getTiltStd()

Tilt standard deviation [deg].

function getTiltSterr

float getTiltSterr()

Tilt standard error [deg].

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 printDataHeader

size_t printDataHeader(
    Print & out
) override

Print the summary columns a logger writes: the means, with the statistics columns each chip group has enabled.

Parameters:

• out Where to print.

Return: Bytes printed.

The streaming form of printDataHeader(), and its definition: that function prints through this one into a String. Pass a File to write the card, Serial to write the monitor. Distinct from printHeader(), which is the burst interface and carries no statistics.

function printDataRow

size_t printDataRow(
    Print & out
) override

Print one summary row, in printDataHeader()’s column order.

Parameters:

• out Where to print.

Return: Bytes printed.

Takes no reading: it prints what the last updateMeasurements() left, which is what lets a caller write the same row to two sinks without acquiring twice.

function defaultAddress

uint8_t defaultAddress() const override

Come back on the bus after the logger cut the sensor rail to sleep.

Return: True when the sensor answered and passed begin()’s gates.

One of the three calls a logger makes on a watched sensor (LIBRARY-DESIGN.md section 14 step 4). It re-runs begin() at the address this sensor was begun with. The address this sensor answers at unless the logger says otherwise.

function wake

bool wake(
    uint8_t address
) override

function acquire

bool acquire() override

Take this row’s readings and store them, for printDataRow() to print.

Return: True when a reading was taken.

function printNote

size_t printNote(
    Print & out,
    bool beginFailed =false
) override

Print one word for the logger’s Note column, with no comma.

Parameters:

• beginFailed print why begin() refused, rather than what the last reading reported.

Return: Bytes printed.

function printHeader

size_t printHeader(
    Print & out
)

Print the header matching printReading(): column names with units, each followed by a comma, for the chips selected by beginReadings(). No statistics columns: one reading has none.

Parameters:

• out Any Print destination (SdFat File, Serial, …).

Return: Bytes written.

function printReading

size_t printReading(
    Print & out
)

Print the stored reading of the selected chips, each value followed by a comma. Does not acquire: call updateDistance(), updateOrientation(), or updateMeasurements() first, or use logReading(). Writes: range [cm] for RANGE; pitch [deg], roll [deg] for ORIENT; range, pitch, roll for ALL.

Return: Bytes written.

function logReading

size_t logReading(
    Print & out
)

Take ONE reading of the selected chips and print it: the one-reading primitive for collecting many readings to a file. Uses updateDistance()/updateOrientation(), not updateMeasurements(), so each call is a single acquisition regardless of nRangeReadings.

Return: Bytes written.

function beginReadings

void beginReadings(
    uint8_t component =ALL,
    uint16_t n =0
)

Begin a run of readings, selecting which chips they cover.

Parameters:

• component Apis::ALL, Apis::RANGE, or Apis::ORIENT.
• n How many readings the run will take (the number of logReading() calls to follow). With n > 1 the device is told in advance (readings-requested word, registers 0x44-0x45) and keeps the LiDAR powered and initialised for exactly that many readings; with 0 or 1 each reading powers the LiDAR up and down. A run that stops short is abandoned by the device after 2 s with a report.

function endReadings

void endReadings()

End a run of readings.

function beginRawReadings

void beginRawReadings(
    uint8_t component =ALL
)

Deprecated:

Use beginReadings().

function takeRawReading

uint16_t takeRawReading(
    char * buf,
    uint16_t offset
)

Deprecated:

Use logReading(Print&) with an SdFat File, Serial, or a buffer-backed Print. Kept for v0.1.x sketches: takes one raw reading and writes CSV into buf at offset (range for RANGE; pitch, roll for ORIENT; all three for ALL). Max bytes: 7 (RANGE), 18 (ORIENT), 25 (ALL).

Return: New offset after writing.

function endRawReadings

void endRawReadings()

Deprecated:

Use endReadings().

Public Attributes Documentation

variable DEFAULT_ADDRESS

static constexpr uint8_t DEFAULT_ADDRESS = 0x41;

Default I2C address: NW-Device-Specification Schema 1 ‘A’ (0x41). Firmware v0.1.x used 0x50.

---

Updated on 2026-10-04 at 04:51:39 +0000