iotile.core.hw.reports

Package Contents

class IndividualReadingReport(rawreport, **kwargs)

Bases:iotile.core.hw.reports.report.IOTileReport

Report format where every reading is packaged in a 20 byte frame.

Args:
rawreport (bytearray): The raw data of this report
ReportType = 0
classmethod HeaderLength(cls)

Return the length of a header needed to calculate this report’s length

Returns:
int: the length of the needed report header
classmethod ReportLength(cls, header)

Given a header of HeaderLength bytes, calculate the size of this report

classmethod FromReadings(cls, uuid, readings)

Generate an instance of the report format from a list of readings and a uuid

decode(self)

Decode this report into a single reading

encode(self)

Turn this report into a serialized bytearray that could be decoded with a call to decode

class IOTileReading(raw_time, stream, value, time_base=None, reading_id=None, reading_time=None)

Base class for readings streamed from IOTile device.

Each reading represents a single time/value pair sent from an IOTile Device. Since many IOTile Devices do not have a hardware realtime clock, the timestamp that is assigned to a reading may only be a relative interval from a fixed event in the past, like the time the device turned on.

If the user knows the absolute time for this event they can pass it as a datetime in time_base to turn the relative reading timestamp into an absolute datetime accessible as reading_time.

Args:
raw_time (int): the number of seconds since the device turned on
when the reading was taken
time_base (datetime): An optional estimate of when the device was
last turned on so that we can calculate the actual time of the reading
reading_time (datetime): An optional UTC time when this event was acquired.
If combined with time_base, this value will take precedence and time_base and raw_time will be ignored.
reading_id (int): An optional unique identifier for this reading that allows
deduplication. If no reading id is passed, InvalidReadingID is used.

stream (int): The stream that this reading is part of value (int): The raw reading value

InvalidReadingID = 0
asdict(self)

Encode the data in this reading into a dictionary.

Returns:
dict: A dictionary containing the information from this reading.
classmethod FromDict(cls, obj)

Create an IOTileReading from the result of a previous call to asdict().

Args:
obj (dict): A dictionary produced by a call to IOTileReading.asdict()
Returns:
IOTileReading: The converted IOTileReading object.
__eq__(self, other)
__str__(self)
class IOTileReport(rawreport, signed, encrypted, received_time=None)

Base class for data streamed from an IOTile device.

All IOTileReports must derive from this class and must implement the following interface

  • class method HeaderLength(cls)

    function returns the number of bytes that must be read before the total length of the report can be determined. HeaderLength() must always be less than or equal to the length of the smallest version of this report.

  • class method ReportLength(cls, header):

    function that takes HeaderLength() bytes and returns the total size of the report, including the header.

  • class method FromReadings(cls, uuid, readings)

    function that creates an instance of an IOTileReport subclass from a list of readings and a device uuid.

  • property ReportType:

    The one byte type code that defines this report type

  • instance method verify(self):

    function that verifies that a report is correctly received and, if possible, that the sender is who it says it is.

  • instance method decode(self):

    function that decodes a report into a series of IOTileReading objects. The function should return a list of readings.

  • instance method serialize(self):

    function that should turn the report into a serialized bytearray that could be decoded with decode().

Args:

rawreport (bytearray): The raw data of this report signed (bool): Whether this report is signed to specify who it is from encrypted (bool): Whether this report is encrypted received_time (datetime): The time in UTC when this report was received from a device.

If not received, the time is assumed to be utcnow().
classmethod HeaderLength(cls)

Return the length of a header needed to calculate this report’s length

Returns:
int: the length of the needed report header
classmethod ReportLength(cls, header)

Given a header of HeaderLength bytes, calculate the size of this report

decode(self)

Decode a raw report into a series of readings

encode(self)

Encode this report into a binary blob that could be decoded by a report format’s decode method.

save(self, path)

Save a binary copy of this report

Args:
path (string): The path where we should save the binary copy of the report
serialize(self)

Turn this report into a dictionary that encodes all information including received timestamp

__str__(self)
class SignedListReport(rawreport, **kwargs)

Bases:iotile.core.hw.reports.report.IOTileReport

A report that consists of a signed list of readings.

Args:
rawreport (bytearray): The raw data of this report
ReportType = 1
classmethod HeaderLength(cls)

Return the length of a header needed to calculate this report’s length

Returns:
int: the length of the needed report header
classmethod ReportLength(cls, header)

Given a header of HeaderLength bytes, calculate the size of this report

classmethod FromReadings(cls, uuid, readings, root_key=AuthProvider.NoKey, signer=None, report_id=IOTileReading.InvalidReadingID, selector=65535, streamer=0, sent_timestamp=0)

Generate an instance of the report format from a list of readings and a uuid.

The signed list report is created using the passed readings and signed using the specified method and AuthProvider. If no auth provider is specified, the report is signed using the default authorization chain.

Args:

uuid (int): The uuid of the deviec that this report came from readings (list): A list of IOTileReading objects containing the data in the report root_key (int): The key that should be used to sign the report (must be supported

by an auth_provider)
signer (AuthProvider): An optional preconfigured AuthProvider that should be used to sign this
report. If no AuthProvider is provided, the default ChainedAuthProvider is used.
report_id (int): The id of the report. If not provided it defaults to IOTileReading.InvalidReadingID.
Note that you can specify anything you want for the report id but for actual IOTile devices the report id will always be greater than the id of all of the readings contained in the report since devices generate ids sequentially.
selector (int): The streamer selector of this report. This can be anything but if the report came from
a device, it would correspond with the query the device used to pick readings to go into the report.

streamer (int): The streamer id that this reading was sent from. sent_timestamp (int): The device’s uptime that sent this report.

decode(self)

