Initial import

.github/workflows/CI.yml

@@ -0,0 +1,36 @@
+name: CI
+on:
+  push:
+    branches:
+      - main
+      - comp/**
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+jobs:
+  buildAndTest:
+    runs-on: ubuntu-24.04
+    container: ros:jazzy
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          path: src/ateam_software
+          submodules: true
+      - name: Install Dependencies
+        shell: bash
+        run: |
+          source /opt/ros/jazzy/setup.bash
+          sudo apt-get update
+          rosdep update --rosdistro=jazzy
+          rosdep install --from-paths . --ignore-src -y
+      - name: Build
+        shell: bash
+        run: |
+          source /opt/ros/jazzy/setup.bash
+          colcon build
+      - name: Test
+        shell: bash
+        run: |
+          source /opt/ros/jazzy/setup.bash
+          colcon test
+          colcon test-result --verbose 

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+# Contributing to ssl_ros_bridge
+
+First off, thanks for taking the time to contribute! ❤️
+
+All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions. 🎉
+
+## Table of Contents
+
+<!-- - [Code of Conduct](#code-of-conduct) -->
+- [I Have a Question](#i-have-a-question)
+- [I Want To Contribute](#i-want-to-contribute)
+  - [Reporting Bugs](#reporting-bugs)
+  - [Suggesting Enhancements](#suggesting-enhancements)
+- [Styleguides](#styleguides)
+
+<!-- TODO
+## Code of Conduct
+
+This project and everyone participating in it is governed by the
+[CONTRIBUTING.md Code of Conduct](blob/master/CODE_OF_CONDUCT.md).
+By participating, you are expected to uphold this code. Please report unacceptable behavior
+to <>. -->
+
+## I Have a Question
+
+> If you want to ask a question, we assume that you have read the available [documentation](README.md).
+
+Before you ask a question, it is best to search for existing [Issues](https://github.com/SSL-A-Team/ssl_ros_bridge/issues) or [Discussions](https://github.com/SSL-A-Team/ssl_ros_bridge/discussions) that might help you. In case you have found a suitable issue/topic and still need clarification, you can write your question in the existing issue/topic.
+
+If you don't find what you're looking for there, you can start a [new question topic](https://github.com/SSL-A-Team/ssl_ros_bridge/discussions/new?category=q-a).
+
+If it turns out your question highlights a new bug in our software, we'll create an issue from your Q&A post.
+
+For quicker / shorter questions, you can also tag "@[A-Team] Matt Barulic" in the [Open Source channel](https://discord.com/channels/465455923415220234/467643497122496543) in the league Discord server.
+
+## I Want To Contribute
+
+> ### Legal Notice 
+> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license.
+
+### Reporting Bugs
+
+#### Before Submitting a Bug Report
+
+A good bug report shouldn't leave others needing to chase you up for more information. Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. Please complete the following steps in advance to help us fix any potential bug as fast as possible.
+
+- Make sure that you are using the latest version.
+- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (Make sure that you have read the [documentation](README.md). If you are looking for support, you might want to check [this section](#i-have-a-question)).
+- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error in the [bug tracker](issues?q=label%3Abug).
+- Collect information about the bug:
+    - Any relevant traces or log output
+    - OS, Platform and Version (Windows, Linux, macOS, x86, ARM)
+    - ROS version being used
+    - Can you reliably reproduce the issue? And can you also reproduce it with older versions?
+
+#### How Do I Submit a Good Bug Report?
+
+We use GitHub issues to track bugs and errors. If you run into an issue with the project:
+
+- Open an [Issue](https://github.com/SSL-A-Team/ssl_ros_bridge/issues/new). (Since we can't be sure at this point whether it is a bug or not, we ask you not to talk about a bug yet and not to label the issue.)
+- Explain the behavior you would expect and the actual behavior.
+- Please provide as much context as possible and describe the *reproduction steps* that someone else can follow to recreate the issue on their own. This usually includes your code. For good bug reports you should isolate the problem and create a reduced test case.
+- Provide the information you collected in the previous section.
+
+Once it's filed:
+
+- The project team will label the issue accordingly.
+- A team member will try to reproduce the issue with your provided steps. If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for those steps and mark the issue as `needs-repro`. Bugs with the `needs-repro` tag will not be addressed until they are reproduced.
+- If the team is able to reproduce the issue, it will be marked `needs-fix`, as well as possibly other tags (such as `critical`), and the issue will be left to be [implemented by someone](#your-first-code-contribution).
+- The project team may convert the issue to a discussions topic if it is a question or otherwise does not capture an actionable issue.
+
+### Suggesting Enhancements
+
+This section guides you through submitting an enhancement suggestion for CONTRIBUTING.md, **including completely new features and minor improvements to existing functionality**. Following these guidelines will help maintainers and the community to understand your suggestion and find related suggestions.
+
+#### Before Submitting an Enhancement
+
+- Make sure that you are using the latest version.
+- Read the [documentation](README.md) carefully and find out if the functionality is already covered, maybe by an individual configuration.
+- Perform a [search](https://github.com/SSL-A-Team/ssl_ros_bridge/issues) to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
+- Find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Keep in mind that we want features that will be useful to the majority of our users and not just a small subset. If you're just targeting a minority of users, consider writing an add-on/plugin library.
+- Feel free to have early discussions about your suggestions via discussions or on Discord as presented in [this section](#i-have-a-question).
+
+#### How Do I Submit a Good Enhancement Suggestion?
+
+Enhancement suggestions are tracked as [GitHub issues](https://github.com/SSL-A-Team/ssl_ros_bridge/issues).
+
+- Use a **clear and descriptive title** for the issue to identify the suggestion.
+- Provide a **step-by-step description of the suggested enhancement** in as many details as possible.
+- **Describe the current behavior** and **explain which behavior you expected to see instead** and why. At this point you can also tell which alternatives do not work for you.
+- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to.
+- **Explain why this enhancement would be useful** to most ssl_ros_bridge users. You may also want to point out the other projects that solved it better and which could serve as inspiration.
+
+## Styleguides
+
+This project follows the [ROS 2 style guides](https://docs.ros.org/en/rolling/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html).
+
+### Commit Messages
+
+Generally, commit messages should be a phrase starting with the verb capturing what the commit changes. A good rule of thumb is to write a sentence like "This commit fixes/changes/improves/etc..." and use everything after "This commit" as your commit message.
+
+Tag relevant issues in your commit messages.
+
+**Good commit message**: "Fixes #1 by reordering network calls."
+
+**Bad commit message**: "Network calls no longer broken."
+
+## Attribution
+
+This guide is based on **contributing.md**. [Make your own](https://contributing.md/)!

README.md

@@ -1,2 +1,174 @@
 # ssl_ros_bridge
-Packages to connect ROS systems to RoboCup Small Size League standard systems
+
+This repository provides ROS 2 packages containing utilities for connecting your ROS system to the RoboCup Small Size League (SSL) standard systems, such as ssl-vision and the Game Controller.
+
+## Installation
+
+This repo is designed to be built in a colcon workspace. You can clone this repo alongside your own code or as a submodule within your own repository.
+
+## Usage
+
+The intended usage of these packages is to configure and run the nodes in the ssl_ros_bridge package alongside your own nodes. Each node is provided as a component with a standalone executable available. Either can be used.
+
+For most teams, in most scenarios, the only parameter that needs to be configured is the team name. Automatic discovery and multi-interface multicast listening will handle most common network setups.
+
+Two launch files are provided in ssl_ros_bridge for basic scenarios: [ssl_ros_bridge.launch.xml](ssl_ros_bridge/launch/ssl_ros_bridge.launch.xml) and [ssl_ros_bridge_localhost_only.launch.xml](ssl_ros_bridge/launch/ssl_ros_bridge_localhost_only.launch.xml). The first listens for multicast traffic on all interfaces. The localhost only launch file restricts the multicast listening to the loopback interface (127.0.0.1) and sets the game controller server address to 127.0.0.1. The localhost only launch file is useful when using simulation to prevent traffic from other simulation setups on the same network from interfering with your system.
+
+> **Note**
+>
+> You may need to enable multicast on the loopback interface as many linux environments have it disabled by default.
+
+Either of these launch files can be included in your own launch file, specifying your team name.
+
+```xml
+<include file="$(find-pkg-share ssl_ros_bridge)/launch/ssl_ros_bridge.launch.xml">
+  <arg name="team_name" value="Your Team Name" />
+</include>
+```
+
+## Packages
+
+### ssl_league_protobufs
+
+This package includes the league-defined protobuf files and builds them into a library available for other packages.
+
+### ssl_league_msgs
+
+This package defines ROS messages which closely mirror the league protobufs.
+
+#### Optional Fields
+
+The SSL League protobufs make extensive use of optional fields, which are unfortunately not currently supported in ROS messages. ssl_ros_bridge uses array field types to hold optionals. These fields will either hold one or zero elements. This does introduce some ambiguity between optional fields and actual array fields. Users should refer to the corresponding protobuf definitions for clarity.
+
+> **Note**
+>
+> ROS fields do support bounded-size array types. We could enforce the "zero or one" behavior with these size limits, but this has caused problems with some ROS tools in the past (ie. PlotJuggler) which don't parse the message definitions correctly with these limits in place.
+
+#### Recursive Message Definitions
+
+The league protobufs include a few recursive definitions. For example, the `GameEvent` message may hold a `MultipleFouls` message which itself holds an array of `GameEvent` messages. ROS does not support recursive message types. In practice, most teams will not need these fields, so ssl_ros_bridge omits them from the ROS messages.
+
+### ssl_ros_bridge_msgs
+
+This package defines interfaces used by the bridge nodes which are not mirrors of league messages. These are mostly services users can use to send requests up to league software.
+
+### ssl_ros_bridge
+
+This package provides the nodes which implement the bridge between league software and ROS systems.
+
+#### vision_bridge
+
+This node listens for the multicast vision messages sent by ssl-vision and publishes them into ROS.
+
+##### Published Topics
+
+* ~/vision_messages
+   * Type: [ssl_league_msgs/msg/VisionWrapper](ssl_league_msgs/msg/vision/VisionWrapper.msg)
+   * Contains vision data including robot detections, ball detections, and field geometry.
+
+##### Parameters
+
+* ssl_vision_ip
+  * Type: string
+  * Default: "224.5.23.2"
+  * The multicast group address to listen for.
+* ssl_vision_port
+  * Type: int
+  * Default: 10020
+  * The multicast group port to listen for.
+* net_interface_address
+  * Type: string
+  * Default: empty
+  * When empty, the node will join the multicast group on all interfaces. When set to an IP address associated with one of your machine's network interfaces, the node will only join the multicast group on that interface.
+
+#### game_controller_bridge
+
+This node listens for multicast game controller messages and republishes them into ROS.
+
+##### Automatic Game Controller Discovery
+
+The team client node needs to know the IP address fo the game controller server to establish its connection. This address is often different at different fields even within the same event and can be tedious to keep configured correctly. The game controller bridge node will automatically configure the team client node with the correct address based on the sender of the multicast messages. The game controller bridge will only reconfigure the team client node if it is not already connected.
+
+##### Published Topics
+
+* ~/referee_messages
+  * Type: [ssl_league_msgs/msg/Referee](ssl_league_msgs/msg/game_controller/Referee.msg)
+  * Contains the latest information from the game controller.
+
+##### Subscribed Topics
+
+* /team_client_node/connection_status
+  * Type: [ssl_ros_bridge_msgs/msg/TeamClientConnectionStatus](ssl_ros_bridge_msgs/msg/TeamClientConnectionStatus.msg)
+  * Used for automatic game controller discovery.
+
+##### Service Clients
+
+* /team_client_node/reconnect
+  * Type: [ssl_ros_bridge_msgs/srv/ReconnectTeamClient](ssl_ros_bridge_msgs/srv/ReconnectTeamClient.srv)
+  * Used for automatic game controller discovery.
+
+##### Parameters
+
+* multicast.address
+  * Type: string
+  * Default: "224.5.23.1"
+  * The multicast group address to listen for.
+* multicast.port
+  * Type: int
+  * Default: 10003
+  * The multicast group port to listen for.
+* net_interface_address
+  * Type: string
+  * Default: empty
+  * When empty, the node will join the multicast group on all interfaces. When set to an IP address associated with one of your machine's network interfaces, the node will only join the multicast group on that interface.
+
+#### team_client
+
+This node connects as a team client to the game controller server. ROS services can then be used to send requests to the game controller, such as changing the goal keeper ID number.
+
+_Note_: Encrypted connections are not currently supported.
+
+##### Published Topics
+
+* ~/connection_status
+  * Type: [ssl_ros_bridge_msgs/msg/TeamClientConnectionStatus](ssl_ros_bridge_msgs/msg/TeamClientConnectionStatus.msg)
+  * Contains the connection status and ping time of the team client to the game controller server.
+
+##### Services
+
+* ~/set_desired_keeper
+  * Type: [ssl_ros_bridge_msgs/srv/SetDesiredKeeper](ssl_ros_bridge_msgs/srv/SetDesiredKeeper.srv)
+  * Sends a request to the game controller to change your team's keeper ID.
+* ~/substitute_bot
+  * Type: [ssl_ros_bridge_msgs/srv/SubstituteBot](ssl_ros_bridge_msgs/srv/SubstituteBot.srv)
+  * Sends a request to the game controller to substitute a bot.
+* ~/reconnect
+  * Type: [ssl_ros_bridge_msgs/srv/ReconnectTeamClient](ssl_ros_bridge_msgs/srv/ReconnectTeamClient.srv)
+  * Reconnects the team client to the game controller.
+  * _Note_: If the address field of the request is empty, the team client node will reconnect to the same server it was previously configured for. If the address field of the request is not empty, the `gc_ip_address` parameter will be overwritten with this new address.
+* ~/set_advantage_choice
+  * Type: [ssl_ros_bridge_msgs/srv/SetTeamAdvantageChoice](ssl_ros_bridge_msgs/srv/SetTeamAdvantageChoice.srv)
+  * Sends a request to set the team's advantage choice to the game controller.
+
+##### Parameters
+
+* gc_ip_address
+  * Type: string
+  * Default: empty
+  * The address of the game controller server. Leave empty to let the game controller bridge discovery the address automatically.
+* gc_port
+  * Type: int
+  * Default: 10008
+  * The port on the game controller server the team client will connect to.
+* team_name
+  * Type: string
+  * Default: "Test Team"
+  * The name of the team the client will try to connect as.
+* team_color
+  * Type: string
+  * Default: "auto"
+  * The team color to connect as. Only relevant if a team is playing against itself and the identical team names need to be disambiguated.
+
+## Contributing
+
+See [our contributing guidelines](CONTRIBUTING.md).