device package

Submodules

device.crypto module

device.crypto.certificate_is_valid(device_id: str, realm: str, credentials_secret: str, pairing_base_url: str, ignore_ssl_errors: bool, crypto_store_dir: str) → bool

Utility function that checks the certificate validity

Parameters:

  • device_id (str) – The device ID

  • realm (str) – The Astarte realm where the device is registered

  • pairing_base_url (str) – The base URL for the Astarte pairing APIs

  • credentials_secret (str) – The credentials secret for the device in the given realm

  • ignore_ssl_errors (str) – Set to True to ignore SSL errors

  • crypto_store_dir (str) – Path to the folder where crypto information are stored

Returns:

True if the certificate is valid, False otherwise.

Return type:

bool

device.crypto.device_has_certificate(device_id: str, realm: str, credentials_secret: str, pairing_base_url: str, ignore_ssl_errors: bool, crypto_store_dir: str) → bool

Utility function that checks if a certificate is present for the device

Parameters:

  • device_id (str) – The device ID

  • realm (str) – The Astarte realm where the device is registered

  • pairing_base_url (str) – The base URL for the Astarte pairing APIs

  • credentials_secret (str) – The credentials secret for the device in the given realm

  • ignore_ssl_errors (str) – Set to True to ignore SSL errors

  • crypto_store_dir (str) – Path to the folder where crypto information is stored

Returns:

True if the certificate is present, False otherwise

Return type:

bool

device.crypto.generate_csr(realm: str, device_id: str, crypto_store_dir: str) → bytes

Utility function that generate the csr for the device

Parameters:

  • realm (str) – The Astarte realm where the device will be registered

  • device_id (str) – The device ID

  • crypto_store_dir (str) – Path to the folder where crypto information is stored

Returns:

The device certificate signing request file

Return type:

bytes

device.crypto.import_device_certificate(client_crt: str, crypto_store_dir: str) → None

Deserialize a client certificate and store the public information permanently in the file system

Parameters:

  • client_crt (str) – Serialized client certificate

  • crypto_store_dir (str) – Directory where to store the public bytes of the certificate

device.database module

API for an SQLite database to be used for Astarte properties persistency.

class device.database.AstarteDatabase

Bases: ABC

Abstract class for a database that can be used to provide persistency to the properties.

abstract clear() → None

Fully clear the database of all the properties.

abstract delete_prop(interface: str, path: str) → None

Delete a property from the database.

Parameters:

  • interface (str) – The interface name.

  • path (str) – The path to the property endpoint.

abstract delete_props_from_interface(interface: str) → None

Delete all the properties from the database belonging to an interface.

Parameters:

interface (str) – The interface name.

abstract load_all_props() → list[tuple[str, int, str, object]]

Load all the properties stored in the database.

Returns:

A list containing all the propeties stored in the database. Each element of the list is a tuple in the format: (interface, interface major version, path, value)

Return type:

list[tuple[str, int, str, object]]

abstract load_prop(interface: str, major: int, path: str) → object | None

Load a property from the database. If a property is found but the major version does not match, the property in the database will be deleted and None will be returned.

Parameters:

  • interface (str) – The interface name.

  • major (int) – The major version for the interface.

  • path (str) – The path to the property endpoint.

Returns:

The property value if the property is present and the provided interface major version matches the interface version stored in the database. None otherwise.

Return type:

object | None

abstract store_prop(interface: str, major: int, path: str, value: object) → None

Store a property value in the database. It will overwrite the previous value where present.

Parameters:

  • interface (str) – The interface name.

  • major (int) – The major version for the interface.

  • path (str) – The path to the property endpoint.

  • value (object) – The new value for the property.

class device.database.AstarteDatabaseSQLite(database_path: Path)

Bases: AstarteDatabase

An implementation for the abstract AstarteDatabase class. This implementation uses the standard SQLite library of Python to implement property persistency.

clear() → None

Fully clear the database of all the properties.

delete_prop(interface: str, path: str) → None

Delete a property from the database.

Parameters:

  • interface (str) – See documentation in AstarteDatabase.

  • path (str) – See documentation in AstarteDatabase.

delete_props_from_interface(interface: str) → None

Delete all the properties from the database belonging to an interface.

