Fejemis ROS2 Software

Back to Fejemis_2026

Fejemis Software Overview

The Fejemis software is split into multiple components. The full ROS2 workspace and related repositories are available on GitHub: https://github.com/Melvin-Angel/Fejemis_Workspace_2026.git

Introduction

This documentation summarises the main software components used on the robot and explains how the system can be distributed across multiple Raspberry Pis (Multi‑Pi setup).

The two primary concerns are:

• Hardware bridge and low-level microcontroller integration (the Fejemis bridge).
• The ROS 2 software stack for mapping, perception, and high-level behaviours (the Fejemis ROS2 workspace).

In this page we focus on the ROS 2 software stack to learn more about the low-level microcontroller integration see Fejemis bridge and Fejemis repository

Fejemis

The top-level fejemis package is the entry point for the robot stack. It ties the bridge, description, map/localisation, simulation, and vision packages together and installs the main launch files for the complete system.

Launch files:

• launch/robot.launch.py - main bringup file for the real robot and multi-Pi setup. It starts the bridge control first and then launches odometry, LiDAR, SLAM, localisation, and vision depending on the selected options.
• launch/sim.launch.py - convenience entry point for simulation. It starts launch/robot.launch.py with in_sim=True.

Configurable parameters in launch/robot.launch.py:

• is_aux - marks whether the launch is running on the auxiliary Raspberry Pi. The default is detected automatically.
• in_sim - enables simulation mode.
• localization - runs RTAB-Map in localisation mode when true.
• map_location - selects the map database to load (lab or asta).
• enable_vision - enables the vision stack for people, cable, and net detection.

Fejemis Bridge

The fejemis_bridge package handles the low-level interface between the main Raspberry Pi and the Teensy controllers. It contains the serial bridge, the command mixer, and the joystick helper nodes used for manual control. See Fejemis Bridge ROS2 for more detailed information

Launch files:

• launch/bridge.launch.py - starts the bridge node itself.
• launch/mixer.launch.py - starts the command mixer and joystick input nodes.
• launch/control.launch.py - launches the full control side of the bridge stack and forwards the serial-device arguments.

Nodes in this package:

• bridge - main bridge executable, published in the fejemis namespace.
• raubase_core/rcmixer - command mixer that combines control inputs.
• joy/game_controller_node - joystick/gamepad input node.
• raubase_core/joy_control - joystick mode switch node.
• joy_brush_toggle.py - button toggle for the brush control.
• joy_linear_actuator.py - button toggle for the linear actuator.
• keyboard_teleop_rover.py - keyboard teleoperation node that publishes RoverCommand messages.
• twist_to_rover_command.py - adapter that converts Twist commands into RoverCommand messages.

Configurable parameters:

• front_device - serial device for the front Teensy controller.
• drive_device - serial device for the drive Teensy controller.
• log_level - logging level for the bridge node.
• in_sim and is_aux - forwarded through the control launch file to select the correct runtime path.
• Joystick helper settings such as joy_topic, steer_manage_topic, linear_actuator_topic, button_index, initial_brush_on, and initial_actuator_up.

Fejemis Description

The fejemis_description package provides the robot model and URDF/Xacro setup. It is responsible for publishing the robot description and state so the rest of the stack can use the same model. Fore more detailed information see Fejemis Description ROS2

Launch files:

• launch/model.launch.py - generates the URDF from the Xacro description and launches robot_state_publisher.

Nodes in this package:

• robot_state_publisher - publishes the robot TF tree from the generated robot_description.

Configurable parameters:

• use_sim_time - enables simulated time when running in Gazebo or another simulator.

Fejemis Sim

The fejemis_sim package contains the Gazebo simulation resources and the simulation bringup. It combines the robot description with the simulation world and connects ROS topics to Gazebo. For more detailed information see Fejemis Sim ROS2

Launch files:

• launch/sim.launch.py - starts the full simulation stack.

