Protocol Description

17 minute read

Table of Contents

Top

motorcortex.proto

Description of the motorcortex-core message.

All core data types, enumerators and RPC messages are defined here.

Version 1.0.0

ConsoleCmdListMsg

Request to execute a list of commands on the server.

User's request to execute a list of commands on the server (console mode).

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

(Note: Currently not implemented).

Field Type Label Description
header Header optional Frame counter and actual time.
cmds ConsoleCmdMsg repeated List of commands

ConsoleCmdMsg

Request to execute command on the server.

User's request to execute a command on the server (console mode).

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

(Note: Currently not implemented).

Field Type Label Description
header Header optional Frame counter and actual time.
value string required Console command

CreateGroupMsg

Request to create a publisher group.

User's request to start publishing specified parameters. Several users may subscribe to the same group. This mechanism reduces the load on the server and allows more clients to get frequent updates.

User may choose a scale factor for the publishing rate of the group.

Server's reply: GroupStatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because the user has no access rights.

StatusCode::FAILED_TO_SET_REQUESTED_FRQ - operation successful, but failed to change publisher's frequency, because the group has already existed.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
frq_divider uint32 required Requested frequency divider, to scale down publisher rate.
alias string required Name of the group.
paths string repeated List of the parameters.

Error

Error description.

System type, which describes an error.

Field Type Label Description
timestamp fixed64 required System time, when error occurred.
error_number fixed32 required Error code.
error_level fixed32 required Error level.
subsystem fixed32 required Subsystem, for example 1 is 1st actuator of the system.
info fixed32 required Additional error code, provided by hardware.

ErrorList

List of errors.

Error messages are sent to the client as a list of N active errors.

Field Type Label Description
errors Error repeated List of active errors.
number_of_errors fixed32 required Number of errors in the list.
update_counter fixed32 required An update couter changes everytime the list of active errors is updated.

GetParameterListMsg

Request to get a list of parameters with info and values.

Server's reply: ParameterListMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
params GetParameterMsg repeated List of requested parameter.

GetParameterMsg

Request to get a parameter info and its value.

Server's reply: ParameterMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
path string required Path of the requested parameter.

GetParameterTreeHashMsg

Request to get a parameter tree hash.

Instead of requesting a complete parameter tree, a client might request only a tree hash to compare it against the cached tree to detect if the tree on the server has been changed. The difference between hashes indicates the changes in the tree structure. Note: Changes in parameter values do not result in a different tree hash.

Server's reply: ParameterTreeHashMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.

GetParameterTreeMsg

Request to get a parameter tree message

Server's reply: ParameterTreeMsg, with following status codes:

StatusCode::OK - user is logged out,

StatusCode::FAILED - operation failed.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.

GetSessionTokenMsg

Request a session token.

After user is logged-in it can request a session token for re-login.

Server's reply: SessionTokenMsg with the token status code.

Field Type Label Description
header Header optional Frame counter and actual time.

GroupMsg

Group message, used by the publisher. (Note: currently is not used, since publisher is not using protobuf)

Field Type Label Description
header Header optional Frame counter and actual time.
params ParameterMsg repeated List of published parameters.

GroupParameterInfo

Parameters' group information.

This data type represents the subscription information, required to decode parameters from the group message.

Field Type Label Description
index uint32 required Index of the subscribed parameter.
offset uint32 required Offset in the group message.
size uint32 required Size of the parameter.
info ParameterInfo required Parameter information.
status StatusCode required Status code.

GroupStatusMsg

Group package description.

Reply for 'CreateGroupMsg', with the package structure.

Message can have following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed,

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::FAILED_TO_SET_REQUESTED_FRQ - operation successful, but failed to change publisher's frequency, because the group has already existed.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
id uint32 required Unique id of the group.
alias string required Name of the group.
params GroupParameterInfo repeated List of parameters' info.
status StatusCode required Status code.

Generic message header, included in the request/reply messages.

Field Type Label Description
frameCounter fixed32 required Frame counter counts number of parameter updates.
timestamp fixed64 required Current server time in the format: microseconds from 1 Jan 2000.

LoadMsg

Request to load parameter values from the disk.

