ModularSensors > Classes > Logger
ModularSensors > Modules > Primary Object Classes > Logger


Logger class

The "Logger" Class handles low power sleep for the main processor, interfacing with the real-time clock and modem, writing to the SD card, and passing data on to the data publishers.

A logger is a device that can control all functions of the modem sensors and that are attached to it and save the values of all variables measured by those sensors to an attached SD card. It must also work with a real-time clock to give timestamps to values. It may also work with a loggerModem for internet connection and send out data over the internet through one or more data publishers.

In this library, all loggers are Arduino-style small processor circuit boards.

Constructors, destructors, conversion operators

Logger(const char* loggerID, uint16_t loggingIntervalMinutes, int8_t SDCardSSPin, int8_t mcuWakePin, VariableArray* inputArray)
Construct a new Logger object.
Logger(const char* loggerID, uint16_t loggingIntervalMinutes, VariableArray* inputArray)
Construct a new Logger object.
Logger()
Construct a new Logger object.
~Logger() virtual
Destroy the Logger object - takes no action.

Basic Logging Parameters

Public functions to get and set basic logging paramters

const char* _loggerID protected
The logger id.
uint16_t _loggingIntervalMinutes protected
The logging interval in minutes.
int8_t _SDCardSSPin protected
Digital pin number on the mcu controlling the SD card slave select.
int8_t _SDCardPowerPin protected
Digital pin number on the mcu controlling SD card power.
int8_t _mcuWakePin protected
Digital pin number on the mcu receiving interrupts to wake from deep-sleep.
int8_t _ledPin protected
Digital pin number on the mcu used to output an alert that the logger is measuring.
int8_t _buttonPin protected
Digital pin number on the mcu receiving interrupts to enter testing mode.
const char* _samplingFeatureUUID protected
The sampling feature UUID.
void setLoggerID(const char* loggerID)
Set the Logger ID.
const char* getLoggerID()
Get the Logger ID.
void setLoggingInterval(uint16_t loggingIntervalMinutes)
Set the logging interval in minutes.
uint16_t getLoggingInterval()
Get the Logging Interval.
void setSamplingFeatureUUID(const char* samplingFeatureUUID)
Set the universally unique identifier (UUID or GUID) of the sampling feature.
const char* getSamplingFeatureUUID()
Get the Sampling Feature UUID.
void setSDCardPwr(int8_t SDCardPowerPin)
Set a digital pin number (on the mcu) to use to control power to the SD card and activate it as an output pin.
void turnOnSDcard(bool waitToSettle = true)
Send power to the SD card by setting the SDCardPowerPin HIGH.
void turnOffSDcard(bool waitForHousekeeping = true)
Cut power to the SD card by setting the SDCardPowerPin LOW.
void setSDCardSS(int8_t SDCardSSPin)
Set a digital pin number for the slave select (chip select) of the SD card and activate it as an output pin.
void setSDCardPins(int8_t SDCardSSPin, int8_t SDCardPowerPin)
Set both pin numbers related to the SD card and activate them as output pins.
void setRTCWakePin(int8_t mcuWakePin, uint8_t wakePinMode = INPUT_PULLUP)
Set digital pin number for the wake up pin used as an RTC interrupt and activate it in the given pin mode.
void setAlertPin(int8_t ledPin)
Set the digital pin number to put out an alert that a measurement is being logged and activate it as an output pin.
void alertOn()
Set the alert pin high.
void alertOff()
Set the alert pin low.
void setTestingModePin(int8_t buttonPin, uint8_t buttonPinMode = INPUT)
Set the digital pin number for an interrupt pin used to enter testing mode, activate that pin as the given input type, and attach the testing interrupt to it.
void setLoggerPins(int8_t mcuWakePin, int8_t SDCardSSPin, int8_t SDCardPowerPin, int8_t buttonPin, int8_t ledPin, uint8_t wakePinMode = INPUT_PULLUP, uint8_t buttonPinMode = INPUT)
Set the digital pin numbers and activate pin modes for the five pins of interest for the logger.

Attached Variable Array Functions

Public functions to get information about the attached variable array

