{"id":15417049,"url":"https://github.com/blueandi/radonulzer","last_synced_at":"2025-10-30T01:12:37.304Z","repository":{"id":89190851,"uuid":"597561400","full_name":"BlueAndi/RadonUlzer","owner":"BlueAndi","description":"Line follower, platooning, sensor fusion with DroidControlSystem and etc.","archived":false,"fork":false,"pushed_at":"2024-10-20T21:17:09.000Z","size":5791,"stargazers_count":5,"open_issues_count":8,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-29T10:44:44.973Z","etag":null,"topics":["cpp11","line-follower","linefollower","platooning","robotics","sensor-fusion","webots","zumo32u4"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BlueAndi.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2023-02-04T22:54:52.000Z","updated_at":"2024-10-20T21:17:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"d28fcb6a-508e-4209-b38e-c5ebcb4c585c","html_url":"https://github.com/BlueAndi/RadonUlzer","commit_stats":{"total_commits":681,"total_committers":11,"mean_commits":61.90909090909091,"dds":0.6417033773861968,"last_synced_commit":"7d6399fe618e4d098cf6a659d63f1d21e2e0ad77"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueAndi%2FRadonUlzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueAndi%2FRadonUlzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueAndi%2FRadonUlzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BlueAndi%2FRadonUlzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BlueAndi","download_url":"https://codeload.github.com/BlueAndi/RadonUlzer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241439484,"owners_count":19963095,"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":["cpp11","line-follower","linefollower","platooning","robotics","sensor-fusion","webots","zumo32u4"],"created_at":"2024-10-01T17:14:29.502Z","updated_at":"2025-10-30T01:12:37.298Z","avatar_url":"https://github.com/BlueAndi.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Radon Ulzer - Firmware for Zumo32U4 \u003c!-- omit in toc --\u003e\r\n\r\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)\r\n[![Repo Status](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\r\n[![Release](https://img.shields.io/github/release/BlueAndi/RadonUlzer.svg)](https://github.com/BlueAndi/RadonUlzer/releases)\r\n[![Build Status](https://github.com/BlueAndi/RadonUlzer/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/BlueAndi/RadonUlzer/actions/workflows/main.yml)\r\n\r\nA robot as fast as the famous pod racer driven by Anakin Skywalker with the powerful engines from Radon Ulzer. :-)\r\n\r\nSeveral kind of exclusive applications are available:\r\n\r\n- Calib - Application used for motor speed calibration.\r\n- Convoy Leader - A line follower, providing information to the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip) in a convoy leader role.\r\n- Line Follower - A line follower, using a PID controller with extended algorithm.\r\n- Line Follower Simple - A simple line follower, using a PID controller.\r\n- Remote Control - The robot is remote controlled by e.g. the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip) in a convoy follower role.\r\n- Sensor Fusion - The robot provides odometry and inertial data to the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip), which calculates the sensor fusion based location information.\r\n\r\n## Table of content \u003c!-- omit in toc --\u003e\r\n\r\n- [The robot](#the-robot)\r\n- [The simulation](#the-simulation)\r\n  - [Installation](#installation)\r\n  - [The Webots library](#the-webots-library)\r\n  - [Build](#build)\r\n  - [Preparation](#preparation)\r\n  - [Run](#run)\r\n    - [Run with Webots launcher (recommended)](#run-with-webots-launcher-recommended)\r\n    - [Run without Webots launcher](#run-without-webots-launcher)\r\n    - [Run via terminal](#run-via-terminal)\r\n  - [Running the robot on track](#running-the-robot-on-track)\r\n  - [Communicate with the supervisor](#communicate-with-the-supervisor)\r\n  - [Communicate with the DroidControlShip](#communicate-with-the-droidcontrolship)\r\n  - [Simulation Performance Issue](#simulation-performance-issue)\r\n- [The target](#the-target)\r\n  - [Build and flash procedure](#build-and-flash-procedure)\r\n- [User Specific Configuration](#user-specific-configuration)\r\n- [OLED Display Support](#oled-display-support)\r\n- [The Applications](#the-applications)\r\n- [Documentation](#documentation)\r\n- [Used Libraries](#used-libraries)\r\n- [Issues, Ideas And Bugs](#issues-ideas-and-bugs)\r\n- [License](#license)\r\n- [Contribution](#contribution)\r\n\r\n## The robot\r\n\r\nThe main target of the firmware is the Pololu Zumo32U4 robot (see \u003chttps://www.pololu.com/category/129/zumo-robots-and-accessories\u003e) from Pololu.\r\n\r\n![deployment](http://www.plantuml.com/plantuml/proxy?cache=no\u0026src=https://raw.githubusercontent.com/BlueAndi/RadonUlzer/master/doc/architecture/uml/PhysicalView/Deployment.plantuml)\r\n\r\n## The simulation\r\n\r\nThe simulation is based on the open source robot simulator *Webots*. The application and the services are equal to the target firmware. Only the HAL is different in the simulation.\r\n\r\n- Website: \u003chttps://cyberbotics.com/#cyberbotics\u003e\r\n- Github: \u003chttps://github.com/cyberbotics/webots\u003e\r\n- Compatible webots versions:\r\n  - v2025a\r\n\r\nExample deployment of the remote control application:\r\n\r\n![deployment](http://www.plantuml.com/plantuml/proxy?cache=no\u0026src=https://raw.githubusercontent.com/BlueAndi/RadonUlzer/main/doc/architecture/uml/PhysicalView/RemoteControl/SimulationDeployment.plantuml)\r\n\r\n### Installation\r\n\r\n1. Install [Webots](https://cyberbotics.com).\r\n2. Setup for [external controllers](https://www.cyberbotics.com/doc/guide/running-extern-robot-controllers):\r\n    1. Set environment variable ```WEBOTS_HOME``` to installation directory of Webots.\r\n    2. Add to path:\r\n        - Linux: ```${WEBOTS_HOME}/lib/controller```\r\n        - Windows: ```%WEBOTS_HOME%\\lib\\controller```\r\n3. Install the native compiler toolchain:\r\n    - Linux: Install the gcc toolchain, depended on your distribution.\r\n    - Windows\r\n        - Install the [MSYS2](https://www.msys2.org) toolchain.\r\n        - Open MSYS2 shell.\r\n            - Update package database: ```pacman -Sy pacman```\r\n            - Install GCC: ```pacman -Sy mingw-w64-ucrt-x86_64-gcc```\r\n4. Ensure a current (\u003e=3.9) Python3 version is installed on your machine and on path.\r\n\r\n### The Webots library\r\n\r\nTo adapt the HAL to the simulation, some sourcecode files from Webots are necessary. Currently there is no Webots library in the platformio registry available. Therefore a local library is created during the build. Ensure that that Webots is already installed, before you try to build it!\r\n\r\nThe library creation is handled in the ```./scripts/create_webots_library.py``` script and runs automatically after building for the WebotsSim environment.\r\n\r\n### Build\r\n\r\n1. Start VSCode.\r\n2. PlatformIO project tasks --\u003e \u0026lt;APP-NAME\u0026gt; --\u003e General --\u003e Build\\\r\n    Example for **LineFollowerSim** application:\\\r\n  ![Example](./doc/images/pio_build.jpg)\r\n\r\nFor the simulation use only the applications with \"Sim\" as postfix, e.g. LineFollowerSim.\r\n\r\n### Preparation\r\n\r\nThe preparation is shown with the line follower application as example. It expects that the **LineFollowerSim** is already built.\r\n\r\n1. Start the Webots simulation.\r\n2. File --\u003e Open World\r\n3. Select ```./webots/worlds/LineFollowerTrack.wbt```.\r\n4. The loaded world should now look like this: ![webots_world](./doc/images/webots_world.jpg)\r\n5. The simulation waits now for the external controller, like the RadonUlzer.\r\n\r\n### Run\r\n\r\nThere are 3 ways how to run now the application. Choose according to your needs.\r\n\r\n#### Run with Webots launcher (recommended)\r\n\r\nChoose this one in case the simulation waits for more than one robot. Adapt the robot name in the *platformio.ini*.\r\n\r\nSee (Single Simulation and Multiple Local Extern Robot Controllers)[https://cyberbotics.com/doc/guide/running-extern-robot-controllers?tab-os=windows#single-simulation-and-multiple-local-extern-robot-controllers] for details.\r\n\r\nPlatformIO project tasks --\u003e \u0026lt;APP-NAME\u0026gt; --\u003e Custom --\u003e WebotsLauncher\r\n\r\nExample for **LineFollowerSim** application:\r\n\r\n![Example](./doc/images/pio_webots_launcher.jpg)\r\n\r\n#### Run without Webots launcher\r\n\r\nThis can be choosen in case the simulation waits just for one robot.\r\n\r\nPlatformIO project tasks --\u003e \u0026lt;APP-NAME\u0026gt; --\u003e General --\u003e Upload\r\n\r\nExample for **LineFollowerSim** application:\r\n\r\n![Example](./doc/images/pio_upload.jpg)\r\n\r\n#### Run via terminal\r\n\r\n1. Open a command line (shell) and change to the folder with the built executable in ```.pio/build/LineFollowerSim```. This folder contains all necessary shared libraries as well.\r\n2. Start the executable.\r\n\r\n### Running the robot on track\r\n\r\n1. Click in the simulation on the display to focus the simulation.\r\n2. Now the keyboard keys a, b and c can be used to control the robot according to the implemented application logic.\r\n\r\n### Communicate with the supervisor\r\n\r\nThe communication with the supervisor goes via a Webots serial connection, which is disabled by default.\r\n\r\nUse the -c flag to enable it with default channels (see *webots_supervisor_serial_rx_channel* and *webots_supervisor_serial_tx_channel* in [platformio.ini](./platformio.ini)).\r\n\r\n```bash\r\nprogram.exe -c\r\n```\r\n\r\nFor simplicity a Platformio project task was added, which enables the Webots serial connection as well.\r\n\r\n![Example](./doc/images/pio_webots_launcher_zumo_com_system.jpg)\r\n\r\n### Communicate with the DroidControlShip\r\n\r\nThe communication with the DroidControlShip goes via a Webots serial connection, which is disabled by default.\r\n\r\nUse the -c flag to enable it with default channels (see *webots_robot_serial_rx_channel* and *webots_robot_serial_tx_channel* in [platformio.ini](./platformio.ini)). Note, this will disable the standard logging, because the serial communication uses the SerialMuxProt procotol for data interchange.\r\n\r\n```bash\r\nprogram.exe -c\r\n```\r\n\r\nFor simplicity a Platformio project task was added, which enables the Webots serial connection as well.\r\n\r\n![Example](./doc/images/pio_webots_launcher_zumo_com_system.jpg)\r\n\r\n### Simulation Performance Issue\r\n\r\nBy default the Zumo robot in Webots looks beautiful, but has the drawback that the simulation performance might be bad depended on the host system.\r\n\r\nTo increase the performance, the robot model can be simplified by enabling the performance mode:\r\n\r\n1. Open Webots and load the world with the robot.\r\n2. Open the Zumo32U4 model in the tree on the left side.\r\n3. Set performanceMode to TRUE with the checkbox.\r\n\r\n## The target\r\n\r\n### Build and flash procedure\r\n\r\n1. PlatformIO project tasks --\u003e \u0026lt;APP-NAME\u0026gt; --\u003e General --\u003e Build\r\n    - For the target use only the applications with \"Target\" as postfix, e.g. LineFollowerTarget.\r\n2. Start the bootloader by triggering twice the reset button. The yellow led will start blinking for 10s. Note, after 10s the target will leave the bootloader!\r\n3. PlatformIO project tasks --\u003e \u0026lt;APP-NAME\u0026gt; --\u003e General --\u003e Upload\r\n4. Ready.\r\n\r\nExample for the **LineFollowerTarget** application:\r\n\r\n![Example](./doc/images/pio_target_build_upload.jpg)\r\n\r\n## User Specific Configuration\r\n\r\nChange your com port settings in the *platformio_override.ini* to your needs, as well as for simulation the robot name and the serial rx/tx channels.\r\n\r\n## OLED Display Support\r\n\r\nTo enable the OLED display support set the *CONFIG_USE_OLED_DISPLAY* in the *platformio_override.ini* to 1 otherwise to 0.\r\n\r\n## The Applications\r\n\r\n| Application | Description | Standalone | DroidControlShop Required | Webots World |\r\n| - | - | - | - | - |\r\n| Calib | Application used for motor speed calibration. | Yes | No | ./webots/worlds/LargeTrack.wbt  ./webots/worlds/LineFollowerTrack.wbt |\r\n| ConvoyLeader | A line follower, providing information to the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip) in a convoy leader role. | No | Yes | ./webots/worlds/zumo_with_com_system/PlatoonTrack.wbt |\r\n| ConvoyFollower | Convoy follower, providing information to the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip) to drive to its target. | No | Yes | ./webots/worlds/zumo_with_com_system/PlatoonTrack.wbt |\r\n| LineFollower | Just a line follower, using a PID controller with differential drive and odometry. | Yes | No | ./webots/worlds/ETrack.wbt  ./webots/worlds/LargeTrack.wbt  ./webots/worlds/LineFollowerTrack.wbt |\r\n| LineFollowerSimple | Just a simple line follower, using a PID controller. | Yes | No | ./webots/worlds/ETrack.wbt  ./webots/worlds/LargeTrack.wbt  ./webots/worlds/LineFollowerTrack.wbt |\r\n| RemoteControl | The robot is remote controlled by e.g. the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip) in a convoy follower role. | No | Yes | ./webots/world/zumo_with_com_system/* |\r\n| SensorFusion | The robot provides odometry and inertial data to the [DroidControlShip](https://github.com/BlueAndi/DroidControlShip), which calculates the sensor fusion based location information. | No | Yes | ./webots/worlds/zumo_with_com_system/LineFollowerTrack.wbt |\r\n| Test | Only for testing purposes on native environment. | Yes | No | N/A |\r\n\r\n## Documentation\r\n\r\n- [SW Architecture](./doc/architecture/README.md)\r\n- [SW Configuration](./doc/configuration/README.md)\r\n\r\n## Used Libraries\r\n\r\n| Library                                                            | Description                                          | License |\r\n| ------------------------------------------------------------------ | ---------------------------------------------------- | ------- |\r\n| [ArduinoNative](https://github.com/BlueAndi/ArduinoNative)         | The Arduino for native environment.                  | MIT     |\r\n| [SerialMuxProt](https://github.com/gabryelreyes/SerialMuxProt)     | Multiplexing Communication Protocol                  | MIT     |\r\n| [ZumoHALATmega32u4](https://github.com/BlueAndi/ZumoHALATmega32u4) | C++ HAL for ATmega32u4 on the Pololu Zumo32u4        | MIT     |\r\n| [ZumoHALInterfaces](https://github.com/BlueAndi/ZumoHALInterfaces) | Abstract C++ HAL interfaces                          | MIT     |\r\n| [ZumoHALWebots](https://github.com/BlueAndi/ZumoHALWebots)         | C++ HAL for Webots simulation of the Pololu Zumo32u4 | MIT     |\r\n\r\n## Issues, Ideas And Bugs\r\n\r\nIf you have further ideas or you found some bugs, great! Create a [issue](https://github.com/BlueAndi/RadonUlzer/issues) or if you are able and willing to fix it by yourself, clone the repository and create a pull request.\r\n\r\n## License\r\n\r\nThe whole source code is published under the [MIT license](http://choosealicense.com/licenses/mit/).\r\nConsider the different licenses of the used third party libraries too!\r\n\r\n## Contribution\r\n\r\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any\r\nadditional terms or conditions.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueandi%2Fradonulzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblueandi%2Fradonulzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblueandi%2Fradonulzer/lists"}