Firmware Over the Air (FOTA) Update system. More...

Collaboration diagram for FOTA:

Classes
struct	FotaCanTiming
	Selection for the supported CAN Bitrates. More...

struct	FotaCanSettings
	CAN Settings. More...

struct	FotaCanMessage
	CAN message structure. More...

struct	FotaDatagramHeaderPacketPayload
	Structure representing the datagram header (In the payload) More...

struct	FotaDatagram
	Structure representing datagram. More...

struct	FotaDatagramPayload_FirmwareMetadata

struct	FotaDatagramPayload_FirmwareChunk

struct	FotaDatagramPayload_JumpToApp

struct	FotaDatagramPayload_Acknowledgement

struct	FotaDFUContext
	DFU Context for writing firmware to flash. More...

struct	FotaPacket
	FOTA Packet structure. More...

struct	GpioAddress
	Port and pin data. More...

struct	UartSettings
	UART Settings. More...

struct	NetworkBuffer
	struct containing details of circular buffer More...

struct	PacketManager
	Packet manager context structure. More...

Macros
#define	CAN_HW_BASE CAN1

#define	FOTA_MAX_DATAGRAM_SIZE (16U * FOTA_PACKET_PAYLOAD_SIZE)
	Maximum supported datagram size (2KB)

#define	FOTA_MAX_PACKETS_PER_DATAGRAM ((FOTA_MAX_DATAGRAM_SIZE / FOTA_PACKET_PAYLOAD_SIZE) + 1U)
	Maximum number of packets that can make up a datagram (8 data + 1 Header)

#define	FOTA_DATAGRAM_HEADER_PAYLOAD_SIZE 10U
	FOTA Datagram header payload size of 10-bytes.

#define	FOTA_ERROR_MSG_LENGTH 256U
	Error message length in bytes.

#define	FOTA_FIRMWARE_ID_LENGTH 256U
	Firmware ID length in bytes.

#define	fota_error_ok_or_return(code)
	Use to forward failures or continue on success. More...

#define	NUM_FLASH_PAGES 128U
	256KB of memory / 2KB per page

#define	FOTA_PAGE_BYTES ((uint32_t)0x800U)
	2KB per flash page as per datasheet

#define	FOTA_PING_BYTES ((uint32_t)0x1000U)
	4KB max per ping

#define	FOTA_ADDR_TO_PAGE(addr) (((uintptr_t)(addr) - (uintptr_t)APP_ACTIVE_START_ADDRESS) / FOTA_PAGE_BYTES)
	Convert memory address to page number. More...

#define	FOTA_PAGE_TO_ADDR(page) ((uintptr_t)(page) * (uintptr_t)FOTA_PAGE_BYTES + (uintptr_t)APP_ACTIVE_START_ADDRESS)
	Convert page number to memory address. More...

#define	LOG_FOTA_DEBUG(fmt, ...) printf("[FOTA DEBUG] %s:%u: " fmt, __FILE__, __LINE__, ##__VA_ARGS__)
	Debug log.

#define	LOG_FOTA_WARNING(fmt, ...) printf("[FOTA WARNING] %s:%u: " fmt, __FILE__, __LINE__, ##__VA_ARGS__)
	Warning log.

#define	LOG_FOTA_ERROR(fmt, ...) printf("[FOTA ERROR] %s:%u: " fmt, __FILE__, __LINE__, ##__VA_ARGS__)
	Error log.

#define	FLASH_START_ADDRESS_LINKERSCRIPT ((uint32_t) & _flash_start)
	Flash start address as defined in the linkerscripts.

#define	FLASH_SIZE_LINKERSCRIPT ((size_t) & _flash_size)
	Flash size as defined in the linkerscripts.

#define	FLASH_PAGE_SIZE_LINKERSCRIPT ((size_t) & _flash_page_size)
	Flash page size as defined in the linkerscripts.

#define	APP_ACTIVE_START_ADDRESS ((uint32_t) & _app_active_start)
	Application Active start address as defined in the linkerscripts.

#define	APP_ACTIVE_SIZE ((size_t) & _app_active_size)
	Application Active size as defined in the linkerscripts.

#define	APP_STAGING_START_ADDRESS ((uint32_t) & _app_staging_start)
	Application Staging start address as defined in the linkerscripts.

#define	APP_STAGING_SIZE ((size_t) & _app_staging_size)
	Application Staging size as defined in the linkerscripts.

