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

#include <BasicStream.h>

Inheritance diagram for OtaUpgrade::BasicStream:

Collaboration diagram for OtaUpgrade::BasicStream:

Public Types
enum class	Error { None , InvalidFormat , UnsupportedData , DecryptionFailed , NoRomFound , RomTooLarge , DowngradeNotAllowed , VerificationFailed , FlashWriteFailed , RomActivationFailed , OutOfMemory , Internal }
	Error code values. More...

Public Member Functions
	BasicStream ()

size_t	write (const uint8_t *data, size_t size) override
	Process chunk of upgrade file. More...

bool	hasError () const
	Returns true if an error happened during the upgrade process. More...

uint16_t	readMemoryBlock (char *data, int bufSize) override
	Read a block of memory. More...

virtual int	available () override
	Return the total length of the stream. More...

bool	isFinished () override
	Check if all data has been read. More...

Public Member Functions inherited from ReadWriteStream
size_t	write (uint8_t charToWrite) override
	From Stream class: We don't write using this stream. More...

virtual size_t	copyFrom (IDataSourceStream *source, size_t size=SIZE_MAX)
	Copy data from a source stream. More...

virtual size_t	write (uint8_t c)=0
	Writes a single character to output stream. More...

size_t	write (const char *str)
	Writes a c-string to output stream. More...

virtual size_t	write (const uint8_t *buffer, size_t size)
	Writes characters from a buffer to output stream. More...

size_t	write (const char *buffer, size_t size)
	Writes characters from a buffer to output stream. More...

Public Member Functions inherited from IDataSourceStream
virtual StreamType	getStreamType () const
	Get the stream type. More...

virtual bool	isValid () const
	Determine if the stream object contains valid data. More...

size_t	readBytes (char *buffer, size_t length) override
	Read chars from stream into buffer. More...

int	read () override
	Read one character and moves the stream pointer. More...

int	peek () override
	Read a character without advancing the stream pointer. More...

virtual int	seekFrom (int offset, SeekOrigin origin)
	Change position in stream. More...

virtual bool	seek (int len)
	Move read cursor. More...

void	flush () override

virtual String	id () const
	Returns unique id of the resource. More...

virtual String	getName () const
	Returns name of the resource. More...

virtual MimeType	getMimeType () const
	Get MIME type for stream content. More...

String	readString (size_t maxLen) override
	Overrides Stream method for more efficient reading. More...

virtual bool	moveString (String &s)
	Memory-based streams may be able to move content into a String. More...

virtual size_t	readBytes (char *buffer, size_t length)
	Read chars from stream into buffer. More...

size_t	readBytes (uint8_t *buffer, size_t length)

Public Member Functions inherited from Stream
	Stream ()

void	setTimeout (unsigned long timeout)
	Set maximum milliseconds to wait for stream data, default is 1 second. More...

bool	find (const char *target)
	Read data from the stream until the target string is found. More...

bool	find (const char *target, size_t length)
	Read data from the stream until the target string of given length is found. More...

bool	findUntil (const char target, const char terminator)
	As `find()` but search ends if the terminator string is found. More...

bool	findUntil (const char target, size_t targetLen, const char terminate, size_t termLen)
	As `findUntil(const char, const char)` but search ends if the terminate string is found. More...

long	parseInt ()
	Returns the first valid (long) integer value from the current position. More...

float	parseFloat ()
	float version of parseInt More...

size_t	readBytes (uint8_t *buffer, size_t length)

size_t	readBytesUntil (char terminator, char *buffer, size_t length)
	As `readBytes()` with terminator character. More...

String	readStringUntil (char terminator)

virtual int	indexOf (char c)

Public Member Functions inherited from Print
virtual	~Print ()

int	getWriteError ()
	Gets last error. More...

void	clearWriteError ()
	Clears the last write error. More...

size_t	write (const char *str)
	Writes a c-string to output stream. More...

size_t	write (const char *buffer, size_t size)
	Writes characters from a buffer to output stream. More...

size_t	print (char c)
	Prints a single character to output stream. More...

size_t	print (const char str[])
	Prints a c-string to output stream. More...

size_t	print (double num, int digits=2)
	Print a floating-point number to output stream. More...

