Skip to main content

Documentation

ROS

ROS utils for use in Transitive robot capabilities. Supports both ROS 1 (using rosnodejs) and ROS 2 (using rclnodejs). The respective classes ROS1 and ROS2 have a unified interface, so that switching between ROS releases is trivial as can be seen in the example below.

Install​

npm i @transitive-sdk/utils-ros

Example​

This example requires a running roscore for ROS 1.

const { ROSs, getForVersion } = require('@transitive-sdk/utils-ros');

const demo = async (version) => {
  const ros = getForVersion(version);
  await ros.init();

  const topic = '/utils_ros/test1';
  const type = version == 1 ? 'std_msgs/String' : 'std_msgs/msg/String';

  const interval = setInterval(() => {
    ros.publish(topic, type, {data: String(Date.now())});
  });

  const sub = ros.subscribe(topic, type, (msg) => {
    console.log('received', msg.data);
  });
};

demo(1); // run demo using ROS1
demo(2); // run demo using ROS2

ROSfs​

Extends AbstractROS(EventEmitter)

A class that is interface-compatible with our ROS and ROS2 classes, but uses the filesystem for pub and sub instead. For non-ROS users, low rate. To enable, set global.rosFs to a truthy value in config.json.

Config options:

  • basePath (default: '/tmp/transitive-ros-fs/'): the root of the file-tree where to publish and subscribe to "topics", i.e., files.
  • publishInterval (default 10000, min: 1000): throttle interval (in ms) for publishing.

Example assuming default config:

  • publish('/my/topic', null, {mytime: 1778801349319}) would write the given JSON to /tmp/transitive-ros-fs/my/topic.
  • subscribe('/my/topic', null, console.log) would watch /tmp/transitive-ros-fs/my/topic and, on changes, print the new content to the console (JSON parsed).

publish​

Publish the given message (json) on the named "topic", i.e., filepath.

subscribe​

subscribe to topic: start watching the respective directory and register event handler

Parameters​
  • topic
  • _type
  • onMessage

unsubscribe​

Unsubscribe from topic

Parameters​
  • topic

refreshFromFile​

Refresh and emit the topic value from file; debounced to handle repeat triggers caused by many ways of modifying the file (including echo "test" > file and some editors)

ROS​

Extends AbstractROS()

Small convenient singleton class for interfacing with ROS, including some auxiliary functions that come in handy in capabilities. Based on rosnodejs.

callAction​

Call an action, i.e., send goal to action server

Parameters​
  • actionServer
  • type
  • goal
  • feedbackCallback (optional, default undefined)

callService​

Call the given service of the given type with the given body (not required when type is "std_srvs/Empty").

Parameters​
  • serviceName
  • type
  • requestBody (optional, default undefined)

createHeader​

create a std_msgs/Header for the given frame_id and date

Parameters​
  • frame_id (optional, default '')
  • date (optional, default new Date())

getActions​

Get available actions

getAvailableTypes​

Get all known message and service types, grouped by package.

getParam​

Get the value of the given ROS parameter

Parameters​
  • param

getServices​

Get available services (list of names).

getServiceType​

Get type of a given service. Note that in ROS 1 this requires connecting to the service provider directly, and we don't want to poll all of them. So only use this on-demand.

Parameters​
  • service

getSubscribedTopics​

Get topics that have subscribers

Parameters​
  • type (optional, default undefined)

getTopics​

Get all topic of a given type or all topics if no type is specified

Parameters​
  • type (optional, default undefined)

getTypeTemplate​

Given a package, category, and type, e.g., 'std_msgs', 'msg', and 'String', return a plain object representing that type, which can be used as a template for creating messages.

Parameters​
  • pkg
  • category
  • type
  • response (optional, default false)

init​

Initialize ROS node. This needs to be called first.

Parameters​
  • suffix (optional, default '')

publish​

Publish the given message (json) on the names topic of type. Will advertise the topic if not yet advertised.

Parameters​
  • topic
  • type
  • message
  • latching (optional, default true)

setParam​

Set the value of the given ROS parameter

Parameters​
  • param
  • value

subscribe​

Subscribe to the named topic of the named type. Each time a new message is received the provided callback is called. Here options is an optional object: { "throttleMs": throttle-in-milliseconds }.