#define	BOOTLOADER_START_ADDRESS ((uint32_t) & _bootloader_start)
	Bootloader start address as defined in the linkerscripts.

#define	BOOTLOADER_SIZE ((size_t) & _bootloader_size)
	Bootloader size as defined in the linkerscripts.

#define	BOOTSTRAP_START_ADDRESS ((uint32_t) & _bootstrap_start)
	Bootstrap start address as defined in the linkerscripts.

#define	BOOTSTRAP_SIZE ((size_t) & _bootstrap_size)
	Bootstrap size as defined in the linkerscripts.

#define	FS_STORAGE_START_ADDRESS ((uint32_t) & _fs_storage_start)
	File System Storage start address as defined in the linkerscripts.

#define	FS_STORAGE_SIZE ((size_t) & _fs_storage_size)
	File System Storage size as defined in the linkerscripts.

#define	SRAM_START_ADDRESS ((uint32_t) & _sram_start)
	SRAM start address as defined in the linkerscripts.

#define	SRAM_SIZE ((size_t) & _sram_size)
	SRAM size as defined in the linkerscripts.

#define	FOTA_PACKET_SOF 0xAAU

#define	FOTA_PACKET_EOF 0xBBU

#define	FOTA_PACKET_PAYLOAD_SIZE 128U

#define	FOTA_PACKET_HEADER_SIZE (1U + 1U + 4U + 1U + 2U)

#define	FOTA_PACKET_SERIALIZED_SIZE (FOTA_PACKET_HEADER_SIZE + FOTA_PACKET_PAYLOAD_SIZE + 4U + 1U)

#define	FOTA_PACKET_MINIMUM_SIZE FOTA_PACKET_SERIALIZED_SIZE

#define	HSE_LSE_TIMEOUT_MS 5000U

#define	USE_INTERNAL_OSCILLATOR 1U

#define	FOTA_TIMEOUT_MS 15000U

#define	FOTA_UART_MAX_BUFFER_LEN 256U
	Maximum size permitted for a UART transaction.

#define	FOTA_UART_TIMEOUT_MS 10U
	Maximum time permitted for a FOTA UART transaction.

#define	NETWORK_BUFFER_SIZE 1024U

#define	FOTA_MAX_ACTIVE_DATAGRAMS 2U
	Maximum number of datagrams that can be processed simultaneously.

Typedefs
typedef struct FotaCanSettings	FotaCanSettings
	CAN Settings. More...

typedef enum FotaDatagramType	FotaDatagramType
	Datagram types corresponding to different FOTA operations.

typedef enum FotaError	FotaError
	FOTA Error code definitions.

typedef void(*	FotaDatagramCompleteCb) (FotaDatagram *datagram)

Enumerations
enum	FotaCanBitrate { FOTA_CAN_BITRATE_125KBPS , FOTA_CAN_BITRATE_250KBPS , FOTA_CAN_BITRATE_500KBPS , FOTA_CAN_BITRATE_1000KBPS , NUM_FOTA_CAN_BITRATES }

enum	Boot_CanMode { CAN_CONTINUOUS = 0 , CAN_ONE_SHOT_MODE , NUM_CAN_MODES , CAN_CONTINUOUS = 0 , CAN_ONE_SHOT_MODE , NUM_CAN_MODES }

enum	FotaDatagramType { FOTA_DATAGRAM_TYPE_FIRMWARE_METADATA , FOTA_DATAGRAM_TYPE_FIRMWARE_CHUNK , FOTA_DATAGRAM_TYPE_JUMP_TO_APP , FOTA_DATAGRAM_TYPE_ACKNOWLEDGEMENT , FOTA_DATAGRAM_TYPE_ERROR }
	Datagram types corresponding to different FOTA operations. More...

enum	FotaDFUState { FOTA_DFU_UNINITIALIZED , FOTA_DFU_IDLE , FOTA_DFU_RECEIVING , FOTA_DFU_COMPLETE , FOTA_DFU_JUMP }
	DFU internal states. More...

