Rclex.GraphMonitor (Rclex (Experimental) v0.12.5)

Copy Markdown View Source

Optional GenServer that monitors the ROS 2 graph and emits :telemetry events when nodes, topics, services, or actions join or leave.

Telemetry events

All measurements are %{count: 1}.

EventMetadata keys
[:rclex, :graph, :node_joined]node_name, node_namespace
[:rclex, :graph, :node_left]node_name, node_namespace
[:rclex, :graph, :topic_joined]topic_name, topic_types
[:rclex, :graph, :topic_left]topic_name, topic_types
[:rclex, :graph, :service_joined]service_name, service_types
[:rclex, :graph, :service_left]service_name, service_types
[:rclex, :graph, :action_joined]action_name, action_types
[:rclex, :graph, :action_left]action_name, action_types

Enabling

Pass graph_monitor: true when starting a node:

Rclex.start_node("my_node", graph_monitor: true)

Requires the :telemetry library to be listed as a dependency in your project.

on_entity/4

Registers a callback that fires when a ROS entity is visible in the graph. The callback receives the matching entity_spec as its only argument. If the entity is already present when on_entity/4 is called, the callback fires before the function returns. Otherwise it fires once the first time the entity joins. Each firing runs in its own Task, so a slow or crashing callback cannot block or crash the GraphMonitor.

Rclex.GraphMonitor.on_entity("my_node", {:node, "camera_node", "/sensors"}, fn entity_spec ->
  IO.inspect(entity_spec, label: "joined")
end)

Summary

Types

entity_spec()

Identifies a ROS graph entity to watch.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_snapshot(node_name, opts \\ [])

Return the current graph snapshot maintained by the monitor.

name(name, namespace \\ "/")
on_entity(node_name, entity_spec, callback, opts \\ [])

Registers callback to be called with entity_spec when it is present in the ROS graph. If the entity is already visible, callback is invoked before this function returns. Otherwise it fires once the first time the entity appears. Each firing runs in its own Task.

start_link(args)

Types

entity_spec()

@type entity_spec() ::
  {:node, node_name :: String.t(), node_namespace :: String.t()}
  | {:topic, topic_name :: String.t()}
  | {:service, service_name :: String.t()}
  | {:action, action_name :: String.t()}

Identifies a ROS graph entity to watch.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_snapshot(node_name, opts \\ [])

@spec get_snapshot(
  monitor_node_name :: String.t(),
  opts :: [{:namespace, String.t()}]
) :: map()

Return the current graph snapshot maintained by the monitor.

The snapshot is a map with keys :nodes, :topics, :services, and :actions, each being a MapSet of the currently known graph entities.

opts

  • :namespace — namespace of the monitor node. Defaults to "/".

name(name, namespace \\ "/")

on_entity(node_name, entity_spec, callback, opts \\ [])

@spec on_entity(
  monitor_node_name :: String.t(),
  entity_spec :: entity_spec(),
  callback :: (entity_spec() -> any()),
  opts :: [{:namespace, String.t()}]
) :: :ok

Registers callback to be called with entity_spec when it is present in the ROS graph. If the entity is already visible, callback is invoked before this function returns. Otherwise it fires once the first time the entity appears. Each firing runs in its own Task.

entity_spec can be:

  • {:node, node_name, node_namespace} — a ROS node
  • {:topic, topic_name} — a topic (any publisher or subscriber)
  • {:service, service_name} — a service server
  • {:action, action_name} — an action server

opts

  • :namespace — namespace of the monitor node. Defaults to "/".

start_link(args)