Jido.Sensors.Heartbeat (Jido v1.1.0-rc)

View Source

A sensor that emits heartbeat signals at configurable intervals.

Summary

Functions

Returns the configured category of the sensor.

Returns a specification to start this module under a supervisor.

Returns the configured description of the sensor.

Retrieves the complete configuration of a sensor.

Retrieves a specific configuration value from a sensor.

Returns the configured name of the sensor.

Returns the configured schema for the sensor.

Updates multiple configuration values for a sensor.

Updates a single configuration value for a sensor.

Starts a new Sensor process.

Returns the configured tags for the sensor.

Converts the sensor metadata to a JSON-compatible map.

Returns the configured version of the sensor.

Functions

category()

@spec category() :: atom() | nil

Returns the configured category of the sensor.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

description()

@spec description() :: String.t() | nil

Returns the configured description of the sensor.

get_config(sensor)

@spec get_config(Jido.Sensor.t()) :: {:ok, map()} | {:error, any()}

Retrieves the complete configuration of a sensor.

Parameters

  • sensor - The sensor to get configuration from. Can be a PID, atom name, or string name.

Return Values

  • {:ok, config} - The complete configuration map
  • {:error, reason} - If the sensor cannot be found or accessed

Examples

iex> {:ok, config} = MySensor.get_config(sensor_pid)
{:ok, %{id: "sensor1", target: {:bus, :my_bus}}}

iex> MySensor.get_config(:nonexistent_sensor)
{:error, :invalid_sensor}

get_config(sensor, key)

@spec get_config(Jido.Sensor.t(), atom()) ::
  {:ok, any()} | {:error, :not_found | any()}

Retrieves a specific configuration value from a sensor.

Parameters

  • sensor - The sensor to get configuration from. Can be a PID, atom name, or string name.
  • key - The configuration key to retrieve

Return Values

  • {:ok, value} - The configuration value for the key
  • {:error, :not_found} - If the key does not exist
  • {:error, reason} - If the sensor cannot be found or accessed

Examples

iex> {:ok, value} = MySensor.get_config(sensor_pid, :target)
{:ok, {:bus, :my_bus}}

iex> MySensor.get_config(sensor_pid, :nonexistent_key)
{:error, :not_found}

name()

@spec name() :: String.t()

Returns the configured name of the sensor.

schema()

@spec schema() :: Keyword.t()

Returns the configured schema for the sensor.

set_config(sensor, config)

@spec set_config(Jido.Sensor.t(), map()) :: :ok | {:error, any()}

Updates multiple configuration values for a sensor.

Parameters

  • sensor - The sensor to update. Can be a PID, atom name, or string name.
  • config - A map containing the configuration key-value pairs to update

Return Values

  • :ok - The configuration was updated successfully
  • {:error, reason} - If the sensor cannot be found or accessed

Examples

iex> MySensor.set_config(sensor_pid, %{key1: "value1", key2: "value2"})
:ok

iex> MySensor.set_config(:nonexistent_sensor, %{key: "value"})
{:error, :invalid_sensor}

set_config(sensor, key, value)

@spec set_config(Jido.Sensor.t(), atom(), any()) :: :ok | {:error, any()}

Updates a single configuration value for a sensor.

Parameters

  • sensor - The sensor to update. Can be a PID, atom name, or string name.
  • key - The configuration key to update
  • value - The new value to set

Return Values

  • :ok - The configuration was updated successfully
  • {:error, reason} - If the sensor cannot be found or accessed

Examples

iex> MySensor.set_config(sensor_pid, :some_key, "new_value")
:ok

iex> MySensor.set_config(:nonexistent_sensor, :key, "value")
{:error, :invalid_sensor}

start_link(opts)

@spec start_link(Keyword.t()) :: GenServer.on_start()

Starts a new Sensor process.

Options

  • :id (String.t/0) - Unique identifier for the sensor instance

  • :target - Required. Target for signal delivery. Can be a single dispatch config tuple or a keyword list of named configurations.

  • :retain_last (pos_integer/0) - Number of last values to retain The default value is 10.

  • :interval (pos_integer/0) - Interval between heartbeats in milliseconds The default value is 5000.

  • :message (String.t/0) - Message to include in heartbeat signal The default value is "heartbeat".

Return Values

  • {:ok, pid} - The sensor was started successfully
  • {:error, reason} - The sensor failed to start

Examples

iex> MySensor.start_link(id: "sensor1", target: {:bus, :my_bus})
{:ok, #PID<0.123.0>}

iex> MySensor.start_link(id: "sensor1", target: {:invalid, :target})
{:error, "invalid target specification"}

tags()

@spec tags() :: [atom()]

Returns the configured tags for the sensor.

to_json()

@spec to_json() :: map()

Converts the sensor metadata to a JSON-compatible map.

Returns a map containing the sensor's name, description, category, tags, version and schema configuration.

Example

iex> MySensor.to_json()
%{
  name: "my_sensor",
  description: "A test sensor",
  category: :test,
  tags: [:test, :example],
  vsn: "1.0.0",
  schema: []
}

vsn()

@spec vsn() :: String.t() | nil

Returns the configured version of the sensor.