Protocol Documentation

Table of Contents

AgentTask.proto

Top

AgentTask

FieldTypeLabelDescription
team_color Team required

general infos Color of the team

task_id uint32 required

identifier for the tasks

robot_id uint32 required

move Move optional

Tasks

retrieve Retrieve optional

deliver Deliver optional

buffer BufferStation optional

explore_machine ExploreWaypoint optional

workpiece_description WorkpieceDescription optional

additional info for the refbox

order_id uint32 optional

cancel_task bool optional

flags and result of the current task cancels current task

pause_task bool optional

if true current task is paused, if false again task is continued

successful bool optional

was the task finished successful?

canceled bool optional

the task was successfully cancled from the agent

error_code uint32 optional

only set if failure, error-codes not yet

BufferStation

Get product from shelf and place it immediately afterwards on the conveyor

FieldTypeLabelDescription
machine_id string required

machine-id because need to know if CS1 or CS2

shelf_number uint32 required

only for old-gripper, valid shelf-numbers: 1, 2, 3

Deliver

Deliver the holding product to the given station

FieldTypeLabelDescription
machine_id string required

name of the machine

machine_point string required

valid machine-points: input, slide

ExploreWaypoint

Move to the given machine (if position already detected), else move to given

waypoint (=zone on the playing field)

FieldTypeLabelDescription
machine_id string required

name of the machine

machine_point string required

valid machine-points: input, output

waypoint string required

Move

Move robot to stated waypoint

FieldTypeLabelDescription
waypoint string required

can be a zone or a machine (default is input side of a machine)

machine_point string optional

can be used to specify the point of the machine (input, output)

Retrieve

Get a workpiece at the given station and hold the product in the gripper

FieldTypeLabelDescription
machine_id string required

name of the machine

machine_point string required

valid machine-points: input, output, shelf

WorkpieceDescription

FieldTypeLabelDescription
base_color BaseColor required

description fo the current workpiece the robot has gripped

ring_colors RingColor repeated

description fo the current workpiece the robot has gripped

cap_color CapColor optional

description fo the current workpiece the robot has gripped

AgentTask.CompType

NameNumberDescription
COMP_ID 8000

COMPONENT 8000 is Simulation

MSG_TYPE 502

WorkpieceDescription.CompType

NameNumberDescription
COMP_ID 8000

MSG_TYPE 510

AttentionMessage.proto

Top

AttentionMessage

FieldTypeLabelDescription
message string required

The message to display, be brief!

time_to_show float optional

Time (sec) the msg should be visible

team_color Team optional

if the message only regards one team

AttentionMessage.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 2

BeaconSignal.proto

Top

BeaconSignal

FieldTypeLabelDescription
time Time required

Local time in UTC

seq uint64 required

Sequence number

number uint32 required

The robot's jersey number

team_name string required

The robot's team name

peer_name string required

The robot's name

team_color Team optional

Team color, teams MUST sent this

pose Pose2D optional

Position and orientation of the robot on the LLSF playing field

task AgentTask optional

Maybe needed for future generalisation of beacon signal and tracking of robots current activity (used by GRIPS currently) current task-id of robot

finished_tasks FinishedTask repeated

a list of all the tasks that the robot has done. Contains the ID of

FinishedTask

FieldTypeLabelDescription
TaskId uint32 required

the specific task thats been done

successful bool required

the result of the task thats been done

BeaconSignal.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 1

ExplorationInfo.proto

Top

ExplorationInfo

FieldTypeLabelDescription
signals ExplorationSignal repeated

The signal assignments

zones ExplorationZone repeated

The zones to explore

ExplorationSignal

FieldTypeLabelDescription
type string required

machine type of this assignment

lights LightSpec repeated

Light specification (MachineInfo.proto)

ExplorationZone

FieldTypeLabelDescription
zone Zone required

Zone to explore

team_color Team required

Team the machine belongs to

ExplorationInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 72

ExplorationSignal.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 70

ExplorationZone.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 71

GameInfo.proto

Top

GameInfo

Game information for controllers

FieldTypeLabelDescription
known_teams string repeated

The new desired phase

SetTeamName

Request setting of a new game phase

FieldTypeLabelDescription
team_name string required

Name of the team to set

team_color Team required

Color of team

GameInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 81

SetTeamName.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 82

GameState.proto

Top

GameState

FieldTypeLabelDescription
game_time Time required

Time in seconds since game start

state GameState.State required

Current game state

phase GameState.Phase required

Current game phase

points_cyan uint32 optional

Awarded points, cyan

team_cyan string optional

Name of the currently playing team

points_magenta uint32 optional

Awarded points, magenta

team_magenta string optional

