API Reference

Global

ROS2.0 JavaScript client with Node.js

globalobj

Members

member

(constant) CallbackReturnCode :number

The values returned by TransitionCallback.
Type:
  • number
Source:
member

(constant) CancelResponse :number

Possible cancel responses.
Type:
  • number
Properties
Name Type Description
REJECT number
ACCEPT number
Source:
member

(constant) ClockChange :number

Enum for ClockChange Represents the type of clock change that occurred during a time jump.
Type:
  • number
Properties
Name Type Description
ROS_TIME_NO_CHANGE number The source before and after the jump is ROS_TIME.
ROS_TIME_ACTIVATED number The source switched to ROS_TIME from SYSTEM_TIME.
ROS_TIME_DEACTIVATED number The source switched to SYSTEM_TIME from ROS_TIME.
SYSTEM_TIME_NO_CHANGE number The source before and after the jump is SYSTEM_TIME.
Source:
member

(constant) ClockType :number

Enum for ClockType
Type:
  • number
Properties
Name Type Description
ROS_TIME number
SYSTEM_TIME number
STEADY_TIME number
Source:
member

(constant) DEFAULT_NUMERIC_RANGE_TOLERANCE :number

The plus/minus tolerance for determining number equivalence.
Type:
  • number
Source:
See:
member

(constant) DistroId

enum style distribution identifiers
Source:
member

(readonly) DurabilityPolicy :number

Enum for DurabilityPolicy
Type:
  • number
Properties
Name Type Description
RMW_QOS_POLICY_DURABILITY_SYSTEM_DEFAULT number
RMW_QOS_POLICY_DURABILITY_TRANSIENT_LOCAL number
RMW_QOS_POLICY_DURABILITY_VOLATILE number
Source:
member

(constant) GoalResponse :number

Possible goal responses.
Type:
  • number
Properties
Name Type Description
REJECT number
ACCEPT number
Source:
member

(readonly) HistoryPolicy :number

Enum for HistoryPolicy
Type:
  • number
Properties
Name Type Description
RMW_QOS_POLICY_HISTORY_SYSTEM_DEFAULT number
RMW_QOS_POLICY_HISTORY_KEEP_LAST number
RMW_QOS_POLICY_HISTORY_KEEP_ALL number
Source:
member

(readonly) LivelinessPolicy :number

Enum for LivelinessPolicy
Type:
  • number
Properties
Name Type Description
RMW_QOS_POLICY_LIVELINESS_SYSTEM_DEFAULT number
RMW_QOS_POLICY_LIVELINESS_AUTOMATIC number
RMW_QOS_POLICY_LIVELINESS_MANUAL_BY_TOPIC number
RMW_QOS_POLICY_LIVELINESS_UNKNOWN number
RMW_QOS_POLICY_LIVELINESS_BEST_AVAILABLE number
Source:
member

(readonly) LoggingSeverity :number

Enum for LoggingSeverity
Type:
  • number
Properties
Name Type Description
UNSET number
DEBUG number
INFO number
WARN number
ERROR number
FATAL number
Source:
member

(constant) PRIMITIVE_TYPE_MAP

Map ROS primitive types to JavaScript types
Source:
member

(constant) ParameterType :number

Enum for ParameterType
Type:
  • number
Properties
Name Type Description
PARAMETER_NOT_SET number
PARAMETER_BOOL number
PARAMETER_INTEGER number
PARAMETER_DOUBLE number
PARAMETER_STRING number
PARAMETER_BYTE_ARRAY number
PARAMETER_BOOL_ARRAY number
PARAMETER_INTEGER_ARRAY number
PARAMETER_DOUBLE_ARRAY number
PARAMETER_STRING_ARRAY number
Source:
member

(constant) PublisherEventType :number

Enumeration for PublisherEventCallbacks event types.
Type:
  • number
Properties
Name Type Description
PUBLISHER_OFFERED_DEADLINE_MISSED number
PUBLISHER_LIVELINESS_LOST number
PUBLISHER_OFFERED_INCOMPATIBLE_QOS number
PUBLISHER_INCOMPATIBLE_TYPE number
PUBLISHER_MATCHED number
Source:
member

