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_t
address - the location in memory to write to.

int
length - 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_t
value - 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.

int
dataSize - 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

ManagedString
key - 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.

int
dataSize - 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

ManagedString
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.

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

ManagedString
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.

size


int
size
()

Description

The size of the flash based KeyValueStore .

Returns

the number of entries in the key value store