enum	FotaError { FOTA_ERROR_SUCCESS , FOTA_ERROR_RESOURCE_EXHAUSTED , FOTA_ERROR_INVALID_ARGS , FOTA_ERROR_INTERNAL_ERROR , FOTA_ERROR_TIMEOUT , FOTA_ERROR_CRC32_MISMATCH , FOTA_ERROR_CRC32_DATA_NOT_ALIGNED , FOTA_ERROR_FLASH_WRITE_FAILED , FOTA_ERROR_FLASH_WRITE_OUT_OF_BOUNDS , FOTA_ERROR_FLASH_WRITE_NOT_ALIGNED , FOTA_ERROR_FLASH_READ_FAILED , FOTA_ERROR_FLASH_ERASE , FOTA_ERROR_FLASH_VERIFICATION_FAILED , FOTA_ERROR_INVALID_PACKET , FOTA_ERROR_BOOTLOADER_SUCCESS , FOTA_ERROR_BOOTLOADER_INVALID_STATE , FOTA_ERROR_BOOTLOADER_UNINITIALIZED , FOTA_ERROR_BOOTLOADER_INVALID_DATAGRAM , FOTA_ERROR_BOOTLOADER_WRITE_IN_PROGRESS , FOTA_ERROR_BOOTLOADER_FAILURE , FOTA_ERROR_BOOTLOADER_SEQUENCE_OUT_OF_ORDER , FOTA_ERROR_BOOTLOADER_BINARY_OVERSIZED , FOTA_CAN_INIT_ERR , FOTA_CAN_TRANSMISSION_ERROR , FOTA_CAN_RECEIVE_ERROR , FOTA_ERROR_NO_MEMORY , FOTA_ERROR_NO_DATAGRAM_FOUND , FOTA_ERROR_JUMP_FAILED }
	FOTA Error code definitions. More...

enum	FotaJumpRequest { FOTA_JUMP_APPLICATION , FOTA_JUMP_BOOTLOADER , FOTA_JUMP_MIDSUN_BOOTSTRAP }

enum	FotaPacketType { FOTA_PACKET_TYPE_DATA = 0 , FOTA_PACKET_TYPE_HEADER , FOTA_PACKET_TYPE_ACK , FOTA_PACKET_TYPE_NACK , FOTA_PACKET_TYPE_ERROR }
	FOTA Packet Type. More...

enum	UartPort { UART_PORT_1 = 0 , UART_PORT_2 , NUM_UART_PORTS , UART_PORT_1 = 0 , UART_PORT_2 , NUM_UART_PORTS }
	UART Port selection.

enum	UartFlowControl { UART_FLOW_CONTROL_NONE , UART_FLOW_CONTROL_RTS , UART_FLOW_CONTROL_CTS , UART_FLOW_CONTROL_RTS_CTS , UART_FLOW_CONTROL_NONE , UART_FLOW_CONTROL_RTS , UART_FLOW_CONTROL_CTS , UART_FLOW_CONTROL_RTS_CTS }
	UART Flow control selection. More...

enum	GpioPort { GPIO_PORT_A = 0 , GPIO_PORT_B , NUM_GPIO_PORTS , GPIO_PORT_A = 0 , GPIO_PORT_B , GPIO_PORT_C , GPIO_PORT_D , GPIO_PORT_E , GPIO_PORT_H , NUM_GPIO_PORTS }
	UART Settings. More...

enum	PacketReceiverState { PKT_STATE_WAITING_SOF , PKT_STATE_READING_PACKET }
	State machine states for packet receiving. More...

Functions
FotaError	fota_init ()

void	fota_process (void)

FotaError	fota_dfu_init (PacketManager *packet_manager, uintptr_t staging_base, uintptr_t app_start_addr)
	Initialize DFU context. More...

FotaError	fota_can_init (const FotaCanSettings *settings)
	Initialize the CAN interface for FOTA. More...

FotaError	fota_can_transmit (uint32_t id, bool extended, const uint8_t *data, size_t len)
	Transmit a CAN message in FOTA. More...

FotaError	fota_can_receive (FotaCanMessage *const msg)
	Receive a CAN message in FOTA. More...

FotaError	fota_datagram_init (FotaDatagram datagram, FotaDatagramType type, uint32_t datagram_id, uint8_t data, uint32_t length)
	Initialize a datagram structure. More...

FotaError	fota_datagram_to_packets (FotaDatagram datagram, FotaPacket packets, uint16_t *num_packets, uint16_t max_packets)
	Fragment a datagram into packets for transmission. More...

FotaError	fota_datagram_process_data_packet (FotaDatagram datagram, FotaPacket packet)
	Process a received packet and incorporate it into a datagram. More...

FotaError	fota_datagram_process_header_packet (FotaDatagram datagram, FotaPacket packet)
	Process a received header packet and incorporate it into a datagram. More...