Parameters​
  • topic
  • type
  • onMessage
  • options (optional, default {})

unsubscribe​

Unsubscribe from topic

Parameters​
  • topic

ROS0​

Extends AbstractROS(EventEmitter)

A class that is interface-compatible with our ROS and ROS2 classes, but connects to ZeroMQ addresses for pub and sub instead. For non-ROS users. To enable, set global.rosFs to a truthy value in config.json. Config options:

  • address (default 'ipc:///tmp/transitive-zmq.sock'): the zeroMQ address to connect Publisher (+.pub suffix) and connect Subscriber (+.sub suffix) to.

init​

Open two UNIX domain sockets: one for pushing and one for pulling

Parameters​
  • config

processQueue​

(Re-)start queue processing if not already running

publish​

Publish the given message (json) on the names topic of type. Will advertise the topic if not yet advertised.

Parameters​
  • topic
  • _type
  • message
  • latching (optional, default true)

subscribe​

Subscribe to the named topic of the named type. Each time a new message is received the provided callback is called.

Parameters​
  • topic
  • _type
  • onMessage

unsubscribe​

Unsubscribe from topic

Parameters​
  • topic

watchForMessages​

Start watching for messages; Do not await this!

ROS2​

Extends AbstractROS()

Small convenient singleton class for interfacing with ROS2, including some auxiliary functions that come in handy in capabilities. Based on rclnodejs.

callAction​

Call an action, i.e., send goal to action server

Parameters​
  • action
  • type
  • goal
  • feedbackCallback (optional, default undefined)

callService​

Call the given service of the given type with the given body (not required when type is "std_srvs/srv/Empty").

Parameters​
  • serviceName
  • type
  • request (optional, default undefined)

createHeader​

create a std_msgs/Header for the given frame_id and date

Parameters​
  • frame_id (optional, default '')
  • date (optional, default new Date())

getActions​

Get available actions

getAvailableTypes​

Get all known message, service, and action types, grouped by package.

getParam​

Get the named parameter. If node is not given, then from our own params. Example: await getParam('background_b', '/turtlesim')

Parameters​
  • param
  • node (optional, default undefined)

getServices​

Get list of available services (list of names).

getServiceType​

Get type of a given service.

Parameters​
  • service

getSubscribedTopics​

Get topics that have subscribers

Parameters​
  • type (optional, default undefined)

getTopics​

Get all topic of a given type or all topics if no type is specified

Parameters​
  • type (optional, default undefined)

getTypeTemplate​

Given a package, category, and type, e.g., 'std_msgs', 'msg', and 'String', return a plain object representing that type, which can be used as a template for creating messages.

Parameters​
  • pkg
  • category
  • type
  • response (optional, default false)

init​

Initialize ROS node. This needs to be called first.

Parameters​
  • suffix (optional, default '')

publish​

Publish the given message (json) on the names topic of type. Will advertise the topic if not yet advertised.

Parameters​
  • topic
  • type
  • message
  • latching (optional, default false)

setParam​

Set parameter param to value, auto-detecting the type of value. If the node argument is not given, it's applied to the current node params. Example: await setParam('background_b', 188, '/turtlesim')

Parameters​
  • param
  • value
  • node (optional, default undefined)

subscribe​

Subscribe to the named topic of the named type. Each time a new message is received the provided callback is called. For available options see https://robotwebtools.github.io/rclnodejs/docs/0.22.3/Node.html#createSubscription. The default options.qos.reliability is best-effort. The options object can contain: "throttleMs": throttle (in milliseconds).

Parameters​
  • topic
  • type
  • onMessage
  • options (optional, default {})

unsubscribe​

Unsubscribe from topic

Parameters​
  • topic

AbstractROS​

An abstract base class for all our ROS and pseudeo-ROS implementations.

Parameters​

  • BaseClass (optional, default Object)

getForVersion​

Get the correct instance for the given ROS version (1 or 2).

Parameters​

  • version

getROS2GoalStatus​

Look up ROS2 goal status for given ROS1 goal handle

Parameters​

  • goalHandle

mapRos1GoalStatusToRos2​

mapping from ROS1 goal statuses to ROS2