Hack Johnny Lab

ROS 2 package for the Hack Johnny's Lab quest: TurtleBot 4 navigation mission, OAK-D video recording, and Robonomics/IPFS result publishing

Table of Contents

1. About Project
   • Project Structure
   • Project Architecture
2. Getting Started
   • Prerequisites
   • Installation and Building
   • Configuration
3. Usage
4. License
5. Media About Project
6. Contact
7. Acknowledgments

About Project

Hack Johnny Lab is a ROS 2 Python package that implements the main robot logic used in the Hack Johnny's Lab quest by Robonomics.

The goal of the project is to execute a full autonomous TurtleBot 4 mission in the lab, generate game artifacts, and publish results through Robonomics:

• receive a launch task containing seed data
• run navigation through predefined waypoints (with random word-to-point mapping)
• record video from OAK-D camera
• save mission data (data.json) and package all artifacts into an archive
• publish archive info via Robonomics datalog pipeline

(back to top)

Project Structure

.
├── config
│   ├── turtlebot4_localization.yaml     # AMCL + map server localization parameters
│   └── turtlebot4_nav2.yaml             # Nav2 stack parameters (planner/controller/costmaps/etc.)
├── launch
│   ├── johnny_lab_launch.py             # Starts Robonomics pubsub + robot handler + lifecycle navigator
│   └── localization_and_nav.launch.py   # Includes TurtleBot4 localization and Nav2 launch files
├── turtlebot4_johnny_lab
│   ├── johnny_lab_navigator.py          # Lifecycle node: mission execution, navigation, video, archive
│   ├── johnny_lab_robonomics.py         # Robonomics handler: launch processing + datalog sending
│   └── ...
└── ...

(back to top)

Project Architecture

The system is organized as three connected layers, where ROS 2 runtime and Web3 services cooperate in one mission pipeline.

1. Robot mission layer (ROS 2 / TurtleBot 4 stack) johnny_lab_navigator is a lifecycle node with states configure -> activate -> deactivate -> cleanup. In these states it:
   • loads mission inputs (seed file path, waypoint configuration)
   • undocks and initializes localization (initial pose + calibration rotations)
   • navigates through route points (NavigateToPose)
   • records mission video from OAK-D (depthai + av)
   • returns to dock, packs artifacts, and publishes archive file name to ROS topic johnny_lab_navigator/archive_name

2. Bridge layer (ROS 2 + Web3 / Robonomics wrapper) robonomics_ros2_pubsub provides launch/datalog and IPFS access for ROS nodes. johnny_lab_robonomics (robot handler) receives launch payloads, prepares mission file for navigator, drives lifecycle transitions via /johnny_lab_navigator/change_state, and sends final archive reference as Robonomics datalog.

3. Application layer (Web3 agents) External agents (Discord bot, dApp, users) create mission demand, read published outputs, and use resulting data in the game flow.

Mission output artifacts:

• Archive file name format: johnny_lab_archive_<DD-MM-YYYY-HH-MM-SS>.zip
• Archive location: in ipfs_dir_path configured and used by Robonomics pubsub
• Archive contents:
  • data.json with:
    • points: coordinates associated with mission stops
    • words: shuffled seed words collected during the run
  • johnny_lab_record.mp4: mission video recorded from OAK-D

Full system scheme:

In the Hack Johnny's Lab game, this architecture allowed the bot to trigger a real robot run, the robot to autonomously produce evidence (video + shuffled seed words), and Robonomics to deliver verifiable mission results back to players through Web3 infrastructure.

(back to top)

Getting Started

Prerequisites

Make sure the following base components are installed and available:

• Linux OS distribution (tested on Ubuntu 22.04.4)
• ROS 2 distribution (tested on Humble)
• Python 3 (tested on 3.10.12)
• TurtleBot 4 software stack (including turtlebot4_navigation)
• Robonomics ROS 2 Wrapper packages
• depthai and av Python packages (used by OAK-D video pipeline)

(back to top)

Installation and Building

1. Complete the baseline TurtleBot 4 setup: https://turtlebot.github.io/turtlebot4-user-manual/setup/basic.html

2. Create a ROS 2 workspace:

   mkdir -p ~/johnny_lab_ws/src
   cd ~/johnny_lab_ws/src

3. Clone this repository:

   git clone https://github.com/Fingerling42/hack-johnny-lab.git

4. Build from workspace root:

   cd ~/johnny_lab_ws
   colcon build

5. Source workspace:

   source install/setup.bash

(back to top)

Configuration

Prepare these inputs before running the mission:

1. Map file for localization launch (e.g. johnny_lab_map.yaml).
2. Navigator parameters YAML with initial pose and waypoint set (navigator_params_path).
3. Robonomics pubsub parameters YAML (pubsub_params_path) with account/IPFS/subscription settings.

Expected navigator parameter structure:

init:
  position: [x, y]
  rotation: 0.0
points:
  1:
    position: [x, y]
    rotation: 0.0
  2:
    position: [x, y]
    rotation: 0.0
  ...

Notes:

• number of route points should match seed phrase words used in the mission logic
• johnny_lab_launch.py supports a namespace launch argument

(back to top)

Usage

Typical flow used in the project:

1. Build a map (SLAM):

ros2 launch turtlebot4_navigation slam.launch.py params:=./turtlebot4_slam.yaml

2. Save map:

ros2 service call /slam_toolbox/save_map slam_toolbox/srv/SaveMap "name:
  data: 'johnny_lab_map'"

3. Start localization and Nav2 with the map:

ros2 launch turtlebot4_johnny_lab localization_and_nav.launch.py map:=./johnny_lab_maps/johnny_lab_map.yaml

4. Start mission stack:

ros2 launch turtlebot4_johnny_lab johnny_lab_launch.py \
  pubsub_params_path:=./robonomics_pubsub_params.yaml \
  namespace:='johnny_lab_navigator' \
  navigator_params_path:=./johnny_lab_params.yaml

(back to top)

License

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

(back to top)

Media About Project

• Quest rules and context: Blog post
• Post-game analysis: Blog post

(back to top)

Contact

Ivan Berman - @berman_ivan - fingerling42@proton.me

(back to top)

Acknowledgments

• Best-README-Template
• TurtleBot 4 Documentation
• Robonomics ROS 2 Wrapper

(back to top)