bool	fota_datagram_is_complete (FotaDatagram *datagram)
	Check if a datagram has been completely received. More...

FotaError	fota_datagram_verify (FotaDatagram *datagram)
	Verify the integrity of a complete datagram. More...

FotaError	fota_dfu_process (FotaDatagram *datagram)
	Process an incoming datagram and write to flash. More...

FotaError	fota_encryption_init ()
	Initialize the encryption unit. More...

uint32_t	fota_calculate_crc32 (uint8_t *data, uint32_t length_words)
	Calculate the CRC32 for a given buffer of 4-byte aligned data. More...

uint32_t	fota_calculate_crc32_on_flash_memory (uintptr_t flash_base_addr, uint32_t flash_size)
	Verify a region of flash memory. More...

FotaError	fota_verify_packet_encryption (FotaPacket *packet)
	Verify a FOTA packets encryption. More...

FotaError	fota_verify_datagram_encryption (FotaDatagram *datagram)
	Verify a FOTA datagrams encryption. More...

FotaError	fota_flash_write (uint32_t address, uint8_t *buffer, size_t buffer_len)
	Write to flash memory. More...

FotaError	fota_flash_erase (uint32_t start_page, uint8_t num_pages)
	Erase some number of flash pages. More...

FotaError	fota_flash_read (uint32_t address, uint8_t *buffer, size_t buffer_len)
	Read from flash memory. More...

FotaError	fota_verify_flash_memory (uintptr_t start_addr, size_t size_bytes)
	Verify that the flash memory is not erased. More...

FotaError	fota_jump (FotaJumpRequest jump_request)

FotaError	fota_packet_init (FotaPacket *packet, FotaPacketType type, uint8_t sequence, uint16_t length)
	Initialize a FOTA packet. More...

FotaError	fota_packet_set_crc (FotaPacket *packet)
	Compute and set CRC32 of payload. More...

FotaError	fota_packet_serialize (FotaPacket packet, uint8_t buffer, uint32_t buf_size, uint32_t *bytes_written)
	Serialize FOTA packet into buffer. More...

FotaError	fota_packet_deserialize (FotaPacket packet, uint8_t buffer, uint32_t buf_size)
	Deserialize buffer into FOTA packet. More...

FotaError	fota_startup (void)
	Initialize MCU system clock and HAL. More...

bool	fota_is_timed_out (void)
	Checks if FOTA has timed out, meaning no requests have been received. More...

FotaError	network_init (UartPort uart, UartSettings settings, NetworkBuffer network_buffer)
	Initialize UART instance, assuming standard 8 bits 1 stop bit. More...

FotaError	network_read (UartPort uart, uint8_t *data, size_t len)
	Read data from the network buffer. More...

FotaError	network_tx (UartPort uart, uint8_t *data, size_t len)
	Transmit data from the UART port. More...

bool	is_network_timeout (bool is_tx)
	Checks if tx or rx command has timed out. More...

FotaError	network_buffer_init (NetworkBuffer *network_buffer)
	Initalizes circular buffer for use, by initalizing assocated structs. More...

uint16_t	network_buffer_num_items (NetworkBuffer *network_buffer)
	Fetches the number of items in the network buffer. More...

uint16_t	network_buffer_num_empty_slots (NetworkBuffer *network_buffer)
	Fetches the number of empty slots in the network buffer. More...

bool	network_buffer_empty (NetworkBuffer *network_buffer)
	Checks if the network buffer is empty. More...

bool	network_buffer_full (NetworkBuffer *network_buffer)
	Checks if the network buffer is full. More...

FotaError	network_buffer_write (NetworkBuffer network_buffer, uint8_t data)
	Write data bytes. More...

FotaError	network_buffer_read (NetworkBuffer network_buffer, uint8_t data)
	Read data bytes. More...

FotaError	packet_manager_init (PacketManager manager, UartPort uart, UartSettings uart_settings, FotaDatagramCompleteCb callback)
	Initialize the packet manager. More...

FotaError	packet_manager_process (PacketManager *manager)
	Process received data from the network buffer. More...

FotaError	packet_manager_send_datagram (PacketManager manager, FotaDatagram datagram, FotaError(send_func)(int8_t data, uint32_t length))
	Send a datagram by fragmenting it into packets. More...

