Control socket protocol

• Basics
• Configuration properties
• Status properties
• 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
• 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>,
		...
	}
}

Status properties list

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"
}