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>/<dev_id>/<entity>/<msg_direction>
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.
Add Commands
The add commands are primarily used to create new objects like groups, users, rooms, and devices. They also utilize suffixes for differentiation. In the following paragraphs, all of the add commands will be described.
Add group
Group creation is done via group topic with create type and value body of a JSON structure with the following format.
<home_id>/<gw_id>/group/in
{
"type": "create",
"timestamp": "timestamp_value",
"value": {
"group_id": "group_id"
}
}
Where the <group_id> can be either a value or field of values.
Room Creation
Room creation is done via room topic with create type and value body of a JSON structure with the following format.
<home_id>/<gw_id>/room/in
{
"type": "create",
"timestamp": "timestamp_value",
"value": {
"room_name": "room_name"
}
}
Scene Creation
Scene creation is done via scene topic with create type and value body of a JSON structure with the following format.
<home_id>/<gw_id>/scene/in
{
"type": "create",
"timestamp": "timestamp_value",
"value": {
"scene_name": "scene_name"
}
}
Add User
For adding a new user, the <home_id>/in topic with command type of create_user with JSON body with following format is used.
<home_id>/in
{
"type": "create_user",
"timestamp": "timestamp_value",
"value": {
"email": "email",
"user_name": "name",
"password": "pwd",
"role": "role"
}
}
Add Device to Group
For adding a new device to selected group, the add_device command type with JSON body with following format is used.
<home_id>/<gw_id>/group/in
{
"type": "add_device",
"timestamp": "timestamp_value",
"value": {
"group_name": "group_name",
"device_id": "device_id"
}
}
Add Device to Scene
For adding a new device to selected scene, the add_device command type with JSON body with following format is used.
<home_id>/<gw_id>/scene/in
{
"type": "add_device",
"timestamp": "timestamp_value",
"value": {
"device_id": "id",
"scene_name": "scene_name"
}
}
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 edit_user with JSON body of:
<home_id>/in
{
"type": "edit_user",
"timestamp": "timestamp_value",
"value": {
"user_id": "id",
"email": "email",
"user_name": "name",
"password": "pwd",
"role": "role"
}
}
Room Editing
Room editing is done by the commands with type of edit with JSON body of:
<home_id>/<gw_id>/room/in
{
"type": "edit",
"timestamp": "timestamp_value",
"value": {
"room_id": "room_id",
"room_name": "rooom_name"
}
}
Scene Editing
Scene editing is done by the commands with type of edit with JSON body of:
<home_id>/<gw_id>/scene/in
{
"type": "edit",
"timestamp": "timestamp_value",
"value": {
"scene_id": "scene_id",
"scene_name": "scene_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, delete command type is exploited and the format is of the JSON body is:
<home_id>/<gw_id>/group/in
{
"type": "delete",
"timestamp": "timestamp_value",
"value": {
"group_id": "group_id"
}
}
where the <group_id> can be either a single value or array.
Remove User
To remove a user, a remove command type is used, with a JSON body of:
<home_id>/in
{
"type": "remove_user",
"timestamp": "timestamp_value",
"value": {
"user_id": "user_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 query_all.
<home_id>/<gw_id>/devices/in
{
"type": "query_all",
"timestamp": "timestamp_value",
"value": "all"
}
Query User Info
Query user info is used to recall information about selected user. Its value field contains the selected user_id.
<home_id>/in
{
"type": "user_info",
"timestamp": "timestamp_value",
"value": "user_id"
}
Query All Devices in Group
Query all devices in specified group. Its value field is filled with group_id.
<home_id>/<gw_id>/group/in
{
"type": "query_all",
"timestamp": "timestamp_value",
"value": "group_id"
}
Query All Groups
Query devices in group asks for all groups. Its value field is filled with group_id.
<home_id>/<gw_id>/group/in
{
"type": "query_all",
"timestamp": "timestamp_value"
}
MQTT Reports
The MQTT reports utilized here are mostly a replies to the commands from the controlled devices. They follow the general report structure and add a specific report names. The report value can be either a simple OK, or a body JSON of following structure:
<home_id>/<gw_id>/devices/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value": "value"
}
, where event_name can be warning or error.
Add Reports
The add reports are generally used to report the result of add commands. They will be describing in following subsections.
Group Creation Report
After the add_group command is received. The device process it and then publishes following message to the same topic:
<home_id>/<gw_id>/group/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":"value"
}
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:
<home_id>/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":{
"event" : "event_value",
"reason" : "reason_value"
}
}
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:
<home_id>/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":"value"
}
Group Editing Report
After the updt_group command is issues, the following response is published into the same topic:
<home_id>/<gw_id>/group/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":"value"
}
Delete Reports
The delete reports are the primary outcome of the events started by delete commands. Their message structure also follows the general report structure. 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 published after the del_group command is issued.
<home_id>/<gw_id>/group/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":"value"
}
Remove User
Is the report which is published after the del_user command is issued.
<home_id>/<gw_id>/user/out
{
"type": "command_response",
"priority_level": 2,
"timestamp": "timestamp_value",
"value": "value"
}
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 selected SH-GW. It has following structure:
<home_id>/<gw_id>/devices/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"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 selected SH-GW. It has following structure:
<home_id>/<gw_id>/group/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":[ "group_1_id", "group_2_id", ...]
}
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:
<home_id>/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"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:
<home_id>/<gw_id>/group/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"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:
<home_id>/out
{
"type": "command_response",
"priority_level": 2,
"timestamp":"timestamp_value",
"value":[ "topic1", "topic2",...]
}
The value can contain a simple topic or a field of topics, as illustrated above.
MQTT2GO Event Topic
MQTT2GO standard also defines a special topic for designated for logging all events happening inside the smart home. This topic is:
<home_id>/<gateway_id>/events/<msg_direction>
Its primary goal is to cumulate all important events at one place. It can be utilized for example by machine-learning controller, that will be sending events about unusual activity into this topic. The structure of the event message is as follows:
{
"priority_level": 2,
"timestamp":"timestamp_value",
"value": {
"event_name": "event_name",
"message": "message"
}
}