FotaError	packet_manager_create_datagram (PacketManager manager, FotaDatagramType type, uint8_t data, uint32_t length, FotaDatagram **datagram)
	Create a new datagram for sending. More...

FotaError	packet_manager_get_datagram (PacketManager manager, uint32_t datagram_id, FotaDatagram *datagram)
	Get a pointer to a completed datagram. More...

FotaError	packet_manager_free_datagram (PacketManager *manager, uint32_t datagram_id)
	Free a datagram slot. More...

Variables
uint32_t	_flash_start

uint32_t	_flash_size

uint32_t	_flash_page_size

uint32_t	_bootstrap_start

uint32_t	_bootstrap_size

uint32_t	_bootloader_start

uint32_t	_bootloader_size

uint32_t	_app_active_start

uint32_t	_app_active_size

uint32_t	_app_staging_start

uint32_t	_app_staging_size

uint32_t	_fs_storage_start

uint32_t	_fs_storage_size

uint32_t	_sram_start

uint32_t	_sram_size

Detailed Description

Firmware Over the Air (FOTA) Update system.

Macro Definition Documentation

◆ FOTA_ADDR_TO_PAGE

#define FOTA_ADDR_TO_PAGE ( addr ) (((uintptr_t)(addr) - (uintptr_t)APP_ACTIVE_START_ADDRESS) / FOTA_PAGE_BYTES)

Convert memory address to page number.

Parameters

addr	Address to be converted to page number

Returns: Page number

◆ fota_error_ok_or_return

#define fota_error_ok_or_return ( code )

Value:

  ({                                    \
    __typeof__(code) fota_err = (code); \
    if (fota_err) return fota_err;      \
  })

Use to forward failures or continue on success.

◆ FOTA_PACKET_SOF

#define FOTA_PACKET_SOF 0xAAU

FotaPacket Serialized Format:

+---------—+-------------—+-----------------------—+ | Field | Size (bytes) | Description | +---------—+-------------—+-----------------------—+ | sof | 1 | Start of Frame (0xAA) | | packet_type| 1 | Packet Type Enum | | datagram_id| 4 | Datagram identifier | | sequence_num| 1 | Packet index in datagram | | payload_len| 2 | Actual data in payload | | payload | 128 | Fixed-size payload | | crc32 | 4 | CRC32 of full payload | | eof | 1 | End of Frame (0xBB) | +---------—+-------------—+-----------------------—+

Total Serialized Size: 142 bytes

◆ FOTA_PAGE_TO_ADDR

#define FOTA_PAGE_TO_ADDR ( page ) ((uintptr_t)(page) * (uintptr_t)FOTA_PAGE_BYTES + (uintptr_t)APP_ACTIVE_START_ADDRESS)

Convert page number to memory address.

Parameters

page	Page number

Returns: 32-bit address

Typedef Documentation

◆ FotaCanSettings

typedef struct FotaCanSettings FotaCanSettings

CAN Settings.

TX Pin will transmit data. RX pin will receive data. The bitrate is the number of bits sent per second. The device ID is the CAN ID of the STM32 node. Loopback will internally connect the transmit and receive CAN lines for testing. Silent mode is used for only listening to the bus.

Enumeration Type Documentation

◆ FotaCanBitrate

enum FotaCanBitrate

Enumerator
FOTA_CAN_BITRATE_125KBPS	125 KBits per second
FOTA_CAN_BITRATE_250KBPS	250 KBits per second
FOTA_CAN_BITRATE_500KBPS	500 KBits per second
FOTA_CAN_BITRATE_1000KBPS	1000 KBits per second
NUM_FOTA_CAN_BITRATES	Number of supported bit rates

◆ FotaDatagramType

enum FotaDatagramType

Datagram types corresponding to different FOTA operations.

Enumerator
FOTA_DATAGRAM_TYPE_FIRMWARE_METADATA	Firmware metadata information
FOTA_DATAGRAM_TYPE_FIRMWARE_CHUNK	Chunk of firmware data
FOTA_DATAGRAM_TYPE_JUMP_TO_APP	Request to jump to application
FOTA_DATAGRAM_TYPE_ACKNOWLEDGEMENT	Acknowledgement information

◆ FotaDFUState

enum FotaDFUState

DFU internal states.

Enumerator
FOTA_DFU_UNINITIALIZED	DFU Uninitialized
FOTA_DFU_IDLE	DFU Idle
FOTA_DFU_RECEIVING	DFU Recieving data
FOTA_DFU_COMPLETE	DFU Complete
FOTA_DFU_JUMP	DFU Jump memory

