#include "sdkconfig.h"
#include <driver/twai.h>
#include <esp_app_format.h>
#include <esp_chip_info.h>
#include <esp_ota_ops.h>
#include <stdint.h>
#include "openlcb/Bootloader.hxx"
#include "openlcb/Defs.hxx"
#include "utils/constants.hxx"
#include "utils/Hub.hxx"

Classes
struct	Esp32BootloaderState
	ESP32 Bootloader internal data. More...

Macros
#define	BOOTLOADER_LOG_LEVEL VERBOSE

#define	BOOTLOADER_TWAI_LOG_LEVEL VERBOSE

#define	BOOTLOADER_STREAM

#define	WRITE_BUFFER_SIZE (CONFIG_WL_SECTOR_SIZE / 2)

Functions
void	bootloader_hw_init (void)
	Callback from the bootloader to configure and start the TWAI hardware.

void	application_entry (void)
	Callback from the bootloader for entering the application.

void	bootloader_reboot (void)
	Callback from the bootloader when a reboot should be triggered.

bool	read_can_frame (struct can_frame *frame)
	Callback from the bootloader to read a single CAN frame.

bool	try_send_can_frame (const struct can_frame &frame)
	Callback from the bootloader to transmit a single CAN frame.

void	get_flash_boundaries (const void flash_min, const void flash_max, const struct app_header **app_header)
	Callback from the bootloader to retrieve flash boundaries.

void	get_flash_page_info (const void address, const void page_start, uint32_t page_length_bytes)
	Callback from the bootloader to retrieve flash page information.

void	erase_flash_page (const void *address)
	Callback from the bootloader to erase a flash page.

void	write_flash (const void address, const void data, uint32_t size_bytes)
	Callback from the bootloader to write to flash.

uint16_t	flash_complete (void)
	Callback from the bootloader to indicate that the full firmware file has been received.

void	checksum_data (const void data, uint32_t size, uint32_t checksum)
	Callback from the bootloader to calculate the checksum of a data block.

uint16_t	nmranet_alias (void)
	Callback from the bootloader to obtain the pre-defined alias to use.

uint64_t	nmranet_nodeid (void)
	Callback from the bootloader to obtain the node-id to use.

void	esp32_bootloader_init (uint8_t reset_reason)
	Initializes the ESP32 Bootloader.

void	esp32_bootloader_run (uint64_t id, gpio_num_t rx, gpio_num_t tx, bool reboot_on_exit=true)
	Runs the ESP32 Bootloader.

Variables
static Esp32BootloaderState	esp_bl_state
	Bootloader configuration data.

static constexpr BaseType_t	MAX_TWAI_WAIT_RX = pdMS_TO_TICKS(250)
	Maximum time to wait for a TWAI frame to be received before giving up.

static constexpr BaseType_t	MAX_TWAI_WAIT_TX = pdMS_TO_TICKS(0)
	Maximum time to wait for a TWAI frame to be transmitted before giving up.

static uint32_t RTC_NOINIT_ATTR	bootloader_request
	Flag used to indicate that we have been requested to enter the bootloader instead of normal node operations.

static constexpr uint32_t	RTC_BOOL_TRUE = 0x92e01a42
	Value to be assigned to bootloader_request when the bootloader should run instead of normal node operations.

static constexpr uint32_t	RTC_BOOL_FALSE = 0
	Default value to assign to bootloader_request when the ESP32-C3 starts the first time or when the bootloader should not be run.

Detailed Description

Copyright: Copyright (c) 2021, Mike Dunston All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ESP32 specific implementation of the HAL (Hardware Abstraction Layer) used by the OpenLCB bootloader.

Additional functions from bootloader_hal.h will be required to be defined by the application code.

Author: Mike Dunston

Date: 3 May 2021

Definition in file Esp32BootloaderHal.hxx.

Macro Definition Documentation

◆ BOOTLOADER_LOG_LEVEL

#define BOOTLOADER_LOG_LEVEL VERBOSE

Definition at line 45 of file Esp32BootloaderHal.hxx.

◆ BOOTLOADER_STREAM

#define BOOTLOADER_STREAM

Definition at line 53 of file Esp32BootloaderHal.hxx.

◆ BOOTLOADER_TWAI_LOG_LEVEL

#define BOOTLOADER_TWAI_LOG_LEVEL VERBOSE

Definition at line 49 of file Esp32BootloaderHal.hxx.

◆ WRITE_BUFFER_SIZE

#define WRITE_BUFFER_SIZE (CONFIG_WL_SECTOR_SIZE / 2)