(constant) QoSPolicyKind :number

Enum of overridable QoS policy kinds. Each value corresponds to a QoS property on the QoS class.
Type:
  • number
Source:
member

(readonly) ReliabilityPolicy :number

Enum for ReliabilityPolicy
Type:
  • number
Properties
Name Type Description
RMW_QOS_POLICY_RELIABILITY_SYSTEM_DEFAULT number
RMW_QOS_POLICY_RELIABILITY_RELIABLE number
RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT number
Source:
member

(constant) ServiceIntrospectionStates :ServiceIntrospectionState

Enum for service introspection states.
Type:
Properties
Name Type Description
OFF ServiceIntrospectionState
METADATA ServiceIntrospectionState
CONTENTS ServiceIntrospectionState
Source:
member

(constant) SubscriptionEventType :number

Enumeration for SubscriptionEventCallbacks event types.
Type:
  • number
Properties
Name Type Description
SUBSCRIPTION_REQUESTED_DEADLINE_MISSED number
SUBSCRIPTION_LIVELINESS_CHANGED number
SUBSCRIPTION_REQUESTED_INCOMPATIBLE_QOS number
SUBSCRIPTION_MESSAGE_LOST number
SUBSCRIPTION_INCOMPATIBLE_TYPE number
SUBSCRIPTION_MATCHED number
Source:
member

(constant) ValidationProblem :string

Validation issue problem types
Type:
  • string
Properties
Name Type Description
UNKNOWN_FIELD string Field exists in object but not in message schema
TYPE_MISMATCH string Field type doesn't match expected type
MISSING_FIELD string Required field is missing
ARRAY_LENGTH string Array length constraint violated
OUT_OF_RANGE string Value is out of valid range
NESTED_ERROR string Nested message validation failed
Source:

Methods

function

_enumToString(val, enumObj) → {string}

Convert a numeric enum value to a lowercase string name.
Parameters:
Name Type Description
val number enum numeric value
enumObj Object the enum object (e.g. QoS.HistoryPolicy)
Source:
Returns:
Type string
function

_resolveQoS(qos) → {QoS}

Resolve QoS profile string to a mutable QoS object. If already a QoS instance, return as-is.
Parameters:
Name Type Description
qos QoS | string
Source:
Returns:
Type QoS
function

_stringToEnum(str, enumObj) → {number}

Convert a lowercase string back to a numeric enum value.
Parameters:
Name Type Description
str string the string value (e.g. "keep_last")
enumObj Object the enum object
Source:
Returns:
Type number
function

applySerializationMode(message, serializationMode) → {*}

Apply serialization mode conversion to a message object
Parameters:
Name Type Description
message * The message object to convert
serializationMode string The serialization mode ('default', 'plain', 'json')
Source:
Returns:
The converted message
Type *
function

assertValidMessage(obj, typeClass, optionsopt) → {void}

Validate a message and throw if invalid
Parameters:
Name Type Attributes Description
obj object Plain object to validate
typeClass function | string | object Message type class or identifier
options object <optional>
 Validation options (same as validateMessage)
Source:
Throws:
If validation fails
Type MessageValidationError
Returns:
Type void
function

compareVersions(version1, version2, operator) → {boolean}

Compare two semantic version strings. Supports version strings in the format: x.y.z or x.y.z.w where x, y, z, w are integers.
Parameters:
Name Type Description
version1 string First version string (e.g., '1.2.3')
version2 string Second version string (e.g., '1.2.4')
operator string Comparison operator: '<', '<=', '>', '>=', '==', '!='
Source:
Returns:
Result of the comparison
Type boolean
Example
compareVersions('1.2.3', '1.2.4', '<')   // true
compareVersions('2.0.0', '1.9.9', '>')   // true
compareVersions('1.2.3', '1.2.3', '==')  // true
compareVersions('1.2.3', '1.2.3', '>=')  // true
function

(async) copy(src, dest, options) → {Promise.<void>}