◆ FotaError

enum FotaError

FOTA Error code definitions.

Enumerator
FOTA_ERROR_SUCCESS	Success error code
FOTA_ERROR_RESOURCE_EXHAUSTED	Resource exhausted error code
FOTA_ERROR_INVALID_ARGS	Invalid arguments error code
FOTA_ERROR_INTERNAL_ERROR	Internal issue error code
FOTA_ERROR_TIMEOUT	Timeout error
FOTA_ERROR_CRC32_MISMATCH	CRC mismatch error code
FOTA_ERROR_CRC32_DATA_NOT_ALIGNED	Data not 4-byte aligned in CRC32 calculation

◆ FotaJumpRequest

enum FotaJumpRequest

Enumerator
FOTA_JUMP_APPLICATION	Jump to application memory
FOTA_JUMP_BOOTLOADER	Jump to bootloader memory
FOTA_JUMP_MIDSUN_BOOTSTRAP	Jump to Midnight Sun bootstrap

◆ FotaPacketType

enum FotaPacketType

FOTA Packet Type.

Enumerator
FOTA_PACKET_TYPE_DATA	Data packet
FOTA_PACKET_TYPE_HEADER	Header packet
FOTA_PACKET_TYPE_ACK	Acknowledgment packet
FOTA_PACKET_TYPE_NACK	Not Acknowledged packet
FOTA_PACKET_TYPE_ERROR	Error packet

◆ GpioPort

enum GpioPort

UART Settings.

TX Pin will transmit data. RX pin will receive data. The baudrate is the number of symbols sent per second. Both devices must agree on the baudrate with a tolerance of +-3%. Flow control is of type UartFlowControl.

Enumerator
GPIO_PORT_A	Gpio port A
GPIO_PORT_B	Gpio port B
NUM_GPIO_PORTS	Number of Gpio Ports
GPIO_PORT_A	GPIO Port A
GPIO_PORT_B	GPIO Port B
GPIO_PORT_C	GPIO Port C
GPIO_PORT_D	GPIO Port D
GPIO_PORT_E	GPIO Port E
GPIO_PORT_H	GPIO Port H
NUM_GPIO_PORTS	Number of GPIO Ports

◆ PacketReceiverState

enum PacketReceiverState

State machine states for packet receiving.

Enumerator
PKT_STATE_WAITING_SOF	Waiting for start of frame
PKT_STATE_READING_PACKET	Reading packet content

◆ UartFlowControl

enum UartFlowControl

UART Flow control selection.

Flow control is a method of synchronizing UART communication between 2 devices. For most applications, this can be set to UART_FLOW_CONTROL_NONE.

Enumerator
UART_FLOW_CONTROL_NONE	Disable flow control
UART_FLOW_CONTROL_RTS	Enable request-to-send flow control
UART_FLOW_CONTROL_CTS	Enable clear-to-send flow control
UART_FLOW_CONTROL_RTS_CTS	Enable both request-to-send and clear-to-send flow control
UART_FLOW_CONTROL_NONE	Disable flow control
UART_FLOW_CONTROL_RTS	Enable request-to-send flow control
UART_FLOW_CONTROL_CTS	Enable clear-to-send flow control
UART_FLOW_CONTROL_RTS_CTS	Enable both request-to-send and clear-to-send flow control

Function Documentation

◆ fota_calculate_crc32()

uint32_t fota_calculate_crc32	(	uint8_t *	data,
		uint32_t	length_words
	)

Calculate the CRC32 for a given buffer of 4-byte aligned data.

Parameters

data_start	Pointer to the start of the data
length_words	Size of the data in words

◆ fota_calculate_crc32_on_flash_memory()

uint32_t fota_calculate_crc32_on_flash_memory	(	uintptr_t	flash_base_addr,
		uint32_t	flash_size
	)

Verify a region of flash memory.

Parameters

flash_base_addr	Base address to begin verification from
flash_size	Size of flash memory to verify in bytes

Returns: FOTA_SUCCESS if encryption is decoded successfully and the datagram is valid

◆ fota_can_init()

FotaError fota_can_init ( const FotaCanSettings * settings )

Initialize the CAN interface for FOTA.

Returns: FOTA_ERROR_SUCCESS if the interface is initialized successfully FOTA_CAN_INIT_ERR if initialization fails

◆ fota_can_receive()

