OTA Upgrade Stream classes

typedef OtaUpgradeStream

Alias for either OtaUpgrade::BasicStream or OtaUpgrade::EncryptedStream, depending on encryption settings.

Application code should use this alias to avoid source code modifications when changing OTA upgrade security settings.

class BasicStream : public ReadWriteStream

A write-only stream to parse and apply firmware unencrypted upgrade files generated by otatool.py.

The class fully automates the firmware upgrade process without any manual configuration. At construction time, the rBoot configuration is read to determine the unused ROM slot which should receive the upgrade. Just feed the upgrade file content into the write() method in arbitrarily sized chunks. The relevant portion(s) of the Flash memory (currently only the application rom) are updated on the fly as data arrives. When the file is complete and signature validation (if enabled) was successful, the updated slot is activated in the rBoot configuration. Call hasError() and/or check the public errorCode member to determine if everything went smoothly.

For further information on configuration options and the file format, refer to the library’s documentation.

See

EncryptedStream for encryption support.

Subclassed by OtaUpgrade::EncryptedStream

Print an integral number to output stream

Parameters

• num: Number to print
• base: The base for output (Default: Decimal (base 10))

Return Value

• size_t: Quantity of characters written to stream

size_t print(unsigned long num, int base = DEC)

size_t print(const unsigned long long &num, int base = DEC)

size_t print(long, int base = DEC)

size_t print(const long long&, int base = DEC)

size_t print(unsigned int num, int base = DEC)

size_t print(unsigned char num, int base = DEC)

size_t print(int num, int base = DEC)

Print an integral number to output stream, appending newline

Parameters

• num: Number to print
• base: The base for output (Default: Decimal (base 10))

Return Value

• size_t: Quantity of characters written to stream

size_t println(unsigned char num, int base = DEC)

size_t println(unsigned int num, int base = DEC)

size_t println(unsigned long num, int base = DEC)

size_t println(const unsigned long long &num, int base = DEC)

size_t println(int num, int base = DEC)

size_t println(long num, int base = DEC)

size_t println(const long long &num, int base = DEC)

Public Types

enum Error

Error code values.

Values:

None

No error occured thus far (default value of errorCode if hasError() returns false)

InvalidFormat

Invalid/unsupported upgrade file format.

UnsupportedData

Some content of the upgrade file is not supported by this version of OtaUpgradeStream.

DecryptionFailed

Decryption failed. Probably wrong decryption key.

NoRomFound

The file did not contain a ROM image suitable for the start address of the slot to upgrade.

RomTooLarge

The contained ROM image does not fit into the application firmware slot.

DowngradeNotAllowed

Attempt to downgrade to older firmware version.

VerificationFailed

Signature/checksum verification failed - updated ROM not activated.

FlashWriteFailed

Error while writing to Flash memory.

RomActivationFailed

Error while activating updated ROM slot.

OutOfMemory

Dynamic memory allocation failed.

Internal

An unexpected error occured.

Public Functions

BasicStream()

size_t write(const uint8_t *data, size_t size)

Process chunk of upgrade file.

Return

If less than size, an error occured. Check errorCode for more details.

Note

Even if write() never returns less than size it is not guaranteed that the upgrade was successful. Always use hasError() to determine success.

Parameters

• data: Pointer to chunk of data.
• size: Size of chunk pointed to by data in bytes.

bool hasError() const

Returns true if an error happened during the upgrade process.

See

errorCode

uint16_t readMemoryBlock(char *data, int bufSize)

Read a block of memory.

Parameters

• data: Pointer to the data to be read
• bufSize: Quantity of chars to read

Return Value

• uint16_t: Quantity of chars read

virtual int available()

Return the total length of the stream.

Return Value

• int: -1 is returned when the size cannot be determined

bool isFinished()

Check if all data has been read.

Return Value

• bool: True on success.

size_t write(uint8_t charToWrite)

Write a single character to the stream.

Parameters

• charToWrite:

Return Value

• size_t: Number of chars written (1 on success, 0 on failure)

size_t write(const char *str)

Writes a c-string to output stream.

Parameters

• str: Pointer to c-string

Return Value

• size_t: Quantity of characters written to stream

size_t write(const char *buffer, size_t size)

Writes characters from a buffer to output stream.

Parameters

• buffer: Pointer to character buffer
• size: Quantity of characters to write

Return Value