Copy file or directory recursively Replaces: fse.copy()
Parameters:
Name Type Description
src string Source path
dest string Destination path
options object Copy options
Source:
Returns:
Type Promise.<void>
function

createMessageValidator(typeClass, defaultOptionsopt) → {function}

Create a validator function for a specific message type
Parameters:
Name Type Attributes Description
typeClass function | string | object Message type class or identifier
defaultOptions object <optional>
 Default validation options
Source:
Returns:
Validator function that takes (obj, options?) and returns validation result
Type function
function

declareQosParameters(entityType, node, topic, qos, options)

Declare QoS override parameters on the node and apply any overrides to the QoS profile in-place.
Parameters:
Name Type Description
entityType 'publisher' | 'subscription'
node Node
topic string Fully resolved topic name.
qos QoS Mutable QoS object (will be modified in-place).
options QoSOverridingOptions
Source:
function

defaultCancelCallback() → {number}

No cancellations.
Source:
Returns:
- Always responds with rejection
Type number
function

defaultGoalCallback() → {number}

Accept all goals.
Source:
Returns:
- Always responds with acceptance.
Type number
function

defaultHandleAcceptedCallback(goalHandle) → {undefined}

Execute the goal.
Parameters:
Name Type Description
goalHandle ServerGoalHandle The server goal handle.
Source:
Returns:
Type undefined
function

detectUbuntuCodename() → {string|null}

Detect Ubuntu codename from /etc/os-release
Source:
Returns:
Ubuntu codename (e.g., 'noble', 'jammy') or null if not detectable
Type string | null
function

(async) emptyDir(dirPath) → {Promise.<void>}

Empty a directory (remove all contents but keep the directory) Replaces: fse.emptyDir()
Parameters:
Name Type Description
dirPath string Path to directory
Source:
Returns:
Type Promise.<void>
function

(async) ensureDir(dirPath) → {Promise.<void>}

Ensure directory exists, create recursively if needed (async) Replaces: fse.ensureDir() / fse.mkdirs()
Parameters:
Name Type Description
dirPath string Path to directory
Source:
Returns:
Type Promise.<void>
function

ensureDirSync(dirPath)

Ensure directory exists, create recursively if needed (sync) Replaces: fse.mkdirSync()
Parameters:
Name Type Description
dirPath string Path to directory
Source:
function

getActionClientNamesAndTypesByNode(node, nodeName, namespace) → {array}

Get a list of action names and types for action clients associated with a node.
Parameters:
Name Type Description
node Node The node used for discovery.
nodeName string The name of a remote node to get action clients for.
namespace string Namespace of the remote node.
Source:
Returns:
- An array of the names and types.
Type array
function

getActionNamesAndTypes(node) → {array}

Get a list of action names and types.
Parameters:
Name Type Description
node Node The node used for discovery.
Source:
Returns:
- An array of the names and types.
Type array
function

getActionServerNamesAndTypesByNode(node, nodeName, namespace) → {array}

Get a list of action names and types for action servers associated with a node.
Parameters:
Name Type Description
node Node The node used for discovery.
nodeName string The name of a remote node to get action servers for.
namespace string Namespace of the remote node.
Source:
Returns:
- An array of the names and types.
Type array
function

(async) getCurrentGeneratorVersion() → {Promise.<(string|null)>}

Get the version of the generator that was used for the currently present interfaces.
Source:
Throws:
if there was an error reading the *generator.json* file (except for it being absent)
Type Error
Returns:
The current version or null if the *generator.json* file was not found
Type Promise.<(string|null)>
function

getFieldNames(typeClass) → {Array.<string>}

Get field names for a message type
Parameters:
Name Type Description
typeClass function | string | object Message type class or identifier
Source:
Returns:
Array of field names
Type Array.<string>
function

getFieldType(typeClass, fieldName) → {object|null}

Get type information for a specific field
Parameters:
Name Type Description
typeClass function | string | object Message type class or identifier
fieldName string Name of the field
Source:
Returns:
Field type information or null if not found
Type object | null
function

getMessageSchema(typeClass) → {object|null}

