uBit.storage

Overview

uBit.storage 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.

About Flash Memory

The micro:bit's central processor, the Nordic NRF52 has 512kB flash memory and 128 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, and more recent Solid State Drives), and is used for uBit.storage. This is opposed to RAM, which requires consistent power (volatile).

Using the Storage

Note

You will be using pointers while working with uBit.storage. If you don't know how to use these, check out W3Schools.

Warning

Currently it is only possible to store five key-value pairs on the micro:bit. You will encounter an error if you try to store more than this.

Important

Key-value pairs will not persist between program flashes; only between power states of the device (on or off).

uBit.storage has three key operations that you can perform:

• put() - The flashing of a key-value pair to memory.
• get() - The retrieval of a key-value pair from memory based on a query key.
• remove() - The removal of a key-value pair from memory based on a query key.

Key-value pairs have a fixed-length key of 16 bytes, and a fixed-length value of 32 bytes.

Tracking Button Presses

The following example describes how you could track the number of times someone presses a button and have it persist between power states. We register a handler for the button press which calls our function. We use get to attempt retrieval of our key-value pair; it checks whether or not the key exists; if it does, it copies the value from flash memory into RAM via the store variable, which can then be accessed anywhere in the program! If it does not, we set it to the default value of 1. We then simply use the put function to store our variable back into flash for future reference.

Example

void displayTimesButtonBPressed(Event) {
    KeyValuePair* pair = uBit.storage.get("buttonBPresses");

    int store;

    if(pair != NULL) {
        memcpy(&store, pair->value, sizeof(int));
        delete pair;
        store++;
    }
    else {
        store = 1;
    }

    uBit.storage.put("buttonBPresses", (uint8_t*)&store, sizeof(int));
    uBit.display.print(store);
}

int main()
{
    uBit.init();

    uBit.messageBus.listen(DEVICE_ID_BUTTON_B, DEVICE_BUTTON_EVT_CLICK, displayTimesButtonBPressed);

    release_fiber();
}

Note

For more information about events and handlers, have a look at the pages for Message Bus and Event.

Message Bus Info

Message Bus ID

None.

Message Bus Events

None.

API

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

KEY_VALUE_OK on success, KEY_VALUE_INVALID_PARAMETER if the key or size is too large, KEY_VALUE_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.

---

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

KEY_VALUE_OK on success, or KEY_VALUE_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

---

wipe

int

wipe

()

Description

Erase all contents of this KeyValue store

---

Component Constructor

Advanced users only

Do not use this unless you really know what you're doing. It's usually best to use uBit.

KeyValueStorage(

NVMController &

controller)

Description

Constructor.

Creates an instance of KeyValueStorage which acts like a KeyValueStore that allows the retrieval, addition and deletion of KeyValuePairs.

controller

The non-volatile storage controller to use

pageNumber

The logical page number for this KeyValueStorage . Optionally use negative number to count from end of address space.

Parameters

NVMController &

controller - The non-volatile storage controller to use

KeyValueStorage(

NVMController &

controller,

int

pageNumber)

Description

Constructor.

Creates an instance of KeyValueStorage which acts like a KeyValueStore that allows the retrieval, addition and deletion of KeyValuePairs.

controller

The non-volatile storage controller to use

pageNumber

The logical page number for this KeyValueStorage . Optionally use negative number to count from end of address space.

Parameters

NVMController &

controller - The non-volatile storage controller to use

int

pageNumber - The logical page number for this KeyValueStorage . Optionally use negative number to count from end of address space.

---