API Reference

Classes for accessing IotaWatt status and data via the Query API.

iotawatt_access.device_login()[source]

Get device URL, username, and password.

Return device URL, username, and password from environment variables “IOTAWATT_URL”, “IOTAWATT_USERNAME”, and “IOTAWATT_PASSWORD” respectively. If not set, return defaults values “http://iotawatt.local”, “admin”, and None respectively.

iotawatt_access.data_path()[source]

Get path for data store.

Return the data path from environment variable “IOTAWATT_DATA_PATH” if set. Otherwise return default value “~/IotaWatt_Data”.

iotawatt_access.str_to_datetime(timestr, utc=False)[source]

Convert a string specifying a date and time into a datetime object.

Parameters:

  • timestr (str) – String specifying a date and time.

  • utc (bool, optional) – Flag indicating whether default time zone should be set to UTC.

Returns:

datetime – A datetime object representation of the date/time.

iotawatt_access.str_to_timestamp(timestr, utc=False)[source]

Convert a string specifying a date and time into a Unix timestamp.

Parameters:

  • timestr (str) – String specifying a date and time.

  • utc (bool, optional) – Flag indicating whether default time zone should be set to UTC.

Returns:

int – Unix timestamp representation of the date/time.

iotawatt_access.timestamp_to_datetime(ts, utc=False)[source]

Convert a Unix timestamp into a datetime object.

Parameters:

  • ts (int) – Unix timestamp.

  • utc (bool, optional) – Flag indicating whether time zone should remain as UTC or be converted to local time.

Returns:

datetime – A datetime object representation of the date/time.

iotawatt_access.timestamp_to_str(ts, utc=False, notz=False)[source]

Convert a Unix timestamp into an ISO-format date/time string.

Parameters:

  • ts (int) – Unix timestamp

  • utc (bool, optional) – Flag indicating whether time zone should remain as UTC or be converted to local time.

  • notz (bool, optional) – Flag indicating whether the time zone should be included in the returned string.

Returns:

string – ISO format string representation of the date/time.

iotawatt_access.dict_list_to_str(dl, keys=None, fmt=None, cnv=None)[source]

Construct a tabular representation of a list of dicts.

Parameters:

  • dl (list) – List of dicts to be tabulated.

  • keys (list) – List of dict keys to be tabulated.

  • fmt (dict) – Dictionary of string formatting specifications.

  • cnv (dict) – Dictionary of value mapping functions.

Returns:

str – Tabular representation of list of dictionaries as string.

iotawatt_access.dict_to_str(d, fmt=None, cnv=None)[source]

Construct a tabular representation of a dict.

Parameters:

  • d (dict) – Dictionary to be tabulated.

  • fmt (dict) – Dictionary of string formatting specifications.

  • cnv (dict) – Dictionary of value mapping functions.

Returns:

str – Tabular representation of dictionary as string.

class iotawatt_access.IotaWattAPI(url='http://iotawatt.local', user='admin', pwd=None, debug=False, dbgfile='iotawatt_api_debug.log')[source]

Bases: object

Access IotaWatt status and recorded data via the Query API.

Variables:

  • auth (HTTPDigestAuth) – Authentication for access to Query API.

  • channels (list) – List of IotaWatt channel names.

  • inputs (list) – List of IotaWatt input channel names.

  • outputs (list) – List of IotaWatt output channel names.

  • url (str) – URL for access to Query API.

Initialize IotaWattAPI object.

Parameters:

  • url (str, optional) – IotaWatt device URL.

  • user (str, optional) – IotaWatt API username.

  • pwd (None, optional) – IotaWatt API password.

get_channel_info(retry=3)[source]

Get details of IotaWatt device input and output channels.

Parameters:

retry (int, optional) – Number of retries allowed.

Returns:

list of dict – Channel details.

get_status(stype='inputs', retry=3)[source]

Get IotaWatt device status.

Valid values for stype: inputs, outputs, wifi, stats, datalogs

Parameters:

  • stype (str, optional) – Status type.

  • retry (int, optional) – Number of retries allowed.

Returns:

dict or list of dict – Status details.

get_channel_data(begin, end, channels=None, interval=5, frcdig=3, retry=3, callback=None)[source]

Get recorded data from IotaWatt device.

Parameters:

  • begin (str) – Start date/time of channel data.

  • end (str) – End date/time of channel data.

  • channels (list or None, optional) – List of current/power channel names. If None, download all of them.

  • interval (int, optional) – Sampling interval in seconds (must be a multiple of 5).

  • frcdig (int, optional) – Number of fractional digits in numeric values.

  • retry (int, optional) – Number of retries allowed.

  • callback (func or None, optional) – Callback function supporting data download progress monitoring.

Returns:

IotaWattData – Channel data and metadata.

class iotawatt_access.IotaWattData(begin, end, vchannels, ichannels, frcdig, cols=None, data=None, time=None)[source]

Bases: object

Dataset downloaded from IotaWatt device.

Variables:

  • begin (str) – Start date/time of channel data.

  • vchannels (list) – List of voltage channel names.

  • ichannels (list) – List of current/power channel names.

  • data (numpy array) – Array of channel data.

  • end (str) – End date/time of channel data.

  • frcdig (int) – Number of fractional digits in numeric values.

  • time (numpy array) – Array of sample times as Unix timestamps.

  • units (str) – Units for channel data.

Initialize IotaWattData object.

Parameters:

  • begin (str) – Start date/time of channel data.

  • end (str) – End date/time of channel data.

  • vchannels (list) – List of voltage channel names.

  • ichannels (list) – List of current/power channel names.

  • frcdig (int) – Number of fractional digits in numeric values.

  • cols (list or None, optional) – List of data column descriptions.

  • data (numpy array or None, optional) – Array of channel data.

  • time (numpy array or None, optional) – Array of sample times.

get_channel_data(name, units)[source]

Get data from channel name in units units.

Parameters:

  • name (str) – Channel name.

  • units (str) – Data units. Valid values are ‘volts’ and ‘hertz’ for voltage channels and ‘watts’, ‘amps’, ‘wh’, ‘va’, ‘var’, ‘varh’, ‘pf’ for current/power channels.

Returns:

numpy array – Channel data.

save(filename)[source]

Save data in numpy NPZ format.

Parameters:

filename (str) – Filename.

classmethod load(filename)[source]

Load data from numpy NPZ format file.

Parameters:

filename (str) – Filename.

Returns:

IotaWattData – Object data retrieved from file.