API Documentation

rboot-api.h

Functions

rboot_config rboot_get_config(void)

Read rBoot configuration from flash.

Note

Returns rboot_config (defined in rboot.h) allowing you to modify any values in it, including the ROM layout.

Return values:: rboot_config – Copy of the rBoot configuration

bool rboot_set_config(rboot_config *conf)

Write rBoot configuration to flash memory.

Note

Saves the rboot_config structure back to configuration sector (BOOT_CONFIG_SECTOR) of the flash, while maintaining the contents of the rest of the sector. You can use the rest of this sector for your app settings, as long as you protect this structure when you do so.

Parameters:: conf – pointer to a rboot_config structure containing configuration to save
Return values:: bool – True on success

uint8_t rboot_get_current_rom(void)

Get index of current ROM.

Note

Get the currently selected boot ROM (this will be the currently running ROM, as long as you haven’t changed it since boot or rBoot booted the rom in temporary boot mode, see rboot_get_last_boot_rom).

Return values:: uint8_t – Index of the current ROM

bool rboot_set_current_rom(uint8_t rom)

Set the index of current ROM.

Note

Set the current boot ROM, which will be used when next restarted.

Note

This function re-writes the whole configuration to flash memory (not just the current ROM index)

Parameters:: rom – The index of the ROM to use on next boot
Return values:: bool – True on success

rboot_write_status rboot_write_init(uint32_t start_addr)

Initialise flash write process.

Note

Call once before starting to pass data to write to flash memory with rboot_write_flash function. start_addr is the address on the SPI flash to write from. Returns a status structure which must be passed back on each write. The contents of the structure should not be modified by the calling code.

Parameters:: start_addr – Address on the SPI flash to begin write to

bool rboot_write_end(rboot_write_status *status)

Complete flash write process.

Note

Call at the completion of flash writing. This ensures any outstanding bytes are written (if data so far hasn’t been a multiple of 4 bytes there will be a few bytes unwritten, until you call this function).

Parameters:: status – Pointer to rboot_write_status structure defining the write status

bool rboot_write_flash(rboot_write_status *status, const uint8_t *data, uint16_t len)

Write data to flash memory.

Note

Call repeatedly to write data to the flash, starting at the address specified on the prior call to rboot_write_init. Current write position is tracked automatically. This method is likely to be called each time a packet of OTA data is received over the network.

Note

Call rboot_write_init before calling this function to get the rboot_write_status structure

Parameters:

status – Pointer to rboot_write_status structure defining the write status
data – Pointer to a block of uint8_t data elements to be written to flash
len – Quantity of uint8_t data elements to write to flash

struct rboot_write_status

#include <rboot-api.h>

Structure defining flash write status.

rboot.h

Defines

CHKSUM_INIT

SECTOR_SIZE

BOOT_CONFIG_SECTOR

BOOT_CONFIG_MAGIC

BOOT_CONFIG_VERSION

MODE_STANDARD

MODE_GPIO_ROM

MODE_TEMP_ROM

MODE_GPIO_ERASES_SDKCONFIG

MODE_GPIO_SKIP

RBOOT_RTC_MAGIC

RBOOT_RTC_READ

RBOOT_RTC_WRITE

RBOOT_RTC_ADDR

BOOT_GPIO_NUM

MAX_ROMS

struct rboot_config

#include <rboot.h>

Structure containing rBoot configuration.

Note

ROM addresses must be multiples of 0x1000 (flash sector aligned). Without BOOT_BIG_FLASH only the first 8Mbit (1MB) of the chip will be memory mapped so ROM slots containing .irom0.text sections must remain below 0x100000. Slots beyond this will only be accessible via spi read calls, so use these for stored resources, not code. With BOOT_BIG_FLASH the flash will be mapped in chunks of 8MBit (1MB), so ROMs can be anywhere, but must not straddle two 8MBit (1MB) blocks.

Public Members

uint8_t magic: Our magic, identifies rBoot configuration - should be BOOT_CONFIG_MAGIC.

uint8_t version: Version of configuration structure - should be BOOT_CONFIG_VERSION.

uint8_t mode: Boot loader mode (MODE_STANDARD | MODE_GPIO_ROM | MODE_GPIO_SKIP)

uint8_t current_rom: Currently selected ROM (will be used for next standard boot)

uint8_t gpio_rom: ROM to use for GPIO boot (hardware switch) with mode set to MODE_GPIO_ROM.

uint8_t count: Quantity of ROMs available to boot.

uint8_t unused[2]: Padding (not used)

uint32_t roms[MAX_ROMS]: Flash addresses of each ROM.