VariableArray* _internalArray protected
A pointer to the internal variable array instance.
void setVariableArray(VariableArray* inputArray)
Set the variable array object.
uint8_t getArrayVarCount()
Get the number of variables in the internal variable array object.
String getParentSensorNameAtI(uint8_t position_i)
Get the name of the parent sensor of the variable at the given position in the internal variable array object.
String getParentSensorNameAndLocationAtI(uint8_t position_i)
Get the name and pin location of the parent sensor of the variable at the given position in the internal variable array object.
String getVarNameAtI(uint8_t position_i)
Get the name of the variable at the given position in the internal variable array object.
String getVarUnitAtI(uint8_t position_i)
Get the unit of the variable at the given position in the internal variable array object.
String getVarCodeAtI(uint8_t position_i)
Get the customized code of the variable at the given position in the internal variable array object.
String getVarUUIDAtI(uint8_t position_i)
Get the UUID of the variable at the given position in the internal variable array object.
String getValueStringAtI(uint8_t position_i)
Get the most recent value of the variable at the given position in the internal variable array object.

Internet and Publisher Functions

Public functions for internet and dataPublishers

loggerModem* _logModem protected
The internal modem instance.
dataPublisher* dataPublishers protected
An array of all of the attached data publishers.
void attachModem(loggerModem& modem)
Attach a loggerModem to the logger to provide internet access.
bool syncRTC()
Use the attahed loggerModem to synchronize the real-time clock with NIST time servers.
void registerDataPublisher(dataPublisher* publisher)
Register a data publisher object to receive data from the logger.
void publishDataToRemotes(void )
Publish data to all registered data publishers.
void sendDataToRemotes(void ) deprecated in v0.22.5
Retained for backwards compatibility, use publishDataToRemotes() in new code.

SD Cards and Saving Data

Public functions for logging data to an SD card

SdFat sd protected
An internal reference to SdFat for SD card control.
File logFile protected
An internal reference to an SdFat file instance.
String _fileName protected
An internal reference to the current filename.
void setFileName(const char* fileName)
Set the file name, if you want to decide on it in advance.
void setFileName(String& fileName)
Set the file name, if you want to decide on it in advance.
String getFileName(void )
Get the current filename.
void printFileHeader(Stream* stream) virtual
Print a header out to a stream.
void printSensorDataCSV(Stream* stream)
Print a comma separated list of volues of sensor data - including the time in the logging timezone - out over an Arduino stream.
bool createLogFile(String& filename, bool writeDefaultHeader = false)
Create a file on the SD card and set the created, modified, and accessed timestamps in that file.
bool createLogFile(bool writeDefaultHeader = false)
Create a file on the SD card and set the created, modified, and accessed timestamps in that file.
bool logToSD(String& filename, String& rec)
Open a file with the given name on the SD card and append the given line to the bottom of it.
bool logToSD(String& rec)
Open a file named with the current internal filename value and append the given line to the bottom of it.
bool logToSD(void )
Open a file named with the current internal filename value and append a line to the bottom of it with the most recent values of all variables in the variable array as a comma separated list.
bool initializeSDCard(void ) protected
Check if the SD card is available and ready to write to.
void generateAutoFileName(void ) protected
Generate a file name from the logger id and the current date.
void setFileTimestamp(File fileToStamp, uint8_t stampFlag) protected
Set a timestamp on a file.
bool openFile(String& filename, bool createFile, bool writeDefaultHeader) protected
Open or creates a file, converting a string file name to a character file name.

Clock and Timezones

Public Functions for sleeping the logger

