Initial draft of the auto-referee CI protocol

Author: g3force

doc/AutoRefCi.md

@@ -0,0 +1,15 @@
+# Auto-referee continuous integration (CI)
+
+To ease integration of the ssl-game-controller and the auto-referee implementations, there are separate unicast protocols that avoid the asynchronous communication via multicast and allows for integration with simulators and running at non-realtime speeds.
+
+## Connection sequence
+
+The connection is described in the following sequence diagram:
+
+![sequence diagram](https://www.websequencediagrams.com/cgi-bin/cdraw?lz=bG9vcAoKU2ltdWxhdG9yIC0-IAADCjogcwATBmUgc3RlcAAZDkF1dG9SZWYgOgACCENpSW5wdXQgeyBTU0xfV3JhcHBlclBha2V0LCBSZWZlcmVlTXNnIH0KCm9wdAoANwgtPiBHQwA7ClRvQ29udHJvbGxlciB7IEdhbWVFdmVudCB9CkdDAGkOAB8KVG8AgQUIeyBSZXBseSB9CmVuZAoAWQwAgUoMAIEoCU91dACBLAZUcmFja2VyAIEsCWNrZXQgfQCCCg4AgSIFAIFbCgAcFwCBIAYAgjgMAFwLAIF5DmVuZAo&s=default)
+
+Source to generate the diagram: [autoRefCi.puml](autoRefCi.puml)
+
+## Protobuf protocol
+
+All protobuf files can be found in [../proto](../proto).

doc/autoRefCi.puml

@@ -0,0 +1,17 @@
+@startuml
+loop
+
+Simulator -> Simulator : simulate step
+Simulator -> AutoRef : AutoRefCiInput { SSL_WrapperPaket, RefereeMsg }
+
+opt
+AutoRef -> GC : AutoRefToController { GameEvent }
+GC -> AutoRef : ControllerToAutoRef { Reply }
+end
+
+AutoRef -> Simulator : AutoRefCiOutput { TrackerWrapperPacket }
+Simulator -> GC : CiInput { TrackerWrapperPacket }
+GC -> Simulator : CiOutput { RefereeMsg }
+
+end
+@enduml

proto/ssl_autoref_ci.proto

@@ -0,0 +1,27 @@
+syntax = "proto2";
+
+import "ssl_vision_wrapper_tracked.proto";
+import "ssl_vision_detection.proto";
+import "ssl_vision_geometry.proto";
+import "ssl_gc_referee_message.proto";
+
+// The AutoRefCiInput contains all packets/messages that would otherwise be received through multicast by the auto-referee
+// It may contain either a raw or a tracked SSL-vision packet. If both are given, the implementation may choose either one.
+message AutoRefCiInput {
+    // Latest referee message
+    optional Referee referee_message = 1;
+    // A tracked SSL-Vision packet to be processed without filtering
+    optional TrackerWrapperPacket tracker_wrapper_packet = 2;
+    // A list of unfiltered SSL-Vision packets (for multiple cameras) to be filtered and processed
+    repeated SSL_DetectionFrame detection = 3;
+    // Current geometry data, to be sent at least once at the beginning of the connection
+    optional SSL_GeometryData geometry = 4;
+}
+
+// The AutoRefCiOutput contains any new data created by the auto-referee for further processing
+message AutoRefCiOutput {
+    // A resulting tracked SSL-Vision packet for input into the ssl-game-controller.
+    // The auto-referee will either generate it from the unfiltered SSL-Vision packets
+    // or simply return the tracked packet from the input.
+    optional TrackerWrapperPacket tracker_wrapper_packet = 1;
+}