Robonomics ROS 2 Wrapper

Python packages with simple wrapper of Robonomics parachain functions for Robot Operating System 2

Table of Contents

1. About Project
   • Project Structure
2. Getting Started
   • Prerequisites
   • Installation and Building
   • Configuration
3. Usage
   • Testing with Turtlesim
   • Programming Your Wrapper Implementation
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About Project

This ROS 2 Python packages are dedicated to wrapping the Robonomics parachain API provided by robonomics-interface into nodes of ROS 2. Robonomics is a decentralized cloud for storing digital twins of robotics and IoT devices and control them through this network.

The goal of the project is to provide ROS 2 developers with a convenient way to integrate their robots or devices with parachain features. The logic behind the integration of a robotic device is that a unique address is created for it in the Robonomics parachain, which is used to control the device or receive its telemetry.

Available features include:

• Launch function — launching a device to execute any command with a specified set of parameters passed as a file.
• Datalog function — publishing any device data in a form of hash to parachain.
• Usage of Robonomics subscription — the ability to send transactions without a fee.
• Secure file storage — to pack and unpack data, InterPlanetary File System is used, which allows to access files by their unique hash; for convenient usage of IPFS, Pinata support included, which allows to pin IPFS files for fast downloading.
• File encryption and decryption — protection of files with public key encryption.

To learn more about Robonomics, please refer to the official documentation: wiki.robonomics.network.

(back to top)

Project Structure

For convenience, the project is divided into several ROS 2 packages:

.
├── config                                   
│   └── robonomics_pubsub_params_template.yaml    # Config file for account credentials, IPFS directory, etc.
├── robonomics_ros2_interfaces                    # A package that describes all types of ROS 2 services and messages
├── robonomics_ros2_pubsub                        # Main package for interaction with Robonomics
│   ├── ipfs_files                                # Default IPFS file storage directory
│   ├── robonomics_ros2_pubsub              
│   │   ├── utils                                 # Directory for various utility functions
│   │   ├── robonomics_ros2_pubsub.py             # Main node for creating ROS 2 services with Robonomics functions
│   │   └── ...
│   └── ...
├── robonomics_ros2_robot_handler                 # A package with templates of robot-specific wrapper implementations
│   ├── launch
│   │   └── robot_template_robonomics_launch.py   # A template for launch file
│   ├── robonomics_ros2_robot_handler
│   │   └── basic_robonomics_handler.py           # A base class for accessing the pubsub node finctions
│   └── ...
├── robots                                        # A directory with packages for robot-specific wrapper implementations
│   └── turtlesim_robonomics                      # A package with turtlesim example for testing
└── ...

(back to top)

Getting Started

Prerequisites

Make sure you have the following software installed:

• Linux OS distribution (tested on Ubuntu 22.04.4)
• ROS 2 distribution (tested on Humble version)
• Python 3 (tested on 3.10.12)
• IPFS node (tested on IPFS Kubo 0.26.0)
• Project specific Python modules can be installed via:

  pip install -r requirements.txt

For testing:

• Turtlesim package for your ROS2 version. For Humble:

  sudo apt install ros-humble-turtlesim

You also need to create an account on Robonomics parachain and write down seed phrase and account type. Make sure, that you have a free account balance to make transactions. The guide is available here: https://wiki.robonomics.network/docs/create-account-in-dapp

(back to top)

Installation and Building

1. Create directory for ROS 2 workspace and the src subdirectory:

   mkdir -p your_project_ws/src
   cd your_project_ws/src

2. Clone this repo to src directory:

   git clone https://github.com/airalab/robonomics-ros2.git

3. Then you can test the repository with turtlesim package or make your own robot-specific wrapper implementations. Anyway, after that you need to build the package. From your_project_ws directory run:

   colcon build

4. Source the package to the environment (you will need it to do in every console instance):

   source install/setup.bash

Configuration

Before starting nodes, you need to set up a configuration file robonomics_pubsub_params_template.yaml, which must be unique for each launched robot that needs to access Robonomics. Copy the template to any place convenient for you and fill in the required fields.

Pay attention to the account_seed and crypto_type fields, as they determine the account of your robot.

WARNING: The seed phrase is sensitive information that allows anyone to use your account. Make sure you don't upload a config file with it to GitHub or anywhere else.

If you want to use a custom Robonomics node or a local one, change the remote_node_url parameter.