static int8_t _loggerTimeZone protected
The static timezone data is being logged in.
static int8_t _loggerRTCOffset protected
The static difference between the timezone of the RTC and the timezone data is being logged in.
extendedWatchDogAVR watchDogTimer
A watch-dog implementation to use to reboot the system in case of lock-ups.
bool setRTClock(uint32_t UTCEpochSeconds)
Veify that the input value is sane and if so sets the real time clock to the given time.
bool checkInterval(void )
Check if the CURRENT time is an even interval of the logging rate.
bool checkMarkedInterval(void )
Check if the MARKED time is an even interval of the logging rate - That is the value saved in the static variable markedLocalEpochTime.
void systemSleep(void )
Put the mcu to sleep to conserve battery life and handle post-interrupt wake actions.
static void setLoggerTimeZone(int8_t timeZone)
Set the static timezone that the data will be logged in.
static int8_t getLoggerTimeZone(void )
Get the Logger Time Zone.
static void setTimeZone(int8_t timeZone) deprecated in v0.22.4
Retained for backwards compatibility; use setLoggerTimeZone(int8_t timeZone) in new code.
static int8_t getTimeZone(void ) deprecated in v0.22.4
Retained for backwards compatibility; use getLoggerTimeZone() in new code.
static void setRTCTimeZone(int8_t timeZone)
Set the static timezone that the RTC is programmed in.
static int8_t getRTCTimeZone(void )
Get the timezone of the real-time clock (RTC).
static void setTZOffset(int8_t offset)
Set the offset between the built-in clock and the time zone where the data is being recorded.
static int8_t getTZOffset(void )
Get the offset between the built-in clock and the time zone where the data is being recorded.
static uint32_t getNowEpoch(void ) deprecated in v0.33.0
Get the current epoch time from the RTC (unix time, ie, the number of seconds from January 1, 1970 00:00:00) and correct it to the logging time zone.
static uint32_t getNowLocalEpoch(void )
Get the current epoch time from the RTC (unix time, ie, the number of seconds from January 1, 1970 00:00:00) and correct it to the logging time zone.
static uint32_t getNowUTCEpoch(void )
Get the current Universal Coordinated Time (UTC) epoch time from the RTC (unix time, ie, the number of seconds from January 1, 1970 00:00:00 UTC)
static void setNowUTCEpoch(uint32_t ts)
Set the real time clock to the given number of seconds from January 1, 1970.
static DateTime dtFromEpoch(uint32_t epochTime)
Convert the number of seconds from January 1, 1970 to a DateTime object instance.
static String formatDateTime_ISO8601(DateTime& dt)
Convert a date-time object into a ISO8601 formatted string.
static String formatDateTime_ISO8601(uint32_t epochTime)
Convert an epoch time (unix time) into a ISO8601 formatted string.
static bool isRTCSane(void )
Check that the current time on the RTC is within a "sane" range.
static bool isRTCSane(uint32_t epochTime)
Check that a given epoch time (seconds since 1970) is within a "sane" range.
static void markTime(void )
Set static variables for the date/time.
static void wakeISR(void )
Set up the Interrupt Service Request for waking.

Do-It-All Convience Functions

Convience functions to call several of the above functions

static uint32_t markedLocalEpochTime
The static "marked" epoch time for the local timezone.
static uint32_t markedUTCEpochTime
The static "marked" epoch time for UTC.
static volatile bool isLoggingNow
Internal flag set to true when logger is currently updating sensors or writing to the SD card.
static volatile bool isTestingNow
Internal flag set to true when the logger is going through the "testing mode" routine.
static volatile bool startTesting
Internal flag set to true with then logger should begin the "testing mode" routine when it finishes other operations.
void begin(const char* loggerID, uint16_t loggingIntervalMinutes, VariableArray* inputArray) virtual
Set all pin levels and does initial communication with the real-time clock and SD card to prepare the logger for full functionality.
void begin(VariableArray* inputArray) virtual
Set all pin levels and does initial communication with the real-time clock and SD card to prepare the logger for full functionality.
void begin() virtual
Set all pin levels and does initial communication with the real-time clock and SD card to prepare the logger for full functionality.
void logData(void ) virtual
This is a one-and-done to log data.
void logDataAndPublish(void )
This is a one-and-done to log data and publish the results to any associated publishers.

Sensor Testing Mode

Public functions for a "sensor testing" mode

void testingMode() virtual
Execute testing mode.
static void testingISR(void )
The interrupt sevice routine called when an iterrupt is detected on the pin assigned for "testing" mode.

Function documentation

Logger(const char* loggerID, uint16_t loggingIntervalMinutes, int8_t SDCardSSPin, int8_t mcuWakePin, VariableArray* inputArray)

Construct a new Logger object.

Parameters
loggerID A name for the logger - unless otherwise specified, files saved to the SD card will be named with the logger id and the date the file was started.
loggingIntervalMinutes The frequency in minutes at which data should be logged
SDCardSSPin The pin of the chip select/slave select for the SPI connection to the SD card
mcuWakePin The pin used to wake the logger from deep sleep - expected to be attached to an alarm pin of the real-time clock. Use a value of -1 to prevent the board from sleeping.
inputArray A variableArray object instance providing data to be logged. This is NOT an array of variables, but an object of the variable array class.

