NHS31xx SW API
event: event bookkeeping module

Detailed Description

This block of code allows an application to store disjoint events. Events can be retrieved using a few basic filtering techniques.
Events can:

It will use the designated portion of the EEPROM to:

The event bookkeeping module main purpose is to store sparse but noteworthy events. Only EEPROM is used, and only a limited portion thereof. Events also take considerable space; once the assigned memory is full, no new events can be stored. Typically, only a handful events of each 'type' - each is then given a different tag value is expected to be stored.

Examples are:

It is expected that each application that requires this module includes it and configures the diversity settings of the module according to its specific needs.

Diversity
This module supports diversity: settings to define the type and size of the EEPROM region placed under control of this module. Check Diversity Settings for all diversity parameters.
How to use the module
  1. First call Event_Init to prepare the module.
  2. After that, at any time, call Event_Set to append a new event.
  3. To retrieve data, use one of the Event_GetByIndex, Event_GetByTime, or Event_GetByTag. The configured callback will be called for each event that matches the given constraints until all memory has been searched.
  4. To ensure that all data is flushed in EEPROM, call Event_DeInit as the last call between two sessions
Example
We define two different values to be used as 'tag':
#define GOOD 0x12
#define BAD 0x34
Two variables are used to check the outcome of the calls to the callback:
static volatile unsigned int sTimestamp;
static volatile unsigned int sCallCount;
The function EventCb is defined as value for EVENT_CB in the diversity settings:
void EventCb(uint8_t tag, int offset, uint8_t len, unsigned int index, uint32_t timestamp, uint32_t context)
{
sCallCount++;
switch (context) {
case 0xAB: /* Retrieved by index. */
sTimestamp = timestamp;
break;
case 0xCD: /* Retrieved by timestamp. */
ASSERT((index == 2) || (index == 3) || (index == 4));
/* Retrieving "gOoD", "bAd" and "BAD", in that order. */
break;
case 0xEF: /* Retrieved by tag. */
ASSERT(tag == GOOD);
ASSERT(len == 4);
ASSERT(offset > 0);
/* Retrieving "good", "gOoD", and "GOOD", in that order. */
break;
}
}
The main code is then storing and checking a total of 6 datasets at three distinct times.
Event_Init(true);
Event_Set(GOOD, "good", 4);
Event_Set(BAD, "bad", 3);
Event_Set(GOOD, "gOoD", 4);
Event_Set(BAD, "bAd", 3);
Event_Set(BAD, NULL, 0);
Event_Set(GOOD, "GOOD", 4);
/* Retrieving one dataset by index. */
sCallCount = 0;
Event_GetByIndex(0, 0, 0xAB);
ASSERT(sCallCount == 1);
/* Retrieving a few datasets by timestamp. */
sCallCount = 0;
sTimestamp += 4;
Event_GetByTime(sTimestamp - 1, sTimestamp + 1, 0xCD);
ASSERT(sCallCount == 3);
/* Retrieving a few datasets by tag. */
sCallCount = 0;
Event_GetByTag(GOOD, 0xEF);
ASSERT(sCallCount == 3);

Modules

 Diversity Settings
 

Typedefs

typedef bool(* pEvent_Cb_t) (uint8_t tag, int offset, uint8_t len, unsigned int index, uint32_t timestamp, uint32_t context)
 

Functions

void Event_Init (bool reset)
 
void Event_DeInit (void)
 
pEvent_Cb_t Event_SetCb (pEvent_Cb_t cb)
 
bool Event_Set (uint8_t tag, void *data, uint8_t len)
 
unsigned int Event_GetByIndex (unsigned int first, unsigned int last, uint32_t context)
 
unsigned int Event_GetByTime (unsigned int begin, unsigned int end, uint32_t context)
 
unsigned int Event_GetByTag (uint8_t tag, uint32_t context)
 
bool Event_GetFirstByTag (uint8_t tag, int *pOffset, uint8_t *pLen, unsigned int *pIndex, uint32_t *pTimestamp)
 
bool Event_GetLastByTag (uint8_t tag, int *pOffset, uint8_t *pLen, unsigned int *pIndex, uint32_t *pTimestamp)
 

