Configuration¶
MiraOS features memory areas for configuring application and hardware. Userconfig, sysconfig, and certificate are such memory areas.
These memory areas share a common format.
Area types¶
Userconfig¶
Use the userconfig area to store application specific data in non-volatile memory. The application may use this area through this API.
The production line may also flash user data into this memory area.
The linker script area CONFIG1/CONFIG2 sets the location of the userconfig areas in memory.
Sysconfig¶
The sysconfig area stores hardware related configuration.
Location¶
| Chip | Location | Size |
|---|---|---|
| nrf52832_XXAA | NRFUICR->CUSTOMER[0..31] (0x10001080) | 128 bytes |
| nrf52840_XXAA | NRFUICR->CUSTOMER[0..31] (0x10001080) | 128 bytes |
| mkw41z512 | Not implemented |
Resilience¶
Updates of application firmware versions in flash should typically not overwrite the sysconfig area. Modify the content of the sysconfig area only when modifying the hardware.
Certificate¶
The certificate area stores the unit's license to run MiraOS.
Format¶
The configuration areas share a common format:
| data fields | type | version | CRC |
|---|---|---|---|
| variable size | 16 bits | 16 bits | 32 bits |
Fields are stored as little endian.
Data fields¶
Userconfig¶
Format of the fields in userconfig are at the discretion of the user.
Sysconfig¶
The only currently supported setting is module ID, in the first uint32_t of the sysconfig area.
Module ID
| value | module name |
|---|---|
| 0 | unknown |
| 1 | Bare nRF52832_XXAA |
| 2 | Bare nRF52840_XXAA |
| 3 | Bare mkw41z512 |
| 4 | LumenRadio MLE N2 |
| 5 | LumenRadio MWA N2 |
| 0x4000 | Custom 0 |
| 0x4001 | Custom 1 |
| 0x4002 | Custom 2 |
| 0x4003 | Custom 3 |
Unrecognized values such as 0xffffffff load the "unknown" configuration by default.
Certificate¶
The format of the certificate memory area is not public. Unused area must be padded with 0xff.
Type¶
The second to last uint32_t of the format stores the configuration type in its least significant uint16_t.
| value | Area type |
|---|---|
| 0 | undefined |
| 1 | userconfig |
| 2 | sysconfig |
| 3 | certificate |
Version¶
The second to last uint32_t of the format stores the format version in its most significant uint16_t. Versioning the format is important in order to read older configurations with new firmware.
CRC¶
The last uint32_t of the area stores the IEEE 802.3 CRC32 of the preceding area.
Content example¶
As an example, the content of the sysconfig area for a unit configured as a custom module 0 is:
0x10001080: 00 40 00 00 FF FF FF FF FF FF FF FF FF FF FF FF
0x10001090: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0x100010A0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0x100010B0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0x100010C0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0x100010D0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0x100010E0: FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
0x100010F0: FF FF FF FF FF FF FF FF 02 00 00 00 1B D1 73 D9
00 40 00 00 is the module type for custom module 0 (0x00004000 in little endian).
02 00 is the configuration area type (2 is sysconfig).
00 00 is the configuration format version.
The last four bytes 1B D1 73 D9 are the CRC-32.
Functions¶
mira_config_get_size¶
Get size of non-volatile configuration memory.
Return value¶
The available size.
mira_config_read¶
Read from non-volatile configuration memory.
This is useful to store per-unit configuration and identification parameters, such as product type or network parameters.
Parameters¶
| Name | Description |
|---|---|
| dst | Pointer to where the read data should be stored. |
| size | Number of bytes to read. |
Return value¶
| Name | Description |
|---|---|
| MIRA_SUCCESS | The operation was successful. |
| MIRA_ERROR_RESOURCE_NOT_AVAILABLE | Memory controller is busy. |
| MIRA_ERROR_INVALID_VALUE | Base + size is out of memory region. |
| MIRA_ERROR_NOT_INITIALIZED | No valid configuration detected in config memory. |
mira_config_read_partition¶
mira_status_t mira_config_read_partition(void *dst, mira_size_t data_size, mira_size_t partition_start);
Read from a partition within non-volatile configuration memory.
This is useful to read configuration parameters which have been stored at a specific place in config memory.
Parameters¶
| Name | Description |
|---|---|
| dst | Pointer to where the read data should be stored. |
| data_size | Number of bytes to read. |
| partition_start | Offset within the configuration memory where the partition starts. |
Return value¶
| Name | Description |
|---|---|
| MIRA_SUCCESS | The operation was successful. |
| MIRA_ERROR_RESOURCE_NOT_AVAILABLE | Memory controller is busy. |
| MIRA_ERROR_INVALID_VALUE | Offset + size is out of memory region. |
| MIRA_ERROR_NOT_INITIALIZED | No valid configuration detected in config memory. |
mira_config_write¶
Write to non-volatile configuration memory.
This is useful to store per-unit configuration and identification parameters, such as product type or network parameters. Writing will erase any previous data in the non-volatile configuration memory. Writing is non-blocking. The process calling this function will be polled upon write completion.
Note
The flash writing can become very slow unless the src and size values are 32-bit aligned.
Parameters¶
| Name | Description |
|---|---|
| src | Pointer to the data to be written. Data on this address must not be changed until configuration memory controller is no longer busy. |
| size | Number of bytes to write. |
Return value¶
| Name | Description |
|---|---|
| MIRA_SUCCESS | The operation started successfully. |
| MIRA_ERROR_INVALID_VALUE | Base + size is out of memory region. |
mira_config_write_partition¶
mira_status_t mira_config_write_partition(mira_size_t partition_start, mira_size_t partition_size, void *src, mira_size_t data_size);
Write to an application defined partition in user config.
This is useful to write configuration data to a specific place in config memory while retaining previous config outside of the specified partition. Writing is non-blocking. The process calling this function will be polled upon write completion.
Note
The flash writing can become very slow unless the src, partition_start and data_size values are 32-bit aligned.
Parameters¶
| Name | Description |
|---|---|
| partition_start | Offset within the configuration memory where the partition starts. |
| partition_size | Size of partition. |
| src | Pointer to the data to be written. Data on this address must not be changed until configuration memory controller is no longer busy. |
| data_size | Number of bytes to write. |
Return value¶
| Name | Description |
|---|---|
| MIRA_SUCCESS | The operation started successfully. |
| MIRA_ERROR_INVALID_VALUE | Base + size is out of memory region. |
mira_config_is_working¶
Check if the non-volatile configuration memory controller is busy.
Used to wait for write completion as in the following example:
Note
Calling mira_config_write() and waiting on mira_config_is_working() has to be done in the same process, as the process mira_config_write() is called from is the one being polled when the write operation is completed.
Return value¶
| Name | Description |
|---|---|
| MIRA_TRUE | Configuration memory controller is busy working. |
| MIRA_FALSE | Configuration memory controller is not busy working. |