Direct ROS Access

For advanced use cases requiring fine-grained control beyond SDK abstractions, you can access ROS directly using two approaches:

Approach	Languages	Use Case
ROSLib/roslibpy	JavaScript, Python	WebSocket-based access via rosbridge - service calls, topic introspection
Native rclpy	Python only	Direct ROS2 access - custom nodes, QoS profiles, action servers

Understanding Execution Environments

The approach you choose depends on where your code runs:

SDK Playground (code runs on the appliance): Both approaches work seamlessly. Your code is deployed to and executed on the appliance, which has the full ROS2 environment. Whether you use ROSLib/roslibpy or native rclpy, both will "just work" because the code runs locally on the appliance.

Standalone SDK (code runs on your machine): Only ROSLib/roslibpy works in this scenario. The WebSocket-based approach communicates with the robot over the network via rosbridge. Native rclpy requires the ROS2 runtime environment, which isn't available on your development machine unless you've installed ROS2 locally.

Hybrid Approach: Sometimes you need the best of both worlds - write a performance-critical or complex script using native rclpy (for QoS control, custom nodes, etc.), save it as a script on the appliance, then invoke it from your standalone application using the SDK's script execution methods. This gives you:

Full rclpy capabilities for the robot-side logic
Remote triggering and orchestration from any SDK client

// Standalone client invoking an rclpy-based script saved on the appliance
await oloClient.core.executeScript('advanced-sensor-fusion');

ROSLib/roslibpy (WebSocket Access)

Access the underlying rosbridge connection directly to use native methods and services.

Language	Property	Returns
JavaScript	`oloClient.core.ros`	ROSLIB.Ros instance
Python	`oloclient.ros`	roslibpy.Ros instance

JavaScript Example

// Access the ROSLIB.Ros connection
const ros = oloClient.core.ros;

if (ros && ros.isConnected) {
    // Use ROSLIB methods directly
    ros.getServices((services) => {
        console.log('Available services:', services);
    });
    
    // Call services directly
    const service = new ROSLIB.Service({
        ros: ros,
        name: '/rosapi/nodes',
        serviceType: 'rosapi/Nodes'
    });
    
    const request = new ROSLIB.ServiceRequest({});
    service.callService(request, (response) => {
        console.log('Nodes:', response.nodes);
    });
}

Python Example (roslibpy)

roslibpy uses callback-based APIs, so we need async wrappers to use them in SDK Playground:

Python:Switch to Python to view sample code

Complete Example: For comprehensive examples of using ROSLib/roslibpy directly, see the SDK Playground example "List Nodes, Services and Parameters (ROSLIB)".

Native rclpy (Python Only)

Python scripts can use rclpy directly for native ROS2 programming - bypassing SDK abstractions when you need fine-grained control over publishers, subscribers, services, transforms, QoS profiles, or other ROS2 features. The SDK provides helper functions for lifecycle management and clean shutdown.

ROS2 Helper Functions

These functions are automatically available in Python scripts:

Function	Description
`rclpy_init()`	Initialize ROS2 context (safe to call multiple times)
`rclpy_create_node(NodeClass, args, *kwargs)`	Create a node instance and register for cleanup
`rclpy_spin_once(node, timeout_sec=0.01)`	Spin node once, returns `False` if should stop
`rclpy_ok()`	Check if ROS2 context is valid and not aborted
`is_aborted()`	Check if script stop was requested
`rclpy_shutdown()`	Cleanup all nodes and shutdown (called automatically)

Basic Pattern

Python:Switch to Python to view sample code

Why Use Helpers vs Raw rclpy?

The helpers solve common issues with ROS2 in the SDK Playground:

Clean shutdown - rclpy_shutdown() is called automatically when scripts stop, preventing "context already shutdown" errors
Abort handling - rclpy_ok() and rclpy_spin_once() check for stop requests, allowing graceful termination
Node tracking - rclpy_create_node() registers nodes for automatic cleanup

Without helpers (not recommended):

Python:Switch to Python to view sample code

When to Use Direct ROS Access

ROSLib/roslibpy (WebSocket):

Standalone SDK applications running outside the ROS environment
Advanced ROS operations not covered by OLO SDK wrappers
Custom service calls with specific message types
Direct parameter manipulation
Low-level ROS debugging and introspection

Native rclpy (Python):

Creating custom publishers/subscribers with specific QoS profiles
Implementing ROS2 services or action servers
Building image processing pipelines with direct topic access
Advanced sensor fusion requiring precise timing control
Prototyping ROS2 node logic before deployment

Remember: rclpy only works in SDK Playground (where code runs on the appliance). For standalone applications, use ROSLib/roslibpy, or create rclpy scripts that you invoke remotely via the SDK.

Note: For most use cases, prefer the SDK wrapper methods (oloclient.core.list_services(), oloclient.core.list_nodes(), etc.) which provide async/await support and consistent error handling.

See SDK Playground examples: "List Nodes, Services and Parameters (ROSLIB)", "Full ROS2 Node Demo", "Direct Image Pipeline", and "Tactical Vision HUD".

On This Page

Getting Started

API Reference

Standalone Client Development