-
Notifications
You must be signed in to change notification settings - Fork 0
Controller interface
This page provides an entry point to the way the drunc server should be interfaced.
This document refers to the Controller in particular. Its proto file can be found here
Remember that all the messages sent to and received from the controller follow the drunc schema described here. All the messages described here will end up in some form or another in the data fields of the Request and Response after being Anyfied.
This message encodes the status (and FSM status) of a controller or DAQ application. It has the form:
message Status {
string name = 1;
string state = 2;
string sub_state = 3;
bool in_error = 4;
bool included = 5;
}
Most of the fields should be self-explanatory. The state refers to the FSM state. There is another (secondary) FSM that encodes transitions themselves. Generally, if the endpoint is not transitioning, you should get state = substate or substate = idle for a DAQ application, otherwise, you will get substate of the form preparing-configure etc.
This message is a list of the above Status, and encodes the statuses of the children of the controller. Schema is:
message ChildrenStatus {
repeated Status children_status = 1;
}
This message is for describing a generic FSM argument. It has the form:
message Argument {
enum Presence{
MANDATORY = 0;
OPTIONAL = 1;
}
enum Type {
INT = 0;
FLOAT = 1;
STRING = 2;
BOOL = 3;
}
string name = 1;
Presence presence = 2;
Type type = 3;
optional google.protobuf.Any default_value = 4;
repeated google.protobuf.Any choices = 5;
string help = 6;
}
Where:
-
nameis the name of the arguments -
presenceis encoded in an enum defined in the Argument schema. -
typeis the data type. Note that the only supported data types are the ones listed here. -
default_valueis the default value that the argument will take (required if presence=optional) -
choicesare the eventual choices that the argument can take -
helpis some string for help.
have the form:
message FSMCommandDescription {
string name = 1;
repeated string data_type = 2;
string help = 3;
string return_type = 4;
repeated Argument arguments = 5;
}
Where:
-
nameis the name of the FSM command (such asconf,enable_triggers, etc.) -
data_typeis what is needed to run the command (it's alwaysFSMCommand- described later) -
helpsome explanatory text of the command (never really filled but would be nice to have at some point) -
return_typeis what is returned by the command (it's alwaysFSMCommandResponse- described later) -
argumentsis a list of the arguments inArgumentformat that are needed to execute the command.
Have the format:
message FSMCommand{
string command_name = 1;
map<string, google.protobuf.Any> arguments = 2;
repeated string children_nodes = 3;
optional string data = 4; // unfortunately, this is just some plain old json data introduced by the fsm interfaces
}
where:
-
command_nameis the name of the command one wants to execute (such asconf,enable_triggers, etc.) -
argumentsis a map of argument name to their values. Their value must be one of the 4: -
children_nodesis used to address command, but is not in use at the moment, so can be ignored -
datais an internal drunc part, which doesn't need to be specified for interfacing the controller.
Is a simple enum to understand if the command was successful or not:
enum FSMCommandResponseCode {
SUCCESSFUL = 0;
UNSUCCESSFUL = 1;
INVALID_TRANSITION = 2;
}
The format is described in here:
message FSMCommandResponse{
FSMCommandResponseCode successful = 1;
string command_name = 2;
google.protobuf.Any data = 3;
map<string,FSMCommandResponseCode> children_successful = 4;
}
where:
-
successfulis a simple enum describing the FSM command's successful execution or not -
command_nameis the command that was executed. -
datais the returned data for the FSM transition (which can be safely ignored for now) -
children_successfulis a map of children_name/FSMCommandResponseCode.
Each RPC call is described here.
... is already described in here.
One can ask the controller to specifically describe its FSM. The controller will answer with data of the format FSMCommandsDescription. This message will contain a list of FSMCommandDescription. These commands can contain a list of Arguments that need to be specified for some transitions.
FSM commands can be sent to the controller by using the RPC endpoint execute_fsm_command, by setting the data in the request to be and FSMCommand. The command specifies:
message FSMCommand{
string command_name = 1;
map<string, google.protobuf.Any> arguments = 2;
repeated string children_nodes = 3;
optional string data = 4;
}
-
command_name(1) is the usualconf,start,drain_dataflowetc. -
arguments(2) are a map of argument names to values. These are defined by the FSM interfaces, and the list is accessible by doingdescribe_fsm. -
children_nodes(3) is a list of children on which to execute the FSM command. If nothing is specified, the controller the command on all the children. -
data(4) is a JSON string that is produced by the controller's FSM interfaces, and used to communicate between controllers. The user should not fill this out manually.
The get_status or get_children_status call can be issued at any point, the controller will return a Status message or a list of statuses for each of the children. There is no way to get status deeper than one of a direct child.
Excluded nodes won't be passed FSM commands. This command will apply to the controller and all its descendants.
service Controller {
rpc ls (Request) returns (Response) {}
rpc describe (Request) returns (Response) {}
rpc get_children_status (Request) returns (Response) {}
rpc get_status (Request) returns (Response) {}
rpc describe_fsm (Request) returns (Response) {}
rpc execute_fsm_command (Request) returns (Response) {}
rpc include (Request) returns (Response) {}
rpc exclude (Request) returns (Response) {}
rpc take_control (Request) returns (Response) {}
rpc surrender_control (Request) returns (Response) {}
rpc who_is_in_charge (Request) returns (Response) {}
}