User's request to load parameter values from XML file.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::USER_LOGGED_IN_NO_CONTROL - User is in read-only mode.

StatusCode::FAILED_TO_OPEN - Failed to create/open a file.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
path string required Path to config file.
file_name string required File name.

LoginMsg

Login request.

User request to get access to the parameter tree.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - user is logged in,

StatusCode::READ_ONLY_MODE - user is logged in, read only mode,

StatusCode::WRONG_PASSWORD - login failed, wrong login or password.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
login string required User's login.
password string required User's password.

LogoutMsg

Logout request.

User request to exit. Logout will happen automatically if user is disconnected.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - user is logged out,

StatusCode::FAILED - operation failed,

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.

OverwriteParameterMsg

Request to overwrite/force a parameter value.

User's request to force a parameter value. For the Input and Parameter types the input value will be overwritten, for the Output type, the output value will be overwritten.

By enabling flag 'activate', overwrite value will be active until the flag is disabled, by ether commanding ReleaseParameterMsg or OverwriteParameterMsg with 'activate' - false.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::USER_LOGGED_IN_NO_CONTROL - User is in read-only mode.

StatusCode::WRONG_PARAMETER_PATH - Wrong parameter path.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
offset ParameterOffset optional Offset of the parameter value.
activate bool required Flag to enable/disable permanent overwrite.
path string required Path of the requested parameter.
value bytes required New values.

ParameterInfo

Parameter information fields.

Active state of the parameter in the tree, including its name, size, data type, io type and active flags.

Field Type Label Description
id uint32 required Unique id, assigned by parameter server.
data_type uint32 required Tag of the data type.
data_size uint32 required Size of one data element.
number_of_elements uint32 required Number of the elements.
flags uint32 required Parameter flags (overwrite, link etc…).
permissions uint32 required Access permissions.
param_type ParameterType required I/O type of the parameter.
group_id UserGroup required Group ID of the owner.
unit Unit required SI unit of the parameter.
path string required Path (including name) of the parameter.

ParameterListMsg

List of parameters with info values.

Reply for 'GetParameterListMsg', with the list of parameters info and values.

Message can have following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
params ParameterMsg repeated List of parameters.
status StatusCode required Status code.

ParameterMsg

Parameter info and its value.

Reply for 'GetParameterMsg', with the parameter info and a value.

Message can have following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
value bytes required Parameter value.
header Header optional Frame counter and actual time.
info ParameterInfo optional Parameter information.
status StatusCode required Status code.

ParameterOffset

ParameterOffset description.

An offset can be applied when setting a new value of the parameter array

Field Type Label Description
type OffsetType required Type of the offset. Default: OFFSET_ELEMENTS
offset uint32 required Starting point.
length uint32 required Length from starting point.

ParameterTreeHashMsg

Parameter tree hash.

Hash of the parameter tree.

Message can have following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
hash uint32 required Hash of the tree.
status StatusCode required Status code.

ParameterTreeMsg

Parameter tree data, which contains information about tree structure and available parameters. Message can have following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
params ParameterInfo repeated Array with available parameters.
hash uint32 required Hash value of the parameter tree stored in 'repeated ParameterInfo params'.
status StatusCode required Status code.

ReleaseParameterMsg

Request to release an overwrite/force.

User's request to cancel overwrite of a parameter value.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::USER_LOGGED_IN_NO_CONTROL - User is in read-only mode.

StatusCode::WRONG_PARAMETER_PATH - Wrong parameter path.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
path string required Path of the requested parameter.

RemoveGroupMsg

Request to remove a publisher group.

User's request to unsubscribe from the group.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed,

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
alias string required Name of the group.

RestoreSessionMsg

Restore session request.

User request to restore the old session to access to the parameter tree.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - user is logged in,

StatusCode::READ_ONLY_MODE - user is logged in, read only mode,

StatusCode::PERMISSION_DENIED - login failed, token expired,

StatusCode::FAILED - operation failed,

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
token string required Session token.

SaveMsg

Request to save parameter values to the disk.

User's request to save parameter values to XML file.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::USER_LOGGED_IN_NO_CONTROL - User is in read-only mode.

StatusCode::FAILED_TO_OPEN - Failed to create/open a file.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
path string required Path to a config file.
file_name string required File name.i