Decode this report into a list of readings

class BroadcastReport(rawreport, **kwargs)

Bases:iotile.core.hw.reports.report.IOTileReport

Base class for all reports that are broadcast without a connection.

This generic class supports a fixed encoding but does not yet support encryption/decryption or signing. The encoding of this report is designed to accommodate a range of use cases and not be a binary match for any specific wire format that a BroadcastReport might be created from, such as part of a bluetooth advertisement packet.

The encoding is designed to accommodate 1 or more IOTileReadings with a fixed size header and a variable length authentication block after the readings.

NO_AUTH = 0
_HEADER_LENGTH = 16
_AUTH_BLOCK_LENGTHS
ReportType = 3
classmethod _parse_header(cls, header)
classmethod HeaderLength(cls)

Return the length of a header needed to calculate this report’s length

Returns:
int: the length of the needed report header
classmethod ReportLength(cls, header)

Given a header of HeaderLength bytes, calculate the size of this report.

Returns:
int: The total length of the report including the header that we are passed.
classmethod FromReadings(cls, uuid, readings, sent_timestamp=0)

Generate a broadcast report from a list of readings and a uuid.

decode(self)

Decode this report into a list of visible readings.

class IOTileReportParser(report_callback=None, error_callback=None)

Accumulates data from a stream and emits IOTileReports

Every time new data is available on the stream, add_data should be called. Every time a complete report has been received, the optional callback passed in will be called with an IOTileReport subclass.

Args:
report_callback (callable): A function to be called every time a new report is received
The signature should be bool report_callback(report, context). The return value is True to indicate that IOTileReportParser should also keep a copy of the report or False to indicate it should delete it.
error_callback (callable): A function to be called every time an error occurs.
The signature should be error_callback(error_code, message, context). If a fatal error occurs, further parsing of reports will be stopped.
WaitingForReportType = 1
WaitingForReportHeader = 2
WaitingForCompleteReport = 3
ErrorState = 4
ErrorFindingReportType = 1
ErrorParsingReportHeader = 2
ErrorParsingCompleteReport = 3
add_data(self, data)

Add data to our stream, emitting reports as each new one is seen

Args:
data (bytearray): A chunk of new data to add
process_data(self)

Attempt to extract a report from the current data stream contents

Returns:
bool: True if further processing is required and process_data should be
called again.
calculate_header_size(self, current_type)

Determine the size of a report header given its report type

calculate_report_size(self, current_type, report_header)

Determine the size of a report given its type and header

parse_report(self, current_type, report_data)

Parse a report into an IOTileReport subclass

deserialize_report(self, serialized)

Deserialize a report that has been serialized by calling report.serialize()

Args:
serialized (dict): A serialized report object
_handle_report(self, report)

Try to emit a report and possibly keep a copy of it

classmethod _build_type_map(cls)

Build a map of all of the known report format processors

class FlexibleDictionaryReport

Bases:iotile.core.hw.reports.report.IOTileReport

A list of events and readings encoded as a dictionary.

This report format is designed to be suitable for storing in any format that supports key/value objects like json, msgpack, yaml, etc.

Args:

rawreport (bytearray): The raw data of this report signed (bool): Whether this report is signed to specify who it is from encrypted (bool): Whether this report is encrypted received_time (datetime): The time in UTC when this report was received from a device.

If not received, the time is assumed to be utcnow().
FORMAT_TAG = v100
classmethod FromReadings(cls, uuid, readings, events, report_id=IOTileReading.InvalidReadingID, selector=65535, streamer=256, sent_timestamp=0, received_time=None)

Create a flexible dictionary report from a list of readings and events.

Args:

uuid (int): The uuid of the device that this report came from readings (list of IOTileReading): A list of IOTileReading objects containing the data in the report events (list of IOTileEvent): A list of the events contained in the report. report_id (int): The id of the report. If not provided it defaults to IOTileReading.InvalidReadingID.

Note that you can specify anything you want for the report id but for actual IOTile devices the report id will always be greater than the id of all of the readings contained in the report since devices generate ids sequentially.
selector (int): The streamer selector of this report. This can be anything but if the report came from
a device, it would correspond with the query the device used to pick readings to go into the report.

streamer (int): The streamer id that this reading was sent from. sent_timestamp (int): The device’s uptime that sent this report. received_time(datetime): The UTC time when this report was received from an IOTile device. If it is being

created now, received_time defaults to datetime.utcnow().
Returns:
FlexibleDictionaryReport: A report containing the readings and events passed in.
decode(self)

Decode this report from a msgpack encoded binary blob.

asdict(self)

Return this report as a dictionary

serialize(self)

Serialize this report including the received time.

class UTCAssigner

Helper class to assign UTC timestamps to device readings.

_Y2KReference
_EpochReference
_load_known_breaks(self)
anchor_stream(self, stream_id, converter='rtc')

Mark a stream as containing anchor points.

classmethod convert_rtc(cls, timestamp)

Convert a number of seconds since 1/1/2000 to UTC time.

classmethod _convert_rtc_anchor(cls, reading)

Convert a reading containing an RTC timestamp to datetime.

classmethod _convert_epoch_anchor(cls, reading)

Convert a reading containing an epoch timestamp to datetime.

add_point(self, reading_id, uptime=None, utc=None, is_break=False)

Add a time point that could be used as a UTC reference.

add_reading(self, reading)

Add an IOTileReading.

add_report(self, report, ignore_errors=False)

Add all anchors from a report.

assign_utc(self, reading_id, uptime=None)

Assign a utc datetime to a reading id.

This method will return an object with assignment information or None if a utc value cannot be assigned. The assignment object returned contains a utc property that has the asssigned UTC as well as other properties describing how reliable the assignment is.