Name of the currently playing team

RandomizeField

SetGamePhase

Request setting of a new game phase

FieldTypeLabelDescription
phase GameState.Phase required

The new desired phase

SetGameState

Request setting of a new game state

FieldTypeLabelDescription
state GameState.State required

The new desired state

GameState.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 20

GameState.Phase

NameNumberDescription
PRE_GAME 0

SETUP 10

EXPLORATION 20

PRODUCTION 30

POST_GAME 40

GameState.State

NameNumberDescription
INIT 0

WAIT_START 1

RUNNING 2

PAUSED 3

RandomizeField.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 23

SetGamePhase.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 22

SetGameState.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 21

MachineCommands.proto

Top

MachineAddBase

Load puck into machine area.

FieldTypeLabelDescription
machine_name string required

Machine to place puck at

SetMachineLights

Set machine lights.

FieldTypeLabelDescription
machine_name string required

Machine to place puck at

lights LightSpec repeated

Desired state of the lights

SetMachineState

Load puck into machine area.

FieldTypeLabelDescription
machine_name string required

Machine to place puck at

state MachineState required

State to set

MachineAddBase.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 18

MachineState

NameNumberDescription
IDLE 1

AVAILABLE 2

PROCESSED 3

DELIVERED 4

RETRIEVED 5

RESET 15

SetMachineLights.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 19

SetMachineState.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 17

MachineDescription.proto

Top

CSOp

NameNumberDescription
RETRIEVE_CAP 1

MOUNT_CAP 2

LightColor

NameNumberDescription
RED 0

YELLOW 1

GREEN 2

LightState

NameNumberDescription
OFF 0

ON 1

BLINK 2

SSOp

NameNumberDescription
STORE 1

RETRIEVE 2

CHANGE_INFO 3

MachineInfo.proto

Top

LightSpec

FieldTypeLabelDescription
color LightColor required

Color and state of described light

state LightState required

Machine

FieldTypeLabelDescription
name string required

Machine name, type, and team

type string optional

state string optional

team_color Team optional

lights LightSpec repeated

Current state of the lights

pose Pose2D optional

Optional pose if known to refbox

zone Zone optional

Which zone the machine is in

rotation uint32 optional

correctly_reported bool optional

Only set during exploration phase Correctly reported? (zone and type correct)

loaded_with uint32 optional

Number of bases loaded Default: 0

ring_colors RingColor repeated

instruction_bs PrepareInstructionBS optional

Instruction information (only clients)

instruction_ds PrepareInstructionDS optional

instruction_ss PrepareInstructionSS optional

instruction_rs PrepareInstructionRS optional

instruction_cs PrepareInstructionCS optional

exploration_rotation_state ExplorationState optional

more fine-grained exploration (only clients)

exploration_zone_state ExplorationState optional

status_ss ShelfSlotInfo repeated

Status of the storage station shelf-slots

MachineInfo

FieldTypeLabelDescription
machines Machine repeated

List of machines states

team_color Team optional

Team color (only broadcast)

ShelfSlotInfo

Shelf Information

FieldTypeLabelDescription
shelf uint32 required

shelf position (see MachineInstructons.proto)

slot uint32 required

slot position

is_filled bool required

fill status

description string optional

additional information of the workpiece in that position

ExplorationState

NameNumberDescription
NO_REPORT 0

CORRECT_REPORT 1

WRONG_REPORT 2

LightSpec.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 10

Machine.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 12

MachineInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 13

ShelfSlotInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 121

MachineInstructions.proto

Top

PrepareInstructionBS

FieldTypeLabelDescription
side MachineSide required

color BaseColor required

PrepareInstructionCS

FieldTypeLabelDescription
operation CSOp required

PrepareInstructionDS

FieldTypeLabelDescription
order_id uint32 required

Send order_id 0 to let DS consume a product without further action. This can be used to get rid of waste products, such as clear bases.

PrepareInstructionRS

FieldTypeLabelDescription
ring_color RingColor required

PrepareInstructionSS

FieldTypeLabelDescription
operation SSOp required

shelf uint32 required

Shelves: Slots: Top 5 4 1 3 5 7 3 0 2 4 6 2 Input ------> OUTPUT 1 (_) BOT 0 |

slot uint32 required

wp_description string optional

Optional description of the workpiece that is stored. The RefBox attaches this description when sending information about stored products

PrepareMachine

FieldTypeLabelDescription
team_color Team required

machine string required

Machine name which to instruct

instruction_bs PrepareInstructionBS optional

instruction_ds PrepareInstructionDS optional

instruction_ss PrepareInstructionSS optional

instruction_rs PrepareInstructionRS optional