Typedef Documentation

◆ pEvent_Cb_t

typedef bool(* pEvent_Cb_t) (uint8_t tag, int offset, uint8_t len, unsigned int index, uint32_t timestamp, uint32_t context)

Whenever data is requested via a call to Event_GetByIndex, Event_GetByTime or Event_GetByTag, the function pointed to by EVENT_CB is called for each matching event. The callback must have this prototype.

Parameters
tagThe tag value associated with the data.
offsetAbsolute EEPROM Offset, in bytes, from where to start reading the associated data. The offset is relative to EEPROM_START and can be given unmodified as offset argument in a call to Chip_EEPROM_Read If this value equals -1, it signifies no data was associated with the tag value. The callback still reports a valid event in that case.
lenThe size of the associated data pointed at, in bytes.
indexThe sequential number of the event. The very first event stored will have index 0. There are two special values, EVENT_CB_OPENING_INDEX and EVENT_CB_CLOSING_INDEX, whose usage can be controlled via EVENT_CB_OPENING_CALL and EVENT_CB_CLOSING_CALL. When used, an extra call is made, not indicating a valid event. Use these extra calls for preparing or concluding running activities.
timestampThe RTC value at the time the data was stored.
contextThe value as given in the call to Event_GetByIndex, Event_GetByTime or Event_GetByTag that triggered this callback.
Note
Events are always reported ordered by time: the oldest events are always reported first.
Returns

Function Documentation

◆ Event_Init()

void Event_Init ( bool  reset)

This function must be the first function to call in this module after going to deep power down or power-off power save mode. Not calling this function will result at best in random data being written and read, and possibly generate hard faults.

Parameters
reset
  • If true, any possible existing data stored in EEPROM is disregarded and becomes irretrievable. When this function returns, 0 events are available and the entire assigned EEPROM memory is empty.
  • If false, any possible existing data stored in EEPROM is kept. When this function returns, all events are available and can be fetched.
Precondition
EEPROM is initialized
RTC is initialized

◆ Event_DeInit()

void Event_DeInit ( void  )

This function must be the last function to call in this module before going to deep power down or power-off power save mode.

Precondition
EEPROM is initialized and is ready to be used.
Postcondition
Possibly, an EEPROM flush was necessary, but that has finished when this function returns.
Warning
Loss of power before end of this call might result in loss of the newly added samples.

◆ Event_SetCb()

pEvent_Cb_t Event_SetCb ( pEvent_Cb_t  cb)

The callback function as set at compile time using the diversity setting EVENT_CB can be overridden dynamically here.

Parameters
cbThe new function that is able to receive the events requested by calling Event_GetByIndex, Event_GetByTime or Event_GetByTag. Providing NULL will reset the callback function to EVENT_CB.
Returns
The callback function that was previously set.

◆ Event_Set()

bool Event_Set ( uint8_t  tag,
void *  data,
uint8_t  len 
)

Stores n samples in persistent storage. The RTC value is used as timestamp and stored together with the data.

Precondition
EEPROM is initialized
RTC is initialized
Parameters
tag: A value holding meaning for the application only. The value is stored as is and will be returned when the data is retrieved. Use this value to provide enough information to allow a correct interpretation of that retrieved data.
data: A pointer to the associated data to store. May be NULL.
len: The length of the associated data pointed to, in bytes. May be 0. The maximum length is restricted by the type and the overhead: the maximum value is restricted to a maximum of 255 - EVENT_OVERHEAD.
Returns
  • true when the data is stored - possibly not yet flushed - in EEPROM.
  • false when not enough space was available to store the data.

◆ Event_GetByIndex()

unsigned int Event_GetByIndex ( unsigned int  first,
unsigned int  last,
uint32_t  context 
)

Retrieves events previously stored with a call to Event_Set. Events are returned one at a time by calling EVENT_CB repetitively, until no more events match the constraints.

  • Using the diversity setting EVENT_CB_OPENING_CALL, the application can control whether EVENT_CB is called one extra time with empty data before the search for matching event starts.
  • Using the diversity setting EVENT_CB_CLOSING_CALL, the application can control whether EVENT_CB is called one last time with empty data to signify the end of the retrieval.

