EEPROM-backed variables with optional wear levelling functionality. More...

#include <PersistentSetting.h>

Inheritance diagram for PersistentSetting< T >:

Public Member Functions
	PersistentSetting (T minimum, T maximum, T defaultValue, uint8_t copies=1, int32_t eepromOffset=-1)

bool	isValid (T v)

void	reset (bool saveIt=false)

T	getValueAt (uint16_t address)

uint16_t	counterOffset (uint8_t idx)

uint16_t	dataOffset (uint8_t idx)

uint8_t	getCurrentIdx ()

T	load ()

void	save ()

T	get ()

T	getMinimum ()

T	getMaximum ()

T	getDefault ()

T	operator= (T v)

bool	set (T v, bool saveIt=false)

uint16_t	size ()

void	dump ()

Protected Attributes
T	_value

T	_minimum

T	_maximum

T	_defaultValue

Detailed Description

template<class T>
class PersistentSetting< T >

EEPROM-backed variables with optional wear levelling functionality.

PersistentSetting is a template class that models a value which may be loaded from and saved to EEPROM. PersistentSettings are constructed with minimum, maximum and default values. A number of redundant copies used for wear levelling may also specified, and optionally the address in EEPROM where the data should be stored. By default the address is calculated as the byte following the previously-constructed PersistentSetting (or 0 when constructing the first object).

If the value loaded from EEPROM is invalid (outside the min-max range), the default value will be set.

After construction, the value of a PersistentSetting may be retrieved with the get() method, and the value set with the set() method. These operations return and set the volatile state of the setting. An explicit save() call must be made to write the setting to EEPROM (or use saveit=true when calling set()).

If the value in EEPROM is the same as the current value, nothing will be written to EEPROM.

EEPROM has a limited number of write cycles (~100,000) before failure. To extend the life of projects which write to EEPROM frequently (e.g. device usage counters), PersistentSettings implements a simple wear levelling scheme.

To enable wear levelling, specify copies > 1 when constructing a PersistentSetting. If copies == n, The amount of EEPROM space used will be (sizeof(T) + 1) * n where T is the type of the data being stored.

For example, a usage counter which we expect to reach 200,000 in the life of the device might be constructed as follows:

PersistentSetting<uint32_t> UsageCounter(0, UINT32_MAX, 0, 3);

Three copies of data are used, so the writes are spread over those copies. if the device would be used 200,000 times, we would expect ~66,666 writes per instance of the data in the lifetime of the device - safely below the write limit.

In the EEPROM, the data would be stored as follows:

Address	Copy #	Data Stored
0	1	Counter
1	1	Data Byte 1
2	1	Data Byte 2
3	1	Data Byte 3
4	1	Data Byte 4
5	2	Counter
6	2	Data Byte 1
7	2	Data Byte 2
8	2	Data Byte 3
9	2	Data Byte 4
10	3	Counter
11	3	Data Byte 1
12	3	Data Byte 2
13	3	Data Byte 3
14	3	Data Byte 4

The Counter values are used to work out which is the most recently saved instance of the data.

NOTE: using wear levelling will increase the time taken for loads and saves propotional to the number of copies.

By contrast, with the number of copies == 1, the EEPROM memory layout would look like this:

Address	Data Stored
0	Data Byte 1
1	Data Byte 2
2	Data Byte 3
3	Data Byte 4

Definition at line 90 of file PersistentSetting.h.

Constructor & Destructor Documentation

◆ PersistentSetting()

template<class T >

PersistentSetting< T >::PersistentSetting	(	T	minimum,
		T	maximum,
		T	defaultValue,
		uint8_t	copies = `1`,
		int32_t	eepromOffset = `-1`
	)

inline

Constructor

Parameters

minimum	the minimum value for this setting.
maximum	the maximum value for this setting.
defaultValue	the default value for this setting.
copies	how many copies of the data should be used for wear levelling.
eepromOffset	if -1, place this setting at the EEPROM address immediately after the previous setting (or 0 if this invocation is the first). If zero or more, use the eepromOffset as the address. When choosing the offset menually, care must be taken to ensure settings to not overlap.

Definition at line 102 of file PersistentSetting.h.

Here is the call graph for this function:

Member Function Documentation

◆ counterOffset()

template<class T >

