#include <DeviceInfoLedger.h>

Inheritance diagram for DeviceInfoLedger:

Public Member Functions
DeviceInfoLedger &	withInfoLedgerName (const char *infoLedgerName)
	Change the device to cloud ledger that holds the device information.

DeviceInfoLedger &	withRetainedBuffer (uint8_t *retainedBuffer, size_t retainedBufferSize)
	Retained buffer for use mainly to save log information in a circular buffer.

DeviceInfoLedger &	withLocalConfigLogLevel (LogLevel level=LOG_LEVEL_INFO, LogCategoryFilters filters={})
	Set the local config log filters from a static array of LogCategoryFilter.

void	setup ()
	Perform setup operations; call this from global application setup()

void	loop ()
	Perform application loop operations; call this from global application loop()

int	getConfigConnectionLog () const
	Get the connectionLog (int) configuration setting from local settings or cloud configuration (default or device override)

DeviceInfoLedger &	withLocalConfigConnectionLog (int value)
	Set a local configuration setting for connectionLog (log size). Default is 0 (disabled).

int	getConfigLastRunLog () const
	Get the lastRunLog (int) configuration setting from local settings or cloud configuration (default or device override)

DeviceInfoLedger &	withLocalConfigLastRunLog (int value)
	Set a local configuration setting for lastRunLog (log size). Default is 0 (disabled).

bool	getConfigLogAllConnections () const
	Get the logAllConnections (bool) configuration setting from local settings or cloud configuration (default or device override)

DeviceInfoLedger &	withLocalConfigLogAllConnections (bool value)
	Set a local configuration setting for logAllConnections. Default is false.

bool	getConfigIncludeGeneral () const
	Get the includeGeneral (bool) configuration setting from local settings or cloud configuration (default or device override)

DeviceInfoLedger &	withLocalConfigIncludeGeneral (bool value)
	Set a local configuration setting for includeGeneral. Default is false.

bool	getConfigIncludeDiag () const
	Get the includeDiag (bool) configuration setting from local settings or cloud configuration (default or device override)

DeviceInfoLedger &	withLocalConfigIncludeDiag (bool value)
	Set a local configuration setting for includeDiag. Default is false.

bool	getConfigIncludeTower () const
	Get the includeTower (bool) configuration setting from local settings or cloud configuration (default or device override)

DeviceInfoLedger &	withLocalConfigIncludeTower (bool value)
	Set a local configuration setting for includeTower. Default is false.

LogLevel	stringToLogLevel (const char *levelStr) const
	Convert a string like LOG_LEVEL_INFO into its numeric equivalent.

const char *	logLevelToString (LogLevel level) const
	Convert a log level value (like LOG_LEVEL_INFO) to a string.

void	getLogLevelFilters (LogLevel &level, LogCategoryFilters &filters) const
	Get the log level settings.

void	write (uint8_t c)
	Called by DeviceInfoLedgerLogHandler to handle log messages.

Public Member Functions inherited from DeviceConfigWrapper
bool	getConfigBool (const char *key, bool defaultValue=false) const
	Get a bool (boolean) configuration setting from local settings or cloud configuration (default or device override)

bool	setLocalConfigBool (const char *key, bool value)
	Set a local config setting using a bool.

int	getConfigInt (const char *key, int defaultValue=0) const
	Get an int (32-bit signed integer) configuration setting from local settings or cloud configuration (default or device override)

bool	setLocalConfigInt (const char *key, int value)
	Set a local config setting using an int (signed 32-bit integer)

double	getConfigDouble (const char *key, double defaultValue=0.0) const
	Get a double (64-bit floating point) configuration setting from local settings or cloud configuration (default or device override)

bool	setLocalConfigDouble (const char *key, double value)
	Set a local config setting using a double (64-bit floating point)

String	getConfigString (const char key, const char defaultValue="") const
	Get a String configuration setting from local settings or cloud configuration (default or device override)

bool	setLocalConfigString (const char key, const char value)
	Set a local config setting using a c-string (null-terminated UTF-8, const char *)

Variant	getConfigVariant (const char *key, Variant defaultValue={}) const
	Get a configuration setting from local settings or cloud configuration (default or device override)

bool	setLocalConfigVariant (const char *key, Variant value)
	Set a local config setting using a Variant.

