Repository files navigation

This ROS 2 Python packages are dedicated to wrapping theRobonomics parachain APIprovided byrobonomics-interfaceinto nodes of ROS 2. Robonomics is a decentralized cloud for storing digital twins of robotics andIoT 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 deviceswith parachain features. The logic behind the integration of a robotic device is that a unique address is createdfor 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 accessfiles by their unique hash; for convenient usage of IPFS,Pinata support included, whichallows 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)

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)

Make sure you have the following software installed:

• Linux OS distribution (tested onUbuntu 22.04.4)
• ROS 2 distribution (tested onHumble version)
• Python 3 (tested on 3.10.12)
• IPFS node (tested onIPFS 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)

1. Create directory for ROS 2 workspace and thesrc subdirectory:

   mkdir -p your_project_ws/srccd your_project_ws/src

2. Clone this repo tosrc 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. Fromyour_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

Before starting nodes, you need to set up a configuration filerobonomics_pubsub_params_template.yaml, which must beunique for each launched robot that needs to access Robonomics. Copy the template to any place convenient for you andfill in the required fields.

Pay attention to theaccount_seed andcrypto_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'tupload a config file with it to GitHub or anywhere else.

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

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

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

Thepinata_api_key andpinata_api_secret_key parameters are needed to access Pinata API.

(back to top)

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 todistinguish 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 datalogtransactions, 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 tothe 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 arecontrolled 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)

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

fromrobonomics_ros2_robot_handler.basic_robonomics_handlerimportBasicRobonomicsHandler...classYourRobotNode(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 inthe/robonomics_ros2_robot_handler/launch directory. This launch file takes two arguments:pubsub_params_path andnamespace.

(back to top)

• 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 canopen issue to request a function or ask for bug fix.

(back to top)

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)

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

(back to top)

Ivan Berman —@berman_ivan —fingerling42@proton.me

(back to top)

• robonomics-interface docs
• Best-README-Template

(back to top)