Get the schema definition for a message type
Parameters:
Name Type Description
typeClass function | string | object Message type class or identifier
Source:
Returns:
Schema definition with fields and constants, or null if not found
Type object | null
Example
const schema = getMessageSchema(StringClass);
// Returns: {
//   fields: [{name: 'data', type: {type: 'string', isPrimitiveType: true, ...}}],
//   constants: [],
//   messageType: 'std_msgs/msg/String'
// }
function

getMessageTypeString(typeClass) → {string}

Get message type string from type class
Parameters:
Name Type Description
typeClass function Message type class
Source:
Returns:
Message type string (e.g., 'std_msgs/msg/String')
Type string
function

getNestedTypeClass(parentTypeClass, fieldName) → {function|null}

Get the type class for a nested field
Parameters:
Name Type Description
parentTypeClass function Parent message type class
fieldName string Field name
Source:
Returns:
Nested type class or null
Type function | null
function

getValueType(value) → {string}

Get the JavaScript type string for a value
Parameters:
Name Type Description
value any Value to get type of
Source:
Returns:
Type description
Type string
function

isClose(a, b, rtolopt, atolopt) → {boolean}

Check if two numbers are equal within a given tolerance. This function compares two numbers using both relative and absolute tolerance, matching the behavior of the 'is-close' npm package. The comparison uses the formula: abs(a - b) <= max(rtol * max(abs(a), abs(b)), atol) Implementation checks: 1. Absolute tolerance: abs(a - b) <= atol 2. Relative tolerance: abs(a - b) / max(abs(a), abs(b)) <= rtol
Parameters:
Name Type Attributes Default Description
a number The first number to compare
b number The second number to compare
rtol number <optional>
 1e-9 The relative tolerance parameter (default: 1e-9)
atol number <optional>
 0.0 The absolute tolerance parameter (default: 0.0)
Source:
Returns:
True if the numbers are close within the tolerance
Type boolean
Example
isClose(1.0, 1.0) // true - exact equality
isClose(1.0, 1.1, 0.01) // false - relative diff: 0.1/1.1 ≈ 0.091 > 0.01
isClose(10, 10.00001, 1e-6) // true - relative diff: 0.00001/10 = 1e-6 <= 1e-6
isClose(0, 0.05, 0, 0.1) // true - absolute diff: 0.05 <= 0.1 (atol)
function

isTypedArray(value) → {boolean}

Check if a value is a TypedArray
Parameters:
Name Type Description
value * The value to check
Source:
Returns:
True if the value is a TypedArray
Type boolean
function

isTypedArray(value) → {boolean}

Check if value is a TypedArray
Parameters:
Name Type Description
value any Value to check
Source:
Returns:
True if TypedArray
Type boolean
function

isValidSerializationMode(mode) → {boolean}

Validate serialization mode
Parameters:
Name Type Description
mode string The serialization mode to validate
Source:
Returns:
True if valid
Type boolean
function

(async) mkdir(dirPath, options) → {Promise.<void>}

Create directory (async) Replaces: fse.mkdir()
Parameters:
Name Type Description
dirPath string Path to directory
options object mkdir options
Source:
Returns:
Type Promise.<void>
function

needsJSONConversion(value) → {boolean}

Check if a value needs JSON conversion (BigInt, functions, etc.)
Parameters:
Name Type Description
value * The value to check
Source:
Returns:
True if the value needs special JSON handling
Type boolean
function

normalizeNodeName(nodeName) → {string}

Normalize a ROS 2 node name by removing the leading slash if present. ROS 2 node names may be specified with or without a leading slash depending on the context. This utility ensures consistent representation without the leading slash, which is the standard format for most ROS 2 APIs.
Parameters:
Name Type Description
nodeName string The node name to normalize
Source:
Returns:
The normalized node name without leading slash
Type string
Example
normalizeNodeName('my_node')    // 'my_node'
normalizeNodeName('/my_node')   // 'my_node'
normalizeNodeName('/ns/my_node') // 'ns/my_node'
function

parameterTypeFromValue(value) → {ParameterType}