Parameters:

interface (str) – See documentation in AstarteDatabase.

load_all_props() → list[tuple[str, int, str, object]]

Load all the properties stored in the database.

Returns:

See documentation in AstarteDatabase.

Return type:

list[tuple[str, int, str, object]]

load_prop(interface: str, major: int, path: str) → object | None

Load a property from the database. If a property is found but the major version does not match, the property in the database will be deleted and None will be returned.

Parameters:

  • interface (str) – See documentation in AstarteDatabase.

  • major (int) – See documentation in AstarteDatabase.

  • path (str) – See documentation in AstarteDatabase.

Returns:

See documentation in AstarteDatabase.

Return type:

object | None

store_prop(interface: str, major: int, path: str, value: object | None) → None

Store a property value in the database. It will overwrite the previous value where present.

Parameters:

  • interface (str) – See documentation in AstarteDatabase.

  • major (int) – See documentation in AstarteDatabase.

  • path (str) – See documentation in AstarteDatabase.

  • value (object) – See documentation in AstarteDatabase.

device.device module

class device.device.ConnectionState(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Possible connection states for a device.

CONNECTED = 2
CONNECTING = 1
DISCONNECTED = 3
class device.device.Device

Bases: ABC

Abstract class defining the minumum APIs for an Astarte device implementation.

This class is agnostic of a transport layer. It should be used to implement transport specific children classes.

add_interface_from_file(interface_file: Path)

Adds an interface to the device, from a json file.

It has to be called before connect(), as it will be used for building the device introspection.

Parameters:

interface_file (Path) – An absolute path to an Astarte interface json file.

Raises:
abstract add_interface_from_json(interface_json: dict)

Adds an interface to the device.

Parameters:

interface_json (dict) – Description of the interface obtained through json.loads() or similar methods.

add_interfaces_from_dir(interfaces_dir: Path)

Adds a series of interfaces to the device, from a directory containing json files.

It has to be called before connect(), as it will be used for building the device introspection.

Parameters:

interfaces_dir (Path) – An absolute path to an a folder containing some Astarte interface json files.

Raises:

InterfaceFileNotFoundError – If specified directory does not exists.

abstract connect() → None

Connects the device to Astarte.

disable_receive_validation()

Disable validation for the message reception.

N.B. This is a temporary workaround specifically designed to bypass bugs in Astarte core.

It should not be used carelessly.

See: https://github.com/astarte-platform/astarte-device-sdk-python/issues/136

abstract disconnect() → None

Disconnects the device from Astarte.

abstract is_connected() → bool

Returns whether the device is currently connected.

Returns:

The device connection status.

Return type:

bool

abstract remove_interface(interface_name: str) → None

Removes an Interface from the device.

Parameters:

interface_name (str) – The name of an Interface previously added with one of the add_interface(s)_from_* functions.

send(interface_name: str, interface_path: str, payload: object, timestamp: datetime | None = None) → None

Sends an individual message to an interface.

Parameters:

  • interface_name (str) – The name of an the Interface to send data to.

  • interface_path (str) – The path on the Interface to send data to.

  • payload (object) – The value to be sent. The type should be compatible to the one specified in the interface path.

  • timestamp (datetime, optional) – If sending a Datastream with explicit_timestamp, you can specify a datetime object which will be registered as the timestamp for the value.

Raises:
send_aggregate(interface_name: str, interface_path: str, payload: Mapping, timestamp: datetime | None = None) → None

Sends an aggregate message to an interface.

Parameters:

  • interface_name (str) – The name of the Interface to send data to.

  • interface_path (str) – The endpoint to send the data to

  • payload (dict) – A dictionary containing the path:value map for the aggregate.

  • timestamp (datetime, optional) – If the Datastream has explicit_timestamp, you can specify a datetime object which will be registered as the timestamp for the value.

Raises:
set_events_callbacks(on_connected: Callable[[Device], None] | None = None, on_data_received: Callable[[Device, str, str, object], None] | None = None, on_disconnected: Callable[[Device, int], None] | None = None, loop: AbstractEventLoop | None = None) → None

Can be used to set various callbacks to user provided functions.

note:: All parameters default to None. Meaning that all unspeficied callbacks will be disabled. Same for the event loop.

Parameters:

  • on_connected (Callable[[Device], None] | None) – A function that will be invoked everytime the device is connected.

  • on_data_received (Callable[[Device, string, string, object], None] | None) – A function that will be invoked everytime data is received from Astarte. Parameters are the device itself, the Interface name, the Interface path, and the payload. The payload will reflect the type defined in the Interface.

  • on_disconnected (Callable[[Device], None] | None) – A function that will be invoked everytime the device experiences a disconnection event. The int parameter bears the disconnect reason. With 0 being a graceful disconnection.

  • loop (asyncio.AbstractEventLoop | None) – An optional loop which will be used for invoking the callbacks. When this is not None, the device will call any specified callback through loop.call_soon_threadsafe, ensuring that the callbacks will be run in thread the loop belongs to. Usually, you want to set this to get_running_loop(). When not sent, callbacks will be invoked as a standard function - keep in mind this means your callbacks might create deadlocks.

unset_property(interface_name: str, interface_path: str) → None

Unset the specified property on an interface.

Parameters:

  • interface_name (str) – The name of the Interface where the property to unset is located.

  • interface_path (str) – The path on the Interface to unset.

Raises:

device.device_grpc module

class device.device_grpc.AstarteClientCallDetails(method, timeout, metadata, credentials, wait_for_ready, compression)

Bases: AstarteClientCallDetails, ClientCallDetails

Astarte implementation for gRPC client call details.

class device.device_grpc.AstarteUnaryStreamInterceptor(node_id)

Bases: UnaryStreamClientInterceptor

Astarte implementation for a gRPC unary-stream client interceptor.

intercept_unary_stream(continuation, client_call_details, request)

Implementation for the abstract interceptor method.

Parameters:

  • continuation (Any) – See parent class.

  • client_call_details (Any) – See parent class.

  • request (Any) – See parent class.

Returns:

See the parent class.

Return type:

Any

class device.device_grpc.AstarteUnaryUnaryInterceptor(node_id)

Bases: UnaryUnaryClientInterceptor

Astarte implementation for a gRPC unary-unary client interceptor.

intercept_unary_unary(continuation, client_call_details, request)

Implementation for the abstract interceptor method.

Parameters:

  • continuation (Any) – See parent class.

  • client_call_details (Any) – See parent class.

  • request (Any) – See parent class.

Returns:

See the parent class.

Return type:

Any

class device.device_grpc.DeviceGrpc(server_addr: str, node_uuid: str)

Bases: Device

Astarte device implementation using the GRPC transport protocol.

Threading and Concurrency

This SDK uses GRPC under the hood as a transport layer. As such, it is bound by GRPC’s behavior in terms of threading. When a device connects, a new thread is spawned and an event loop is run there to manage all the connection events.

This SDK spares the user from this detail - on the other hand, when configuring callbacks, threading has to be taken into account. When configuring the callback functions, it is possible to specify an asyncio.loop() to automatically manage this detail. When a loop is specified, all callbacks will be called in the context of that loop, guaranteeing thread-safety and making sure that the user does not have to take any further action beyond consuming the callback.

When a loop is not specified, callbacks are invoked just as standard Python functions. This inevitably means that the user will have to take into account the fact that the callback will be invoked in the thread of the GRPC connection. In particular, blocking the execution of that thread might cause deadlocks and, in general, malfunctions in the SDK. For this reason, the usage of asyncio is strongly recommended.

add_interface_from_json(interface_json: dict)

See parent class.

Parameters:

interface_json (dict) – See parent class.

Raises:

DeviceConnectingError – When attempting to add an interface while the device if performing a connection.

connect() → None

Connect the device in synchronous mode.

disconnect() → None

Disconnects the node, detaching it from the message hub.

This method won’t have any effect if the device is not already connected.

is_connected() → bool

Returns whether the device is currently connected.

Returns:

The device connection status.

Return type:

bool

remove_interface(interface_name: str) → None

See parent class.

Parameters:

interface_name (str) – See parent class.

Raises:

DeviceConnectingError – When attempting to add an interface while the device if performing a connection.

device.device_grpc.add_node_id_in_metadata(node_id: str, client_call_details: grpc._interceptor._ClientCallDetails)

Add an Astarte message hub ID to che grpc client call details as a metadata fields.

Note: This function doesn’t perform in place changes to client_call_details. It returns a totally new set of client call details.

Parameters:

  • node_id (str) – The node ID to add.

  • client_call_details (Any) – The client call details to modify.

Returns:

The new client call details.

Return type:

grpc._interceptor._ClientCallDetails

device.device_mqtt module

class device.device_mqtt.DeviceMqtt(device_id: str, realm: str, credentials_secret: str, pairing_base_url: str, persistency_dir: str, database: AstarteDatabase | None = None, ignore_ssl_errors: bool = False)

Bases: Device

Astarte device implementation using the MQTT transport protocol.

Threading and Concurrency

This SDK uses paho-mqtt under the hood as a transport layer. As such, it is bound by paho-mqtt’s behavior in terms of threading. When a device connects, a new thread is spawned and an event loop is run there to manage all the connection events.

This SDK spares the user from this detail - on the other hand, when configuring callbacks, threading has to be taken into account. When configuring the callback functions, it is possible to specify an asyncio.loop() to automatically manage this detail. When a loop is specified, all callbacks will be called in the context of that loop, guaranteeing thread-safety and making sure that the user does not have to take any further action beyond consuming the callback.

When a loop is not specified, callbacks are invoked just as standard Python functions. This inevitably means that the user will have to take into account the fact that the callback will be invoked in the thread of the MQTT connection. In particular, blocking the execution of that thread might cause deadlocks and, in general, malfunctions in the SDK. For this reason, the usage of asyncio is strongly recommended.

add_interface_from_json(interface_json: dict)

See parent class.

Parameters:

interface_json (dict) – See parent class.

Raises:

DeviceConnectingError – When attempting to add an interface while the device if performing a connection.

connect() → None

Connects the device asynchronously.

When calling connect, a new connection thread is spawned and the device will start a connection routine. The function might return before the device connects: you want to use the on_connected callback to ensure you are notified upon connection.

In case the device gets disconnected unexpectedly, it will try to reconnect indefinitely until disconnect() is called.

Raises:

APIError – When the obtained broker URL is invalid.

disconnect() → None

Disconnects the device.

When calling disconnect, the connection thread is requested to terminate the connection, and the thread is stopped when the disconnection happens. This function won’t return before the device has been disconnected. Calling this function should result in the callback on_disconnected being called with return code parameter 0, meaning the disconnection happened following an explicit disconnection request.

get_device_id() → str

Returns the device ID of the device.

Returns:

The ID of the device

Return type:

str

is_connected() → bool

Returns whether the device is currently connected.

Returns:

The device connection status.

Return type:

bool

remove_interface(interface_name: str) → None

See parent class.

Parameters:

interface_name (str) – See parent class.

Raises:

device.exceptions module

exception device.exceptions.APIError(body)

Bases: AstarteError

Exception raised when Astarte APIs throw unhandled errors.

body -- the body of the API reply, which may carry further details
exception device.exceptions.AstarteError

Bases: Exception

Base class for Astarte Errors.

exception device.exceptions.AuthorizationError(body)

Bases: AstarteError

Exception raised when Astarte APIs refuse authentication.

body -- the body of the API reply, which may carry further details
exception device.exceptions.DeviceAlreadyRegisteredError

Bases: AstarteError

Exception raised in case a device being registered has already been registered.

exception device.exceptions.DeviceConnectingError(msg)

Bases: AstarteError

Exception raised when an operation is attempted while the device MQTT client has been started but is not yet connected.

msg -- A message error carrying further details
exception device.exceptions.DeviceDisconnectedError(msg)

Bases: AstarteError

Exception raised if attempting a send while the device is disconnected from Astarte.

msg -- A message error carrying further details
exception device.exceptions.InterfaceFileDecodeError(msg)

Bases: AstarteError

Exception raised when an interface .json file is not correctly formatted.

msg -- A message error carrying further details
exception device.exceptions.InterfaceFileNotFoundError(msg)

Bases: AstarteError

Exception raised when a file containing an interface definition does not exists.

msg -- A message error carrying further details
exception device.exceptions.InterfaceNotFoundError(msg)

Bases: AstarteError

Exception raised when an interface is not found in the device introspection.

msg -- A message error carrying further details
exception device.exceptions.JWTGenerationError(msg)

Bases: AstarteError

Exception raised when the generation of a Jason Web Token has failed.

msg -- A message error carrying further details
exception device.exceptions.PersistencyDirectoryNotFoundError(body)

Bases: AstarteError

Exception raised when the provided persistency directory is not found.

body -- the body of the API reply, which may carry further details
exception device.exceptions.ValidationError(msg)

Bases: AstarteError

Exception raised when validation has failed.

msg -- A message error carrying further details

device.interface module

class device.interface.Interface(interface_definition: dict)

Bases: object

Class that represent an Interface definition

Interfaces are a core concept of Astarte which defines how data is exchanged between Astarte and its peers. They are not to be intended as OOP interfaces, but rather as the following definition:

In Astarte each interface has an owner, can represent either a continuous data stream or a snapshot of a set of properties, and can be either aggregated into an object or be an independent set of individual members.

name

Interface name

Type:

str

version_major

Interface version major number

Type:

int

version_minor

Interface version minor number

Type:

int

type

Interface type

Type:

str

ownership

Interface ownership

Type:

str

aggregation

Interface aggregation policy

Type:

str

mappings

Interface mapping dictionary, keys are the endpoint of each mapping

Type:

dict(Mapping)

get_mapping(endpoint) → Mapping | None

Retrieve the Mapping with the given endpoint from the Interface :param endpoint: The Mapping endpoint :type endpoint: str

Returns:

The Mapping if found, None otherwise

Return type:

Mapping or None

get_reliability(endpoint: str) → int

Get the reliability for the mapping corresponding to the provided endpoint.

Parameters:

endpoint (str) – The Mapping endpoint to deduce reliability from.

Returns:

The deduced reliability, one of [0,1,2].

Return type:

int

Raises:

InterfaceNotFoundError – If the interface is not declared in the introspection.

is_aggregation_object() → bool

Check if the current Interface is a datastream with aggregation object :returns: True if aggregation: object :rtype: bool

is_property_endpoint_resettable(endpoint)

Check the resettability of an endpoint. :param endpoint: The Mapping endpoint :type endpoint: str

Returns:

True if type is properties, endpoint is valid and resettable

Return type:

bool

is_server_owned() → bool

Check the Interface ownership :returns: True if ownership: server :rtype: bool

is_type_properties()

Check the Interface type :returns: True if type: properties :rtype: bool

validate_path(path: str, payload)

Validate that the provided path conforms to the interface.

Parameters:

  • path (str) – Path to validate. In case of an individual interface it should correspond to the full endpoint, while in case of aggregated interfaces it should correspond to the common part to all the endpoints.

  • payload (object) – Payload used to extrapolate the remaining endpoints for aggregated interfaces.

Raises:

ValidationError – When validation has failed.

validate_payload(path: str, payload)

Validate that the payload conforms to the interface definition.

Parameters:

  • path (str) – Path on which the payload has been received. This is assumed to correspond to a valid mapping (or partial mapping in case of aggregate interface). Should be first checked with validate_path().

  • payload (object) – Data to validate

Raises:

ValidationError – When validation has failed.

validate_payload_and_timestamp(path: str, payload, timestamp: datetime | None)

Validate that path, payload and timestamp conform to the interface definition.

Parameters:

  • path (str) – Data endpoint in interface

  • payload (object) – Data to validate

  • timestamp (datetime or None) – Timestamp associated to the payload

Raises:

ValidationError – When validation has failed.

device.introspection module

class device.introspection.Introspection

Bases: object

Class that represent the introspection of a device.

The introspection is the list od interfaces that the device declares to the server it is compatible with.

In any given time a device can have a single interface with a given name, multiple interfaces with the same name but different major/minor are not supported.

add_interface(interface: Interface) → None

Adds an interface to the introspection

This will add an interface to the device.

Parameters:

interface (Interface) – An Astarte interface object. Usually obtained by using json.loads() on an interface file and then using the loaded json to initialize the interface object.

get_all_interfaces() → list[Interface]

Retrieve all the list of all Interfaces in device’s Introspection

Returns:

The list of all Interfaces in the Introspection

Return type:

list

get_all_server_owned_interfaces() → list[Interface]

Retrieve all the list of all Interfaces in device’s Introspection with server ownership

Returns:

The list of all Interfaces in the Introspection that have ownership “server”

Return type:

list

get_interface(interface_name: str) → Interface | None

Retrieve an Interface definition from the Introspection

Parameters:

interface_name (str) – The name of an Interface previously added with add_interface().

Returns:

the Interface definition if found in the Introspection, None otherwise

Return type:

Interface or None

remove_interface(interface_name: str) → None

Removes an Interface from the Introspection

Removes an Interface definition from the device. It has to be called before connect(), as it will be used for building the device Introspection.

Parameters:

interface_name (str) – The name of an Interface previously added with add_interface().

device.mapping module

class device.mapping.AstarteTypesLookupElement(type, subtype)

Bases: tuple

subtype

Alias for field number 1

type

Alias for field number 0

device.mapping.MapType

Lookup table for mapping Astarte type to Python type

alias of int | float | str | bytes | bool | datetime | List[int] | List[float] | List[str] | List[bytes] | List[bool] | List[datetime]

class device.mapping.Mapping(mapping_definition: dict, is_datastream: bool)

Bases: object

Class that represent a data Mapping Mappings are designed around REST controller semantics: each mapping describes an endpoint which is resolved to a path, it is strongly typed, and can have additional options. Just like in REST controllers, Endpoints can be parametrized to build REST-like collection and trees. Parameters are identified by %{parameterName}, with each endpoint supporting any number of parameters (see Limitations).

endpoint

Path of the Mapping

Type:

str

type

Type of the Mapping (see notes)

Type:

str

explicit_timestamp

Flag that defines if the Mapping requires a timestamp associated to the Payload before send.

Type:

bool

reliability

Reliability level of the Mapping (see notes)

allow_unset

Allow unsetting for properties

Notes

Supported data types

The following types are supported:

  • double: A double-precision floating-point number as specified by binary64, by the IEEE

    754 standard (NaNs and other non-numerical values are not supported).

  • integer: A signed 32 bit integer.

  • boolean: Either true or false, adhering to JSON boolean type.

  • longinteger: A signed 64-bit integer (please note that longinteger is represented as a

    string by default in JSON-based APIs.).

  • string: An UTF-8 string, at most 65536 bytes long.

  • binaryblob: An arbitrary sequence of any byte that should be shorter than 64 KiB. (

    binaryblob is represented as a base64 string by default in JSON-based APIs.).

  • datetime: A UTC timestamp, internally represented as milliseconds since 1st Jan 1970

    using a signed 64 bits integer. (datetime is represented as an ISO 8601 string by default in JSON based APIs.)

  • doublearray, integerarray, booleanarray, longintegerarray, stringarray,

    binaryblobarray, datetimearray: A list of values, represented as a JSON Array. Arrays can have up to 1024 items and each item must respect the limits of its scalar type (i.e. each string in a stringarray must be at most 65535 bytes long, each binary blob in a binaryblobarray must be shorter than 64 KiB.)

Quality of Service

Data messages QoS is chosen according to mapping settings, such as reliability. Properties are always published using QoS 2.

INTERFACE TYPE

RELIABILITY

QOS

properties

always unique

2

datastream

unreliable

0

datastream

guaranteed

1

datastream

unique

2
validate_path(path: str)

Validate an endpoint against the endpoints declared in the mapping.

Parameters:

path (Str) – Path to validate.

Raises:

ValidationError – When validation has failed.

validate_payload(payload: int | float | str | bytes | bool | datetime | List[int] | List[float] | List[str] | List[bytes] | List[bool] | List[datetime])

Mapping data validation

Parameters:

payload (MapType) – Data to validate

Raises:

ValidationError – When validation has failed.

validate_timestamp(timestamp: datetime | None)

Mapping timestamp validation

Parameters:

timestamp (datetime or None) – Timestamp associated to the payload

Raises:

ValidationError – When validation has failed.

device.pairing_handler module

device.pairing_handler.generate_device_id(namespace: UUID, unique_data: str) → str

Deterministically generate a device Id based on UUID namespace identifier and unique data.

Parameters:

  • namespace (UUID) – UUID namespace of the device_id

  • unique_data (str) – device unique data used to generate the device_id

Returns:

the generated device Id, using the standard Astarte device ID encoding (base64 urlencoding without padding).

Return type:

str

device.pairing_handler.generate_random_device_id() → str

Quick way to generate a device Id. Pay attention that each time this value is different and the use in production is discouraged.

Returns:

the generated device Id, using the standard Astarte device ID encoding (base64 urlencoding without padding).

Return type:

str

device.pairing_handler.obtain_device_certificate(device_id: str, realm: str, credentials_secret: str, pairing_base_url: str, crypto_store_dir: str, ignore_ssl_errors: bool) → None

Utility function that gets a device certificate from Astarte based on a locally generated csr

Parameters:

  • device_id (str) – The device ID

  • realm (str) – The Astarte realm where the device is registered

  • credentials_secret (str) – The credentials secret for the device in the given realm

  • pairing_base_url (str) – The base URL for the Astarte pairing APIs

  • crypto_store_dir (str) – Path to the folder where crypto information are stored

  • ignore_ssl_errors (str) – Set to True to ignore SSL errors

Raises:
device.pairing_handler.obtain_device_transport_information(device_id: str, realm: str, credentials_secret: str, pairing_base_url: str, ignore_ssl_errors: bool) → dict

Utility function that requests the device transport information to Astarte

Parameters:

  • device_id (str) – The device ID

  • realm (str) – The Astarte realm where the device is registered

  • credentials_secret (str) – The credentials secret for the device in the given realm

  • pairing_base_url (str) – The base URL for the Astarte pairing APIs

  • ignore_ssl_errors (str) – Set to True to ignore SSL errors

Returns:

The device transport information

Return type:

dict

Raises:
device.pairing_handler.register_device_with_jwt_token(device_id: str, realm: str, jwt_token: str, pairing_base_url: str, ignore_ssl_errors: bool = False) → str

Registers a device against an Astarte instance/realm with a JWT Token

Returns the Credentials secret for the device

Parameters:

  • device_id (str) – The device ID to register.

  • realm (str) – The Realm in which to register the device.

  • jwt_token (str) – A JWT Token to Authenticate against Pairing API. The token must have access to Pairing API and to the agent API paths.

  • pairing_base_url (str) – The Base URL of Pairing API of the Astarte Instance the device will be registered in.

  • ignore_ssl_errors (bool) – Useful if you’re registering a device into a test instance of Astarte with self-signed certificates. It is not recommended to leave this true in production. Defaults to false, if true SSL errors will be ignored when registering a device.

Returns:

The credentials secret obtained after the registration

Return type:

str

device.pairing_handler.register_device_with_private_key(device_id: str, realm: str, private_key_file: str, pairing_base_url: str, ignore_ssl_errors: bool) → str

Registers a device against an Astarte instance/realm with a Private Key

Returns the Credentials secret for the device

Parameters:

  • device_id (str) – The device ID to register.

  • realm (str) – The Realm in which to register the device.

  • private_key_file (str) – Path to the Private Key file for the Realm. It will be used to Authenticate against Pairing API.

  • pairing_base_url (str) – The Base URL of Pairing API of the Astarte Instance the device will be registered in.

  • ignore_ssl_errors (str) – Set to True to ignore SSL errors

Returns:

The credentials secret obtained after the registration

Return type:

str

device.pairing_handler.verify_device_certificate(device_id: str, realm: str, credentials_secret: str, pairing_base_url: str, ignore_ssl_errors: bool, cert_pem: str) → bool

Utility function that verifies the validity of a device certificate with Astarte

Parameters:

  • device_id (str) – The device ID

  • realm (str) – The Astarte realm where the device is registered

  • pairing_base_url (str) – The base URL for the Astarte pairing APIs

  • credentials_secret (str) – The credentials secret for the device in the given realm

  • ignore_ssl_errors (str) – Set to True to ignore SSL errors

  • cert_pem (str) – Certificate to verify in the PEM format

Raises:
Returns:

True if the certificate is valid, False otherwise.

Return type:

bool

Module contents