Static Public Member Functions
static DeviceInfoLedger &	instance ()
	Gets the singleton instance of this class, allocating it if necessary.

Static Public Attributes
static const uint32_t	retainedMagicBytes = 0xde8e46cc
	Magic bytes at the beginning of the RetainedBufferHeader.

Protected Member Functions
	DeviceInfoLedger ()
	The constructor is protected because the class is a singleton.

virtual	~DeviceInfoLedger ()
	The destructor is protected because the class is a singleton and cannot be deleted.

	DeviceInfoLedger (const DeviceInfoLedger &)=delete

DeviceInfoLedger &	operator= (const DeviceInfoLedger &)=delete

void	configureLogHandler ()
	Configure the log handler with the current settings in logLevel and logFilter.

virtual void	onCloudConnection ()
	Called on the any cloud connection completed.

void	updateConfig ()
	Called at setup and when the configuration is updated.

Protected Attributes
String	infoLedgerName = "device-info"
	Name of the info ledger.

uint8_t *	retainedBuffer = nullptr
	Retained buffer for lastRunLog and other purposes.

size_t	retainedBufferSize = 0
	Retained buffer size for lastRunLog and other purposes.

char *	lastRunLog = nullptr
	lastRunLog, set during setup(), cleared when uploaded

uint8_t *	connectionLogBuffer = nullptr
	Buffer for connectionLog, allocated during updateConfig()

size_t	connectionLogSize = 0
	Size of buffer for connectionLog, set during updateConfig()

std::atomic< uint32_t >	connectionLogOffset
	Offset for writing to connectionLog. Written in write().

bool	writeToConnectionLog = true
	Whether to save data to the connection log.

bool	isCellularConnected = false
	Internal state, true if Cellular.ready() returned true.

bool	isWiFiConnected = false
	Internal state, true if WiFi.ready() returned true.

bool	isNetworkConnected = false
	Internal state, true if Network.ready() returned true.

bool	isCloudConnected = false
	Internal state, true if Particle.connected() returned true.

int	connectionCount = 0
	Internal state, number of times Particle.connected() has transitioned to trye.

bool	setupComplete = false
	Internal state, true if setup has been called and completed.

RetainedBufferHeader *	retainedHdr = nullptr
	Convenience pointer into retainedBuffer. Set during setup.

uint8_t *	retainedData = nullptr
	Convenience pointer into retainedBuffer for retained log data. Set during setup.

size_t	retainedDataSize = 0
	Amount of spaces for retained log data. Set during setup.

int	resetReason = RESET_REASON_NONE
	Reset reason, saved at the beginning of setup.

uint32_t	resetReasonData = 0
	Reset reason data, saved at the beginning of setup if RESET_REASON_USER.

Ledger	infoLedger
	Ledger object for device information, initialized during setup.

DeviceInfoLedgerLogHandler *	logHandler = nullptr
	The StreamLogHandler object.

Static Protected Attributes
static DeviceInfoLedger *	_instance
	Singleton instance of this class.

Detailed Description

This class is a singleton; you do not create one as a global, on the stack, or with new.

From global application setup you must call: DeviceInfoLedger::instance().setup();

From global application loop you must call: DeviceInfoLedger::instance().loop();

Constructor & Destructor Documentation

◆ DeviceInfoLedger() [1/2]

DeviceInfoLedger::DeviceInfoLedger ( )

protected

The constructor is protected because the class is a singleton.

Use DeviceInfoLedger::instance() to instantiate the singleton.

◆ DeviceInfoLedger() [2/2]

DeviceInfoLedger::DeviceInfoLedger ( const DeviceInfoLedger & )

protecteddelete

This class is a singleton and cannot be copied

Member Function Documentation

◆ getConfigConnectionLog()

int DeviceInfoLedger::getConfigConnectionLog ( ) const

inline

Get the connectionLog (int) configuration setting from local settings or cloud configuration (default or device override)

Returns: int The size of the connection log in bytes to be included in the ledger.

The ledger has a maximum size of 16 Kbytes, and could be lower on some devices due to RAM limitations. Be sure to make this field and others small enough that the ledger fits. A normal value would be 2048 bytes.

◆ getConfigIncludeDiag()

bool DeviceInfoLedger::getConfigIncludeDiag ( ) const

