MQTT Controllers
MQTT Controllers are devices which are primarily serving as a controlling units. These devices can be either a physical device (touchscreen controller, smartphone, etc.) or a software controllers, which are accessible from the network (i.e., via HTTP).
Topics Structure
The basic topic structure is based on the general MQTT2GO topic structure. The only difference here is that the controller can either control the end devices directly, or indirectly through groups and gateways.
<home_id>/<gateway_id>/<group_id>/<device_type>/<dev_id>
MQTT Commands
The MQTT commands for the controllers are used to control the end devices. This means that most of the commands are targeted at setting up selected parameters of the end devices or changing the structure of the MQTT2GO households. Their structure is based on the MQTT Commands.
Set commands
The set commands are used to change / add device parameters and information. They are exactly the same as in Table with MQTT2GO commands with the addition of the set_group command type, which is used to set / change the group of selected end device. Its JSON body is:
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "set_group",
"value": {
"group_id": "group_id"
}
}
Where the <group_id> can be either a value or field of values.
Add Commands
The add commands are primarily used to create new objects like groups, users, and devices. They also utilize suffixes for differentiation. In the following paragraphs, all of the add commands will be described.
Group Creation
Group creation is done via add_group command type with value body of a JSON structure with the following format.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "add_group",
"value": {
"group_name": "group_name"
}
}
Add User
For adding a new user, the add_user command type with JSON body with following format is used.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "add_user",
"value": {
"user_id": "id",
"email": "email",
"user_name": "name",
"role": "role"
}
}
Edit Commands
The edit commands are used to edit parameters of objects such as users, groups, and devices.
User Editing
User editing is done by commands with type of updt_user with JSON body of:
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "updt_user",
"value": {
"user_id": "id",
"email": "email",
"user_name": "name",
"role": "role"
}
}
Group Editing
Group editing is done by the commands with type of updt_group with JSON body of:
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "updt_group",
"value": {
"group_id": "group_id",
"group_name": "group_name"
}
}
Delete Commands
Delete commands are primarily used to remove objects such as groups, devices, and users.Their suffixes are again based on the targeted functionality and are used as follows.
Remove Group
To remove a group, del_group command type is exploited and the format is of the JSON body is:
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "del_group",
"value": {
"group_id": "group_id"
}
}
where the <group_id> can be either a single value or array.
Remove User
To remove a user, a del_user command type is used, with a JSON body of:
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "del_user",
"value": {
"user_id": "user_id"
}
}
Remove Device
To remove a device, a del_device command type is used. Its JSON body is:
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "del_device",
"value": {
"dev_id": "dev_id"
}
}
Query Commands
The query commands utilized by the controllers are following the extension typology as the aforementioned set commands. The command type is therefore in form of query_querytype. They can be divided by their command type.
Query All Devices
Query all devices is used to request all available devices, its value will be all.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "query_all",
"value": "all"
}
Query Device Info
Query device info requests information about selected device. Its value will be the selected dev_id.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "query_dev_info",
"value": "dev_id"
}
Query User Info
Query user info is used to recall information about selected user. Its value field contains the selected user_id.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "query_user_info",
"value": "user_id"
}
Query All Devices in Group
Query devices in group asks for all devices in specified group. Its value field is filled with group_id.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "query_all_in_group",
"value": "group_id"
}
Query All Groups
Query devices in group asks for all groups. Its value field is filled with group_id.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "query_all_groups",
"value": "all"
}
Query User’s Topics
Query user’s topics requests the topics that selected user is subscribed to. Its value field contains the user_id.
{
"type": "command",
"timestamp": "timestamp_value",
"command_type": "query_user_topics",
"value": "user_id"
}
MQTT Reports
The MQTT reports utilized here are mostly a replies to the commands from the controlled devices. They follow the genaral report structure and addd a specific report names. The report value can be either a simple OK, or a body JSON of following structure:
{
"event": "event_name",
"reason": "event_description"
}
, where event_name can be warning or error
Add Reports
The add reports are generally used to report the reuslt of add commands. They will be describing in following subsections.
Group Creation Report
After the add_group command is received. The device proccess it and then publishes following message to the same topic:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"add_group",
"value":"ok"
}
Add User Report
After the add_user command is received, the devices processes it and then publishes following message into the same topic from which the command came:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"add_user",
"value":{
"event" : "error",
"reason" : "user_already_exists"
}
}
Edit Reports
The edit reports are used to report the outcome of edit commands.
User Editing report
After the updt_user command is issues, the following response is published into the same topic:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"updt_user",
"value":"ok"
}
Group Editing Report
After the updt_group command is issues, the following response is published into the same topic:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"updt_group",
"value":"ok"
}
Delete Reports
The delete reports are the primary outcome of the events started by delete commands. Their message structure also follows the general report struture. Its value follows the same pattern as the general MQTT report, described in this chapter. Therefore the value can be either a simple ok, or a JSON body with the event name and description.
Remove Group
Is the report which is pubilshed after the del_group command is issued.
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"del_group",
"value":"ok"
}
Remove User
Is the report which is pubilshed after the del_user command is issued.
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"del_user",
"value":"ok"
}
Remove Device
Is the report which is pubilshed after the del_group command is issued.
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"del_device",
"value":"ok"
}
Query Reports
Query reports are the most bulky reports from this chapter. They contain a response that is awaited by the controlled after issuing a query command. The query command is usually used to force important device information.
Query All Devices Report
Is used to return all devices under seleced SH-GW. It has following structure:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"query_all",
"value":[ "device_1_id", "device_2_id",...]
}
The value of this report contains a field of all available devices ids.
Query All Groups Report
Is used to return all devices under seleced SH-GW. It has following structure:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"query_all_groups",
"value":[ "group_1_id", "group_2_id",...]
}
Query Device Info Report
This report is utilized to return all device information requested by the query_dev_info command. Its structure is following:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"query_dev_info",
"value": {
"dev_id": "device_id",
"dev_name": "device_name",
"dev_group": "device_group"
}
}
Query User Info Report
This report provides information about the user. This report is invoked by the query_user_info command. Its structure is following:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"query_user_info",
"value": {
"user_id": "user_id",
"email": "john.doe@mail.com",
"user_name": "John Doe",
"role": "administrator"
}
}
Query All Devices in Group Report
Is used to return all devices in specified group. It has following structure:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"query_all_in_group",
"value":[ "device_1_id", "device_2_id",...]
}
The value of this report contains a field of ids for all devices in specified group.
Query User’s Topics Report
This report contains all topics of specified user. Its structure is following:
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":"timestamp_value",
"report_name":"query_user_topics",
"value":[ "topic1", "topic2",...]
}
The value can contain a simple topic or a field of topics, as illustrated above.