API Reference

Class: ParameterEventHandler

ROS2.0 JavaScript client with Node.js

class

ParameterEventHandler(node, optionsopt)

ParameterEventHandler Monitors and responds to parameter changes on any node in the ROS 2 graph by subscribing to the `/parameter_events` topic. Unlike ParameterWatcher, which is tied to a single remote node and requires waiting for that node's parameter services, ParameterEventHandler responds to parameter events from any node without needing service availability. Two types of callbacks are supported: - **Parameter callbacks**: fired when a specific parameter on a specific node is added or changed (new_parameters + changed_parameters). Note: deleted parameters are not dispatched to parameter callbacks; use event callbacks to observe deletions. - **Event callbacks**: fired for every ParameterEvent message received, including deletions.

Constructor

class

new ParameterEventHandler(node, optionsopt)

Create a ParameterEventHandler.
Parameters:
Name Type Attributes Description
node object The rclnodejs Node used to create the subscription
options object <optional>
 Options
Properties
Name Type Attributes Description
qos object <optional>
 QoS profile for the parameter_events subscription
Source:
Example
const handler = node.createParameterEventHandler();

// Watch a specific parameter on a specific node
const handle = handler.addParameterCallback(
  'my_param',
  '/my_node',
  (parameter) => {
    console.log(`Parameter changed: ${parameter.name} = ${parameter.value}`);
  }
);

// Watch all parameter events
const eventHandle = handler.addParameterEventCallback((event) => {
  console.log(`Event from node: ${event.node}`);
});

// Remove callbacks when done
handler.removeParameterCallback(handle);
handler.removeParameterEventCallback(eventHandle);

// Destroy when no longer needed
handler.destroy();

Methods

function

addParameterCallback(parameterName, nodeName, callback) → {ParameterCallbackHandle}

Add a callback for a specific parameter on a specific node. The callback is invoked whenever the named parameter is added or changed on the specified node. The callback receives the parameter message object (rcl_interfaces/msg/Parameter) with `name` and `value` fields.
Parameters:
Name Type Description
parameterName string Name of the parameter to monitor
nodeName string Fully qualified name of the node (e.g., '/my_node')
callback function Called with (parameter) when the parameter changes
Source:
Throws:
  • If the handler has been destroyed
    Type Error
  • If arguments are invalid
    Type TypeError
Returns:
Handle for removing this callback later
Type ParameterCallbackHandle
function

addParameterEventCallback(callback) → {ParameterEventCallbackHandle}

Add a callback that is invoked for every parameter event. The callback receives the full ParameterEvent message (rcl_interfaces/msg/ParameterEvent) with `node`, `new_parameters`, `changed_parameters`, and `deleted_parameters` fields.
Parameters:
Name Type Description
callback function Called with (event) for every ParameterEvent
Source:
Throws:
  • If the handler has been destroyed
    Type Error
  • If callback is not a function
    Type TypeError
Returns:
Handle for removing this callback later
Type ParameterEventCallbackHandle
function

configureNodesFilter(nodeNamesopt) → {boolean}

Configure which node parameter events will be received. If nodeNames is omitted or empty, the current node filter is cleared. When a filter is active, parameter and event callbacks only receive events from the specified nodes.
Parameters:
Name Type Attributes Description
nodeNames Array.<string> <optional>
 Node names to filter parameter events from. Relative names are resolved against the handler node namespace.
Source:
Returns:
True if the filter is active or was successfully cleared.
Type boolean
function

destroy()

Destroy the handler and clean up resources. Removes the subscription and clears all callbacks.
Source:
function

isDestroyed() → {boolean}

Check if the handler has been destroyed.
Source:
Returns:
True if destroyed
Type boolean
function

removeParameterCallback(handle)

Remove a previously added parameter callback.
Parameters:
Name Type Description
handle ParameterCallbackHandle The handle returned by addParameterCallback
Source:
Throws:
If the handle is not found or handler is destroyed
Type Error
function

removeParameterEventCallback(handle)

Remove a previously added parameter event callback.
Parameters:
Name Type Description
handle ParameterEventCallbackHandle The handle returned by addParameterEventCallback
Source:
Throws:
If the handle is not found or handler is destroyed
Type Error
function

(static) getParameterFromEvent(event, parameterName, nodeName) → {object|null}

Get a specific parameter from a ParameterEvent message.
Parameters:
Name Type Description
event object A ParameterEvent message
parameterName string The parameter name to look for
nodeName string The node name to match
Source:
Returns:
The matching parameter message, or null
Type object | null
function

(static) getParametersFromEvent(event) → {Array.<object>}

Get all parameters from a ParameterEvent message (new + changed).
Parameters:
Name Type Description
event object A ParameterEvent message
Source:
Returns:
Array of parameter messages
Type Array.<object>