Logger(const char* loggerID, uint16_t loggingIntervalMinutes, VariableArray* inputArray)

Construct a new Logger object.

Parameters
loggerID A name for the logger - unless otherwise specified, files saved to the SD card will be named with the logger id and the date the file was started.
loggingIntervalMinutes The frequency in minutes at which data should be logged
inputArray A variableArray object instance providing data to be logged. This is NOT an array of variables, but an object of the variable array class.

Logger()

Construct a new Logger object.


void setLoggerID(const char* loggerID)

Set the Logger ID.

Parameters
loggerID A pointer to the logger ID

Unless otherwise specified, files saved to the SD card will be named with the logger id and the date the file was started.


const char* getLoggerID()

Get the Logger ID.

Returns const char* A pointer to the logger ID

void setLoggingInterval(uint16_t loggingIntervalMinutes)

Set the logging interval in minutes.

Parameters
loggingIntervalMinutes The frequency with which to update sensor values and write data to the SD card.

uint16_t getLoggingInterval()

Get the Logging Interval.

Returns uint16_t The logging interval in minutes

void setSamplingFeatureUUID(const char* samplingFeatureUUID)

Set the universally unique identifier (UUID or GUID) of the sampling feature.

Parameters
samplingFeatureUUID A pointer to the sampling feature UUID

const char* getSamplingFeatureUUID()

Get the Sampling Feature UUID.

Returns const char* The sampling feature UUID

void setSDCardPwr(int8_t SDCardPowerPin)

Set a digital pin number (on the mcu) to use to control power to the SD card and activate it as an output pin.

Parameters
SDCardPowerPin A digital pin number on the mcu controlling power to the SD card.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.


void turnOnSDcard(bool waitToSettle = true)

Send power to the SD card by setting the SDCardPowerPin HIGH.

Parameters
waitToSettle True to add a short (6ms) delay between powering on the card and beginning initialization. Defaults to true.

Optionally waits for the card to "settle." Has no effect if a pin has not been set to control power to the SD card.


void turnOffSDcard(bool waitForHousekeeping = true)

Cut power to the SD card by setting the SDCardPowerPin LOW.

Parameters
waitForHousekeeping True to add a 1 second delay between to allow any on-chip writing to complete before cutting power. Defaults to true.

Optionally waits for the card to do "housekeeping" before cutting the power. Has o effect if a pin has not been set to control power to the SD card.


void setSDCardSS(int8_t SDCardSSPin)

Set a digital pin number for the slave select (chip select) of the SD card and activate it as an output pin.

Parameters
SDCardSSPin The pin on the mcu connected to the slave select of the SD card.

This over-writes the value (if any) given in the constructor. The pin mode of this pin will be set as OUTPUT.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.


void setSDCardPins(int8_t SDCardSSPin, int8_t SDCardPowerPin)

Set both pin numbers related to the SD card and activate them as output pins.

Parameters
SDCardSSPin The pin on the mcu connected to the slave select of the SD card.
SDCardPowerPin A digital pin number on the mcu controlling power to the SD card.

These over-write the values (if any) given in the constructor. The pin mode of these pins will be set as OUTPUT.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.


void setRTCWakePin(int8_t mcuWakePin, uint8_t wakePinMode = INPUT_PULLUP)

Set digital pin number for the wake up pin used as an RTC interrupt and activate it in the given pin mode.

Parameters
mcuWakePin The pin on the mcu to be used to wake the mcu from deep sleep.
wakePinMode The pin mode to be used for wake up on the clock alert pin. Must be either INPUT OR INPUT_PULLUP. Optional with a default value of INPUT_PULLUP. The DS3231 has an active low interrupt, so the pull-up resistors should be enabled.

This over-writes the value (if any) given in the constructor. Use a value of -1 to prevent the board from attempting to sleep. If using a SAMD board with the internal RTC, the value of the pin is irrelevant as long as it is positive.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.


void setAlertPin(int8_t ledPin)

Set the digital pin number to put out an alert that a measurement is being logged and activate it as an output pin.

Parameters
ledPin The pin on the mcu to be held HIGH while sensor data is being collected and logged.

The pin mode of this pin will be set as OUTPUT. This is intended to be a pin with a LED on it so you can see the light come on when a measurement is being taken.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.