inline

Get the includeDiag (bool) configuration setting from local settings or cloud configuration (default or device override)

Returns: bool

◆ getConfigIncludeGeneral()

bool DeviceInfoLedger::getConfigIncludeGeneral ( ) const

inline

Get the includeGeneral (bool) configuration setting from local settings or cloud configuration (default or device override)

Returns: bool

◆ getConfigIncludeTower()

bool DeviceInfoLedger::getConfigIncludeTower ( ) const

inline

Get the includeTower (bool) configuration setting from local settings or cloud configuration (default or device override)

Returns: bool

◆ getConfigLastRunLog()

int DeviceInfoLedger::getConfigLastRunLog ( ) const

inline

Get the lastRunLog (int) configuration setting from local settings or cloud configuration (default or device override)

Returns: int The size of the last run log in bytes to be included in the ledger.

The ledger has a maximum size of 16 Kbytes, and could be lower on some devices due to RAM limitations. Be sure to make this field and others small enough that the ledger fits. A normal value would be 2048 bytes.

This is also limited by the amount of retained memory passed to withRetainedBuffer.

◆ getConfigLogAllConnections()

bool DeviceInfoLedger::getConfigLogAllConnections ( ) const

inline

Get the logAllConnections (bool) configuration setting from local settings or cloud configuration (default or device override)

Returns: bool

◆ getLogLevelFilters()

void DeviceInfoLedger::getLogLevelFilters	(	LogLevel &	level,
		LogCategoryFilters &	filters ) const

Get the log level settings.

Parameters

level
filters

◆ instance()

DeviceInfoLedger & DeviceInfoLedger::instance ( )

static

Gets the singleton instance of this class, allocating it if necessary.

Use DeviceInfoLedger::instance() to instantiate the singleton.

◆ logLevelToString()

const char * DeviceInfoLedger::logLevelToString ( LogLevel level ) const

Convert a log level value (like LOG_LEVEL_INFO) to a string.

Parameters

level

Returns: const char* string string such as "INFO".

◆ loop()

void DeviceInfoLedger::loop ( )

Perform application loop operations; call this from global application loop()

You typically use DeviceInfoLedger::instance().loop();

The DeviceInfoLedger needs loop time to process the connectivity changes; the configuration library does not need a loop call.

◆ operator=()

DeviceInfoLedger & DeviceInfoLedger::operator= ( const DeviceInfoLedger & )

protecteddelete

This class is a singleton and cannot be copied

◆ setup()

void DeviceInfoLedger::setup ( )

Perform setup operations; call this from global application setup()

You typically use DeviceInfoLedger::instance().setup();

This must only be called once at boot and not again. You cannot use this to reconfigure settings!

◆ stringToLogLevel()

LogLevel DeviceInfoLedger::stringToLogLevel ( const char * levelStr ) const

Convert a string like LOG_LEVEL_INFO into its numeric equivalent.

Parameters

levelStr The string (case-sensitive)

Returns: LogLevel numeric log level corresponding to the constant

Note that it really only searches for case-sensitive "INFO", "TRACE", etc.

◆ withInfoLedgerName()

DeviceInfoLedger & DeviceInfoLedger::withInfoLedgerName ( const char * infoLedgerName )

inline

Change the device to cloud ledger that holds the device information.

Parameters

infoLedgerName New name to use.

Returns: DeviceConfigLedger& A reference to this object to chain withXXX() calls, fluent style.

Default is "device-info".

Must be called before setup().

◆ withLocalConfigConnectionLog()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigConnectionLog ( int value )

inline

Set a local configuration setting for connectionLog (log size). Default is 0 (disabled).

Parameters

value to set

Returns: bool true if successfully set

◆ withLocalConfigIncludeDiag()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigIncludeDiag ( bool value )

inline

Set a local configuration setting for includeDiag. Default is false.

Parameters

value to set

Returns: bool true if successfully set

◆ withLocalConfigIncludeGeneral()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigIncludeGeneral ( bool value )

inline

Set a local configuration setting for includeGeneral. Default is false.

Parameters

value to set

Returns: bool true if successfully set

◆ withLocalConfigIncludeTower()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigIncludeTower ( bool value )

inline

Set a local configuration setting for includeTower. Default is false.

Parameters

value to set