• size_t: Quantity of characters written to stream

virtual size_t copyFrom(IDataSourceStream *source, size_t size)

Copy data from a source stream.

Parameters

• source: Stream to read data from
• size: Quantity of chars to write, determines size of intermediate buffer to use

Return Value

• size_t: Quantity of chars actually written, may be less than requested

virtual StreamType getStreamType() const

Get the stream type.

Return Value

• StreamType: The stream type.

virtual bool isValid() const

Determine if the stream object contains valid data.

Note

Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Return Value

• bool: true if valid, false if invalid

int read()

Read one character and moves the stream pointer.

Return Value

• The: character that was read or -1 if none is available

int peek()

Read a character without advancing the stream pointer.

Return Value

• int: The character that was read or -1 if none is available

virtual int seekFrom(int offset, unsigned origin)

Change position in stream.

Note

This method is implemented by streams which support random seeking, such as files and memory streams.

Parameters

• offset:
• origin: SEEK_SET, SEEK_CUR, SEEK_END

Return Value

• New: position, < 0 on error

virtual bool seek(int len)

Move read cursor.

Parameters

• len: Relative cursor adjustment

Return Value

• bool: True on success.

int length()

Return the total length of the stream.

Return Value

• int: -1 is returned when the size cannot be determined

void flush()

virtual String id() const

Returns unique id of the resource.

Return Value

• String: the unique id of the stream.

virtual String getName() const

Returns name of the resource.

Note

Commonly used to obtain name of file

Return Value

• String:

String readString(size_t maxLen = UINT16_MAX)

Overrides Stream method for more efficient reading.

Note

Content is read using readMemoryBlock() so read position (for seekable streams) is not changed

String readString()

void setTimeout(unsigned long timeout)

bool find(char *target)

bool find(char *target, size_t length)

bool findUntil(char *target, char *terminator)

bool findUntil(char *target, size_t targetLen, char *terminate, size_t termLen)

long parseInt()

float parseFloat()

size_t readBytes(char *buffer, size_t length)

size_t readBytesUntil(char terminator, char *buffer, size_t length)

String readStringUntil(char terminator)

virtual int indexOf(char c)

int getWriteError()

Gets last error.

Return Value

• int: Error number of last write error

void clearWriteError()

Clears the last write error.

size_t print(char c)

Prints a single character to output stream.

Parameters

• c: Character to print

Return Value

• size_t: Quantity of characters written to stream

size_t print(const char str[])

Prints a c-string to output stream.

Parameters

• str: c-string to print

Return Value

• size_t: Quantity of characters written to output stream

size_t print(double num, int digits = 2)

Print a floating-point number to output stream.

Parameters

• num: Number to print
• digits: The decimal places to print (Default: 2, e.g. 21.35)

Return Value

• size_t: Quantity of characters written to stream

size_t print(const Printable &p)

Prints a Printable object to output stream.

Parameters

• p: Object to print

Return Value

• size_t: Quantity of characters written to stream

size_t print(const String &s)

Prints a String to output stream.

Parameters

• s: String to print

Return Value

• size_t: Quantity of characters written to stream

size_t println()

Prints a newline to output stream.

Return Value

• size_t: Quantity of characters written to stream

size_t println(const char str[])

Prints a c-string to output stream, appending newline.

Parameters

• str: c-string to print

Return Value

• size_t: Quantity of characters written to stream

size_t println(char c)

Prints a single character to output stream, appending newline.

Parameters

• c: Character to print

Return Value

• size_t: Quantity of characters written to stream

size_t println(double num, int digits = 2)

Print a floating-point number to output stream, appending newline.

Parameters

• num: Number to print
• digits: The decimal places to print (Default: 2, e.g. 21.35)

Return Value

• size_t: Quantity of characters written to stream

size_t println(const Printable &p)

Prints a Printable object to output stream, appending newline.

Parameters

• p: Object to print

Return Value

• size_t: Quantity of characters written to stream

size_t println(const String &s)

Prints a String to output stream, appending newline.

Parameters

• s: String to print

Return Value

• size_t: Quantity of characters written to stream

size_t printf(const char *fmt, ...)

Prints a formatted c-string to output stream.

Note

Use standard printf placeholders, e.g. d for integer, s for c-string, etc.

Parameters

• fmt: Pointer to formated c-string to print
• ...: Parameters for placeholders within formated string

