{"id":28759451,"url":"https://github.com/niryorobotics/ned-ros2-driver","last_synced_at":"2025-06-17T05:06:58.040Z","repository":{"id":298275939,"uuid":"994626997","full_name":"NiryoRobotics/ned-ros2-driver","owner":"NiryoRobotics","description":"A ROS2 driver package that bridges ROS1 interfaces on Niryo NED robots to ROS2 interfaces, enabling seamless integration with modern ROS2 applications while maintaining compatibility with the robot's ROS1-based control system.","archived":false,"fork":false,"pushed_at":"2025-06-10T08:26:20.000Z","size":10741,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-10T09:33:31.333Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NiryoRobotics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-02T08:26:40.000Z","updated_at":"2025-06-10T08:26:23.000Z","dependencies_parsed_at":"2025-06-10T09:48:20.527Z","dependency_job_id":null,"html_url":"https://github.com/NiryoRobotics/ned-ros2-driver","commit_stats":null,"previous_names":["niryorobotics/ned-ros2-driver"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/NiryoRobotics/ned-ros2-driver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiryoRobotics%2Fned-ros2-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiryoRobotics%2Fned-ros2-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiryoRobotics%2Fned-ros2-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiryoRobotics%2Fned-ros2-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NiryoRobotics","download_url":"https://codeload.github.com/NiryoRobotics/ned-ros2-driver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NiryoRobotics%2Fned-ros2-driver/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260294464,"owners_count":22987623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-17T05:06:57.072Z","updated_at":"2025-06-17T05:06:57.992Z","avatar_url":"https://github.com/NiryoRobotics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Niryo NED ROS2 Driver\n\nA ROS2 driver package that bridges ROS1 interfaces on Niryo NED robots to ROS2 interfaces, enabling seamless integration with modern ROS2 applications while maintaining compatibility with the robot's ROS1-based control system.\n\n[![Code Quality](https://img.shields.io/badge/Code%20Quality-Ruff-blue)](https://github.com/astral-sh/ruff)\n[![License](https://img.shields.io/badge/License-BSD--3--Clause-green.svg)](LICENSE)\n\n- [Niryo NED ROS2 Driver](#niryo-ned-ros2-driver)\n  - [Overview](#overview)\n  - [System Architecture](#system-architecture)\n    - [Design Philosophy](#design-philosophy)\n    - [Components](#components)\n    - [Communication Flow](#communication-flow)\n  - [Installation](#installation)\n    - [Prerequisites](#prerequisites)\n    - [Building from Source](#building-from-source)\n  - [Usage](#usage)\n    - [Using the Launch File](#using-the-launch-file)\n      - [Configuring Robot Connections](#configuring-robot-connections)\n      - [Launching the driver](#launching-the-driver)\n      - [Interface whitelisting](#interface-whitelisting)\n        - [Settings whitelists via command line](#settings-whitelists-via-command-line)\n        - [Using a Whitelist YAML File](#using-a-whitelist-yaml-file)\n        - [Whitelist behavior](#whitelist-behavior)\n    - [Running the node directly](#running-the-node-directly)\n    - [Verify connections](#verify-connections)\n  - [Interfaces](#interfaces)\n    - [Topics](#topics)\n    - [Services](#services)\n    - [Actions](#actions)\n  - [Limitations](#limitations)\n  - [Troubleshooting](#troubleshooting)\n    - [Common Issues](#common-issues)\n  - [License](#license)\n  - [Acknowledgments](#acknowledgments)\n\n\n## Overview\n\nThe `niryo_ned_ros2_driver` package provides a bridge between ROS1 and ROS2, allowing ROS2 clients to communicate with the Niryo NED robot which runs on ROS1. This driver handles:\n\n- Topic mapping between ROS1 and ROS2\n- Service mapping between ROS1 and ROS2\n- Action mapping between ROS1 and ROS2\n- Special handling for TF transformations\n- Multiple robot connections\n\n## System Architecture\n\n### Design Philosophy\n\nThe driver is designed with these principles in mind:\n\n1. **Transparency**: Almost each ROS1 interface has a corresponding ROS2 interface with the same name and functionality. Interfaces that have no equivalent on the ROS2 side are blacklisted.\n2. **Efficiency**: Only subscribed interfaces are bridged to minimize network traffic.\n3. **Configurability**: Interfaces can be filtered based on user-defined whitelists.\n\n### Components\n\nThe package consists of these main components:\n\n- **ROS2Driver**: Main class that handles connection to the robot and interface registration.\n- **Topic**: Maps ROS1 topics to ROS2 topics (and vice versa).\n- **Service**: Maps ROS1 services to ROS2 services.\n- **Action**: Maps ROS1 actions to ROS2 actions.\n- **StaticTFTopic**: Special handler for static TF transformations.\n\n### Communication Flow\n\n```\nROS2 Client ↔ niryo_ned_ros2_driver (Remote computer) ↔ ROSBridge Server (Robot side) ↔ Niryo NED Robot stack (ROS1)\n```\n\nMessages and requests pass through this chain in both directions, with appropriate message type conversions handled by the driver.\n\n## Installation\n\n### Prerequisites\n\nThe driver has been tested on this setup:\n- ROS2 Jazzy Jellyfish\n- Python 3.12.3\n\nIt should work seemlessly with older version of ROS2. If it is not the case, don't hesitate to contact us.\n\n### Building from Source\n\n1. Create a ROS2 workspace:\n   ```bash\n   mkdir -p ~/ros2_drivers_ws/src\n   cd ~/ros2_drivers_ws/src\n   git clone https://github.com/NiryoRobotics/ned-ros2-driver.git\n   ```\n\n2. Install dependencies:\n   ```bash\n   cd ~/ros2_drivers_ws\n   rosdep install --from-paths src --ignore-src -r -y\n   ```\n\n3. Create a Python virtual environment (recommended):\n   ```bash\n   python3 -m venv venv --system-site-packages\n   source venv/bin/activate\n   pip install -r src/requirements.txt\n   ```\n\n4. Build the package:\n   ```bash\n   source /opt/ros/jazzy/setup.bash\n   colcon build\n   ```\n\n## Usage\n\nThe ROS2 driver can be used either through the provided launch file or by directly running the node. The driver is designed to connect to one or multiple Niryo robots simultaneously.\n\n### Using the Launch File\n\nThe launch file provides a convenient way to start one or more driver instances with customizable parameters.\n\n#### Configuring Robot Connections\n\nThe driver uses a YAML configuration file to specify which robots to connect to. The default location is `config/drivers_list.yaml`:\n\n```yaml\nrosbridge_port: 9090\nrobot_namespaces:\n  - \"robot1\"\n  - \"robot2\"\nrobot_ips:\n  - \"\u003crobot_model\u003e-\u003crobot_id\u003e.local\" # If you know the hostname of your robot (Recommended)\n  - \"192.168.1.101\"\n```\n- **rosbridge_port**: The port number for the ROSBridge server (same port used for all robots).\n- **robot_namespaces**: List of namespaces for each robot (must be the same length as robot_ips).\n- **robot_ips**: List of IP addresses of the robots to connect to. It is recommended to use the robot's hostname (`\u003crobot_model\u003e-\u003crobot_id\u003e.local` with `robot_id` in the form `aa-bbb-ccc`) if known since it will never be modified even if the robot's Ip change.\n\nFor a single robot with no namespace, you can use:\n```yaml\nrosbridge_port: 9090\nrobot_namespaces:\n  - \"\"  # Empty string for no namespace\nrobot_ips:\n  - \"\u003crobot_model\u003e-\u003crobot_id\u003e.local\"\n```\n\n#### Launching the driver\n\n1. Source the workspace:\n```bash\nsource ~/ros2_drivers_ws/install/setup.bash\n```\n\n2. Launch the driver with default settings:\n```bash\nros2 launch niryo_ned_ros2_driver driver.launch.py\n```\n\nThis will use the default [drivers_list.yaml](niryo_ned_ros2_driver/config/drivers_list.yaml) located in the package's config directory.\n\n3. Launch the driver with a custom configuration file:\n```bash\nros2 launch niryo_ned_ros2_driver driver.launch.py drivers_list_file:=path/to/my_drivers_list.yaml\n```\n\n#### Interface whitelisting\n\nThe driver uses whitelists to filter which ROS interfaces (topics, services, actions) are bridged between ROS1 and ROS2. This helps reduce network traffic and processing overhead.\nBy default, all compatible interfaces are whitelisted.\n\n##### Settings whitelists via command line\n\nYou can specify whitelist patterns directly when launching the driver:\n```bash\nros2 launch niryo_ned_ros2_driver driver.launch.py \\\n    topic_whitelist:=['\"/joint_states\"', '\"/tf.*\"', '\"/hardware_status\"'] \\\n    service_whitelist:=['\"/calibrate.*\"'] \\\n    action_whitelist:=['\"/.*trajectory\"']\n```\n\n##### Using a Whitelist YAML File\n\nFor more complex configurations, create a YAML file like the one provided [whitelist.yaml](niryo_ned_ros2_driver/config/whitelist.yaml)\n```yaml\n/**:\n  ros__parameters:\n    topic_whitelist:\n      - \"/joint_states\"\n      - \"/tf.*\"\n      - \"/hardware_status\"\n\n    service_whitelist:\n      - \"/calibrate_motors\"\n      - \"/get_.*\"\n      - \"/set_.*\"\n\n    action_whitelist:\n      - \"/follow_joint_trajectory\"\n      - \"/robot_action\"\n```\n\nAnd use it when launching the driver:\n```bash\nros2 launch niryo_ned_ros2_driver driver.launch.py whitelist_params_file:=path/to/whitelist.yaml\n```\n##### Whitelist behavior\n\n- Each whitelist entry is treated as a regular expression (regex)\n- An entry like \".*\" matches everything (the default)\n- More specific patterns like \"/joint_states\" match exactly that interface\n- Patterns like \"/tf.*\" match anything starting with \"/tf\"\n- If an interface doesn't match any whitelist pattern, it won't be bridged\n\n### Running the node directly\n\nFor more control or scripting purposes, you can run the ROS2 driver node directly:\n```bash\nros2 run niryo_ned_ros2_driver ros2_driver --ros-args \\\n    -p robot_ip:=ned2-aa-bbb-ccc.local \\\n    -p robot_namespace:=robot1 \\\n    -p rosbridge_port:=9090 \\\n    -p topic_whitelist:=['\"/joint_states\"', '\"/tf\"', '\"/hardware_status\"'] \\\n    -p service_whitelist:=['\"/calibrate_motors\"', '\"/get_pose\"'] \\\n    -p action_whitelist:=['\"/follow_joint_trajectory\"']\n```\n\nThis approach is useful for programmatically starting drivers or when you need to control exactly the configuration of each running driver.\n\n### Verify connections\n\nTo check if your drivers are connected and working:\n1. List running nodes\n```bash\nros2 node list\n```\nYou should see a node for each robot with their namespaces, e.g.: `/ros2_driver_robot1`, `/ros2_driver_robot2` or if running only one drivr `/ros2_driver_default`\n\n2. View available topics\n```bash\nros2 topic list\n```\n3. Check topic data for a specific robot:\n``` bash\nros2 topic echo /joint_states # or /\u003cyour_bot_namespace\u003e/joint_states if you specified a namespace\n```\n\n## Interfaces\n\nThe driver bridges all topics, services, and actions from the Niryo NED robot to ROS2, preserving their original names. Here are some key interfaces:\n\n### Topics\n\n| Topic | Type | Description |\n|-------|------|-------------|\n| `/joint_states` | sensor_msgs/msg/JointState | Current robot joint states |\n| `/niryo_robot_hardware_interface/hardware_status` | niryo_ned_ros2_interfaces/msg/HardwareStatus | Robot hardware status |\n| `/tf` | tf2_msgs/msg/TFMessage | Dynamic transformation frames |\n| `/tf_static` | tf2_msgs/msg/TFMessage | Static transformation frames |\n| `/niryo_robot/robot_state` | niryo_ned_ros2_interfaces/msg/RobotState | Current end effector pose |\n| `/niryo_robot_status/robot_status` | niryo_ned_ros2_interfaces/msg/RobotStatus | Current robot status |\n\n### Services\n\n| Service | Type | Description |\n|---------|------|-------------|\n| `/niryo_robot/joints_interface/calibrate_motors` | niryo_ned_ros2_interfaces/srv/SetInt | Calibrate robot motors (Ned2 only) |\n| `/niryo_robot_tools_commander/set_tcp` | niryo_ned_ros2_interfaces/srv/SetTCP | Set a new TCP transform and activate it | \n| `/niryo_robot_tools_commander/enable_tcp` | niryo_ned_ros2_interfaces/srv/SetBool | Enable or disable the TCP  |\n| `/niryo_robot_rpi/get_digital_io` | niryo_ned_ros2_interfaces/srv/GetDigitalIO | Get state of digital IOs |\n| `/niryo_robot_rpi/set_digital_io` | niryo_ned_ros2_interfaces/srv/SetDigitalIO | Set state of a digital IO |\n| `/niryo_robot_rpi/get_analog_io` | niryo_ned_ros2_interfaces/srv/GetAnalogIO | Get state of analog IO |\n| `/niryo_robot_rpi/set_analog_io` | niryo_ned_ros2_interfaces/srv/SetAnalogIO | Set state of a analog IO |\n\n### Actions\n\n| Action | Type | Description |\n|--------|------|-------------|\n| `/niryo_robot_follow_joint_trajectory_controller/follow_joint_trajectory` | control_msgs/action/FollowJointTrajectory | Execute joint trajectory |\n| `/niryo_robot_arm_commander/robot_action` | niryo_ned_ros2_interfaces/action/RobotMove | Execute a robot motion using the high-level robot arm commander |\n| `/niryo_robot_tools_commander/action_server` | niryo_ned_ros2_interfaces/action/Tool | Execute a a tool command |\n\n\nFor more informations about the available interfaces, please refer to [the Ned's ROS documentation](https://niryorobotics.github.io/ned_ros/).\n\n## Limitations\n\n1. **Message Compatibility**: Some complex message types might have fields only available in either ROS1 or ROS2. These fields will be ignored.\n2. **Network Dependencies**: Requires a stable network connection to the robot.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Cannot connect to ROSBridge server**:\n   - Ensure the robot is powered on and connected to the network\n   - Verify the IP address and port are correct\n   - Check if the ROSBridge server is running on the robot (You can use try to connect using [NiryoStudio](https://niryo.com/niryostudio/) which also uses ROSbridge for the communication)\n\n2. **Topics/services not appearing in ROS2**:\n   - Check if they're included in your whitelist configuration\n   - Verify the topics exist on the ROS1 side on the robot using `rostopic list`\n\n## License\n\nThis project is licensed under the BSD-3-Clause License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Niryo for the Niryo NED robot platform\n- ROSBridge developers for enabling ROS1-ROS2 communication: [Rosbridge](https://github.com/RobotWebTools/rosbridge_suite)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniryorobotics%2Fned-ros2-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fniryorobotics%2Fned-ros2-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fniryorobotics%2Fned-ros2-driver/lists"}