AceUtils  0.6.0
Useful Arduino utilties which are too small as separate libraries, but complex enough to be shared among multiple projects, and often have external dependencies to other libraries.
Public Member Functions | List of all members
ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E > Class Template Reference

Thin wrapper around the EEPROM object (from the the built-in EEPROM library) to read and write a given block of data along with its CRC check. More...

#include <CrcEeprom.h>

Public Member Functions

 CrcEeprom (T_E &eeprom, uint32_t contextId=0, Crc32Calculator crcCalc=ace_crc::crc32_nibblem::crc_calculate)
 Constructor with an optional contextId identifier and an optional Crc32Calculator crcCalc function pointer. More...
 
template<typename T >
size_t writeWithCrc (size_t address, const T &data)
 Convenience method that writes the given data of type T at given address. More...
 
template<typename T >
bool readWithCrc (size_t address, T &data) const
 Convenience function that reads the given data of type T at given address. More...
 
size_t writeDataWithCrc (size_t address, const void *data, size_t dataSize)
 Write the data with its CRC and its contextId. More...
 
bool readDataWithCrc (size_t address, void *data, size_t dataSize) const
 Read the data from EEPROM along with its CRC and contextId. More...
 

Detailed Description

template<template< typename > class T_EI, typename T_E>
class ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E >

Thin wrapper around the EEPROM object (from the the built-in EEPROM library) to read and write a given block of data along with its CRC check.

When the data is read back, the CRC is recomputed and checked against the CRC stored in EEPROM. If they do not match, the readWithCrc() method returns false.

An optional contextId can also be stored with the data. It is provided by the calling application to identify the context of the data being stored in the EEPROM. If another app happens to store a different data, with the same data length, the CRC would return valid even though the data is not compatible. This application-defined identifier prevents the collision.

The contextId is written before the data block because the contextId will not change over multiple updates to the data block. This will help with wear-leveling on the AVR platforms.

The CRC is written after the data block, instead of at the beginning of the data block to reduce flash write wear of the bytes corresonding to the CRC. Over time, it is expected that the size of the data block will change, as fields are added or deleted. Therefore, the location of the CRC bytes will also change, which helps wear-leveling. If the CRC bytes were at the beginning, those CRC byes would experience the highest level of writes, even when the data block size changes.

Template Parameters
T_EIthe template class representing the EEPROM adapter interface, one of AvrStyleEeprom or EspStyleEeprom (this is a nested template class, hence the funny template syntax below)
T_Ethe EEPROM class, e.g. EEPROMClass or BufferedEEPROMClass

Definition at line 89 of file CrcEeprom.h.

Constructor & Destructor Documentation

◆ CrcEeprom()

template<template< typename > class T_EI, typename T_E >
ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E >::CrcEeprom ( T_E &  eeprom,
uint32_t  contextId = 0,
Crc32Calculator  crcCalc = ace_crc::crc32_nibblem::crc_calculate 
)
inlineexplicit

Constructor with an optional contextId identifier and an optional Crc32Calculator crcCalc function pointer.

Parameters
eepromthe specific EEPROM instance (of type T_E) used on the given platform. Internally, it is wrapped inside a T_EI to provide a common API to access the different EEPROM implementations on various platforms.
contextIdan optional application-defined identifier of the data being stored. This prevents collisions between 2 different data which just happens to be the same size. The default is 0 for backwards compatibility but this field is highly recommended to be defined. You can use the toContextId() function to convert 4 human-readable characters into a uint32_t. But I have actually found it more useful to just generate a random 32-bit number and use that for a given application.
crcCalcan optional CRC32 calculator. By default, the Crc32Calculator will be set to ace_crc::crc32_nibble::crc_calculate() except on ESP8266 where it will be set to ace_crc::crc32_nibblem::crc_calculate() because the latter is 2.7X faster on the ESP8266. Both of these algorithms use a 4-bit (16 element) lookup table and has a good balance between flash memory consumption and speed. See https://github.com/bxparks/AceCRC for details.

Definition at line 116 of file CrcEeprom.h.

Member Function Documentation

◆ readDataWithCrc()

template<template< typename > class T_EI, typename T_E >
bool ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E >::readDataWithCrc ( size_t  address,
void *  data,
size_t  dataSize 
) const
inline

Read the data from EEPROM along with its CRC and contextId.

Return true if both the CRC of the retrieved data and its contextId matches the expected CRC and contextId when it was written.

Definition at line 183 of file CrcEeprom.h.

◆ readWithCrc()

template<template< typename > class T_EI, typename T_E >
template<typename T >
bool ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E >::readWithCrc ( size_t  address,
T &  data 
) const
inline

Convenience function that reads the given data of type T at given address.

The compiler figures out the sizeof(T) automatically before calling readDataWithCrc().

Template Parameters
Ttype of data

Definition at line 150 of file CrcEeprom.h.

◆ writeDataWithCrc()

template<template< typename > class T_EI, typename T_E >
size_t ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E >::writeDataWithCrc ( size_t  address,
const void *  data,
size_t  dataSize 
)
inline

Write the data with its CRC and its contextId.

Returns the number of bytes written, or 0 if a failure occurred.

Definition at line 158 of file CrcEeprom.h.

◆ writeWithCrc()

template<template< typename > class T_EI, typename T_E >
template<typename T >
size_t ace_utils::crc_eeprom::CrcEeprom< T_EI, T_E >::writeWithCrc ( size_t  address,
const T &  data 
)
inline

Convenience method that writes the given data of type T at given address.

The compiler figures out the sizeof(T) automatically before calling writeDataWithCrc().

Template Parameters
Ttype of data

Definition at line 138 of file CrcEeprom.h.


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