template<typename T >
std::enable_if< has_printTo< T >::value, size_t >::type	print (const T &obj)
	Prints a Printable object to output stream. More...

size_t	print (const String &s)
	Prints a String to output stream. More...

template<typename E >
std::enable_if< std::is_enum< E >::value &&!std::is_convertible< E, int >::value, size_t >::type	print (E value)
	enums can be printed as strings provided they have a `toString(E)` implementation. More...

size_t	println ()
	Prints a newline to output stream. More...

template<typename... Args>
size_t	println (const Args &... args)
	Print value plus newline to output stream. More...

size_t	printf (const char *fmt,...)
	Prints a formatted c-string to output stream. More...

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

template<typename... Args>
size_t	print (unsigned long num, Args... args)

template<typename... Args>
size_t	print (const unsigned long long &num, Args... args)

size_t	print (long num, uint8_t base=DEC)

template<typename... Args>
size_t	print (long num, Args... args)

template<typename... Args>
size_t	print (const long long &num, Args... args)

template<typename... Args>
size_t	print (unsigned int num, Args... args)

template<typename... Args>
size_t	print (unsigned char num, Args... args)

template<typename... Args>
size_t	print (int num, Args... args)

Public Attributes
Error	errorCode = Error::None
	Error code. Only relevant if `hasError()` returns `true`. More...

Protected Member Functions
void	setError (Error ec)

Protected Member Functions inherited from Stream
int	timedRead ()

int	timedPeek ()

int	peekNextDigit ()
	returns the next numeric digit in the stream or -1 if timeout More...

long	parseInt (char skipChar)
	Like regular `parseInt()` but the given skipChar is ignored. More...

float	parseFloat (char skipChar)
	Like `parseInt(skipChar)` for float. More...

Protected Member Functions inherited from Print
void	setWriteError (int err=1)

Additional Inherited Members
Protected Attributes inherited from Stream
uint16_t	receiveTimeout = 1000
	number of milliseconds to wait for the next char before aborting timed read More...

Detailed Description

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 also: EncryptedStream for encryption support.

Member Enumeration Documentation

◆ Error

enum OtaUpgrade::BasicStream::Error

strong

Error code values.

Enumerator
None	No error occurred 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 occurred.

Constructor & Destructor Documentation

◆ BasicStream()

OtaUpgrade::BasicStream::BasicStream ( )

Member Function Documentation

◆ available()

virtual int OtaUpgrade::BasicStream::available ( )

inlineoverridevirtual

Return the total length of the stream.

Return values

int	-1 is returned when the size cannot be determined

Reimplemented from IDataSourceStream.

◆ hasError()

bool OtaUpgrade::BasicStream::hasError ( ) const

inline

Returns true if an error happened during the upgrade process.

See also: errorCode

◆ isFinished()

bool OtaUpgrade::BasicStream::isFinished ( )

inlineoverridevirtual

Check if all data has been read.

Return values

bool	True on success.

Implements IDataSourceStream.

◆ readMemoryBlock()

uint16_t OtaUpgrade::BasicStream::readMemoryBlock	(	char *	data,
		int	bufSize
	)

inlineoverridevirtual

Read a block of memory.

Parameters

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

Return values

uint16_t Quantity of chars read

Todo:: Should IDataSourceStream::readMemoryBlock return same data type as its bufSize param?

Implements IDataSourceStream.

◆ setError()

void OtaUpgrade::BasicStream::setError ( Error ec )

protected

◆ write()

size_t OtaUpgrade::BasicStream::write	(	const uint8_t *	data,
		size_t	size
	)

overridevirtual

Process chunk of upgrade file.

Parameters

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

Returns: If less than size, an error occurred. 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.

Implements ReadWriteStream.

Reimplemented in OtaUpgrade::EncryptedStream.

Member Data Documentation

◆ errorCode

Error OtaUpgrade::BasicStream::errorCode = Error::None

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

The documentation for this class was generated from the following file:

BasicStream.h

Public Types

Public Member Functions

Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Error

Constructor & Destructor Documentation

◆ BasicStream()

Member Function Documentation

◆ available()

◆ hasError()

◆ isFinished()

◆ readMemoryBlock()

◆ setError()

◆ write()

Member Data Documentation

◆ errorCode