Infer a ParameterType for JS primitive types: string, boolean, number and arrays of these types. A TypeError is thrown for a value who's type is not one of the set listed.
Parameters:
Name Type Description
value any The value to infer it's ParameterType
Source:
Returns:
- The ParameterType that best scribes the value.
Type ParameterType
function

(async) pathExists(filePath) → {Promise.<boolean>}

Check if path exists (async) Replaces: fse.exists()
Parameters:
Name Type Description
filePath string Path to check
Source:
Returns:
Type Promise.<boolean>
function

readJsonSync(filePath, options) → {any}

Read and parse JSON file synchronously Replaces: fse.readJsonSync()
Parameters:
Name Type Description
filePath string Path to JSON file
options object Read options
Source:
Returns:
Parsed JSON data
Type any
function

(async) remove(filePath) → {Promise.<void>}

Remove file or directory (async) Replaces: fse.remove()
Parameters:
Name Type Description
filePath string Path to remove
Source:
Returns:
Type Promise.<void>
function

removeSync(filePath)

Remove file or directory (sync) Replaces: fse.removeSync()
Parameters:
Name Type Description
filePath string Path to remove
Source:
function

resolveTypeClass(typeClass) → {function|null}

Resolve a type class from various input formats
Parameters:
Name Type Description
typeClass string | object | function Type identifier
Source:
Returns:
The resolved type class or null
Type function | null
function

ros2Launch(packageName, launchFile, argsopt) → {Promise.<{process: ChildProcess}>}

Run a ROS2 launch file using 'ros2 launch' command.
Parameters:
Name Type Attributes Default Description
packageName string The name of the ROS2 package.
launchFile string The name of the launch file to run.
args Array.<string> <optional>
 [] Additional arguments to pass to the launch file.
Source:
Returns:
A Promise that resolves with the process.
Type Promise.<{process: ChildProcess}>
function

ros2Run(packageName, executableName, argsopt) → {Promise.<{process: ChildProcess}>}

Run a ROS2 package executable using 'ros2 run' command.
Parameters:
Name Type Attributes Default Description
packageName string The name of the ROS2 package.
executableName string The name of the executable to run.
args Array.<string> <optional>
 [] Additional arguments to pass to the executable.
Source:
Returns:
A Promise that resolves with the process.
Type Promise.<{process: ChildProcess}>
function

toJSONSafe(obj) → {*}

Convert a message to be fully JSON-safe
Parameters:
Name Type Description
obj * The object to convert
Source:
Returns:
The JSON-safe converted object
Type *
function

toJSONString(obj, spaceopt) → {string}

Convert a message to a JSON string
Parameters:
Name Type Attributes Description
obj * The object to convert
space number <optional>
 Space parameter for JSON.stringify formatting
Source:
Returns:
The JSON string representation
Type string
function

toPlainArrays(obj) → {*}

Convert a message to plain arrays (TypedArray -> regular Array)
Parameters:
Name Type Description
obj * The object to convert
Source:
Returns:
The converted object with plain arrays
Type *
function

validType(parameterType) → {boolean}

Determine if a number maps to is a valid ParameterType.
Parameters:
Name Type Description
parameterType ParameterType The value to test.
Source:
Returns:
- True if value is a valid ParameterType; false otherwise.
Type boolean
function

validValue(value, type) → {boolean}

Test if value can be represented by a ParameterType.
Parameters:
Name Type Description
value number The value to test.
type ParameterType The ParameterType to test value against.
Source:
Returns:
- True if value can be represented by type.
Type boolean
function

validateArrayConstraints(value, fieldType) → {object|null}

Validate array constraints
Parameters:
Name Type Description
value any Array value to validate
fieldType object Field type definition
Source:
Returns:
Validation issue or null if valid
Type object | null
function

validateMessage(obj, typeClass, optionsopt) → {Object}

Validate a message object against its schema
Parameters:
Name Type Attributes Description
obj object Plain object to validate
typeClass function | string | object Message type class or identifier
options object <optional>
 Validation options