Definition at line 56 of file Esp32BootloaderHal.hxx.

Function Documentation

◆ application_entry()

void application_entry ( void )

Callback from the bootloader for entering the application.

Enters the application.

This will default to reboot the ESP32.

Definition at line 169 of file Esp32BootloaderHal.hxx.

◆ bootloader_hw_init()

void bootloader_hw_init ( void )

Callback from the bootloader to configure and start the TWAI hardware.

Called after hw_set_to_safe and after the bss and data segments are initialized.

Definition at line 144 of file Esp32BootloaderHal.hxx.

◆ bootloader_reboot()

void bootloader_reboot ( void )

Callback from the bootloader when a reboot should be triggered.

Resets the microcontroller.

Currently a NO-OP.

Definition at line 184 of file Esp32BootloaderHal.hxx.

◆ checksum_data()

void checksum_data	(	const void *	data,
		uint32_t	size,
		uint32_t *	checksum
	)

Callback from the bootloader to calculate the checksum of a data block.

Computes checksum over a block of data.

Parameters

data	Start of block to calculate checksum for.
size	Number of bytes to calcuate checksum for.
checksum	Calculated checksum for the data block.

NOTE: The ESP32 does not use this method and will always set the checksum value to zero.

Definition at line 437 of file Esp32BootloaderHal.hxx.

◆ erase_flash_page()

void erase_flash_page ( const void * address )

Callback from the bootloader to erase a flash page.

Erases the flash page at a specific address.

Parameters

address Flash address to erase.

NOTE: This is a NO-OP on the ESP32 as this is handled internally by the esp_ota_write() API.

Definition at line 276 of file Esp32BootloaderHal.hxx.

◆ esp32_bootloader_init()

void esp32_bootloader_init ( uint8_t reset_reason )

Initializes the ESP32 Bootloader.

Parameters

reset_reason Reason for the ESP32 startup.

NOTE: This method must be called during the startup of the ESP32, failure to call this method will result in the bootloader checks having undefined behavior since RTC memory is not cleared upon startup!

Example:

void setup()
{
  ...
  uint8_t reset_reason = Esp32SocInfo.print_soc_info();
  esp32_bootloader_init(reset_reason);
  ...
}

Definition at line 485 of file Esp32BootloaderHal.hxx.

◆ esp32_bootloader_run()

void esp32_bootloader_run	(	uint64_t	id,
		gpio_num_t	rx,
		gpio_num_t	tx,
		bool	reboot_on_exit = `true`
	)

Runs the ESP32 Bootloader.

Parameters

id	Node ID to advertise on the TWAI (CAN) bus.
rx	Pin connected to the SN65HVD23x/MCP2551 R (RX) pin.
tx	Pin connected to the SN65HVD23x/MCP2551 D (TX) pin.
reboot_on_exit	Reboot the ESP32 upon completion, default is true.

Definition at line 501 of file Esp32BootloaderHal.hxx.

◆ flash_complete()

uint16_t flash_complete ( void )

Callback from the bootloader to indicate that the full firmware file has been received.

Signals that the bootloading operation is complete.

Returns: ERROR_CODE_OK (0x0000) if the firmware has been received and updated to be used for the next startup, otherwise ERROR_FIRMWARE_CSUM (0x2088) indicating there was a failure that may be recoverable by retrying.

Definition at line 406 of file Esp32BootloaderHal.hxx.

◆ get_flash_boundaries()

void get_flash_boundaries	(	const void **	flash_min,
		const void **	flash_max,
		const struct app_header **	app_header
	)

Callback from the bootloader to retrieve flash boundaries.

Returns the boundaries of the user flash.

Parameters

flash_min	Minimum flash address to write to.
flash_max	Maximum flash address to write to.
app_header	Pointer to the app_header struct for the currently running firmware.

NOTE: This will default to set

Parameters

flash_min	to zero,
flash_max	to the partition size and
app_header	to a statically declared struct with only the size populated.

Definition at line 242 of file Esp32BootloaderHal.hxx.

◆ get_flash_page_info()

void get_flash_page_info	(	const void *	address,
		const void **	page_start,
		uint32_t *	page_length_bytes
	)

Callback from the bootloader to retrieve flash page information.

Rounds a flash address into a flash page.

Parameters

address	Flash address to retrieve information on.
page_state	Starting address for the page.
page_length_bytes	Length of the page.

Definition at line 258 of file Esp32BootloaderHal.hxx.

◆ nmranet_alias()

uint16_t nmranet_alias ( void )

Callback from the bootloader to obtain the pre-defined alias to use.

