AceUtils  0.5.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 Types | Public Member Functions | Static Public Member Functions | List of all members
ace_utils::crc_eeprom::CrcEeprom Class 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 Types

typedef uint32_t(* Crc32Calculator) (const void *data, size_t dataSize)
 Function pointer to the CRC32 calculator. More...
 

Public Member Functions

 CrcEeprom (IEepromAdapter &eepromAdapter, 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...
 
void begin (size_t size)
 Initialize the underlying eepromAdapter with the given size. 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...
 

Static Public Member Functions

static constexpr uint32_t toContextId (char a, char b, char c, char d)
 Convert 4 characters into a uint32_t contextId Example ‘toContextId('d’, 'e', 'm', 'o')`. More...
 
static constexpr size_t toSavedSize (size_t dataSize)
 Return the actual number of bytes saved to EEPROM for the given dataSize. More...
 

Detailed Description

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.

Definition at line 130 of file CrcEeprom.h.

Member Typedef Documentation

◆ Crc32Calculator

typedef uint32_t(* ace_utils::crc_eeprom::CrcEeprom::Crc32Calculator) (const void *data, size_t dataSize)

Function pointer to the CRC32 calculator.

For example, ace_crc::crc32_nibble::crc_calculate or ace_crc::crc32_byte::crc_calculate.

Definition at line 137 of file CrcEeprom.h.

Constructor & Destructor Documentation

◆ CrcEeprom()

ace_utils::crc_eeprom::CrcEeprom::CrcEeprom ( IEepromAdapter eepromAdapter,
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
eepromAdapteran instance of IEepromAdapter that encapsulates a specific EEPROM instance for a given platform. The IEepromAdapter provides 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. Use the toContextId() function to convert 4 human-readable characters into a uint32_t.
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 184 of file CrcEeprom.h.

Member Function Documentation

◆ begin()

void ace_utils::crc_eeprom::CrcEeprom::begin ( size_t  size)
inline

Initialize the underlying eepromAdapter with the given size.

Some EEPROM implementations will just ignore the size, or do nothing upon this call.

Definition at line 203 of file CrcEeprom.h.

◆ readDataWithCrc()

bool ace_utils::crc_eeprom::CrcEeprom::readDataWithCrc ( size_t  address,
void *  data,
size_t  dataSize 
) const

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 35 of file CrcEeprom.cpp.

◆ readWithCrc()

template<typename T >
bool ace_utils::crc_eeprom::CrcEeprom::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 227 of file CrcEeprom.h.

◆ toContextId()

static constexpr uint32_t ace_utils::crc_eeprom::CrcEeprom::toContextId ( char  a,
char  b,
char  c,
char  d 
)
inlinestaticconstexpr

Convert 4 characters into a uint32_t contextId Example ‘toContextId('d’, 'e', 'm', 'o')`.

On little-endian processors, the implemented formula will cause the uint32_t number to be written as (a,b,c,d) in memory, which helps debugging.

Definition at line 145 of file CrcEeprom.h.

◆ toSavedSize()

static constexpr size_t ace_utils::crc_eeprom::CrcEeprom::toSavedSize ( size_t  dataSize)
inlinestaticconstexpr

Return the actual number of bytes saved to EEPROM for the given dataSize.

This includes the contextId header and the CRC. This is the minimum size that should be passed into the begin() method.

Definition at line 157 of file CrcEeprom.h.

◆ writeDataWithCrc()

size_t ace_utils::crc_eeprom::CrcEeprom::writeDataWithCrc ( size_t  address,
const void *  data,
size_t  dataSize 
)

Write the data with its CRC and its contextId.

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

Definition at line 11 of file CrcEeprom.cpp.

◆ writeWithCrc()

template<typename T >
size_t ace_utils::crc_eeprom::CrcEeprom::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 215 of file CrcEeprom.h.


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