Return Value

• size_t: Quantity of characters written to stream

Public Members

Error errorCode = Error::None

Error code. Only relevant if hasError() returns true.

Public Static Functions

static String errorToString(Error code)

Convert error code to string.

See

errorCode

class EncryptedStream : public OtaUpgrade::BasicStream

Encryption wrapper for BasicStream.

The class processes encrypted firmware upgrade files created by otatool.py. A buffer is allocated dynamically to fit the largest chunk of the encryption container (2kB unless otatool.py was modified). The actual processing of the decrypted data is defered to BasicStream.

Print an integral number to output stream

Parameters

• num: Number to print
• base: The base for output (Default: Decimal (base 10))

Return Value

• size_t: Quantity of characters written to stream

size_t print(unsigned long num, int base = DEC)

size_t print(const unsigned long long &num, int base = DEC)

size_t print(long, int base = DEC)

size_t print(const long long&, int base = DEC)

size_t print(unsigned int num, int base = DEC)

size_t print(unsigned char num, int base = DEC)

size_t print(int num, int base = DEC)

Print an integral number to output stream, appending newline

Parameters

• num: Number to print
• base: The base for output (Default: Decimal (base 10))

Return Value

• size_t: Quantity of characters written to stream

size_t println(unsigned char num, int base = DEC)

size_t println(unsigned int num, int base = DEC)

size_t println(unsigned long num, int base = DEC)

size_t println(const unsigned long long &num, int base = DEC)

size_t println(int num, int base = DEC)

size_t println(long num, int base = DEC)

size_t println(const long long &num, int base = DEC)

Public Types

enum Error

Error code values.

Values:

None

No error occured thus far (default value of errorCode if hasError() returns false)

InvalidFormat

Invalid/unsupported upgrade file format.

UnsupportedData

Some content of the upgrade file is not supported by this version of OtaUpgradeStream.

DecryptionFailed

Decryption failed. Probably wrong decryption key.

NoRomFound

The file did not contain a ROM image suitable for the start address of the slot to upgrade.

RomTooLarge

The contained ROM image does not fit into the application firmware slot.

DowngradeNotAllowed

Attempt to downgrade to older firmware version.

VerificationFailed

Signature/checksum verification failed - updated ROM not activated.

FlashWriteFailed

Error while writing to Flash memory.

RomActivationFailed

Error while activating updated ROM slot.

OutOfMemory

Dynamic memory allocation failed.

Internal

An unexpected error occured.

Public Functions

EncryptedStream()

~EncryptedStream()

size_t write(const uint8_t *data, size_t size)

Process an arbitrarily sized chunk of an encrypted OTA upgrade file.

Return

If less than size, an error occured. Check for more details.

Note

size does not have to match the chunk size used by otatool.py

Parameters

• data: Pointer to chunk of data.
• size: Size of chunk pointed to by data in bytes.

size_t write(uint8_t charToWrite)

Write a single character to the stream.

Parameters

• charToWrite:

Return Value

• size_t: Number of chars written (1 on success, 0 on failure)

size_t write(const char *str)

Writes a c-string to output stream.

Parameters

• str: Pointer to c-string

Return Value

• size_t: Quantity of characters written to stream

size_t write(const char *buffer, size_t size)

Writes characters from a buffer to output stream.

Parameters

• buffer: Pointer to character buffer
• size: Quantity of characters to write

Return Value

• size_t: Quantity of characters written to stream

bool hasError() const

Returns true if an error happened during the upgrade process.

See

errorCode

uint16_t readMemoryBlock(char *data, int bufSize)

Read a block of memory.

Parameters

• data: Pointer to the data to be read
• bufSize: Quantity of chars to read

Return Value

• uint16_t: Quantity of chars read

virtual int available()

Return the total length of the stream.

Return Value

• int: -1 is returned when the size cannot be determined

bool isFinished()

Check if all data has been read.

Return Value

• bool: True on success.

virtual size_t copyFrom(IDataSourceStream *source, size_t size)

Copy data from a source stream.

Parameters

• source: Stream to read data from
• size: Quantity of chars to write, determines size of intermediate buffer to use

Return Value

• size_t: Quantity of chars actually written, may be less than requested

virtual StreamType getStreamType() const

Get the stream type.

Return Value

• StreamType: The stream type.

virtual bool isValid() const

Determine if the stream object contains valid data.

