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 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>/<group_id>/<device_type>/<dev_id>
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
The command types used in the MQTT Commands are describing the targeted functionality of the whole command. The command types are:
- Set commands, which can be further specified by underscore to match a certain command. I.e., set_temperature.
- Query commands, which are used to query information from the end devices. They are used to force the readout out of the periodic report time cycle.
Table with Commands
| Name | Device type | Command Type | Command |
|---|---|---|---|
| Garage door | garage_door | set set_timer |
up, down, stop <timer> |
| Smart Watering | smart_water | set set_timer |
on, off <timer> |
| Lawnmowers | lawnmower | set setup |
on, off, start, stop <setup> |
| Security Cameras | camera | set query |
on, off stream |
| Doorbell | doorbell | set query |
disable, enable stream |
| Doorlock | doorlock | set setup |
lock, unlock <setup> |
| Blinds and Sunscreens | blinds | set set_timer |
up, down, stop <timer> |
| Smart Sockets | socket | set set_timer query </br> |
on, off <timer> consumption, current, voltage, power |
| Smart Plant Pots | plant_pot | setup set set_timer query |
<setup> watering_start, watering_stop <timer> moisture, ph, water_level |
| Motion Sensors | motion | set query |
on, off motion |
| Temperature Sensors | temperature | set query |
on, off temperature |
| Multi Sensors | multi_sensor | set query |
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 set_channel set_volume_level |
on, off, volume_up, volume_down, play, pause <channel> <volume> |
| Thermostat | thermostat | query set_temperature setup |
temperature <temperature> <setup> |
| Vacuum Cleaners | vacuum | set setup |
on, off, send_to_dock <setup> |
| Flood / Water Sensor | flood | set | on, off |
| Health Sensors | health | set query setup |
on, off weight, temperature, bmi, pressure <setup> |
| Washers & Dryers | washer_dryer | set set_timer setup |
on, off <timer> <setup> |
| Smart Spots / Lights | light | set set_color set_brightness set_temperature |
on, off <color> <brightness> <temperature> |
| Radiator Valve | radiator | set set_temperature setup |
on, off set_temperature <setup> |
| Solar Panels | solar | set query setup |
on, off current_power <setup> |
| Curtains | curtains | set setup |
up, down, stop <setup> |
| Climate Control | climate | set setup set_timer |
on, off <setup> <timer> |
| Smoke Detector | smoke | set query |
on, off smoke |
| Coffee Machines | coffee | set set_timer setup |
on, off <timer> <setup> |
| Voice Assistants | voice_assistant | set setup |
on, off <setup> |
| Dishwasher | dishwasher | set set_timer setup |
on, off <timer> <setup> |
| Keyfob & Remotes | keyfob_remote | set set_button setup |
on, off <button_press> <setup> |
| Ovens | oven | set set_timer setup |
on, off <timer> <setup> |
| Door / Window sensors | door | set query |
on, off state |
| Weather Stations | weather | set setup query |
on, off <setup> temperature, current_weather, humidity, wind, uv, forecast |
| Alarm | alarm | set query setup |
on, off, siren_on, siren_off, siren_walk_in, siren_walk_out, arm, disarm state <setup> |
| Utility meter | utility_meter | set setup query |
on, off <setup> voltage, frequency, tarif, current_consumption, state, weekly_consumption, monthly_consumption |
MQTT Commands Examples
To provide some examples of the MQTT Commands usage, we provide simple and complex examples.
Simple Command Example
{
"type": "command",
"timestamp": 1567677926,
"command_type": "set",
"value": "on"
}
Complex Command Example
{
"type": "command",
"timestamp":1567677926,
"command_type":"set_color",
"value": {
"unit": "hsb",
"h": 100,
"s": 100,
"b": 50
}
}
MQTT Reports
The MQTT Reports are used for the periodic and forced reports (replies). Their main purpose is therefore to report the measured values or action results back to the controlling app.
Description of Report Types
The report types are used to distinguish between different reports based on their purpose. They are further divided into:
- Status, which is reporting the current status of the device,
- Command response used to immediately report after the command request,
- Periodic report used to periodically publish current data/state into subscribed topics,
- Error used to inform about critical states or malfunctions.
Table with Reports
| Name | Device type | Report name | Report |
|---|---|---|---|
| Garage door | garage_door | state | closed, open, stopped, repair_needed |
| Smart Watering | smart_water | state | out_of_water |
| Lawnmowers | lawnmower | state | mowing, battery_low, battery_ok, repair_needed |
| Security Cameras | camera | stream state |
<stream_url> stream_failed |
| Doorbell | doorbell | stream state |
<stream_url> ringing, stream_failed |
| Doorlock | doorlock | state | locked, unlocked, lock_breach, lock_jammed, lock_failed, unlock_failed |
| Blinds and Sunscreens | blinds | state | closed, open, stopped, repair_needed |
| Smart Sockets | socket | state consumption current voltage power |
on, off <consumption> <current> <voltage> <power> |
| Smart Plant Pots | plant_pot | state | out_of_water |
| Motion Sensors | motion | state | motion_present |
| Temperature Sensors | temperature | temperature | <temperature> |
| Multi Sensors | multi_sensor | state temperature humidity motion smoke water |
on, off, repair_needed <temperature> <humidity> motion smoke water |
| Smart Speakers | speaker | state | on, off, no_media, playing, streaming_error, repair_needed |
| Smart TVs | tv | state channel_number volume_level |
on, off, repair_needed <channel_number> <volume_level> |
| Thermostat | thermostat | current_temperature set_temperature state |
<curr_temperature> <set_temperature> <mode> |
| Vacuum Cleaners | vacuum | state | on, off, vacuuming, battery_low, stuck, repair_needed |
| Flood / Water Sensor | flood | state | flood |
| Health Sensors | health | state weight temperature bmi pressure |
on, off, sensor_error <weigh> <temperature> <bmi> <pressure> |
| Washers & Dryers | washer_dryer | state timer |
on, off, in_progress, water_error, repair_needed <timer> |
| Smart Spots / Lights | light | state color brightness temperature |
on, off <color> <brightness> <temperature> |
| Radiator Valve | radiator | state current_temperature set_temperature |
on, off <curr_temperature> <set_temperature> |
| Solar Panels | solar | state power |
on, off, panel_error, battery_error <curr_power> |
| Wall Switches / Built-in Switches | switch | state timer |
on, off, mode <set_timer> |
| Curtains | curtains | state | closed, open, stopped, stuck |
| Climate Control | climate | state timer humidity |
on, off <set_timer> <humidity> |
| Smoke Detector | smoke | state | smoke_alarm |
| Coffee Machines | coffee | state timer |
on, off, water_low, water_ok, coffee_low, coffee_ok, milk_low, milk_ok, cleaning_needed, repair_needed <set_timer> |
| Voice Assistants | voice_assistant | state setup |
on, off <setup> |
| Dishwasher | dishwasher | state timer |
on, off, in_progress, water_error, repair_needed <set_timer> |
| Keyfob & Remotes | keyfob_remote | state mode |
on, off <mode> |
| Ovens | oven | state timer mode temperature |
on, off, light_on, light_off <set_timer> <mode> <temperature> |
| Door / Window sensors | door | state | open, closed |
| Weather Stations | weather | state temperature current_weather humidity wind uv forecast |
on, off <temperature> <current_weather> <humidity> <wind> <uv> <forecast> |
| Alarm | alarm | state | 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 | state value |
on, off utility_value |
MQTT Reports Examples
As for the commands, here we present two examples of the reports:
Simple Report Example
{
"type": "report",
"priority_level":2,
"report_type":"command_response",
"timestamp":1567677946,
"report_name":"state",
"report":"on"
}
Complex Report Example
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":1567677956,
"report_name":"color",
"report": {
"unit": "hsb",
"h": 100,
"s": 100,
"b": 50
}
}
MQTT2GO units
In this section, we provide a table with all units needed by 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 specfied inside the value field. The units 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 | % hsb, rgb |
| Weather Stations | Wind UV | m/s, km/h mW/cm2, mJ/cm2 |
| Smart TVs | Volume | % |
| Security Cameras Doorbells | Stream | URL address |
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 units example
Here we provide sample command and report to depict the correct usage of units:
MQTT2GO unit command
{
"type": "command",
"timestamp":1567677926,
"command_type":"set_color",
"value": {
"unit": "hsb",
"h": 100,
"s": 100,
"b": 50
}
}
MQTT2GO unit report
{
"type": "report",
"priority_level": 2,
"report_type":"command_response",
"timestamp":1567677956,
"report_name":"color",
"report": {
"unit": "hsb",
"h": 100,
"s": 100,
"b": 50
}
}