-
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 Any
fied.
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:
-
name
is the name of the arguments -
presence
is encoded in an enum defined in the Argument schema. -
type
is the data type. Note that the only supported data types are the ones listed here. -
default_value
is the default value that the argument will take (required if presence=optional) -
choices
are the eventual choices that the argument can take -
help
is 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:
-
name
is the name of the FSM command (such asconf
,enable_triggers
, etc.) -
data_type
is what is needed to run the command (it's alwaysFSMCommand
- described later) -
help
some explanatory text of the command (never really filled but would be nice to have at some point) -
return_type
is what is returned by the command (it's alwaysFSMCommandResponse
- described later) -
arguments
is a list of the arguments inArgument
format 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_name
is the name of the command one wants to execute (such asconf
,enable_triggers
, etc.) -
arguments
is a map of argument name to their values. Their value must be one of the 4: -
children_nodes
is used to address command, but is not in use at the moment, so can be ignored -
data
is 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:
-
successful
is a simple enum describing the FSM command's successful execution or not -
command_name
is the command that was executed. -
data
is the returned data for the FSM transition (which can be safely ignored for now) -
children_successful
is 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_dataflow
etc. -
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) {}
}