void setTestingModePin(int8_t buttonPin, uint8_t buttonPinMode = INPUT)

Set the digital pin number for an interrupt pin used to enter testing mode, activate that pin as the given input type, and attach the testing interrupt to it.

Parameters
buttonPin The pin on the mcu to listen to for a value-change interrupt.
buttonPinMode The pin mode to be used for the button pin. Must be either INPUT OR INPUT_PULLUP. Optional with a default value of INPUT. Using INPUT_PULLUP will enable processor input resistors, while using INPUT will explicitly disable them. If your pin is externally pulled down or the button is a normally open (NO) switch with common (COM) connected to Vcc, like the EnviroDIY Mayfly), you should use the INPUT pin mode. Coversely, if your button connect to ground when activated, you should enable the processor pull-up resistors using INPUT_PULLUP.

Intended to be used for a pin attached to a button or other manual interrupt source.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.

Once in testing mode, the logger will attempt to connect the the internet and take 25 measurements spaced at 5 second intervals writing the results to the main output destination (ie, Serial). Testing mode cannot be entered while the logger is taking a scheduled measureemnt. No data is written to the SD card in testing mode.


void setLoggerPins(int8_t mcuWakePin, int8_t SDCardSSPin, int8_t SDCardPowerPin, int8_t buttonPin, int8_t ledPin, uint8_t wakePinMode = INPUT_PULLUP, uint8_t buttonPinMode = INPUT)

Set the digital pin numbers and activate pin modes for the five pins of interest for the logger.

Parameters
mcuWakePin The pin on the mcu to listen to for a value-change interrupt to wake from deep sleep. The mode of this pin will be set to wakePinMode.
SDCardSSPin The pin on the mcu connected to the slave select of the SD card. The pin mode of this pin will be set as OUTPUT.
SDCardPowerPin A digital pin number on the mcu controlling power to the SD card. The pin mode of this pin will be set as OUTPUT.
buttonPin The pin on the mcu to listen to for a value-change interrupt to enter testing mode. The mode of this pin will be set to buttonPinMode.
ledPin The pin on the mcu to be held HIGH while sensor data is being collected and logged. The pin mode of this pin will be set as OUTPUT.
wakePinMode The pin mode to be used for wake up on the mcuWakePin (clock alert) pin. Must be either INPUT OR INPUT_PULLUP. Optional with a default value of INPUT_PULLUP. The DS3231 has an active low interrupt, so the pull-up resistors should be enabled.
buttonPinMode The pin mode to be used for the button pin. Must be either INPUT OR INPUT_PULLUP. Optional with a default value of INPUT. Using INPUT_PULLUP will enable processor input resistors, while using INPUT will explicitly disable them. If your pin is externally pulled down or the button is a normally open (NO) switch with common (COM) connected to Vcc, like the EnviroDIY Mayfly), you should use the INPUT pin mode. Coversely, if your button is active when connected to ground, you should enable the processor pull-up resistors using INPUT_PULLUP.

Because this sets the pin mode, this function should only be called during the setup() or loop() portion of an Arduino program.


void setVariableArray(VariableArray* inputArray)

Set the variable array object.

Parameters
inputArray A variable array object instance. This is NOT an array of variables, but an object of the variable array class.

uint8_t getArrayVarCount()

Get the number of variables in the internal variable array object.

Returns uint8_t The number of variables in the internal variable array object

String getParentSensorNameAtI(uint8_t position_i)

Get the name of the parent sensor of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The name of the parent sensor of that variable, if applicable.

String getParentSensorNameAndLocationAtI(uint8_t position_i)

Get the name and pin location of the parent sensor of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The concatenated name and pin location of the parent sensor of that variable, if applicable.

String getVarNameAtI(uint8_t position_i)

Get the name of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The variable name

Variable names must follow the controlled vocabulary documented here: http://vocabulary.odm2.org/variablename/


String getVarUnitAtI(uint8_t position_i)

Get the unit of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The variable unit

Variable units must follow the controlled vocabulary documented here: http://vocabulary.odm2.org/units/


String getVarCodeAtI(uint8_t position_i)

Get the customized code of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The variable code

String getVarUUIDAtI(uint8_t position_i)

Get the UUID of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The variable UUID