Nodes in this package:

• ros_gz_sim/create - spawns the robot in Gazebo from /robot_description.
• ros_gz_bridge/parameter_bridge - bridges ROS and Gazebo topics.
• raubase_core/rover_2_twist - optional adapter that converts rover commands into Twist commands for Gazebo.

Configurable parameters:

• world - world file to load, defaulting to fejemis_sim::worlds/room.world.
• rover_cmd_adapter - enables or disables the RoverCommand-to-Twist adapter.
• rviz - optional RViz flag provided by the launch file.

Fejemis Maploc

The fejemis_maploc package contains the mapping, localisation, navigation, and sensor bringup for the robot. It is the package that ties the RealSense camera, LiDAR, odometry, RTAB-Map, Nav2, and the behaviour-tree layer together. See Fejemis Maploc Ros2 for more detailed information

Launch files:

• launch/lidar.launch.py - starts the LiDAR driver and forwards the serial-port and container settings.
• launch/tf.launch.py - publishes the static transforms between the robot, camera, and LiDAR frames.
• launch/odometry.launch.py - launches the EKF and IMU filter for wheel and IMU odometry.
• launch/map.launch.py - starts the map server component for the local map container.
• launch/lifecycle.launch.py - starts the Nav2 lifecycle managers.
• launch/planning.launch.py - starts the Nav2 planning stack, path follower, behavior server, and coverage server.
• launch/behavior.launch.py - starts the BT engine and behavior-tree-related runtime nodes.
• launch/realsense.launch.py - starts the RealSense camera driver.
• launch/rtabmap_slam.launch.py - starts RTAB-Map SLAM or localisation.

Main nodes and components:

• imu_filter_madgwick_node - filters raw IMU data before fusion.
• robot_localization/ekf_node - fuses wheel odometry and IMU data.
• ldlidar_stl_ros2 LiDAR driver - publishes the laser scan used by navigation and SLAM.
• tf2_ros/static_transform_publisher - publishes the fixed camera and LiDAR transforms.
• depthimage_to_laserscan_node - converts the depth image to a laser scan for the costmaps.
• rtabmap_sync/rgbd_sync and rtabmap_odom/icp_odometry - prepare RGB-D data and odometry for RTAB-Map.
• rtabmap_slam/rtabmap - runs SLAM or localisation depending on the launch arguments.
• nav2_map_server::MapServer - provides the occupancy grid map.
• nav2_controller/controller_server, nav2_planner/planner_server, nav2_behaviors/behavior_server, and nav2_bt_navigator/bt_navigator - navigation and behaviour nodes.
• nav2_lifecycle_manager/lifecycle_manager - manages the Nav2 lifecycle transitions.
• fejemis_maploc/nav2_cmd_vel_deg_relay.py - relays Nav2 velocity commands into the robot control format.
• fejemis_maploc/brush_control_service.py - exposes the brush control service used by the planning stack.
• fejemis_maploc/complete_coverage_planner.py and fejemis_maploc/fixed_complete_coverage_planner.py - coverage planners for generating full-field coverage actions.
• fejemis_maploc/mission_trigger.py - publishes the cleaning mission and supporting blackboard values.
• fejemis_maploc/rviz_goal_relay.py - converts RViz goal clicks into NavigateToPose actions.
• opennav_coverage/opennav_coverage - optional coverage server when the coverage packages are available.

Configurable parameters:

• use_sim_time - switches the stack to simulated time.
• is_aux - used by the top-level bringup to decide which side of the multi-Pi setup launches the sensor stack.
• localization - selects between SLAM mode and localisation mode in RTAB-Map.
• map_location - selects which RTAB-Map database to load (lab or asta).
• enable_vision - enables the vision stack from the top-level bringup.
• enable_coverage - enables the coverage navigation components.
• namespace - namespace used by the SLAM and navigation nodes.
• port_name - serial port for the LiDAR.
• ld_make_container, ld_container, and ld_container_ns - control how the LiDAR node is placed in its component container.
• camera_namespace - namespace passed to the RealSense driver.
• world, rover_cmd_adapter, and rviz - simulation parameters forwarded from the top-level bringup.

