Control socket protocol

• Basics
• Configuration properties
• Status properties
• Interface lock-status
• Date and Time
• Reboot
• Poweroff
• Errors

Basics

The communication protocol consists in exchanging of messages. Each message consists of binary-based length field followed by text-based json package. The message can be described by this packed C structure:

struct __attribute__((packed)) message {
	uint32_t length;
	uint8_t  json[];
};

At the root level each json package must contain element named as id. Its string-typed value determines both the meaning of json package and also the presence of another elements. So the minimal json package looks like this:

{
	"id": <value>
}

Configuration properties

Configuration properties have these features:

• They determine MGB behaviour
• They have their counterparts in web interface
• They are persistent
• You can both set and get them
• Their changes are broadcasted

Currently the validation of configuration properties is very limited, so it is mainly on user's own responsibility to set the correct values.

Set configuration properties

You can set the configuration properties with:

{
	"id": "set_configuration_properties",
	"properties": {
		<property_name>: <property_value>,
		<property_name>: <property_value>,
		...
	}
}

Any unknown property is ignored silently.

Response:

{
	"id": "set_configuration_properties_response",
	"result": <value>
	"properties": {
		<property_name>: <property_value>,
		<property_name>: <property_value>,
		...
	}
}

Result is contained in boolean-typed result element. Possible values:

Get configuration properties

You can get the configuration properties with:

{
	"id": "get_configuration_properties",
	"properties": [<property_name>, <property_name>, ...]
}

Empty properties element is considered as to get all available configuration properties. Any unknown property is ignored silently.

Response:

{
	"id": "get_configuration_properties_response",
	"properties": {
		<property_name>: <property_value>,
		<property_name>: <property_value>,
		...
	}
}

Configuration properties change

Whenever the configuration properties are changed, then all the control socket clients (not causing this change) are informed with:

{
	"id": "configuration_properties",
	"properties": {
		<property_name>: <property_value>,
		<property_name>: <property_value>,
		...
	}
}

Configuration properties list

Status properties

Status properties have these features:

• They report about MGB status
• You can only get them
• If required, their changes are broadcasted

Get status properties

You can get the status properties with:

{
	"id": "get_status_properties",
	"properties": [<property_name>, <property_name>, ...]
}

Empty properties element is considered as to get all available status properties. Any unknown property is ignored silently.

Response:

{
	"id": "get_status_properties_response",
	"properties": {
		<property_name>: <property_value>,
		<property_name>: <property_value>,
		...
	}
}

Status properties change

Whenever the status properties are changed, then all the control socket clients are informed with:

{
	"id": "status_properties",
	"properties": {
		<property_name>: <property_value>,
		<property_name>: <property_value>,
		...
	}
}

Each control socket client gets only its own subscribed status properties.

Subscription to status properties

When control socket client wants to receive changed status properties, it must subscribe to them with:

{
	"id": "subscribe_status_properties",
	"properties": [<property_name>, <property_name>, ...]
}

Empty properties element is considered as to subscribe to all available status properties. Any unknown property is ignored silently.

Response:

{
	"id": "subscribe_status_properties_response",
	"result": <value>
}

Result is contained in boolean-typed result element. Possible values:

When control socket client doesn't want to receive changed status properties, it must unsubscribe to them with:

{
	"id": "unsubscribe_status_properties",
	"properties": [<property_name>, <property_name>, ...]
}

Empty properties element is considered as to unsubscribe to all subscribed status properties. Any unknown property is ignored silently.

Response:

{
	"id": "unsubscribe_status_properties_response",
	"result": <value>
}

Result is contained in boolean-typed result element. Possible values:

The subscription state of each just connected control socket client is controlled by system_statprop_defsubscr configuration property. When the property is set to true, then each just connected control socket client is subscribed to all available status properties automatically. When the property is set to false, then each just connected client is not subscribed to any status property.

Status properties list

Interface lock-status

Lock-drop counter reset

You can reset lock-drop counter with:

{
	"id": "reset_iface_lockdrop_counter"
}

Response:

{
	"id": "reset_iface_lockdrop_counter_response",
	"result": <value>
}

Result is contained in boolean-typed result element. Possible values:

Date and Time

All datetime elements are string-typed and hold the local date and time in this format (see POSIX function strptime):

%Y-%m-%d %H:%M:%S

Set local date and time

You can set the local date and time with:

{
	"id": "set_local_datetime",
	"datetime": <value>
}

Response:

{
	"id": "set_local_datetime_response",
	"result": <value>
}

Result is contained in boolean-typed result element. Possible values:

Get local date and time

You can get the local date and time with:

{
	"id": "get_local_datetime"
}

Response:

{
	"id": "get_local_datetime_response",
	"datetime": <value>
}

Reboot

{
	"id": "reboot"
}

There is no response. However if the command is executed successfully, then the control socket closes at the MGB side.

Poweroff

{
	"id": "poweroff"
}

There is no response. However if the command is executed successfully, then the control socket closes at the MGB side.

Errors

In case of any problem with parsing of received json package (missing, unknown or wrong-typed elements), the response will be:

{
	"id": "error"
}