Note
This protocol is still in draft mode and subject to changes
Protobuf files for a common simulation protocol for the Small Size League for easier exchange of different simulator implementations.
It consists of the following files:
- ssl_simulation_robot_control - Control the robots
- ssl_simulation_robot_feedback - Receive robot feedback
- ssl_simulation_control - Control the simulation itself
- ssl_simulation_config - Change the configuration of the simulator
- ssl_simulation_error - Error messages for responses
- ssl_gc_common - Common types from game-controller (RobotId)
- ssl_geometry - Geometry from ssl-vision
The protocol defines mostly optional fields. All unset variables should be interpreted as unmodified. A simulator may decide to not implement all features. Returning an error in case a field is set that is not supported is considered good practice. Errors should have a unique code for the simulator implementation that allows teams to automatically handle the errors in their software.
There are three ports that a simulator should offer:
Control and configure the simulation.
- Accepts
SimulatorCommandmessages (ssl_simulation_control) - Returns
SimulatorResponsemessages (ssl_simulation_control) - Default port: 10300 UDP
Control the blue team.
- Accepts
RobotControlmessages (ssl_simulation_robot_control) - Returns
RobotControlResponsemessages (ssl_simulation_robot_feedback) - Default port: 10301 UDP
Control the yellow team.
- Accepts
RobotControlmessages (ssl_simulation_robot_control) - Returns
RobotControlResponsemessages (ssl_simulation_robot_feedback) - Default port: 10302 UDP
All connections use bidirectional UDP communication.
When a simulator is used in a tournament, it should only allow UDP packets from one IP per team. Simulation control and configuration should be disabled in the simulator or for example restricted to localhost or also to only one IP, so that teams can not (accidentally) connect to the simulation control, but an autoRef or similar can.
During development and for automated tests it might be useful to have a synchronous communication with the team software. Additionally, a multicast protocol might cause issues in these scenarios. There are also things like authentication for a tournament mode to be considered.
For that, an additional communication interface is planned. There are multiple ideas:
- Use a bidirectional TCP connection, like the game-controller provides (messages a drafted in ssl_simulation_synchronous.proto)
- Providing C-Interfaces to avoid network communication completely
- Using gRPC, esp. for configuration
In any case, the protobuf messages would still be used, but a layer would be added on top. These different ideas still need more evaluation. Feedback and opinions can be addressed to the SSL TC.
The protocol has been divided into three individual connections to easily disable the control protocol during a tournament and to make sure each team can only command their own robots and can only receive feedback from their own robots.
It is expected that each simulator has their specifics, and it will be hard to generalize the protocol in a way, that all parameters can be handled by all implementations and even that they have the exact same behavior. For that reason, each simulator can add custom messages for realism, robot specs and robot feedback with an individual documentation and behavior.
All simulators will require some configuration. While there are some with a UI where the parameters can be configured, others may be completely headless and stateless. Additionally, teams may want to integrate a simulator in their own software and configure it from there, instead of running a separate UI. That's why the simulator configuration can be specified via the protocol.
UDP is an unreliable communication protocol, so datagrams (and thus protobuf messages) may get lost. This is ok for robot commands, as they are sent repeatedly in a high frequency anyway and there is no need for a retransmission. It is also a little simpler to send data through UDP than through TCP (implementation wise). To keep the overall protocol simple, the simulation control also uses UDP.