iotile.core.hw.update

Classes and routines for creating remote update scripts for IOTile devices.

Package Contents

class UpdateScript(records)

An update script that consists of a list of UpdateRecord objects.

Args:
records (list of UpdateRecord): The records that make up this script.
SCRIPT_MAGIC = 523124044
SCRIPT_HEADER_LENGTH = 24
logger
classmethod ParseHeader(cls, script_data)

Parse a script integrity header.

This function makes sure any integrity hashes are correctly parsed and returns a ScriptHeader structure containing the information that it was able to parse out.

Args:
script_data (bytearray): The script that we should parse.
Raises:
ArgumentError: If the script contains malformed data that
cannot be parsed.
Returns:
ScriptHeader: The parsed script header information
classmethod FromBinary(cls, script_data, allow_unknown=True, show_rpcs=False)

Parse a binary update script.

Args:

script_data (bytearray): The binary data containing the script. allow_unknown (bool): Allow the script to contain unknown records

so long as they have correct headers to allow us to skip them.
show_rpcs (bool): Show SendRPCRecord matches for each record rather than
the more specific operation
Raises:
ArgumentError: If the script contains malformed data that cannot
be parsed.

DataError: If the script contains unknown records and allow_unknown=False

Returns:
UpdateScript: The parsed update script.
encode(self)

Encode this record into a binary blob.

This binary blob could be parsed via a call to FromBinary().

Returns:
bytearray: The binary encoded script.
__eq__(self, other)
__ne__(self, other)
class UpdateRecord

The base class for all update actions inside of an update script.

HEADER_LENGTH = 8
KNOWN_CLASSES
PLUGINS_LOADED = False
classmethod MatchType(cls)

Return the record type that this record matches.

All records must match an 8-bit record type field that is used to decode a binary script. Note that multiple records may match the same 8-bit record type if they have different levels of specificity.

Returns:
int: The single record type that this record matches.
encode(self)

Encode this record into binary, suitable for embedded into an update script.

This function just adds the required record header and delegates all work to the subclass implementation of encode_contents().

Returns:
bytearary: The binary version of the record that could be parsed via
a call to UpdateRecord.FromBinary()
encode_contents(self)

Encode the contents of this update record without including a record header.

Returns:
bytearary: The encoded contents.
classmethod LoadPlugins(cls)

Load all registered iotile.update_record plugins.

classmethod MatchQuality(cls, record_data, record_count=1)

Check how well this record matches the given binary data.

This function will only be called if the record matches the type code given by calling MatchType() and this function should check how well this record matches and return a quality score between 0 and 100, with higher quality matches having higher scores. The default value should be MatchQuality.GenericMatch which is 50. If this record does not match at all, it should return MatchQuality.NoMatch.

Many times, only a single record type will match a given binary record but there are times when multiple different logical records produce the same type of record in a script, such as set_version and set_userkey both producing a call_rpc record with different RPC values. The MatchQuality method is used to allow for rich decoding of such scripts back to the best possible record that created them.

Args:
record_data (bytearay): The raw record that we should check for
a match.
record_count (int): If we are asked for a match on multiple
records in a row, because we previously returned MatchQuality.DeferMatch then this will indicate how many binary records are included together.
Returns:

int: The match quality between 0 and 100.

You should use the constants defined in MatchQuality as much as possible. The only exception to the 0 to 100 rules is if you return MatchQuality.DeferMatch which means that we are matching a multi-record statement with a single logical UpdateRecord.

classmethod RegisterRecordType(cls, record_class)

Register a known record type in KNOWN_CLASSES.

Args:
record_class (UpdateRecord): An update record subclass.
classmethod FromBinary(cls, record_data, record_count=1)

Create an UpdateRecord subclass from binary record data.

This should be called with a binary record blob (including the record type header) and it will return the best record class match that it can find for that record.

Args:
record_data (bytearray): The raw record data that we wish to parse
into an UpdateRecord subclass including its 4 byte record header.
record_count (int): If we are asked to create a record from multiple
records, the record_data will be passed to the record subclass with headers intact since there will be more than one header.
Raises:
ArgumentError: If the record_data is malformed and cannot be parsed. DataError: If there is no matching record type registered.
Returns:
UpdateRecord: A subclass of UpdateRecord based on what record
type matches the best.
__ne__(self, other)