element

class element.ElementApi(api_location, api_key) → None[source]

Class to interact with the Element API. The instance should be, if possible, passed to functions so the internal cache can be utilized.

Parameters:

  • api_location (str) – The location where the Element API is hosted including the version e.g. https://dew21.element-iot.com/api/v1

  • api_key (str) – The API key as provided to you

property _address_to_id_mapping: dict[str, dict[str, int]]
_make_req(route, params={}, max_pages=None) → ApiReturn[T][source]
Return type:

ApiReturn[TypeVar(T)]

address_from_decentlab_id(decentlab_id, folder) → str[source]

Retrieve the address in the hexadecimal format e.g. DEC0054B0 from the decenlab id e.g. 21680.

The issue is, that the decentlab serial number/id is not part of the regular metadata in the IoT system. As far as we can see, you only get this when requesting actual data. Hence this may be really slow since in the worst case we have to go through all available stations. We try our best to cache this as part of the instance.

Parameters:

  • decentlab_id (int) – The decentlab serial nr/id in the format of e.g. 21680

  • folder (str) – The folder in the Element IoT system to query for this this can be e.g. 'stadt-dortmund-klimasensoren-inaktiv-sht35'

Return type:

str

decentlab_id_from_address(address, folder=None) → int[source]

Get the decentlab id in the format of e.g. 21680 from the hexadecimal device address e.g. DEC0054B0.

Parameters:

  • address (str) – the address of the device in a hexadecimal format as retrieved from the devices’s mac-address e.g. DEC0054B0

  • folder (str | None) – The folder in the Element IoT system to query for this this can be e.g. 'stadt-dortmund-klimasensoren-inaktiv-sht35' if not specified, searching the cache may be slower (default: None)

Return type:

int

get_device(address) → ApiReturn[Device][source]

Get information for a single device via the hexadecimal address.

Parameters:

address (str) – the address of the device in a hexadecimal format as retrieved from the devices’s mac-address e.g. DEC0054B0, If only the decentlab_id is present, this may be retrieved using address_from_decentlab_id().

Return type:

ApiReturn[Device]

get_device_addresses(folder) → list[str][source]

Get the hexadecimal addresses e.g. DEC0054B0 from all available devices in the folder(-slug)

Parameters:

folder (str) – The folder(-slug) to get the devices from

Return type:

list[str]

get_devices(folder) → ApiReturn[list[Device]][source]

Get all available devices in the current folder

Parameters:

folder (str) – The folder(-slug) to get the devices from

Return type:

ApiReturn[list[Device]]

get_folder_slugs() → list[str][source]

Get all available folder slugs. This can be: 'stadt-dortmund-klimasensoren-inaktiv-sht35'

Return type:

list[str]

get_folders() → ApiReturn[list[Folder]][source]

Get the folders from the API as the raw return values. If you just want the slugs (names), use get_folder_slugs().

Return type:

ApiReturn[list[Folder]]

get_packets(*, device_name=None, folder=None, packet_type=None, start=None, end=None, limit=100, stream=False, timeout=None, max_pages=None) → ApiReturn[list[Packet]][source]

Get the original packets from the API. This is returned as the raw API-return-value. The sorting is fixed to transceived_at.

Parameters:

  • device_name (str | None) – The name of the device as the hexadecimal address e.g. DEC0054B0. If only the decentlab_id is present, this may be retrieved using address_from_decentlab_id(). This is mutually exclusive with folder (default: None)

  • folder (str | None) – The folder in the Element IoT system to query for this this can be e.g. 'stadt-dortmund-klimasensoren-inaktiv-sht35'. This is mutually exclusive with device_name (default: None)

  • packet_type (Literal['up', 'down'] | None) – Filter for packet_types (either up or down) if None all package types are returned (default: None)

  • start (datetime | None) – The datetime to start getting readings for. If None, all available readings will be retrieved. (default: None)

  • end (datetime | None) – The datetime to stop getting readings for. If None, all available readings will be retrieved. (default: None)

  • limit (int) – How many values to fetch per API request (must be between 1 and 100). (default: 100)

  • stream (bool) – Whether to stream the data or not. This is useful for very large datasets. limit is ignored when streaming, use start and end to limit the data. (default: False)

  • timeout (int | None) – The timeout for the request in milliseconds. The server will close the connection after this time. This sometimes needs to be increased for very large datasets. It must be at least 250 ms and at most 180000 ms. (default: None)

  • max_pages (int | None) – After how many pages of pagination we stop, to avoid infinitely requesting data from the API. (default: None)