String getValueStringAtI(uint8_t position_i)

Get the most recent value of the variable at the given position in the internal variable array object.

Parameters
position_i The position of the variable in the array.
Returns String The value of the variable as a string with the correct number of significant figures.

void attachModem(loggerModem& modem)

Attach a loggerModem to the logger to provide internet access.

Parameters
modem An instance of the loggerModem class

See Modem and Internet Functions for more information on how the modem must be set up before it is attached to the logger. You must include an ampersand to tie in the already created modem! If you do not attach a modem, no action will be taken to publish data.


bool syncRTC()

Use the attahed loggerModem to synchronize the real-time clock with NIST time servers.

Returns bool True if clock synchronization was successful

void registerDataPublisher(dataPublisher* publisher)

Register a data publisher object to receive data from the logger.

Parameters
publisher A dataPublisher object

void sendDataToRemotes(void ) deprecated in v0.22.5

Retained for backwards compatibility, use publishDataToRemotes() in new code.


void setFileName(const char* fileName)

Set the file name, if you want to decide on it in advance.

Parameters
fileName The file name

If the file name is set using this function, the same file name will be used for every single file created by the logger.


void setFileName(String& fileName)

Set the file name, if you want to decide on it in advance.

Parameters
fileName The file name

If the file name is set using this function, the same file name will be used for every single file created by the logger.


String getFileName(void )

Get the current filename.

Returns String The name of the file data is currently being saved to.

This may be a single filename set using the setFileName(name) function or an auto-generated filename which is a concatenation of the logger id and the date when the file was started.


void printFileHeader(Stream* stream) virtual

Print a header out to a stream.

Parameters
stream An Arduino stream instance - expected to be an SdFat file - but could also be the "main" Serial port for debugging.

This removes need to pass around very long string objects which can crash the logger


void printSensorDataCSV(Stream* stream)

Print a comma separated list of volues of sensor data - including the time in the logging timezone - out over an Arduino stream.

Parameters
stream An Arduino stream instance - expected to be an SdFat file - but could also be the "main" Serial port for debugging.

bool createLogFile(String& filename, bool writeDefaultHeader = false)

Create a file on the SD card and set the created, modified, and accessed timestamps in that file.

Parameters
filename The name of the file to create
writeDefaultHeader True to write a header to the file, default is false
Returns bool True if the file was successfully created.

The filename will be the value specified in the function. If desired, a header will also be written to the file based on the variable information from the variable array. This can be used to force a logger to create a file with a secondary file name.


bool createLogFile(bool writeDefaultHeader = false)

Create a file on the SD card and set the created, modified, and accessed timestamps in that file.

Parameters
writeDefaultHeader True to write a header to the file, default is false
Returns bool True if the file was successfully created.

The filename will be the one set by setFileName(String) or generated using the logger id and the date. If desired, a header will also be written to the file based on the variable information from the variable array.


bool logToSD(String& filename, String& rec)

Open a file with the given name on the SD card and append the given line to the bottom of it.

Parameters
filename The name of the file to write to
rec The line to be written to the file
Returns bool True if the file was successfully accessed or created and data appended to it.

If a file with the specified name does not already exist, attempt to create the file and add a header to it. Set the modified and accessed timestamps of the file to the current time.


bool logToSD(String& rec)

Open a file named with the current internal filename value and append the given line to the bottom of it.

Parameters
rec The line to be written to the file
Returns bool True if the file was successfully accessed or created and data appended to it.

If a file with the with the intenal filename does not already exist, attempt to create a file with that name and add a header to it. Set the modified and accessed timestamps of the file to the current time.


bool logToSD(void )

Open a file named with the current internal filename value and append a line to the bottom of it with the most recent values of all variables in the variable array as a comma separated list.

Returns bool True if the file was successfully accessed or created and data appended to it.

If a file with the with the intenal filename does not already exist, attempt to create the file and add a header to it. Set the modified and accessed timestamps of the file to the current time.


bool initializeSDCard(void )

Check if the SD card is available and ready to write to.

Returns bool True if the SD card is ready

We run this check before every communication with the SD card to prevent hanging.


void generateAutoFileName(void )

Generate a file name from the logger id and the current date.


void setFileTimestamp(File fileToStamp, uint8_t stampFlag)

Set a timestamp on a file.

