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.
See also
Note
The user application should not modify the contents of this structure.
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.
-
uint8_t magic