Return type:

ApiReturn[list[Packet]]

get_readings(device_name, *, sort='measured_at', sort_direction='asc', start=None, end=None, limit=100, max_pages=None, stream=False, timeout=None, as_dataframe=False) → ApiReturn[list[Reading]] | DataFrame[source]

Get acutal readings from the API. This may be returned as the raw API-return-value or already converted to a pandas.DataFrame.

Parameters:

  • device_name (str) – The name of the device as the hexadecimal address e.g. DEC0054B0. If only the decentlab_id is present, this may be retrieved using address_from_decentlab_id().

  • sort (Literal['measured_at', 'inserted_at']) – How the values should be sorted, currently this can only be measured_at or inserted_at. (default: 'measured_at')

  • sort_direction (Literal['asc', 'desc']) – The direction the sorting should be applied. Either asc for ascending or desc for descending. (default: 'asc')

  • start (datetime | None) – The datetime to start getting readings for. If None, all available readings will be retrieved. (default: None)

  • end (datetime | None) – The datetime to stop getting readings for. If None, all available readings will be retrieved. (default: None)

  • limit (int) – How many values to fetch per API request (must be between 1 and 100). (default: 100)

  • max_pages (int | None) – After how many pages of pagination we stop, to avoid infinitely requesting data from the API. (default: None)

  • stream (bool) – Whether to stream the data or not. This is useful for very large datasets. limit is ignored when streaming, use start and end to limit the data. (default: False)

  • timeout (int | None) – The timeout for the request in milliseconds. The server will close the connection after this time. This sometimes needs to be increased for very large datasets. (default: None)

  • as_dataframe (bool) – Determines whether this function returns a pandas.DataFrame or the raw API return (which is the default) (default: False)

Return type:

ApiReturn[list[Reading]] | DataFrame

element.decode_ATM41(msg, hex=False, protocol_version=2) → ATM41Measurement[source]

Decode the message returned from the Meter ATM41 weather station (ATM41) sensor.

Parameters:

  • msg (bytes) – byte-string returned e.g. b'02530400038283800080008000803488CD8076815C80CBA708816D817D80197FF680007FDB7FDB0AAE'

  • hex (bool) – whether or not the provided message is in hexadecimals (default: False)

  • protocol_version (int) – The expected version of the protocol. If the protocol_version in the msg does not match this version, an exception will be raised (default: 2)

Return type:

ATM41Measurement

element.decode_BLG(msg, hex=False, protocol_version=2) → BLGMeasurement[source]

Decode the message returned from the blackglobe sensor (BLG).

Parameters:

  • msg (bytes) – byte-string returned e.g. b'0254970003498800830BF7'

  • hex (bool) – whether or not the provided message is in hexadecimals (default: False)

  • protocol_version (int) – The expected version of the protocol. If the protocol_version in the msg does not match this version, an exception will be raised (default: 2)

Return type:

BLGMeasurement

element.decode_STH35(msg, hex=False, protocol_version=2) → SHT35Measurement[source]

Decode the message returned from the temperature and relative humidity sensor (SHT35).

Parameters:

  • msg (bytes) – byte-string returned e.g. b'0254A60003783F596E0C17'

  • hex (bool) – whether or not the provided message is in hexadecimals (default: False)

  • protocol_version (int) – The expected version of the protocol. If the protocol_version in the msg does not match this version, an exception will be raised (default: 2)

Return type:

SHT35Measurement