FotaError fota_can_receive ( FotaCanMessage *const msg )

Receive a CAN message in FOTA.

Parameters

msg	Pointer to the message that will be updated with incoming data

Returns: FOTA_ERROR_SUCCESS if the message is received successfully FOTA_CAN_RECEIVE_ERROR if receiving the message fails

◆ fota_can_transmit()

FotaError fota_can_transmit	(	uint32_t	id,
		bool	extended,
		const uint8_t *	data,
		size_t	len
	)

Transmit a CAN message in FOTA.

Parameters

id	CAN Message arbitration Id
extended	Boolean flag to select 11-bit vs 29-bit CAN transmission
data	Pointer to the data buffer to transmit
len	Length of the data buffer

Returns: FOTA_ERROR_SUCCESS if the message is transmitted successfully FOTA_CAN_TRANSMISSION_ERROR if transmitting the message fails

◆ fota_datagram_init()

FotaError fota_datagram_init	(	FotaDatagram *	datagram,
		FotaDatagramType	type,
		uint32_t	datagram_id,
		uint8_t *	data,
		uint32_t	length
	)

Initialize a datagram structure.

Parameters

datagram	Pointer to datagram to initialize
type	Type of datagram
datagram_id	Unique ID for this datagram
data	Data to include in datagram (can be NULL if building incrementally)
length	Length of data

Returns: FotaError Error code

◆ fota_datagram_is_complete()

bool fota_datagram_is_complete ( FotaDatagram * datagram )

Check if a datagram has been completely received.

Parameters

datagram Datagram to check

Returns: TRUE if datagram is complete FALSE otherwise

◆ fota_datagram_process_data_packet()

FotaError fota_datagram_process_data_packet	(	FotaDatagram *	datagram,
		FotaPacket *	packet
	)

Process a received packet and incorporate it into a datagram.

Parameters

datagram	Datagram being reconstructed
packet	Received packet

Returns: FotaError Error code

◆ fota_datagram_process_header_packet()

FotaError fota_datagram_process_header_packet	(	FotaDatagram *	datagram,
		FotaPacket *	packet
	)

Process a received header packet and incorporate it into a datagram.

Parameters

datagram	Datagram being reconstructed
packet	Received header packet

Returns: FotaError Error code

◆ fota_datagram_to_packets()

FotaError fota_datagram_to_packets	(	FotaDatagram *	datagram,
		FotaPacket *	packets,
		uint16_t *	num_packets,
		uint16_t	max_packets
	)

Fragment a datagram into packets for transmission.

Parameters

datagram	Datagram to fragment
packets	Array to store generated packets
num_packets	Pointer to store number of packets generated (Including the header packet)
max_packets	Maximum number of packets that can be stored in the array

Returns: FotaError Error code

◆ fota_datagram_verify()

FotaError fota_datagram_verify ( FotaDatagram * datagram )

Verify the integrity of a complete datagram.

Parameters

datagram Datagram to verify

Returns: FotaError Error code

◆ fota_dfu_init()

FotaError fota_dfu_init	(	PacketManager *	packet_manager,
		uintptr_t	staging_base,
		uintptr_t	app_start_addr
	)

Initialize DFU context.

Parameters

packet_manager	Pointer to packet manager instance
staging_base	Flash base address where firmware will be staged
app_start_addr	Address to jump to after flashing

Returns: FOTA_ERROR_SUCCESS or FOTA_ERROR_INVALID_ARGS

◆ fota_dfu_process()

FotaError fota_dfu_process ( FotaDatagram * datagram )

Process an incoming datagram and write to flash.

Parameters

datagram Pointer to fully received, verified datagram

Returns: FOTA_ERROR_SUCCESS or flash/write errors

◆ fota_encryption_init()

FotaError fota_encryption_init ( )

Initialize the encryption unit.

Returns: FOTA_SUCCESS if initialized successfully FOTA_ERROR_INTERNAL_ERROR if initialization fails

◆ fota_flash_erase()

FotaError fota_flash_erase	(	uint32_t	start_page,
		uint8_t	num_pages
	)

Erase some number of flash pages.

Parameters

start_page	Initial page number to erase
num_pages	Number of pages to erase

Returns: FOTA_ERROR_SUCCESS if data is erased successfully FOTA_ERROR_FLASH_ERASE if page is out of bounds OR erasing failed

◆ fota_flash_read()