Note

Where inherited classes are initialised by constructor this method indicates whether that was successful or not (e.g. FileStream)

Return Value

• bool: true if valid, false if invalid

int read()

Read one character and moves the stream pointer.

Return Value

• The: character that was read or -1 if none is available

int peek()

Read a character without advancing the stream pointer.

Return Value

• int: The character that was read or -1 if none is available

virtual int seekFrom(int offset, unsigned origin)

Change position in stream.

Note

This method is implemented by streams which support random seeking, such as files and memory streams.

Parameters

• offset:
• origin: SEEK_SET, SEEK_CUR, SEEK_END

Return Value

• New: position, < 0 on error

virtual bool seek(int len)

Move read cursor.

Parameters

• len: Relative cursor adjustment

Return Value

• bool: True on success.

int length()

Return the total length of the stream.

Return Value

• int: -1 is returned when the size cannot be determined

void flush()

virtual String id() const

Returns unique id of the resource.

Return Value

• String: the unique id of the stream.

virtual String getName() const

Returns name of the resource.

Note

Commonly used to obtain name of file

Return Value

• String:

String readString(size_t maxLen = UINT16_MAX)

Overrides Stream method for more efficient reading.

Note

Content is read using readMemoryBlock() so read position (for seekable streams) is not changed

String readString()

void setTimeout(unsigned long timeout)

bool find(char *target)

bool find(char *target, size_t length)

bool findUntil(char *target, char *terminator)

bool findUntil(char *target, size_t targetLen, char *terminate, size_t termLen)

long parseInt()

float parseFloat()

size_t readBytes(char *buffer, size_t length)

size_t readBytesUntil(char terminator, char *buffer, size_t length)

String readStringUntil(char terminator)

virtual int indexOf(char c)

int getWriteError()

Gets last error.

Return Value

• int: Error number of last write error

void clearWriteError()

Clears the last write error.

size_t print(char c)

Prints a single character to output stream.

Parameters

• c: Character to print

Return Value

• size_t: Quantity of characters written to stream

size_t print(const char str[])

Prints a c-string to output stream.

Parameters

• str: c-string to print

Return Value

• size_t: Quantity of characters written to output stream

size_t print(double num, int digits = 2)

Print a floating-point number to output stream.

Parameters

• num: Number to print
• digits: The decimal places to print (Default: 2, e.g. 21.35)

Return Value

• size_t: Quantity of characters written to stream

size_t print(const Printable &p)

Prints a Printable object to output stream.

Parameters

• p: Object to print

Return Value

• size_t: Quantity of characters written to stream

size_t print(const String &s)

Prints a String to output stream.

Parameters

• s: String to print

Return Value

• size_t: Quantity of characters written to stream

size_t println()

Prints a newline to output stream.

Return Value

• size_t: Quantity of characters written to stream

size_t println(const char str[])

Prints a c-string to output stream, appending newline.

Parameters

• str: c-string to print

Return Value

• size_t: Quantity of characters written to stream

size_t println(char c)

Prints a single character to output stream, appending newline.

Parameters

• c: Character to print

Return Value

• size_t: Quantity of characters written to stream

size_t println(double num, int digits = 2)

Print a floating-point number to output stream, appending newline.

Parameters

• num: Number to print
• digits: The decimal places to print (Default: 2, e.g. 21.35)

Return Value

• size_t: Quantity of characters written to stream

size_t println(const Printable &p)

Prints a Printable object to output stream, appending newline.

Parameters

• p: Object to print

Return Value

• size_t: Quantity of characters written to stream

size_t println(const String &s)

Prints a String to output stream, appending newline.

Parameters

• s: String to print

Return Value

• size_t: Quantity of characters written to stream

size_t printf(const char *fmt, ...)

Prints a formatted c-string to output stream.

Note

Use standard printf placeholders, e.g. d for integer, s for c-string, etc.

Parameters

• fmt: Pointer to formated c-string to print
• ...: Parameters for placeholders within formated string

Return Value

• size_t: Quantity of characters written to stream

Public Members

uint8_t header[crypto_secretstream_xchacha20poly1305_HEADERBYTES]

uint16_t chunkSizeMinusOne

Error errorCode = Error::None

Error code. Only relevant if hasError() returns true.

Public Static Functions

static String errorToString(Error code)

Convert error code to string.

See

errorCode