If you have a Robonomics subscription that allows you to send transactions without fees, please insert the address of the subscription owner to the rws_owner_address field. Don't forget that your account must be added to your subscription.

You may also want to change the directory where the files for IPFS will be stored. To do this, change the parameter ipfs_dir_path, otherwise it will use the current directory. The ipfs_gateway parameter allows you to specify the gateway through which IPFS files will be downloaded.

The pinata_api_key and pinata_api_secret_key parameters are needed to access Pinata API.

(back to top)

Usage

Testing with Turtlesim

1. First, launch IPFS Daemon:

   ipfs daemon

2. Create two configuration files for two pubsub instances, each for a different Turtlesim.

3. Run the ROS 2 launch files for two turtle with different configuration files and namespaces (this is necessary to distinguish between identical nodes). They will launch all necessary nodes: Turtlesim itself, wrapper implementation for Turtlesim and Robonomics pubsub:

   ros2 launch turtlesim_robonomics turtlesim_robonomics_launch.py pubsub_params_path:=./turtlesim1_pubsub_params.yaml namespace:='turtlesim1'

   ros2 launch turtlesim_robonomics turtlesim_robonomics_launch.py pubsub_params_path:=./turtlesim2_pubsub_params.yaml namespace:='turtlesim2'

4. You will see the simulator with turtles and ROS 2 logs in the console with IPFS ID, path to directory with IPFS files, and Robonomics address. The node starts publish datalogs with turtles position every 2 min. You can check the datalog transactions, using, for example, Subscan explorer (just enter the Robonomics address).

5. In order for one of the turtle instance to receive the last datalog from another, call the following request to the service (do not forget to insert address):

   ros2 service call /turtlesim1/robonomics/receive_datalog robonomics_ros2_interfaces/srv/RobonomicsROS2ReceiveDatalog "{sender_address: 'TURTLE2_ADDRESS', datalog_file_name: 'test_name.json'}"

   A file with the position of one of the turtles will be downloaded to the IPFS directory.

6. The nodes also start waiting for every launch command, that will be sent to specified address. The turtles are controlled using /cmd_vel topic, so you need to prepare corresponding messages, that will go as a launch parameter. For convenience, these messages are prepared as JSON-file:

   [
     {
        "linear": {
           "x": 5.0,
           "y": 0.0,
           "z": 0.0
        },
        "angular": {
           "x": 0.0,
           "y": 0.0,
           "z": 1.5
        }
     },
     {
        "linear": {
           "x": 2.0,
           "y": 0.0,
           "z": 0.0
        },
        "angular": {
           "x": 0.0,
           "y": 0.0,
           "z": 2.5
        }
     }
   ]

   This JSON example will command the turtle to move twice.

7. Save this JSON to IPFS directory of some turtle and run the following:

   ros2 service call /turtlesim1/robonomics/send_launch robonomics_ros2_interfaces/srv/RobonomicsROS2SendLaunch {"param: 'test_name.json', target_address: 'TURTLE2_ADDRESS'"}

   Watch for the simulation, the turtle should start moving.

(back to top)

Programming Your Wrapper Implementation

When programming your own robot, you will need to create a robot-specific wrapper implementation based on prepared basic node class BasicRobonomicsHandler. Create your ROS 2 Python packages and import the following to your node:

from robonomics_ros2_robot_handler.basic_robonomics_handler import BasicRobonomicsHandler
...
class YourRobotNode(BasicRobonomicsHandler):

    def __init__(self) -> None:
        super().__init__()
...

The class has the structure shown in the figure below.

For the convenience of launching all nodes and pushing a common namespace to them, you can use the launch file template in the /robonomics_ros2_robot_handler/launch directory. This launch file takes two arguments: pubsub_params_path and namespace.

(back to top)

Roadmap

• Add basic datalog and launch functions
• Add IPFS support
• Add file encryption
• Add support for Robonomics subscription
• Add support for IPFS pinning service (Pinata)
• Add a selection of the IPFS gateway
• Add digital twin functionality
• Rosbag2 integration?

You can open issue to request a function or ask for bug fix.

(back to top)

Contributing

If you have a suggestion or correction, please feel free to participate! You should:

1. Fork the project
2. Add and commit your changes
3. Open a pull request

(back to top)

License

Distributed under the Apache-2.0 License. See LICENSE.txt for more information.

(back to top)

Contact

Ivan Berman — @berman_ivan — [email protected]

(back to top)

Acknowledgments

• robonomics-interface docs
• Best-README-Template

(back to top)