MQTT Objects
MQTT objects are describing all end devices that are connected to the MQTT2GO system. Their primary purpose is to either periodically report measurement results back to the SH-GW or to be controlled by the users and controllers to fulfill their role in the smart home.
Topics Structure
The topic structure for MQTT objects is in line with the general structure described in MQTT Topics. The topic structure is following.
<home_id>/<gateway_id>/<dev_id>/<entity>/<msg_direction>
Furthermore, as the MQTT standard allows users to define message retention, it is advised to turn this feature on for the MQTT2GO standard topics. This way, it can be made sure the devices will always know the last set state and behave accordingly.
MQTT Commands
The MQTT Commands described in this section are device specific and therefore they are arranged in tables for better understanding. The structure of the command is again compliant to the general structure from MQTT Commands.
Description of command types
To distinguish between the MQTT2GO commands that are going to the device, the msg_direction part of the topic is utilized. For all the commands, the msg_direction has to be set to in. Furthermore, to distinguish between different type of messages, the type is utilized. For the commands, it is mostly set type. If the type is set, the value contains the value that is going to be set. If the type is from the query "family", the value is ommited. If more complex setup is needed, a JSON structure will be sent inside the value.
Table with Commands
The table below summarizes the most common Smart Home devices and their device type in the MGTT2GO conventions. On top of that, also the command types and their expected values are given.
| Name | Device type | Type | Command |
|---|---|---|---|
| Garage door | garage_door | set | up, down, stop <timer> |
| Smart Watering | smart_water | set | on, off <timer> |
| Lawnmowers | lawnmower | set | on, off, start, stop <setup> |
| Security Cameras | camera | set stream |
on, off stream |
| Doorbell | doorbell | set stream |
disable, enable stream |
| Doorlock | doorlock | set | lock, unlock <setup> |
| Blinds and Sunscreens | blinds | set | up, down, stop <timer> |
| Smart Sockets | socket | set | on, off <timer> consumption, current, voltage, power |
| Smart Plant Pots | plant_pot | set | <setup> watering_start, watering_stop <timer> moisture, ph, water_level |
| Motion Sensors | motion | set | on, off motion |
| Temperature Sensors | temperature | set | on, off temperature |
| Multi Sensors | multi_sensor | set | on, off temperature, humidity, motion, smoke, water |
| Smart Speakers | speaker | set | on, off, play, shuffle, volume_up, volume_down, volume_level |
| Smart TVs | tv | set | on, off, volume_up, volume_down, play, pause <channel> <volume> |
| Thermostat | thermostat | set | temperature <temperature> <setup> |
| Vacuum Cleaners | vacuum | set | on, off, send_to_dock <setup> |
| Flood / Water Sensor | flood | set | on, off |
| Health Sensors | health | set | on, off weight, temperature, bmi, pressure <setup> |
| Washers & Dryers | washer_dryer | set | on, off <timer> <setup> |
| Smart Spots / Lights | light | set color brightness color_temp |
on, off <color> <brightness> <temperature> |
| Radiator Valve | radiator | set | on, off set_temperature <setup> |
| Solar Panels | solar | set | on, off current_power <setup> |
| Curtains | curtains | set | up, down, stop <setup> |
| Climate Control | climate | set | on, off <setup> <timer> |
| Smoke Detector | smoke | set | on, off smoke |
| Coffee Machines | coffee | set | on, off <timer> <setup> |
| Voice Assistants | voice_assistant | set | on, off <setup> |
| Dishwasher | dishwasher | set | on, off <timer> <setup> |
| Keyfob & Remotes | keyfob_remote | set | on, off <button_press> <setup> |
| Ovens | oven | set | on, off <timer> <setup> |
| Door / Window sensors | door | set | on, off state |
| Weather Stations | weather | set | on, off <setup> temperature, current_weather, humidity, wind, uv, forecast |
| Alarm | alarm | set | on, off, siren_on, siren_off, siren_walk_in, siren_walk_out, arm, disarm state <setup> |
| Utility meter | utility_meter | set | on, off <setup> voltage, frequency, tarif, current_consumption, state, weekly_consumption, monthly_consumption |
MQTT Device Removal Process
To be able to remove a device from the MQTT2GO system, a remove topic has to be used. The command structure is presented below.
<home_id>/<gw_id>/<device_id>/remove/in
{
"type": "control",
"timestamp": 1567677926,
"value": "true"
}
MQTT Commands Examples
To provide some examples of the MQTT Commands usage, we provide simple and complex structure examples.
Simple Command Example
<home_id>/<gw_id>/<device_id>/switch/in
{
"type": "set",
"timestamp": 1567677926,
"value": "on"
}
Complex Command Example
<home_id>/<gw_id>/<device_id>/color/in
{
"type": "color",
"timestamp":1567677926,
"value": {
"r": 100,
"g": 100,
"b": 50
}
}
MQTT Reports
The MQTT Reports are used for the periodic (with type of periodic_report) and forced reports (type of command_response). Their main purpose is therefore to report the measured values or action results back to the controlling app.
Table with Reports
The table below summarizes the most common Smart Home devices and their device type in the MGTT2GO conventions. On top of that, also, the reported values (or their format) are given.
| Name | Device type | Report |
|---|---|---|
| Garage door | garage_door | closed, open, stopped, repair_needed |
| Smart Watering | smart_water | out_of_water |
| Lawnmowers | lawnmower | mowing, battery_low, battery_ok, repair_needed |
| Security Cameras | camera | <stream_url> stream_failed |
| Doorbell | doorbell | <stream_url> ringing, stream_failed |
| Doorlock | doorlock | locked, unlocked, lock_breach, lock_jammed, lock_failed, unlock_failed |
| Blinds and Sunscreens | blinds | closed, open, stopped, repair_needed |
| Smart Sockets | socket | on, off <consumption> <current> <voltage> <power> |
| Smart Plant Pots | plant_pot | out_of_water |
| Motion Sensors | motion | motion_present |
| Temperature Sensors | temperature | <temperature> |
| Multi Sensors | multi_sensor | on, off, repair_needed <temperature> <humidity> motion smoke water |
| Smart Speakers | speaker | on, off, no_media, playing, streaming_error, repair_needed |
| Smart TVs | tv | on, off, repair_needed <channel_number> <volume_level> |
| Thermostat | thermostat | <curr_temperature> <set_temperature> <mode> |
| Vacuum Cleaners | vacuum | on, off, vacuuming, battery_low, stuck, repair_needed |
| Flood / Water Sensor | flood | flood |
| Health Sensors | health | on, off, sensor_error <weigh> <temperature> <bmi> <pressure> |
| Washers & Dryers | washer_dryer | on, off, in_progress, water_error, repair_needed <timer> |
| Smart Spots / Lights | light | on, off <color> <brightness> <temperature> |
| Radiator Valve | radiator | on, off <curr_temperature> <set_temperature> |
| Solar Panels | solar | on, off, panel_error, battery_error <curr_power> |
| Wall Switches / Built-in Switches | switch | on, off, mode <set_timer> |
| Curtains | curtains | closed, open, stopped, stuck |
| Climate Control | climate | on, off <set_timer> <humidity> |
| Smoke Detector | smoke | smoke_alarm |
| Coffee Machines | coffee | on, off, water_low, water_ok, coffee_low, coffee_ok, milk_low, milk_ok, cleaning_needed, repair_needed <set_timer> |
| Voice Assistants | voice_assistant | on, off <setup> |
| Dishwasher | dishwasher | on, off, in_progress, water_error, repair_needed <set_timer> |
| Keyfob & Remotes | keyfob_remote | on, off <mode> |
| Ovens | oven | on, off, light_on, light_off <set_timer> <mode> <temperature> |
| Door / Window sensors | door | open, closed |
| Weather Stations | weather | on, off <temperature> <current_weather> <humidity> <wind> <uv> <forecast> |
| Alarm | alarm | alarm_button_pressed, alarm_off_button_pressed, arc_alert, arc_alert_arm_status, arc_alert_deprovision, arc_alert_revision, arc_error, arc_test_result, arm_status_change, glass_breakage, panic_button_pressed, tamper_cleared, tamper_detected |
| Utility meter | utility_meter | on, off utility_value |
MQTT Reports Examples
To provide complete example of the command - report message structure. Below we provide the example structure for simple and complex reports.
Simple Report Example
<home_id>/<gw_id>/<device_id>/switch/out
{
"priority_level":2,
"timestamp":1567677946,
"type":"command_response",
"report":"on"
}
Complex Report Example
<home_id>/<gw_id>/<device_id>/color/out
{
"priority_level": 2,
"timestamp":1567677956,
"type":"command_response",
"report": {
"unit": "hsb",
"h": 100,
"s": 100,
"b": 50
}
}
MQTT2GO units
In this section, we provide a table with all currently utilized units in the MQTT2GO messages. If the unit needs to be specified for selected command/report (meaning the command/report is not simple on,off,etc.), then the value will be specified inside the value field. The utilized unit types are following:
| Device type | Data type | Unit |
|---|---|---|
| Smart Sockets Solar Panels | Power | W |
| Multi Sensors Thermostats Radiator Valves Health Sensors Climate Control Ovens Weather Stations | Temperature | C, F, K |
| Garage Doors Smart Watering Blinds and Sunscreens Smart Sockets Smart Plant Pots Washers & Dryers Climate Control Coffee Machines Dishwashers Ovens | Timer | hh:mm:ss |
| Smart Plant Pots Weather Stations | Humidity PH | % 0-14 |
| Health Sensors | Weight BMI Pressure | kg, lb kg/m2 mmHg |
| Smart Spots / Lights | Brightness Color Temperature | % hsb, rgb, rgbwaf, xy |
| Weather Stations | Wind UV | m/s, km/h mW/cm2, mJ/cm2 |
| Smart TVs | Volume | % |
The units specified above are for currently supported devices. If a new type of device will be added, the unit structure should follow the MQTT2GO standard.
MQTT2GO About Topic Example
About Command
<home_id>/<gw_id>/<device_id>/about/in
{
"priority_level": 2,
"timestamp":1567677956,
"type":"query"
}
About Response
<home_id>/<gw_id>/<device_id>/about/in
{
"priority_level": 2,
"timestamp":1567677956,
"type":"command_response",
"value": {
"device_id": "device_id_value",
"topics": ["topic_name_1", ...],
"status": "status_value"
}
}