Parameters
fileToStamp The filename to change the timestamp of
stampFlag The "flag" of the timestamp to change - should be T_CREATE, T_WRITE, or T_ACCESS

bool openFile(String& filename, bool createFile, bool writeDefaultHeader)

Open or creates a file, converting a string file name to a character file name.

Parameters
filename The name of the file to open
createFile True to create the file if it did not already exist
writeDefaultHeader True to add a header to the file if it is created
Returns bool True if a file was successfully opened or created.

bool setRTClock(uint32_t UTCEpochSeconds)

Veify that the input value is sane and if so sets the real time clock to the given time.

Parameters
UTCEpochSeconds The number of seconds since 1970 in UTC.
Returns bool True if the input timestamp passes sanity checks and the clock has been successfully set.

bool checkInterval(void )

Check if the CURRENT time is an even interval of the logging rate.

Returns bool True if the current time on the RTC is an even interval of the logging rate.

bool checkMarkedInterval(void )

Check if the MARKED time is an even interval of the logging rate - That is the value saved in the static variable markedLocalEpochTime.

Returns bool True if the marked time is an even interval of the logging rate.

This should be used in conjunction with markTime() to ensure that all data outputs from a single data update session (SD, EnviroDIY, serial printing, etc) have the same timestamp even though the update routine may take several (or many) seconds.


void systemSleep(void )

Put the mcu to sleep to conserve battery life and handle post-interrupt wake actions.


static void setLoggerTimeZone(int8_t timeZone)

Set the static timezone that the data will be logged in.

Parameters
timeZone The timezone data shold be saved to the SD card in. This need not be the same as the timezone of the real time clock.

static int8_t getLoggerTimeZone(void )

Get the Logger Time Zone.

Returns int8_t The timezone data is be saved to the SD card in. This is not be the same as the timezone of the real time clock.

static void setTimeZone(int8_t timeZone) deprecated in v0.22.4

Retained for backwards compatibility; use setLoggerTimeZone(int8_t timeZone) in new code.

Parameters
timeZone The timezone data shold be saved to the SD card in. This need not be the same as the timezone of the real time clock.

static int8_t getTimeZone(void ) deprecated in v0.22.4

Retained for backwards compatibility; use getLoggerTimeZone() in new code.

Returns int8_t The timezone data is be saved to the SD card in. This is not be the same as the timezone of the real time clock.

static void setRTCTimeZone(int8_t timeZone)

Set the static timezone that the RTC is programmed in.

Parameters
timeZone The timezone of the real-time clock (RTC)

static int8_t getRTCTimeZone(void )

Get the timezone of the real-time clock (RTC).

Returns int8_t The timezone of the real-time clock (RTC)

static void setTZOffset(int8_t offset)

Set the offset between the built-in clock and the time zone where the data is being recorded.

Parameters
offset The difference between the timezone of the RTC and the saved data

If your RTC is set in UTC and your logging timezone is EST, this should be -5. If your RTC is set in EST and your timezone is EST this does not need to be called.


static int8_t getTZOffset(void )

Get the offset between the built-in clock and the time zone where the data is being recorded.

Returns int8_t The offset between the built-in clock and the time zone where the data is being recorded.

static uint32_t getNowEpoch(void ) deprecated in v0.33.0

Get the current epoch time from the RTC (unix time, ie, the number of seconds from January 1, 1970 00:00:00) and correct it to the logging time zone.

Returns uint32_t The number of seconds from January 1, 1970 in the logging time zone.

static uint32_t getNowLocalEpoch(void )

Get the current epoch time from the RTC (unix time, ie, the number of seconds from January 1, 1970 00:00:00) and correct it to the logging time zone.

Returns uint32_t The number of seconds from January 1, 1970 in the logging time zone.

static uint32_t getNowUTCEpoch(void )

Get the current Universal Coordinated Time (UTC) epoch time from the RTC (unix time, ie, the number of seconds from January 1, 1970 00:00:00 UTC)

Returns uint32_t The number of seconds from 1970-01-01T00:00:00Z0000

static void setNowUTCEpoch(uint32_t ts)

Set the real time clock to the given number of seconds from January 1, 1970.

Parameters
ts The number of seconds since 1970.

The validity of the timestamp is not checked in any way! In practice, setRTClock(ts) should be used to avoid setting the clock to an obviously invalid value. The input value should be in the timezone of the RTC.


