{"id":30886886,"url":"https://github.com/discower/bsk-ros2-bridge","last_synced_at":"2025-09-08T13:52:33.523Z","repository":{"id":309704104,"uuid":"950736671","full_name":"DISCOWER/bsk-ros2-bridge","owner":"DISCOWER","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-13T09:48:44.000Z","size":206,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-13T11:39:04.654Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DISCOWER.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,"zenodo":null}},"created_at":"2025-03-18T15:59:03.000Z","updated_at":"2025-08-13T09:48:50.000Z","dependencies_parsed_at":"2025-08-13T11:39:06.697Z","dependency_job_id":"87e6501c-6898-4a35-bdb9-702b00e59b71","html_url":"https://github.com/DISCOWER/bsk-ros2-bridge","commit_stats":null,"previous_names":["discower/bsk-ros2-bridge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/DISCOWER/bsk-ros2-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DISCOWER%2Fbsk-ros2-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DISCOWER%2Fbsk-ros2-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DISCOWER%2Fbsk-ros2-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DISCOWER%2Fbsk-ros2-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DISCOWER","download_url":"https://codeload.github.com/DISCOWER/bsk-ros2-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DISCOWER%2Fbsk-ros2-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274196102,"owners_count":25239148,"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","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-09-08T13:52:31.587Z","updated_at":"2025-09-08T13:52:33.510Z","avatar_url":"https://github.com/DISCOWER.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Basilisk-ROS2 Bridge\n\nA ROS2 package that bridges the [Basilisk astrodynamics simulator](https://hanspeterschaub.info/basilisk/) with ROS 2, enabling real-time spacecraft simulation and control. Uses ZeroMQ for high-performance, low-latency communication.\n\n## Components\n\n- **Bridge Node** (`bsk-ros2-bridge.py`) - ROS 2 node that handles ZMQ\u003c-\u003eROS2 message conversion\n- **Handler Module** (`bsk_module/rosBridgeHandler.py`) - Basilisk module for scenario integration\n- **Example Scenarios** - Four example configurations demonstrating single/multi-spacecraft control\n\n## Tested Configurations\n\nThis package has been successfully built and exercised on the following configurations:\n\n| Environment                                | ROS 2 Distro             | Basilisk Build  | Details \u0026 Notes                                                     |\n|--------------------------------------------|--------------------------|-----------------|----------------------------------------------------------------------|\n| Ubuntu 22.04 LTS                           | ROS 2 Humble             | Linux           | Native desktop─full build, CLI tools, and launch files tested        |\n| Ubuntu 24.04 LTS                           | ROS 2 Jazzy              | Linux           | Native desktop─full build, CLI tools, and launch files tested        |\n| Windows (via WSL, Ubuntu 24.04)            | ROS 2 Rolling            | Linux           | Runs within WSL; build, topic communication, and launch verified     |\n\n**Known limitations**  \n- WSL environment requires correction for ROS 2 on [locale settings, e.g. from ROS 2 Rolling](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debs.html#set-locale).\n- Minor latency observed with GUI tools (e.g., BSK-Vizard) over WSL; CLI tools operate normally.  \n\n## Quick Start\n\n### 0. Software Pre-requisites\nBoth **Basilisk** and **ROS 2** are required to be installed prior to running this package. Details on corresponding installation guides can be found from:\n- [**Basilisk**](https://avslab.github.io/basilisk/Install.html)\n- **ROS 2**: \n    - [ROS 2 Humble](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html)\n    - [ROS 2 Rolling](https://docs.ros.org/en/rolling/Installation/Ubuntu-Install-Debs.html)\n\nAfter installation of **Basilisk**, it is recommended to export the user path of Basilisk to `.bashrc` as:\n```bash\nexport BSK_PATH=your_BSK_path\n```\n\n### 1. Install Dependencies\n\n```bash\n# Install custom ROS2 messages\ncd your_ros2_workspace/src\ngit clone https://github.com/DISCOWER/bsk-msgs.git\ncd ..\ncolcon build --packages-select bsk-msgs\nsource install/setup.bash\n\n# Install this package\ncd your_ros2_workspace/src\ngit clone https://github.com/DISCOWER/bsk-ros2-bridge.git\ncd ..\ncolcon build --packages-select bsk-ros2-bridge\nsource install/setup.bash\n\n# Install required packages from `requirements.txt`\n# This snippet has to be run as GLOBAL pip installation, it might not work within virtual environments (e.g., python venv, conda env).\ncd your_ros2_workspace/src/bsk-ros2-bridge\npip install -r requirements.txt\n\n```\n\n### 2. Run Example\n\n```bash\n# Terminal 1: Start bridge\nros2 launch bsk-ros2-bridge bridge.launch.py\n\n# Terminal 2: Start Basilisk simulation (requires BSK environment)\nsource $BSK_PATH/.venv/bin/activate\npython examples/scenarioRosBasic_da.py\n\n# Terminal 3: Start controller (here with namespace bskSat0 and direct allocation mode)\nros2 run bsk-ros2-bridge dummy-data-processor --ros-args -r __ns:=/bskSat0 -p mode:=da\n```\n\n## Examples\n\n| Scenario | Type | Control Mode |\n|----------|------|--------------|\n| `scenarioRosBasic_da.py` | Single spacecraft no Earth | Direct thruster allocation |\n| `scenarioRosBasic_wrench.py` | Single spacecraft  no Earth| Force/torque commands |\n| `scenarioRosFormation_da.py` | Multi-spacecraft in LEO | Direct thruster allocation |\n| `scenarioRosFormation_wrench.py` | Multi-spacecraft in LEO | Force/torque commands |\n| `scenarioRosLeaderFollowerBasic_wrench.py` | 1 leader 2 followers no Earth | Force/torque commands |\n| `scenarioRosLeaderFollowerOrbit_wrench.py` | 1 leader 2 followers in LEO | Force/torque commands |\n\n### Control Modes\n\n**Direct Allocation (`da`)**\n- Commands 12 individual thrusters (0-1.5N each)\n- Topic: `/[namespace]/bsk/in/thr_array_cmd_force`\n\n**Wrench Control (`wrench`)**\n- Commands 3D forces and torques, mapped to thrusters by Basilisk\n- Topics: `/[namespace]/bsk/in/cmd_force`, `/[namespace]/bsk/in/cmd_torque`\n\n### Multi-Spacecraft Usage\n\n```bash\n# Start formation scenario\nsource $BSK_PATH/.venv/bin/activate\npython examples/scenarioRosFormation_da.py\n\n# Control each spacecraft separately\nros2 run bsk-ros2-bridge dummy-data-processor --ros-args -r __ns:=/bskSat0 -p mode:=da\nros2 run bsk-ros2-bridge dummy-data-processor --ros-args -r __ns:=/bskSat1 -p mode:=da\n```\n\n### Time Synchronization\n\nThe bridge automatically publishes Basilisk simulation time to `/clock` using `rosgraph_msgs/Clock`. To enable ROS 2 nodes to use simulation time:\n\n```bash\nros2 run your_node --ros-args -p use_sim_time:=true\n```\n\nThis ensures all ROS 2 nodes are synchronized with the Basilisk simulation time instead of system time.\n\n## Development\n\n### Integrating RosBridgeHandler in Scenarios\n\n```python\n# Import and setup\nfrom bsk_module.rosBridgeHandler import RosBridgeHandler\nros_bridge = RosBridgeHandler()\nros_bridge.ModelTag = \"ros_bridge\"\n\n# Add publishers (Basilisk -\u003e ROS2)\nros_bridge.add_ros_publisher('SCStatesMsgPayload', 'SCStatesMsgIn', 'sc_states', 'bskSat')\n\n# Add subscribers (ROS2 -\u003e Basilisk)  \nros_bridge.add_ros_subscriber('THRArrayCmdForceMsgPayload', 'THRArrayCmdForceMsgOut', 'thr_array_cmd_force', 'bskSat')\n\n# Connect to Basilisk messages\nros_bridge.bskSat.SCStatesMsgIn.subscribeTo(scObject.scStateOutMsg)\nthrFiringSchmittObj.thrForceInMsg.subscribeTo(ros_bridge.bskSat.THRArrayCmdForceMsgOut)\n\n# Finally, add module to simulation task\nscSim.AddModelToTask(simTaskName, ros_bridge)\n```\n\n### Method Signatures\n\n```python\n# Publisher: Sends Basilisk data to ROS2\nros_bridge.add_ros_publisher(msg_type_name, handler_name, topic_name, namespace)\n\n# Subscriber: Receives ROS2 commands in Basilisk\nros_bridge.add_ros_subscriber(msg_type_name, handler_name, topic_name, namespace)\n```\n\n**Parameters:**\n- `msg_type_name` - Basilisk message type (e.g., `'SCStatesMsgPayload'`, `'CmdForceBodyMsgPayload'`)\n- `handler_name` - Internal message handler (e.g., `'SCStatesMsgIn'`, `'CmdForceBodyMsgOut'`)\n- `topic_name` - ROS2 topic name (e.g., `'sc_states'`, `'cmd_force'`)\n- `namespace` - Spacecraft identifier (e.g., `'bskSat'`, `'bskSat0'`)\n\n### Topic Structure\n\nTopics follow the pattern: `/[namespace]/bsk/[direction]/[topic_name]`\n\n**Common Topics:**\n- `/clock` - Simulation time synchronization\n- `/[namespace]/bsk/out/sc_states` - Spacecraft states  \n- `/[namespace]/bsk/in/thr_array_cmd_force` - Thruster commands\n- `/[namespace]/bsk/in/cmd_force` - Force commands\n- `/[namespace]/bsk/in/cmd_torque` - Torque commands\n\n### Port Configuration\n\nDefault ZMQ ports: 5550 (Basilisk-\u003eBridge), 5551 (Bridge-\u003eBasilisk), 5552 (heartbeat)\n\n**Custom ports:**\n```bash\nros2 launch bsk-ros2-bridge bridge.launch.py sub_port:=6550 pub_port:=6551 heartbeat_port:=6552\n```\n\n```python\nros_bridge = RosBridgeHandler(send_port=6550, receive_port=6551, heartbeat_port=6552)\n```\n\n## Features\n\n- **Dynamic Namespace Support** - Automatically creates ROS2 topics for multiple spacecraft\n- **Real-time Communication** - Optimized for low-latency spacecraft control\n- **Heartbeat Monitoring** - Ensures connection health between Basilisk and ROS2\n- **Automatic Topic Creation** - Bridge discovers and creates topics based on Basilisk messages\n- **Context Manager Support** - Automatic resource cleanup on shutdown\n- **Custom Message Types** - Uses `bsk_msgs` package that mirrors Basilisk's internal message structure\n- **Configurable Ports** - Runtime port configuration for multiple bridge instances\n\n## Troubleshooting\n\n**Missing message types:** Ensure `bsk_msgs` is built and sourced\n\n**Port conflicts:** Check ports status with: \n```bash\nlsof -i :5550 \u0026\u0026 lsof -i :5551 \u0026\u0026 lsof -i :5552\n```\nKill occupied ports via PID if they are not closed properly:\n```bash\nkill -9 {port PID}\n```\n\n**Connection issues:** Ensure bridge is running, verify BSK environment is activated\n\n## References\n\n- [Basilisk Astrodynamics Simulation](https://hanspeterschaub.info/basilisk/)\n- [ROS 2 Documentation](https://www.ros.org/)\n- [ZeroMQ Documentation](https://zeromq.org/)\n- [BSK ROS 2 Messages](https://github.com/DISCOWER/bsk-msgs.git)\n- [BSK ROS 2 MPC Controller](https://github.com/DISCOWER/bsk-ros2-mpc.git)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscower%2Fbsk-ros2-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdiscower%2Fbsk-ros2-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdiscower%2Fbsk-ros2-bridge/lists"}