instruction_cs PrepareInstructionCS optional

sent_at uint64 optional

time since Unix epoch in seconds if specified and the message is too old it gets ignored (threshold is specified in globals.clp)

ResetMachine

FieldTypeLabelDescription
team_color Team required

machine string required

Machine name which to instruct

MachineSide

NameNumberDescription
INPUT 1

OUTPUT 2

PrepareMachine.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 101

ResetMachine.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 104

MachineReport.proto

Top

MachineReport

Robots send this to announce recognized

machines to the refbox.

FieldTypeLabelDescription
team_color Team required

Team for which the report is sent

machines MachineReportEntry repeated

All machines already already recognized or a subset thereof

MachineReportEntry

FieldTypeLabelDescription
name string optional

Machine name and recognized type and zone the machine is in

type string optional

zone Zone optional

rotation uint32 optional

[0-360] in deg

MachineReportInfo

The refbox periodically sends this to

acknowledge reported machines

FieldTypeLabelDescription
reported_machines string repeated

Names of machines for which the refbox received a report from a robot (which may have been correct or wrong)

team_color Team required

Team for which the report is sent

reported_types MachineTypeFeedback repeated

Responses to reports that were received by the refbox and that contained machine types and zones

MachineTypeFeedback

FieldTypeLabelDescription
type string required

Feedback about whether a reported type in a zone is correct "name" and "team_color" are only set if the reported type is located in the zone and if the number of reported types did not exceed the number of machines with the types

zone Zone required

name string optional

team_color Team optional

MachineReport.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 61

MachineReportEntry.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 60

MachineReportInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 62

MachineTypeFeedback.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 63

Top

NavigationRoutes

FieldTypeLabelDescription
team_color Team required

routes Route repeated

Route

FieldTypeLabelDescription
id uint32 required

route Zone repeated

reached Zone repeated

remaining Zone repeated

NavigationRoutes.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 250

OrderInfo.proto

Top

ConfirmDelivery

FieldTypeLabelDescription
delivery_id uint32 required

correct bool required

Order

FieldTypeLabelDescription
id uint32 required

ID and requested product of this order

complexity Order.Complexity required

base_color BaseColor required

ring_colors RingColor repeated

cap_color CapColor required

quantity_requested uint32 required

Quantity requested and delivered

quantity_delivered_cyan uint32 required

quantity_delivered_magenta uint32 required

delivery_period_begin uint32 required

Start and end time of the delivery period in seconds of game time

delivery_period_end uint32 required

delivery_gate uint32 required

The gate to deliver to, defaults to any (non-defunct, i.e. non-red light) gate

unconfirmed_deliveries UnconfirmedDelivery repeated

competitive bool required

OrderInfo

FieldTypeLabelDescription
orders Order repeated

The current orders

SetOrderDelivered

FieldTypeLabelDescription
team_color Team required

order_id uint32 required

UnconfirmedDelivery

FieldTypeLabelDescription
id uint32 required

team Team required

delivery_time Time required

ConfirmDelivery.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 46

Order.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 42

Order.Complexity

Ordered product type

NameNumberDescription
C0 0

C1 1

C2 2

C3 3

OrderInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 41

SetOrderDelivered.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 43

UnconfirmedDelivery.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 45

Pose2D.proto

Top

Pose2D

Pose information on 2D map

Data is relative to the LLSF field frame

FieldTypeLabelDescription
timestamp Time required

Time when this pose was measured

x float required

X/Y coordinates in meters

y float required

ori float required

Orientation in rad

ProductColor.proto

Top

BaseColor

NameNumberDescription
BASE_RED 1

BASE_BLACK 2

BASE_SILVER 3

BASE_CLEAR 4

CapColor

NameNumberDescription
CAP_BLACK 1

CAP_GREY 2

RingColor

NameNumberDescription
RING_BLUE 1

RING_GREEN 2

RING_ORANGE 3

RING_YELLOW 4

RingInfo.proto

Top

Ring

FieldTypeLabelDescription
ring_color RingColor required

Ring color this concerns

raw_material uint32 required

number of additional bases required to produce this ring type

RingInfo

FieldTypeLabelDescription
rings Ring repeated

List of all known pucks

RingInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 110

RobotCommands.proto

Top

SetRobotMaintenance

Set a robot's maintenance state

FieldTypeLabelDescription
robot_number uint32 required

Number of robot to set state

maintenance bool required

True to activate maintenance, false to bring back robot

team_color Team required

Team the robot belongs to

SetRobotMaintenance.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 91

RobotInfo.proto

Top

Robot

FieldTypeLabelDescription
name string required

Name, team, and number of the robot as it was announced by the robot in the BeaconSignal message.