static DateTime dtFromEpoch(uint32_t epochTime)

Convert the number of seconds from January 1, 1970 to a DateTime object instance.

Parameters
epochTime The number of seconds since 1970.
Returns DateTime The equivalent DateTime

static String formatDateTime_ISO8601(DateTime& dt)

Convert a date-time object into a ISO8601 formatted string.

Parameters
dt A DateTime object to convert
Returns String An ISO8601 formatted String.

This assumes the supplied date/time is in the LOGGER's timezone and adds the LOGGER's offset as the time zone offset in the string.


static String formatDateTime_ISO8601(uint32_t epochTime)

Convert an epoch time (unix time) into a ISO8601 formatted string.

Parameters
epochTime The number of seconds since 1970.
Returns String An ISO8601 formatted String.

This assumes the supplied date/time is in the LOGGER's timezone and adds the LOGGER's offset as the time zone offset in the string.


static bool isRTCSane(void )

Check that the current time on the RTC is within a "sane" range.

Returns bool True if the current time on the RTC passes sanity range checking

To be sane the clock must be between 2020 and 2030.


static bool isRTCSane(uint32_t epochTime)

Check that a given epoch time (seconds since 1970) is within a "sane" range.

Parameters
epochTime The epoch time to be checked.
Returns bool True if the given time passes sanity range checking.

To be sane the clock must be between 2020 and 2025.


static void markTime(void )

Set static variables for the date/time.

This is needed so that all data outputs (SD, EnviroDIY, serial printing, etc) print the same time for updating the sensors - even though the routines to update the sensors and to output the data may take several seconds. It is not currently possible to output the instantaneous time an individual sensor was updated, just a single marked time. By custom, this should be called before updating the sensors, not after.


static void wakeISR(void )

Set up the Interrupt Service Request for waking.

In this case, we're doing nothing, we just want the processor to wake. This must be a static function (which means it can only call other static funcions.)


void begin(const char* loggerID, uint16_t loggingIntervalMinutes, VariableArray* inputArray) virtual

Set all pin levels and does initial communication with the real-time clock and SD card to prepare the logger for full functionality.

Parameters
loggerID An ID for the logger - will be used to auto-generate file names. Supplying a logger ID here will override any value given in the constructor.
loggingIntervalMinutes The interval in minutes at which to log data. Supplying an interval here will override any value given in the constructor.
inputArray A variableArray object instance providing data to be logged. This is NOT an array of variables, but an object of the variable array class. Supplying a variableArray object here will override any value given in the constructor.

This is used for operations that cannot happen in the logger constructor

  • they must happen at run time, not at compile time.

void begin(VariableArray* inputArray) virtual

Set all pin levels and does initial communication with the real-time clock and SD card to prepare the logger for full functionality.

Parameters
inputArray A variableArray object instance providing data to be logged. This is NOT an array of variables, but an object of the variable array class. Supplying a variableArray object here will override any value given in the constructor.

This is used for operations that cannot happen in the logger constructor

  • they must happen at run time, not at compile time.

void begin() virtual

Set all pin levels and does initial communication with the real-time clock and SD card to prepare the logger for full functionality.

This is used for operations that cannot happen in the logger constructor

  • they must happen at run time, not at compile time.

void testingMode() virtual

Execute testing mode.

In testing mode, the logger uses the loggerModem, if attached, to connect to the internet. It then powers up all sensors tied to variable in the internal variable array. The logger then updates readings from all sensors 25 times with a 5 second wait in between. All results are output to the "main" output - ie Serial - and NOT to the SD card. After 25 measurements, the sensors are put to sleep, the modem is disconnected from the internet, and the logger goes back to sleep.



Variable documentation

int8_t Logger::_ledPin protected

Digital pin number on the mcu used to output an alert that the logger is measuring.

Expected to be connected to a LED.


int8_t Logger::_buttonPin protected

Digital pin number on the mcu receiving interrupts to enter testing mode.

Expected to be connected to a user button.


loggerModem* Logger::_logModem protected

The internal modem instance.


static int8_t Logger::_loggerTimeZone protected

The static timezone data is being logged in.


static int8_t Logger::_loggerRTCOffset protected

The static difference between the timezone of the RTC and the timezone data is being logged in.