Returns: bool true if successfully set

◆ withLocalConfigLastRunLog()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigLastRunLog ( int value )

inline

Set a local configuration setting for lastRunLog (log size). Default is 0 (disabled).

Parameters

value to set

Returns: bool true if successfully set

◆ withLocalConfigLogAllConnections()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigLogAllConnections ( bool value )

inline

Set a local configuration setting for logAllConnections. Default is false.

Parameters

value to set

Returns: bool true if successfully set

◆ withLocalConfigLogLevel()

DeviceInfoLedger & DeviceInfoLedger::withLocalConfigLogLevel	(	LogLevel	level = LOG_LEVEL_INFO,
		LogCategoryFilters	filters = {} )

Set the local config log filters from a static array of LogCategoryFilter.

Parameters

level
filters

Returns: DeviceInfoLedger&

◆ withRetainedBuffer()

DeviceInfoLedger & DeviceInfoLedger::withRetainedBuffer	(	uint8_t *	retainedBuffer,
		size_t	retainedBufferSize )

inline

Retained buffer for use mainly to save log information in a circular buffer.

Parameters

retainedBuffer
retainedBufferSize

Returns: DeviceInfoLedger& A reference to this object to chain withXXX() calls, fluent style.

This log may be useful for debugging problems that cause a device panic, or similar issues that occur before a device reboot.

Because of the way retained memory works on RTL872x devices (P2/Photon 2), this log may be missing the latest data written to the log.

This does not need to match the cloud setting, but the cloud setting can't be used to store more than the size of the retained buffer. Thus you will probably want to make the retained buffer as large as is reasonable for your application.

Must be called before setup().

◆ write()

void DeviceInfoLedger::write ( uint8_t c )

Called by DeviceInfoLedgerLogHandler to handle log messages.

Parameters

c	A character written to the logger

Field Documentation

◆ _instance

DeviceInfoLedger * DeviceInfoLedger::_instance

staticprotected

Singleton instance of this class.

The object pointer to this class is stored here. It's NULL at system boot.

◆ infoLedgerName

String DeviceInfoLedger::infoLedgerName = "device-info"

protected

Name of the info ledger.

Change name using withInfoLedgerName() (before setup).

◆ logHandler

DeviceInfoLedgerLogHandler* DeviceInfoLedger::logHandler = nullptr

protected

The StreamLogHandler object.

Allocated during setup() and when the configuration changes.

◆ retainedBuffer

uint8_t* DeviceInfoLedger::retainedBuffer = nullptr

protected

Retained buffer for lastRunLog and other purposes.

Set using withRetainedBuffer() before setup.

◆ retainedBufferSize

size_t DeviceInfoLedger::retainedBufferSize = 0

protected

Retained buffer size for lastRunLog and other purposes.

Set using withRetainedBuffer() before setup.

◆ retainedMagicBytes

const uint32_t DeviceInfoLedger::retainedMagicBytes = 0xde8e46cc

static

Magic bytes at the beginning of the RetainedBufferHeader.

This is used to see if the structure has been initialized.

The documentation for this class was generated from the following files:

src/DeviceInfoLedger.h
src/DeviceInfoLedger.cpp

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DeviceInfoLedger() [1/2]

◆ DeviceInfoLedger() [2/2]

Member Function Documentation

◆ getConfigConnectionLog()

◆ getConfigIncludeDiag()

◆ getConfigIncludeGeneral()

◆ getConfigIncludeTower()

◆ getConfigLastRunLog()

◆ getConfigLogAllConnections()

◆ getLogLevelFilters()

◆ instance()

◆ logLevelToString()

◆ loop()

◆ operator=()

◆ setup()

◆ stringToLogLevel()

◆ withInfoLedgerName()

◆ withLocalConfigConnectionLog()

◆ withLocalConfigIncludeDiag()

◆ withLocalConfigIncludeGeneral()

◆ withLocalConfigIncludeTower()

◆ withLocalConfigLastRunLog()

◆ withLocalConfigLogAllConnections()

◆ withLocalConfigLogLevel()

◆ withRetainedBuffer()

◆ write()

Field Documentation

◆ _instance

◆ infoLedgerName

◆ logHandler

◆ retainedBuffer

◆ retainedBufferSize

◆ retainedMagicBytes