Arduino library for the Margay data logger. More…

#include <Margay.h>

Inherits from NW_Logger

Public Functions

  Name
  Margay(board model_ =MODEL_3v0, build specs_ =BUILD_B)
Instantiate a Margay logger object.
bool begin(uint8t * vals, uint8_t numVals, String header) override
Initialise the logger with a list of external I2C sensor addresses.
const char * name() const override
< begin(header) with no external sensors
size_t printStatus(Print & out, bool boot =false) override
The logger’s own status line: name, serial, hardware version, library version, report code and note word, Pages 0-2 in hex (its reading of itself: battery, onboard environment, clock). The same columns as a sensor’s.
float getVoltage()
Read voltage from the on-board MCP3421 ADC.
void addDataPoint(String(*)(void) update) override
Log one data point immediately, outside the normal run() cycle.
float getTemp(temp_source sensor =thermistor_temp_sensor)
Read temperature from an on-board sensor.
float getBatVoltage()
Read battery pack voltage.
float getBatPercentage()
Estimate remaining battery charge as a percentage.
void initADC(uint8_t desiredResolution)
Initialise the on-board MCP3421 ADC at a given resolution.
void powerOB(bool state)
Control the on-board 3.3 V power rail.
void powerAux(bool state)
Control the auxiliary 3.3 V power rail for external sensors.

Public Attributes

  Name
uint8_t VRef_Pin
ADC pin connected to voltage reference.
uint8_t ThermSense_Pin
ADC pin connected to on-board NTC thermistor divider.
uint8_t BatSense_Pin
ADC pin connected to battery voltage divider.
uint8_t VSwitch_Pin
Voltage switch control pin.
uint8_t Ext3v3Ctrl
Enable pin for the auxiliary 3.3 V sensor power rail.
uint8_t PG
Power-good indicator pin.
uint8_t ExtInt
External interrupt pin (legacy; use setExtInt()).
uint8_t BatSwitch
Battery switch control pin (255 = not present on this model).
uint8_t TX
Hardware Serial1 TX pin (sensor-facing UART).
uint8_t RX
Hardware Serial1 RX pin (sensor-facing UART).
uint8_t D0
General-purpose digital I/O pin 0.
uint8_t NCells
Number of AA cells in series in the battery pack. Used by getBatPercentage().
float BatVoltageError
Battery voltage threshold [V] below which BatError is set and logged.
float BatPercentageWarning
Battery charge threshold [%] below which BatWarning is set and logged.
const String LibVersion
Library version string, the logger’s FW column in the status file.

Detailed Description

class Margay;

Arduino library for the Margay data logger.

Provides timed SD card logging, on-board diagnostics (BME280, battery voltage, RTC), external sensor I2C management, sleep/wake via RTC alarm, manual log button, and optional external interrupt counting.

Typical usage:

Margay Logger(MODEL_3v0);
void setup() { Logger.begin(I2CVals, sizeof(I2CVals), header); }
void loop()  { Logger.run(update, 60); }

Public Functions Documentation

function Margay

Margay(
    board model_ =MODEL_3v0,
    build specs_ =BUILD_B
)

Instantiate a Margay logger object.

Parameters:

  • model_ Hardware model version (default MODEL_3v0).
  • specs_ Build variant selecting on-board ADC address (default BUILD_B).

Sets board-specific pin assignments based on model and build. Does not initialise hardware; call begin() in setup().

function begin

bool begin(
    uint8_t * vals,
    uint8_t numVals,
    String header_
) override

Initialise the logger with a list of external I2C sensor addresses.

Parameters:

  • vals Pointer to array of 7-bit I2C addresses of external sensors.
  • numVals Number of addresses in vals. Silently truncated to 128.
  • header_ Comma-separated column header string for the log file, matching the CSV data returned by the user’s update() function.

Powers on hardware, initialises the RTC, SD card, BME280, and ADC. Reads the serial number from EEPROM. Runs self-tests for I2C devices, clock, SD card, battery, and power rail, reporting results over Serial at 38400 baud and signalling status via the RGB LED. Attaches RTC alarm and manual-log-button interrupts. Accepts an optional time string over Serial (format YYMMDDHHMMSS) to set the RTC clock on first use.

function name

inline const char * name() const override

< begin(header) with no external sensors

“Margay”.

function printStatus

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

The logger’s own status line: name, serial, hardware version, library version, report code and note word, Pages 0-2 in hex (its reading of itself: battery, onboard environment, clock). The same columns as a sensor’s.

function getVoltage

float getVoltage()

Read voltage from the on-board MCP3421 ADC.

Return: Voltage in volts, or 0 if no on-board ADC is present.

