Astarte.Device (astarte_device v1.1.1)

A process that manages a device connection to Astarte. See Astarte.Device.start_link/1 for the options.

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor. See Supervisor in Elixir v1.6+.

Returns the pid of the Astarte.Device process for the given realm/device_id pair, or nil if there's no existing device for that pair.

Send a property value to Astarte.

Unset a property value to Astarte.

Blocks until the device succesfully connects to the broker, then returns :ok.

Link to this section Types

Link to this type

device_option()

Specs

device_option() ::
  {:pairing_url, String.t()}
  | {:realm, String.t()}
  | {:device_id, String.t()}
  | {:credentials_secret, String.t()}
  | {:credential_storage, {module(), term()}}
  | {:interface_provider, {module(), term()} | String.t()}
  | {:handler, {module(), term()}}
  | {:ignore_ssl_errors, boolean()}
Link to this type

device_options()

Specs

device_options() :: [device_option()]

Link to this section Functions

Link to this function

child_spec(arg)

Returns a specification to start this module under a supervisor. See Supervisor in Elixir v1.6+.

Link to this function

connected(arg1, arg2, data)

Link to this function

connecting(arg1, arg2, data)

Link to this function

disconnected(arg1, arg2, data)

Link to this function

get_pid(realm, device_id)

Specs

get_pid(
  realm :: String.t(),
  device_id :: Astarte.Core.Device.encoded_device_id()
) :: pid() | nil

Returns the pid of the Astarte.Device process for the given realm/device_id pair, or nil if there's no existing device for that pair.

Devices are registered to Astarte.Device.Registry with key {realm, device_id} when they are started.

Link to this function

no_certificate(arg1, arg2, data)

Link to this function

no_keypair(arg1, arg2, data)

Link to this function

send_datastream(pid, interface_name, path, value, opts \\ [])

Specs

send_datastream(
  pid :: pid(),
  interface_name :: String.t(),
  path :: String.t(),
  value :: term(),
  opts :: options
) :: :ok | {:error, reason :: term()}
when options: [option],
     option:
       {:qos, qos :: Tortoise.qos()} | {:timestamp, timestamp :: DateTime.t()}

Send a datastream value to Astarte.

This call is blocking and waits for the message to be ACKed at the MQTT level.

Link to this function

set_property(pid, interface_name, path, value)

Specs

set_property(
  pid :: pid(),
  interface_name :: String.t(),
  path :: String.t(),
  value :: term()
) :: :ok | {:error, reason :: term()}

Send a property value to Astarte.

This call is blocking and waits for the message to be ACKed at the MQTT level.

Link to this function

start_link(device_options)

Specs

start_link(opts :: device_options()) :: :gen_statem.start_ret()

Start an Astarte.Device.

Device Options

  • pairing_url - base URL of the Astarte Pairing API instance the device will connect to, e.g. https://astarte.api.example.com/pairing or http://localhost:4003 for a local installation.
  • realm - Realm which the device belongs to.
  • device_id - Device ID of the device. The device ID must be 128-bit long and must be encoded with url-safe base64 without padding. You can generate a random one with :crypto.strong_rand_bytes(16) |> Base.url_encode64(padding: false).
  • credentials_secret - The credentials secret obtained when registering the device using Pairing API (to register a device use Astarte.API.Pairing.Agent.register_device/2 or see https://docs.astarte-platform.org/latest/api/index.html?urls.primaryName=Pairing API#/agent/registerDevice).
  • interface_provider - A tuple {module, args} where module is a module implementing Astarte.Device.InterfaceProvider behaviour and args are the arguments passed to its init function. It's also possible to pass a path containing the JSON interfaces the device will use, and that path will be passed to Astarte.Device.FilesystemInterfaceProvider.
  • credential_storage (optional) - A tuple {module, args} where module is a module implementing Astarte.Device.CredentialStorage behaviour and args are the arguments passed to its init function. If not provided, Astarte.Device.InMemoryStorage will be used.
  • handler (optional) - A tuple {module, args} where module is a module implementing Astarte.Device.Handler behaviour and args are the arguments passed to its init_state function. If not provided, Astarte.Device.DefaultHandler will be used.
  • ignore_ssl_errors (optional) - Defaults to false, if true the device will ignore SSL errors during connection. Useful if you're using the Device to connect to a test instance of Astarte with self signed certificates, it is not recommended to leave this true in production.
  • max_http_redirects (optional) - The maximum number of HTTP redirects that will be followed by the Pairing HTTP client. Defaults to 5.
Link to this function

unset_property(pid, interface_name, path)

Specs

unset_property(
  pid :: pid(),
  interface_name :: String.t(),
  path :: String.t()
) :: :ok | {:error, reason :: term()}

Unset a property value to Astarte.

This call is blocking and waits for the message to be ACKed at the MQTT level.

Link to this function

wait_for_connection(pid)

Specs

wait_for_connection(pid :: pid()) :: :ok

Blocks until the device succesfully connects to the broker, then returns :ok.

Useful to ensure the device has established the initial connection before beginning to publish.

Link to this function

waiting_for_info(arg1, arg2, data)