Suggests an NMRAnet CAN alias for use.

Returns: zero to have the bootloader assign one based on the node-id.

Definition at line 449 of file Esp32BootloaderHal.hxx.

◆ nmranet_nodeid()

uint64_t nmranet_nodeid ( void )

Callback from the bootloader to obtain the node-id to use.

Returns: node-id provided to esp32_bootloader_run.

Definition at line 459 of file Esp32BootloaderHal.hxx.

◆ read_can_frame()

bool read_can_frame ( struct can_frame * frame )

Callback from the bootloader to read a single CAN frame.

Checks if there is an incoming CAN frame from the hardware.

Parameters

frame buffer for receiving a CAN frame into.

Returns: true when successful, false otherwise.

Definition at line 193 of file Esp32BootloaderHal.hxx.

◆ try_send_can_frame()

bool try_send_can_frame ( const struct can_frame & frame )

Callback from the bootloader to transmit a single CAN frame.

Parameters

frame CAN frame to transmit.

Returns: true when successful, false otherwise.

Definition at line 215 of file Esp32BootloaderHal.hxx.

◆ write_flash()

void write_flash	(	const void *	address,
		const void *	data,
		uint32_t	size_bytes
	)

Callback from the bootloader to write to flash.

Writes data to the flash.

Parameters

address	Flash address to write to.
data	Buffer to write to flash.
size_bytes	Number of bytes to write to flash.

This method leverages the ESP32 OTA APIs to write the flash data. Upon writing to flash address zero (first address), the

Parameters

data	will be validated to ensure the firmware being received is applicable to the ESP32 and that it appears correct (has correct image magic byte). If the firmware is not applicable or otherwise corrupted for the first flash address the ESP32 will reboot to abort the bootloader download.

Definition at line 295 of file Esp32BootloaderHal.hxx.

Variable Documentation

◆ bootloader_request

uint32_t RTC_NOINIT_ATTR bootloader_request

static

Flag used to indicate that we have been requested to enter the bootloader instead of normal node operations.

Note that this value will not be initialized by the system and a check for power on reset will need to be made to initialize it on first boot.

Definition at line 130 of file Esp32BootloaderHal.hxx.

◆ esp_bl_state

Esp32BootloaderState esp_bl_state

static

Bootloader configuration data.

Definition at line 118 of file Esp32BootloaderHal.hxx.

◆ MAX_TWAI_WAIT_RX

constexpr BaseType_t MAX_TWAI_WAIT_RX = pdMS_TO_TICKS(250)

staticconstexpr

Maximum time to wait for a TWAI frame to be received before giving up.

Definition at line 121 of file Esp32BootloaderHal.hxx.

◆ MAX_TWAI_WAIT_TX

constexpr BaseType_t MAX_TWAI_WAIT_TX = pdMS_TO_TICKS(0)

staticconstexpr

Maximum time to wait for a TWAI frame to be transmitted before giving up.

Definition at line 124 of file Esp32BootloaderHal.hxx.

◆ RTC_BOOL_FALSE

constexpr uint32_t RTC_BOOL_FALSE = 0

staticconstexpr

Default value to assign to bootloader_request when the ESP32-C3 starts the first time or when the bootloader should not be run.

Definition at line 138 of file Esp32BootloaderHal.hxx.

◆ RTC_BOOL_TRUE

constexpr uint32_t RTC_BOOL_TRUE = 0x92e01a42

staticconstexpr

Value to be assigned to bootloader_request when the bootloader should run instead of normal node operations.

Definition at line 134 of file Esp32BootloaderHal.hxx.

Classes

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ BOOTLOADER_LOG_LEVEL

◆ BOOTLOADER_STREAM

◆ BOOTLOADER_TWAI_LOG_LEVEL

◆ WRITE_BUFFER_SIZE

Function Documentation

◆ application_entry()

◆ bootloader_hw_init()

◆ bootloader_reboot()

◆ checksum_data()

◆ erase_flash_page()

◆ esp32_bootloader_init()

◆ esp32_bootloader_run()

◆ flash_complete()

◆ get_flash_boundaries()

◆ get_flash_page_info()

◆ nmranet_alias()

◆ nmranet_nodeid()

◆ read_can_frame()

◆ try_send_can_frame()

◆ write_flash()

Variable Documentation

◆ bootloader_request

◆ esp_bl_state

◆ MAX_TWAI_WAIT_RX

◆ MAX_TWAI_WAIT_TX

◆ RTC_BOOL_FALSE

◆ RTC_BOOL_TRUE