Only available on BUILD_B, BUILD_C, and BUILD_D. Temporarily switches the I2C bus to the internal bus, takes a reading, and restores the bus to its prior state.

function addDataPoint

void addDataPoint(
    String(*)(void) update
) override

Log one data point immediately, outside the normal run() cycle.

Parameters:

  • update Pointer to the user’s update() function.

Switches the I2C bus to external, calls the user’s update() function to obtain sensor data, restores the bus, prepends on-board values (timestamp, BME280, RTC temp, battery voltage), and writes the complete row to the SD card.

function getTemp

float getTemp(
    temp_source sensor =thermistor_temp_sensor
)

Read temperature from an on-board sensor.

Parameters:

  • sensor Temperature source. Options:

  • thermistor_temp_sensor (0): on-board NTC thermistor
  • RTC_temp_sensor (1): DS3231 RTC internal sensor Defaults to thermistor_temp_sensor.

Return: Temperature in degrees Celsius, or -1234 on invalid input.

function getBatVoltage

float getBatVoltage()

Read battery pack voltage.

Return: Battery pack voltage in volts.

Reads the voltage divider on BatSense_Pin and applies a compensation factor derived from the on-board voltage reference. The 3.3 V regulator is used as the ADC reference.

function getBatPercentage

float getBatPercentage()

Estimate remaining battery charge as a percentage.

Return: Charge percentage in [0, 100], or -1 if NCells == 0.

Uses a quadratic fit developed for Duracell AA alkaline cells. Should generalise well to most alkalines; accuracy not guaranteed for other chemistries. Accurate to within ~1% from 30% to 100% capacity at 25°C. Configure the number of cells in series via the public member variable NCells (default 3). NCells must be > 0; setting it to 0 will print an error to Serial and return -1.

function initADC

void initADC(
    uint8_t desiredResolution
)

Initialise the on-board MCP3421 ADC at a given resolution.

Parameters:

  • desiredResolution ADC resolution in bits (12, 14, 16, or 18).

Only meaningful on BUILD_B, BUILD_C, and BUILD_D. Called automatically by begin() for those builds; exposed publicly for advanced use in high-speed sketches.

function powerOB

void powerOB(
    bool state
)

Control the on-board 3.3 V power rail.

Parameters:

  • state ON to enable, OFF to disable.

Drives the BatSwitch pin to connect or disconnect the battery from the on-board sense circuitry. Has no effect on board models without a battery switch (WDHold == 255 models).

function powerAux

void powerAux(
    bool state
)

Control the auxiliary 3.3 V power rail for external sensors.

Parameters:

  • state ON to enable, OFF to disable.

Drives Ext3v3Ctrl to enable or disable power to the external sensor connector. Logic is inverted on MODEL_0v0/1v0 relative to MODEL_2v0 and later. Enabling auxiliary power also enables on-board power via powerOB().

Public Attributes Documentation

variable VRef_Pin

uint8_t VRef_Pin = 2;

ADC pin connected to voltage reference.

variable ThermSense_Pin

uint8_t ThermSense_Pin = 1;

ADC pin connected to on-board NTC thermistor divider.

variable BatSense_Pin

uint8_t BatSense_Pin = 0;

ADC pin connected to battery voltage divider.

variable VSwitch_Pin

uint8_t VSwitch_Pin = 3;

Voltage switch control pin.

variable Ext3v3Ctrl

uint8_t Ext3v3Ctrl = 19;

Enable pin for the auxiliary 3.3 V sensor power rail.

variable PG

uint8_t PG = 18;

Power-good indicator pin.

variable ExtInt

uint8_t ExtInt = 11;

External interrupt pin (legacy; use setExtInt()).

variable BatSwitch

uint8_t BatSwitch = 22;

Battery switch control pin (255 = not present on this model).

variable TX

uint8_t TX = 11;

Hardware Serial1 TX pin (sensor-facing UART).

variable RX

uint8_t RX = 10;

Hardware Serial1 RX pin (sensor-facing UART).

variable D0

uint8_t D0 =  3;

General-purpose digital I/O pin 0.

variable NCells

uint8_t NCells = 3;

Number of AA cells in series in the battery pack. Used by getBatPercentage().

variable BatVoltageError

float BatVoltageError = 3.3;

Battery voltage threshold [V] below which BatError is set and logged.

variable BatPercentageWarning

float BatPercentageWarning = 50;

Battery charge threshold [%] below which BatWarning is set and logged.

variable LibVersion

const String LibVersion = MARGAY_LIBRARY_VERSION;

Library version string, the logger’s FW column in the status file.

Updated on 2026-09-24 at 01:53:23 +0000