uint16_t PersistentSetting< T >::counterOffset ( uint8_t idx )

inline

Get the address of the counter for specified wear-level index.

Parameters

idx	is the index of the wear-level structure to get

Definition at line 159 of file PersistentSetting.h.

Here is the caller graph for this function:

◆ dump()

template<class T >

void PersistentSetting< T >::dump ( )

inline

Print values for this setting to serial (if DEBUG is enabled)

Definition at line 292 of file PersistentSetting.h.

Here is the call graph for this function:

◆ get()

template<class T >

T PersistentSetting< T >::get ( )

inline

Get the current value of the setting

Definition at line 237 of file PersistentSetting.h.

◆ getDefault()

template<class T >

T PersistentSetting< T >::getDefault ( )

inline

Get the default value of the setting

Definition at line 249 of file PersistentSetting.h.

◆ getMaximum()

template<class T >

T PersistentSetting< T >::getMaximum ( )

inline

Get the maximum value of the setting

Definition at line 245 of file PersistentSetting.h.

◆ getMinimum()

template<class T >

T PersistentSetting< T >::getMinimum ( )

inline

Get the minimum value of the setting

Definition at line 241 of file PersistentSetting.h.

◆ getValueAt()

template<class T >

T PersistentSetting< T >::getValueAt ( uint16_t address )

inline

Get the value of type T starting at the specified EEPROM address.

Parameters

address the address of the first byte of the value.

Definition at line 143 of file PersistentSetting.h.

Here is the caller graph for this function:

◆ isValid()

template<class T >

bool PersistentSetting< T >::isValid ( T v )

inline

Determine if a value is valid or not (within min / max limits).

Parameters

v	the value to test.

Returns: true if v is a valid value, else false.

Definition at line 124 of file PersistentSetting.h.

Here is the caller graph for this function:

◆ load()

template<class T >

T PersistentSetting< T >::load ( )

inline

Load value from EEPROM, and return it. If the value in EEPROM is not valid, use the default value.

Returns: the loaded value.

Definition at line 189 of file PersistentSetting.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator=()

template<class T >

T PersistentSetting< T >::operator= ( T v )

inline

Sets the in-RAM value of the setting.

Parameters

v	the value to be set. If v is less than the minimum value or greater than the maximum value, no change will be made. Note: this function does NOT save the new value to EEPROM. To do that, save() must be called.

Definition at line 257 of file PersistentSetting.h.

Here is the call graph for this function:

◆ reset()

template<class T >

void PersistentSetting< T >::reset ( bool saveIt = false )

inline

Reset the setting to its default value.

Parameters

saveIt if true, also save the setting to EEPROM.

Definition at line 132 of file PersistentSetting.h.

Here is the call graph for this function:

◆ save()

template<class T >

void PersistentSetting< T >::save ( )

inline

Save the value to EEPROM Note: we're using the EEPROM.update() call, so EEPROM is only actually written if the value is different from the value currently in EEPROM. This measure is an attempt to reduce wear on the EEPROM

Definition at line 204 of file PersistentSetting.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set()

template<class T >

bool PersistentSetting< T >::set	(	T	v,
		bool	saveIt = `false`
	)

inline

Sets the in-RAM value of the setting.

Parameters

v	the value to be set. If v is less than the minimum value or greater than the maximum value, no change will be made.

Returns: true if the value was set successfully, false otherwise (invalid v) Note: this function does NOT save the new value to EEPROM. To do that, save() must be called.

Definition at line 266 of file PersistentSetting.h.

Here is the call graph for this function:

◆ size()

template<class T >

uint16_t PersistentSetting< T >::size ( )

inline

Get the size in bytes of the setting in EEPROM.

Definition at line 280 of file PersistentSetting.h.

Here is the caller graph for this function:

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

src/PersistentSetting.h

Public Member Functions

Protected Attributes

Detailed Description

template<class T> class PersistentSetting< T >

Constructor & Destructor Documentation

◆ PersistentSetting()

Member Function Documentation

◆ counterOffset()

◆ dump()

◆ get()

◆ getDefault()

◆ getMaximum()

◆ getMinimum()

◆ getValueAt()

◆ isValid()

◆ load()

◆ operator=()

◆ reset()

◆ save()

◆ set()

◆ size()

template<class T>
class PersistentSetting< T >