SessionTokenMsg

Session token.

A token with current session id. The toke is used for re-logging if the connection is lost.

Server's reply: SessionTokenmsg with the token and one of the following status codes:

StatusCode::OK - token is granted,

StatusCode::PERMISSION_DENIED - user has no permission,

StatusCode::FAILED - operation failed,

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
token string required Session token.
status StatusCode required Status code.

SetParameterListMsg

Request to set a list of parameters values.

User's request to update a list of parameters values.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::USER_LOGGED_IN_NO_CONTROL - User is in read-only mode.

StatusCode::WRONG_PARAMETER_PATH - Wrong parameter path.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
params SetParameterMsg repeated List of parameter set messages.

SetParameterMsg

Request to set a parameter value.

User's request to update a parameter value.

Server's reply: StatusMsg, with following status codes:

StatusCode::OK - operation successful,

StatusCode::FAILED - operation failed.

StatusCode::PERMISSION_DENIED - Permission denied because user has no access rights.

StatusCode::USER_LOGGED_IN_NO_CONTROL - User is in read-only mode.

StatusCode::WRONG_PARAMETER_PATH - Wrong parameter path.

StatusCode::FAILED_TO_DECODE - failed to decode request message.

Field Type Label Description
header Header optional Frame counter and actual time.
offset ParameterOffset optional Offset of the parameter value.
path string required Path of the requested parameter.
value bytes required New values has to be encoded according to the data type, which is provided in the parameter info.

StatusMsg

Status code message.

Reply with a status code for various request messages.

Field Type Label Description
header Header optional Frame counter and actual time.
status StatusCode required Return status of the request.

DataType

Available data types.

Data types supported by a parameter server.

User data types can be added after the tag USER_TYPE.

Name Number Description
data_type_undefined 0
INT8 1 integer 1 byte
UINT8 2 unsigned integer 1 byte
INT16 3 short int
UINT16 4 unsigned short int
INT32 5 int
UINT32 6 unsigned int
INT64 7 long
UINT64 8 unsigned long
BOOL 9 boolean
FLOAT 257 float
DOUBLE 258 double
CHAR 513 char
STRING 514 C-string
BYTES 1177 bytes array
USER_TYPE 1280 end of the system types

ErrorLevel

Available error levels.

Generic user levels generated by the logic. (Note: Check examples of the state machine.)

Name Number Description
error_level_undefined 0
INFO 1 Information message.
WARNING 2 Warning message.
FORCED_DISENGAGE 3 Graceful software stop, caused by a hardware malfunction or a wrong user actions.
SHUTDOWN 4 More abrupt software stop, caused by a hardware malfunction.
EMERGENCY_STOP 5 Abrupt software and hardware stop, caused by a hardware malfunction.

OffsetType

Avaliable offset types.

When setting a parameter value user can specify an offset and length

Name Number Description
offset_type_undefined 0
OFFSET_ELEMENTS 1 Offset and length is calculated in the elements. For example update an array starting from the element number 3.
OFFSET_BYTES 2 Offset and length is calculated in bytes.
OFFSET_BITS 3 Offset and length is calculated in bits.

ParameterFlag

System parameter's flag

Parameter can have various system flags, which shows that it is been overwritten or linked. (Note: This list will grow in future)

Name Number Description
LINK_IS_ACTIVE 1 Parameter is linked to another parameter.
OVERWRITE_IS_ACTIVE 2 Parameter is being overwritten.

ParameterType

Parameter's IO types.

Each parameter in the tree can be an INPUT, an OUTPUT or a PARAMETER.

PARAMETER type is both an input and output, it can be saved and loaded from the disk.

Value of a parameter with OUTPUT type cannot be set, but can be overwritten (forced). Force operation on the OUTPUT will only change the parameter value on everything that is linked to it. It will NOT change the internal value of the block to which the output belongs.

Name Number Description
param_type_undefined 0
INPUT 1 Input parameter.
OUTPUT 16 Output parameter.
PARAMETER 256 Input/output parameter, which is saved and loaded from the disk on request.
PARAMETER_VOLATILE 257 Input/output parameter, which is valotile, not saved or loaded from the disk.
PARAMETER_PERSISTENT 258 Input/output parameter, which is persistent, continuously saved and loaded from the disk.

