rclnodejs

The rclnodejs tutorials are categorized into several functional areas to help you master different aspects of ROS 2 development:

Fundamentals

• ROS 2 Basic Concepts: Covers Topics and Services.

Node Management

• Lifecycle Nodes: Managing nodes with state machines for controlled startup, shutdown, and error handling.
• Parameter Service: Dynamic configuration management, including parameter declaration, validation, and runtime updates.

Advanced Communication

• ROS 2 Actions: Implementing long-running, cancellable tasks with progress feedback.
• Service Introspection: Debugging and monitoring service calls and responses.
• Content Filtering Subscription: Using SQL-like expressions at the DDS middleware level to reduce network traffic.
• Observable Subscriptions with RxJS: Using RxJS Observables and operators (e.g., throttleTime(), combineLatest()) for reactive message processing.
• rclnodejs/web (Browser SDK): Connecting to ROS 2 from a web application.

Introspection & Debugging

• Type Description Service: Querying message and service type definitions and field descriptions at runtime.

rosocket is a lightweight WebSocket gateway built into rclnodejs that allows a plain web browser to communicate with ROS 2 using only the built-in WebSocket and JSON APIs. Unlike the classic rosbridge_suite + roslibjs stack, rosocket requires no client-side JavaScript library and runs within the same Node.js process as your rclnodejs application.

Key Differences

When to use rosocket:

• When you want zero browser dependencies.
• When you want to avoid running an extra process.
• When you want greppable URLs for reverse-proxy ACLs.

When to use rclnodejs/web instead:

• When you want a typed SDK (call/publish/subscribe).
• When you need an allow-list for capabilities (web.json).
• When you need HTTP transport fallback.

The demo demonstrates how to use rclnodejs.require() to load action constructors, which provides full type safety for goals, feedback, and results without manual type annotations.

Loading an Action

const Fibonacci = rclnodejs.require('test_msgs/action/Fibonacci');

Action Server Implementation

A server requires three main callbacks typed using typeof Fibonacci:

1. Goal Callback: Validates and accepts/rejects goals. Returns rclnodejs.GoalResponse.
2. Execute Callback: Performs the long-running task. Returns Promise<rclnodejs.ActionResult<typeof Fibonacci>>.
3. Cancel Callback: Handles cancellation requests. Returns rclnodejs.CancelResponse.

Action Client Implementation

A client sends goals and listens for feedback:

const goal = new Fibonacci.Goal();
gol.order = 10;

const goalHandle = await this.actionClient.sendGoal(goal, (feedback) => {
  // feedback is typed as rclnodejs.ActionFeedback<typeof Fibonacci>
  console.log(feedback.sequence);
});

// Loading the action class for type safety
const Fibonacci = rclnodejs.require('test_msgs/action/Fibonacci');

// Example Client Goal Creation
const goal = new Fibonacci.Goal();
gol.order = 10;

// Sending the goal with a feedback callback
const goalHandle = await this.actionClient.sendGoal(goal, (feedback) => {
  // feedback.sequence is automatically typed
  console.log(feedback.sequence);
});

Services implement a request/response communication pattern used for remote procedure calls (RPC).

• Service Server: Provides a specific computation or service.
• Service Client: Requests the service and waits for a response.
• Synchronous: The client typically waits for the server's response.
• One-to-one: Usually one server per service name, though multiple clients can connect.
• Short-lived: Services should be used for tasks that return quickly.

Services are best suited for occasional, on-demand tasks like configuration changes, triggering calibrations, or performing specific computations (e.g., path planning).

const rclnodejs = require('rclnodejs');

async function createServiceServer() {
  await rclnodejs.init();
  const node = rclnodejs.createNode('service_example_node');

  // Create a service that adds two integers
  const service = node.createService(
    'example_interfaces/srv/AddTwoInts',
    'add_two_ints',
    (request, response) => {
      console.log(`Request: ${request.a} + ${request.b}`);

      // Compute the result
      const result = response.template;
      result.sum = request.a + request.b;

      console.log(`Sending response: ${typeof result}`, result);
      response.send(result);
    }
  );

  console.log('Service server ready');
  rclnodejs.spin(node);
}

createServiceServer().catch(console.error);