Properties
Name Type Attributes Default Description
strict boolean <optional>
 false If true, unknown fields cause validation failure
checkTypes boolean <optional>
 true If true, validate field types
checkRequired boolean <optional>
 false If true, check for missing fields
path string <optional>
 '' Current path for nested validation (internal use)
Source:
Returns:
Validation result
Type Object
function

validatePrimitiveValue(value, fieldType) → {object|null}

Validate a primitive value against its expected type
Parameters:
Name Type Description
value any Value to validate
fieldType object Field type definition
Source:
Returns:
Validation issue or null if valid
Type object | null
function

waitForMessage(typeClass, node, topic, optionsopt) → {Promise.<object>}

Wait for a single message on a topic. Creates a temporary subscription, waits for the first message to arrive, and returns it. The temporary subscription is always cleaned up, even on timeout or error. The node must be spinning before calling this function. This is the rclnodejs equivalent of rclpy's `wait_for_message`.
Parameters:
Name Type Attributes Description
typeClass function | string | object The ROS message type class.
node Node The node to create the temporary subscription on.
topic string The topic name to listen on.
options object <optional>
 Options.
Properties
Name Type Attributes Description
timeout number <optional>
 Timeout in milliseconds. If omitted, waits indefinitely.
qos object <optional>
 QoS profile for the subscription.
Source:
Throws:
If timeout expires before a message arrives.
Type Error
Returns:
- Resolves with the received message.
Type Promise.<object>
Example
node.spin();
const msg = await waitForMessage(
  'std_msgs/msg/String',
  node,
  '/my_topic',
  { timeout: 5000 }
);
console.log('Received:', msg.data);
function

(async) writeFile(filePath, data, options) → {Promise.<void>}

Write file with content (async) Replaces: fse.writeFile()
Parameters:
Name Type Description
filePath string Path to file
data string | Buffer Content to write
options object Write options
Source:
Returns:
Type Promise.<void>

Type Definitions

typedef

PostSetParametersCallback(parameters) → {undefined}

A callback invoked after parameters have been successfully set. It receives the final parameter list. For side effects only (return value is ignored).
Parameters:
Name Type Description
parameters Array.<Parameter> The parameters that were set.
Source:
See:
Returns:
Type undefined
typedef

PreSetParametersCallback(parameters) → {Array.<Parameter>}

A callback invoked before parameter validation and setting. It receives the parameter list and must return a (possibly modified) parameter list.
Parameters:
Name Type Description
parameters Array.<Parameter> The parameters about to be set.
Source:
See:
Returns:
- The modified parameter list to proceed with.
Type Array.<Parameter>
typedef

RequestCallback(request, response) → {undefined}

This callback is called when a request is sent to service
Parameters:
Name Type Description
request Object The request sent to the service
response Response The response to client. Use response.send() to send response object to client
Source:
See:
Returns:
Type undefined
typedef

ResponseCallback(response)

This callback is called when a response is sent back from service
Parameters:
Name Type Description
response Object The response sent from the service
Source:
See:
typedef

SerializedState

Type:
  • object
Properties
Name Type Description
id number code identifying the type of this state.
label string readable name of this state.
Source:
typedef

ServiceIntrospectionState

Type:
  • number
Source:
typedef

SetParametersCallback(parameters) → {rcl_interfaces.msg.SetParameterResult}

This callback is called when declaring a parameter or setting a parameter. The callback is provided a list of parameters and returns a SetParameterResult to indicate approval or veto of the operation.
Parameters:
Name Type Description
parameters Array.<Parameter> The message published
Source:
See:
Returns:
-
Type rcl_interfaces.msg.SetParameterResult
typedef

SubscriptionCallback(message)

This callback is called when a message is published
Parameters:
Name Type Description
message Object The message published
Source:
See:
typedef

TransitionCallback(previousState) → {CallbackReturnCode}

This callback is invoked when LifecycleNode is transitioning to a new state.
Parameters:
Name Type Description
previousState State The previous node lifecycle state.
Source:
See:
Returns:
- The result of the callback.
Type CallbackReturnCode