Permission

Available parameters' permissions. Different users/groups may require access to different and/or protected parts of the parameter tree. Permission flags allow fine-tuning access levels of the groups.

The Motorcortex permissions structure is similar to that of Unix file permissions. Permissions are represented either in symbolic notation or in octal notation. (Note: User rights are not yet implemented, instead use Group rights)

For example:

———- (0000): no permission

-rwx—— (0700): read, write, & execute only for owner (Note: currently not implemented, user group flags instead)

-rwxrwx— (0770): read, write, & execute for owner and group (Note: execute flag is used as a permission to open folders)

-rwxrwxr-x (0775): read, write, & execute for owner and group, read & execute for all others.

-rwxrwxrwx (0777): full access

Name Number Description
permission_undefined 0
USER_READ 256 owner user read -r——–
USER_WRITE 128 owner user write –w——-
USER_EXECUTE 64 owner user execute —e——
GROUP_READ 32 owner group read —-r—–
GROUP_WRITE 16 owner group write —–w—-
GROUP_EXECUTE 8 owner group execute ——e—
OTHERS_READ 4 other users read ——-r–
OTHERS_WRITE 2 other users write ——–w-
OTHERS_EXECUTE 1 other users ———e

StatusCode

Return status codes.

Return status codes are included in the reply for every user's request. Using these codes user can verify if request was successful or there was a failure.

Name Number Description
OK 0 Request was processed successfully.
READ_ONLY_MODE 1 Login is successful, but user has read-only right.
FAILED 65280 Generic failure mask.
FAILED_TO_DECODE 4096 Failed to decode request message.
SUB_LIST_IS_FULL 4352 Failed to subscribe for a parameter, because subscription list is full. Create new parameter group.
WRONG_PARAMETER_PATH 4608 Failed to find parameter, because requested path is wrong.
FAILED_TO_SET_REQUESTED_FRQ 4864 When several clients share the same publisher's group, original publishing frequency is preserved.
FAILED_TO_OPEN_FILE 5120 Failed to open/save/load a file.
WRONG_PASSWORD 8448 Login failed, wrong login or password.
USER_NOT_LOGGED_IN 8704 Operation not permitted, because user is not logged in.
PERMISSION_DENIED 8960 Permission denied because user has no access rights.

Unit

Some SI units.

Name Number Description
unit_undefined 0
Length 15 Length mask 0xf
mm 1 millimeters 0x1
m 2 meters 0x2
Angle 241 Angle mask 0xf1
rad 49 radians 0x31
deg 65 degrees 0x41
Time 242 Time mask 0xf2
nanosec 18 nanoseconds 0x12
microsec 34 microseconds 0x22
millisec 50 milliseconds 0x32
sec 66 seconds 0x42
Weight 243 Weight mask 0xf3
gram 19 grams 0x13
kg 35 kilograms 0x23
Velocity 244 Velocity mask 0xf4
m_sec 20 linear velocity, meters per second 0x14
rad_sec 36 angular velocity, radians per second 0x24
Acceleration 245 Acceleration mask 0xf5
m_sec2 21 linear acceleration meters per second^2 0x15
rad_sec2 37 angular acceleration radians per second^2 0x25
Force 246 Force mask 0xf6
N 22 force, newtons 0x16
Nm 38 torque, newton-metres 0x26
percent 23 percentages 0x17

UserGroup

Available user groups.

Group determines an access level of the user. Users can belong to one group: Administrator, Operator or Guest. System is reserved for internal motorcortex-core use. By default Operator cannot read or write Administrator's related parameters. The administrator has a full access to the Operator's data.

Group access can be reconfigured in C++ server code or in the server configuration file. Furthermore, parameterization of the access can be done by setting permission level (Permission) of the parameter.

Name Number Description
user_group_undefined 0
SYSTEM 1 System group has full access. It is not available for the users.
ADMINISTRATOR 3 Administrator group has full access, except for system-level parameters.
OPERATOR 7 Operator has limited write access and read access.
GUEST 2147483647 Guest has read access.

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
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)
Last modified April 17, 2021: added protobuf description (592b516)