Fejemis Vision

The fejemis_vision package provides the vision pipeline for the robot. In the current bringup, only the nodes launched from launch/main.launch.py are listed here. See Fejemis Vision ROS2 for more detailed information.

Nodes launched in launch/main.launch.py:

• tf2_ros/static_transform_publisher - publishes the test camera transform when both enable_vision and test_static_tf are true.
• rviz2/rviz2 - opens RViz with the vision configuration when enable_vision and open_rviz are true.
• fejemis_vision/main.py - runs the main vision node when enable_vision is true.

Configurable parameters:

• enable_vision - master switch for the vision stack.
• open_rviz - opens RViz for the vision stack when enabled.
• test_static_tf - adds a temporary static transform for camera frame testing.
• The main vision node also loads config/main.yaml and uses use_sim_time=False in this launch file.

Dependencies (src/deps)

The repository vendors a set of third-party and support packages under ``src/deps``. These are kept in-tree to ensure reproducible builds and known-good versions for Fejemis.

For a short index and per-package summaries see Dependencies Index.

Multi pi setup

This system supports a multi‑Pi arrangement where some hardware (for example, a RealSense camera or other sensors) runs on an auxiliary Raspberry Pi while the main robot and ROS 2 stack run on the primary Pi.

Recommended minimal steps for a Multi‑Pi setup:

1. Network and host setup

• Ensure all Pis are on the same local network (switch, VLAN or Wi‑Fi SSID) and can reach each other via IP.
• Prefer DHCP reservations or static IPs for each Pi to simplify configuration.

2. SSH and automation

• Install SSH keys on each Pi so you can run remote commands and automation without passwords.

3. Clone the workspace and install dependencies On each Pi that needs software from the repository, clone the workspace and run the provided install scripts:

 git clone https://github.com/Melvin-Angel/Fejemis_Workspace_2026.git
 cd Fejemis_Workspace_2026
 ./install.sh
 source ./activate.sh

4. Camera / sensor hosts

• If the camera is on an auxiliary Pi, run the camera driver or streaming node there and expose the expected ROS topics across the network.
• In this workspace the mapping components expect RealSense RGB‑D topics; when the camera is on an aux Pi you can launch the camera remotely. Example (run on the primary Pi to start the aux launch):

```bash fejemis launch_aux fejemis_maploc realsense.launch.py ```

5. Time sync and reliability

• Enable NTP or systemd‑timesyncd on all Pis so timestamps on messages line up for logging and perception.

Convenience commands

These helper commands make working with a two‑Pi setup easier.

• fejemis launch_aux — start a launch file on an auxiliary Pi from the primary Pi. This is commonly used to start camera or sensor nodes remotely. Example:

fejemis launch_aux fejemis robot.launch.py

• fejemis sync_clocks — synchronise system clocks across Pis (uses SSH and sudo on targets). Run this before recording or starting perception stacks so timestamps align. Example:

fejemis sync_clocks

ROS Network files

The bash scripts used for configuring the ROS 2 network are located in the bin/ directory:

• bash_setup.sh - Configures the ROS 2 network settings for the Main Raspberry Pi
• bash_setup_aux.sh - Configures the ROS 2 network settings for the Aux Raspberry Pi

These scripts set up:

• ROS 2 environment variables
• CycloneDDS configuration
• Static peer discovery
• Network interface binding for Ethernet communication

The scripts are automatically sourced during system startup, ensuring that the ROS 2 network is configured correctly whenever the Raspberry Pi units boot.

Additional information about Ethernet configuration and the required ROS 2 network setup on external computers can be found in the Electronics section.