FotaError fota_flash_read	(	uint32_t	address,
		uint8_t *	buffer,
		size_t	buffer_len
	)

Read from flash memory.

Parameters

address	Base memory address to read from
buffer	Pointer to the data buffer
buffer_len	Length of the data buffer

Returns: FOTA_ERROR_SUCCESS if data is read successfully FOTA_ERROR_FLASH_READ_FAILED if data read failed

◆ fota_flash_write()

FotaError fota_flash_write	(	uint32_t	address,
		uint8_t *	buffer,
		size_t	buffer_len
	)

Write to flash memory.

Parameters

address	Base memory address to write to
buffer	Pointer to the data buffer
buffer_len	Length of the data buffer

Returns: FOTA_ERROR_SUCCESS if data is written successfully FOTA_ERROR_FLASH_WRITE_FAILED if HAL flash fails FOTA_ERROR_FLASH_WRITE_OUT_OF_BOUNDS if address is out of bounds FOTA_ERROR_FLASH_WRITE_NOT_ALIGNED if data is not aligned

◆ fota_is_timed_out()

bool fota_is_timed_out ( void )

Checks if FOTA has timed out, meaning no requests have been received.

Returns: TRUE if a timeout event has occurred FALSE if no timeout has occurred

◆ fota_packet_deserialize()

FotaError fota_packet_deserialize	(	FotaPacket *	packet,
		uint8_t *	buffer,
		uint32_t	buf_size
	)

Deserialize buffer into FOTA packet.

Parameters

packet	Output FotaPacket struct
buffer	Input buffer
buf_size	Size of input buffer

Returns: FOTA_ERROR_SUCCESS or error

◆ fota_packet_init()

FotaError fota_packet_init	(	FotaPacket *	packet,
		FotaPacketType	type,
		uint8_t	sequence,
		uint16_t	length
	)

Initialize a FOTA packet.

Parameters

packet	Pointer to packet
type	Packet type
sequence	Sequence number
length	Length of actual data (≤ FOTA_PACKET_PAYLOAD_SIZE, multiple of 4)

Returns: FOTA_ERROR_SUCCESS or error

◆ fota_packet_serialize()

FotaError fota_packet_serialize	(	FotaPacket *	packet,
		uint8_t *	buffer,
		uint32_t	buf_size,
		uint32_t *	bytes_written
	)

Serialize FOTA packet into buffer.

Parameters

packet	Packet to serialize
buffer	Output buffer
buf_size	Size of output buffer
bytes_written	Number of bytes written

Returns: FOTA_ERROR_SUCCESS or error

◆ fota_packet_set_crc()

FotaError fota_packet_set_crc ( FotaPacket * packet )

Compute and set CRC32 of payload.

Parameters

packet Pointer to packet

Returns: FOTA_ERROR_SUCCESS or error

◆ fota_startup()

FotaError fota_startup ( void )

Initialize MCU system clock and HAL.

Call this function once at the start of your application

◆ fota_verify_datagram_encryption()

FotaError fota_verify_datagram_encryption ( FotaDatagram * datagram )

Verify a FOTA datagrams encryption.

Parameters

datagram Pointer to the encrypted datagram

Returns: FOTA_SUCCESS if encryption is decoded successfully and the datagram is valid

◆ fota_verify_flash_memory()

FotaError fota_verify_flash_memory	(	uintptr_t	start_addr,
		size_t	size_bytes
	)

Verify that the flash memory is not erased.

This checks the entire application flash memory to ensure it is not entirely erased

Parameters

start_addr	Start address to begin verifying flash memory
size_bytes	Size of flash memory to verify in bytes

Returns: FOTA_ERROR_SUCCESS if the memomry is valid FOTA_ERROR_FLASH_ERR if the memory is corrupt

◆ fota_verify_packet_encryption()

FotaError fota_verify_packet_encryption ( FotaPacket * packet )

Verify a FOTA packets encryption.

Parameters

packet Pointer to the encrypted packet

Returns: FOTA_SUCCESS if encryption is decoded successfully and the datagram is valid

◆ is_network_timeout()

bool is_network_timeout ( bool is_tx )

Checks if tx or rx command has timed out.

Subtracts the difference of current clock time and clock time when command started

Parameters

is_tx if it is checking timeout for a tx or an rx command

Returns: true if time elapsed is greater than FOTA_UART_TIMEOUT_MS false if time elapsed is less than FOTA_UART_TIMEOUT_MS