team string required

team_color Team required

number uint32 required

host string required

Host from where the BeaconSignal was received

last_seen Time required

Timestamp in UTC when a BeaconSignal was received last from this robot

pose Pose2D optional

Pose information (reported by robot)

vision_pose Pose2D optional

Pose information (reported by vision)

state RobotState optional

Current state of this robot

maintenance_time_remaining float optional

Time in seconds remaining in current maintenance cycle, negative if overdue Default: 0

maintenance_cycles uint32 optional

number of times maintenance has been performed, including current

RobotInfo

FieldTypeLabelDescription
robots Robot repeated

List of all known robots

Robot.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 31

RobotInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 30

RobotState

NameNumberDescription
ACTIVE 1

MAINTENANCE 2

DISQUALIFIED 3

SimTimeSync.proto

Top

SimTimeSync

FieldTypeLabelDescription
sim_time Time required

real_time_factor float required

paused bool required

SimTimeSync.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 327

Team.proto

Top

Team

Team identifier.

NameNumberDescription
CYAN 0

MAGENTA 1

Time.proto

Top

Time

Time stamp and duration structure.

Can be used for absolute times or

durations alike.

FieldTypeLabelDescription
sec int64 required

Time in seconds since the Unix epoch in UTC or seconds part of duration

nsec int64 required

Nano seconds after seconds for a time or nanoseconds part for duration

VersionInfo.proto

Top

VersionInfo

FieldTypeLabelDescription
version_major uint32 required

version_minor uint32 required

version_micro uint32 required

version_string string required

VersionInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 3

WorkpieceInfo.proto

Top

Workpiece

FieldTypeLabelDescription
id uint32 required

Puck unique ID

at_machine string required

Machine which detected the workpiece

visible float optional

last seen at machine

team_color Team optional

Team the puck belongs to

base_color BaseColor optional

ring_colors RingColor repeated

cap_color CapColor optional

WorkpieceAddRing

FieldTypeLabelDescription
id uint32 required

Puck unique ID

ring_color RingColor required

WorkpieceInfo

FieldTypeLabelDescription
workpieces Workpiece repeated

List of all known pucks

Workpiece.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 55

WorkpieceAddRing.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 57

WorkpieceInfo.CompType

NameNumberDescription
COMP_ID 2000

MSG_TYPE 56

Zone.proto

Top

Zone

Zone identifiers

NameNumberDescription
C_Z18 18

C_Z28 28

C_Z38 38

C_Z48 48

C_Z58 58

C_Z68 68

C_Z78 78

C_Z17 17

C_Z27 27

C_Z37 37

C_Z47 47

C_Z57 57

C_Z67 67

C_Z77 77

C_Z16 16

C_Z26 26

C_Z36 36

C_Z46 46

C_Z56 56

C_Z66 66

C_Z76 76

C_Z15 15

C_Z25 25

C_Z35 35

C_Z45 45

C_Z55 55

C_Z65 65

C_Z75 75

C_Z14 14

C_Z24 24

C_Z34 34

C_Z44 44

C_Z54 54

C_Z64 64

C_Z74 74

C_Z13 13

C_Z23 23

C_Z33 33

C_Z43 43

C_Z53 53

C_Z63 63

C_Z73 73

C_Z12 12

C_Z22 22

C_Z32 32

C_Z42 42

C_Z52 52

C_Z62 62

C_Z72 72

C_Z11 11

C_Z21 21

C_Z31 31

C_Z41 41

M_Z18 1018

M_Z28 1028

M_Z38 1038

M_Z48 1048

M_Z58 1058

M_Z68 1068

M_Z78 1078

M_Z17 1017

M_Z27 1027

M_Z37 1037

M_Z47 1047

M_Z57 1057

M_Z67 1067

M_Z77 1077

M_Z16 1016

M_Z26 1026

M_Z36 1036

M_Z46 1046

M_Z56 1056

M_Z66 1066

M_Z76 1076

M_Z15 1015

M_Z25 1025

M_Z35 1035

M_Z45 1045

M_Z55 1055

M_Z65 1065

M_Z75 1075

M_Z14 1014

M_Z24 1024

M_Z34 1034

M_Z44 1044

M_Z54 1054

M_Z64 1064

M_Z74 1074

M_Z13 1013

M_Z23 1023

M_Z33 1033

M_Z43 1043

M_Z53 1053

M_Z63 1063

M_Z73 1073

M_Z12 1012

M_Z22 1022

M_Z32 1032

M_Z42 1042

M_Z52 1052

M_Z62 1062

M_Z72 1072

M_Z11 1011

M_Z21 1021

M_Z31 1031

M_Z41 1041

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)