This is a synchronous function: it only returns after all calls to that callback have finished.

Precondition
EEPROM is initialized
Parameters
first: the sequence number of the event to retrieve first. A value of 0 will retrieve the very first event stored.
last: the sequence number of the event to retrieve last.
  • If this value equals first, precisely one event will be returned. In this case, the callback will be called twice: the first time reporting the single matched event, the second time with empty data.
  • If this value is strictly smaller than first, no events will be returned. In this case, the callback will be called once with empty data.
contextMay be any number. Is not stored or looked at, only passed on as last argument in every call to EVENT_CB. Use for your own housekeeping, as a means to provide contextual information to the callback.
Returns
The number of events reported, not including the possible opening and closing calls.
See also
pEvent_Cb_t

◆ Event_GetByTime()

unsigned int Event_GetByTime ( unsigned int  begin,
unsigned int  end,
uint32_t  context 
)

Retrieves events previously stored with a call to Event_Set. Events are returned one at a time by calling EVENT_CB repetitively, until no more events match the constraints.

  • Using the diversity setting EVENT_CB_OPENING_CALL, the application can control whether EVENT_CB is called one extra time with empty data before the search for matching event starts.
  • Using the diversity setting EVENT_CB_CLOSING_CALL, the application can control whether EVENT_CB is called one last time with empty data to signify the end of the retrieval.

This is a synchronous function: it only returns after all calls to that callback have finished.

Precondition
EEPROM is initialized
Parameters
begin: events are only reported when they have a timestamp equal to or later than begin. A value of 0 will disable this check.
end: events are only reported when they have a timestamp equal to or earlier than end. A value of 0xFFFFFFFF will disable this check.
contextMay be any number. Is not stored or looked at, only passed on as last argument in every call to EVENT_CB. Use for your own housekeeping, as a means to provide contextual information to the callback.
Note
Since the RTC value is used as timestamp, it is possible that events that are stored at a later time have a timestamp that is smaller than an earlier event. This function will scan all events and report all those that have a timestamp between (and including) begin and end.
Returns
The number of events reported, not including the possible opening and closing calls.
See also
pEvent_Cb_t

◆ Event_GetByTag()

unsigned int Event_GetByTag ( uint8_t  tag,
uint32_t  context 
)

Retrieves events previously stored with a call to Event_Set. Events are returned one at a time by calling EVENT_CB repetitively, until no more events match the constraints.

  • Using the diversity setting EVENT_CB_OPENING_CALL, the application can control whether EVENT_CB is called one extra time with empty data before the search for matching event starts.
  • Using the diversity setting EVENT_CB_CLOSING_CALL, the application can control whether EVENT_CB is called one last time with empty data to signify the end of the retrieval.

This is a synchronous function: it only returns after all calls to that callback have finished.

Precondition
EEPROM is initialized
Parameters
tag: only events which have the same tag value are reported.
contextMay be any number. Is not stored or looked at, only passed on as last argument in every call to EVENT_CB. Use for your own housekeeping, as a means to provide contextual information to the callback.
Returns
The number of events reported, not including the possible opening and closing calls.

◆ Event_GetFirstByTag()

bool Event_GetFirstByTag ( uint8_t  tag,
int *  pOffset,
uint8_t *  pLen,
unsigned int *  pIndex,
uint32_t *  pTimestamp 
)

Convenience function to retrieve information about the first event that matches the given tag value. No callback function is called.

Parameters
tag: the first event which has the same tag value is reported.
pOffset: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
pLen: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
pIndex: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
pTimestamp: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
Returns
true if a matching event was found. If false, the arguments have not been written to.

◆ Event_GetLastByTag()

bool Event_GetLastByTag ( uint8_t  tag,
int *  pOffset,
uint8_t *  pLen,
unsigned int *  pIndex,
uint32_t *  pTimestamp 
)

Convenience function to retrieve information about the last event that matches the given tag value. No callback function is called.

Parameters
tag: the last event which has the same tag value is reported.
pOffset: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
pLen: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
pIndex: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
pTimestamp: May be NULL. Only touched when a matching event is found. See pEvent_Cb_t
Returns
true if a matching event was found. If false, the arguments have not been written to.