uBit.storage#
Overview#
MicroBitStorage provides a simple way to store data on the micro:bit that persists
through power cycles. It currently takes the form of a key value store which contains
a number of key value pairs.
If a user wanted to determine if a micro:bit has just been flashed over USB they could simply write the following:
#include "MicroBit.h"
MicroBit uBit;
int main()
{
uBit.init();
KeyValuePair* firstTime = uBit.storage.get("boot");
int stored;
if(firstTime == NULL)
{
//this is the first boot after a flash. Store a value!
stored = 1;
uBit.storage.put("boot", (uint8_t *)&stored, sizeof(int));
uBit.display.scroll("Stored!");
}
else
{
//this is not the first boot, scroll our stored value.
memcpy(&stored, firstTime->value, sizeof(int));
delete firstTime;
uBit.display.scroll(stored);
}
}What is flash memory?#
The micro:bit has 256 kB flash memory and 16 kB random access memory (RAM). Flash memory is non-volatile, which essentially means that data is not forgotten when the device is powered off, this is the technology that many USB sticks use.
The alternative, Random Access Memory (also known as volatile memory), cannot be persisted through power cycling the device as its operation relies upon maintaining a constant supply of power.
Therefore, MicroBitStorage utilises the non-volatile nature of flash memory, to
store its data. This class is utilised by the compass, accelerometer
and bleManager to improve the user experience by persisting calibration
and bonding data.
Operations#
You can put(), get() and remove() key value pairs from the store.
Key Value pairs have a fixed length key of 16 bytes, and a fixed length value of
32 bytes. This class only populates a single block (1024 bytes) in its current state,
which means that 21 Key Value pairs can be stored.
Message Bus ID#
None.
Message Bus Events#
None.
API#
Constructor#
MicroBitStorage()#
Description#
Default constructor.
Creates an instance of MicroBitStorage which acts like a KeyValueStore that allows the retrieval, addition and deletion of KeyValuePairs.
writeBytes#
int writeBytes( uint8_t * buffer, uint32_t address, int length)#
Description#
Writes the given number of bytes to the address specified.
Parameters#
uint8_t *buffer - the data to write.uint32_taddress - the location in memory to write to.intlength - the number of bytes to write.
Note
currently not implemented.
flashPageErase#
void flashPageErase( uint32_t * page_address)#
Description#
Method for erasing a page in flash.
page_address
Address of the first word in the page to be erased.
Parameters#
uint32_t *page_address - Address of the first word in the page to be erased.
flashWordWrite#
void flashWordWrite( uint32_t * address, uint32_t value)#
Description#
Method for writing a word of data in flash with a value.
address
Address of the word to change.
value
Value to be written to flash.
Parameters#
uint32_t *address - Address of the word to change.uint32_tvalue - Value to be written to flash.
put#
int put( const char * key, uint8_t * data, int dataSize)#
Description#
Places a given key, and it’s corresponding value into flash at the earliest available point.
Parameters#
const char *key - the unique name that should be used as an identifier for the given data. The key is presumed to be null terminated.uint8_t *data - a pointer to the beginning of the data to be persisted.intdataSize - the size of the data to be persisted
Returns#
MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if the key or size is too large, MICROBIT_NO_RESOURCES if the storage page is full
int put( ManagedString key, uint8_t * data, int dataSize)#
Description#
Places a given key, and it’s corresponding value into flash at the earliest available point.
Parameters#
ManagedStringkey - the unique name that should be used as an identifier for the given data.uint8_t *data - a pointer to the beginning of the data to be persisted.intdataSize - the size of the data to be persisted
Returns#
MICROBIT_OK on success, MICROBIT_INVALID_PARAMETER if the key or size is too large, MICROBIT_NO_RESOURCES if the storage page is full
get#
KeyValuePair get( const char * key)#
Description#
Retreives a KeyValuePair identified by a given key.
Parameters#
const char *key - the unique name used to identify a KeyValuePair in flash.
Returns#
a pointer to a heap allocated KeyValuePair struct, this pointer will be NULL if the key was not found in storage.
Note
it is up to the user to free memory after use.
KeyValuePair get( ManagedString key)#
Description#
Retreives a KeyValuePair identified by a given key.
Parameters#
ManagedStringkey - the unique name used to identify a KeyValuePair in flash.
Returns#
a pointer to a heap allocated KeyValuePair struct, this pointer will be NULL if the key was not found in storage.
Note
it is up to the user to free memory after use.
remove#
int remove( const char * key)#
Description#
Removes a KeyValuePair identified by a given key.
Parameters#
const char *key - the unique name used to identify a KeyValuePair in flash.
Returns#
MICROBIT_OK on success, or MICROBIT_NO_DATA if the given key was not found in flash.
int remove( ManagedString key)#
Description#
Removes a KeyValuePair identified by a given key.
Parameters#
ManagedStringkey - the unique name used to identify a KeyValuePair in flash.
Returns#
MICROBIT_OK on success, or MICROBIT_NO_DATA if the given key was not found in flash.
size#
int size()#
Description#
The size of the flash based KeyValueStore .
Returns#
the number of entries in the key value store