TapHome

Shelly Gas MQTT

Packet Parser → MQTT
Submitted by
Last updated: 08. 2026

This device supports mDNS

Instead of using an IP address, you can reach the device at:

shellygas-{MAC}.local

Replace {MAC} with your device's MAC address (uppercase, no colons).

TapHome supports mDNS — using a hostname is more reliable than a static IP.

Shelly Gas MQTT

The Shelly Gas (model SHGS-1) is a mains-powered Wi-Fi detector for combustible gas. It plugs directly into a wall socket, measures gas concentration continuously and raises its own sound and light alarm when the concentration crosses a threshold. It is sold as two separate products — Shelly Gas CNG for compressed natural gas (methane) and Shelly Gas LPG for liquefied petroleum gas (propane / butane). Both share the same firmware and the same MQTT topics, so this one template works with either; only the sensor element and the recommended mounting height differ.

This template connects to an MQTT broker, not to the device directly. The module subscribes to shellies/# on the broker and filters out the messages belonging to one Shelly Gas unit by its Device ID. TapHome receives the alarm state and the gas concentration as the device publishes them, and can start a sensor self-test.

An HTTP variant of this template is also available (Shelly Gas). Use this MQTT template when an MQTT broker already runs in the installation and push updates are preferred; use the HTTP template when there is no broker.

Shelly Gas is a safety device. The TapHome integration supplements its built-in buzzer and LED alarm — it does not replace them. The buzzer and the LED work independently of MQTT, of the broker and of the TapHome control unit, and keep working when any of those is unavailable.

Hardware

Placement

The unit plugs into a mains socket — there is no wiring. The correct mounting height depends on the gas variant, because the two gases behave differently in air.

VariantGas detectedBehaviour in airRecommended placement
Shelly Gas CNGCompressed natural gas (methane)Lighter than air, collects at the ceiling0.3–1 m below the ceiling, vertically, and 1.5 m from the gas source
Shelly Gas LPGLiquefied petroleum gas (propane / butane)Heavier than air, collects at floor level0.3 m above the floor, within 1.5 m of the gas source

CNG and LPG are two separate products with different sensors, not a switchable mode. If the variant is unclear, check the markings on the back of the device.

Specification
ParameterValue
Power supply110–230 V ±10 %, 50/60 Hz AC
Power consumption< 3 W
Alarm sensitivity6 % LEL (lower explosive limit)
Sound level≥ 70 dB
Wi-Fi802.11 b/g/n, 2400–2484 MHz
Rangeup to 50 m outdoors, up to 30 m indoors
Operational temperature−10 °C to +50 °C
Valve manipulator jack output11–13 V, 500 mA (external accessory, not controlled by this template)
Dimensions89.5 × 89.5 × 38 mm (plug not included)
Local indication

The LED ring and the buzzer are the device’s own indication. TapHome sees only the two topics described under Device capabilities, so these signals carry information that does not reach the control unit.

LED ringMeaning
Solid greenSensor in normal operation
Solid yellowSensor fault
Flashing redAlarm
Flashing red / yellow / green in sequenceSensor warming up
Buzzer patternEvent
Two short beeps per secondWarm-up started after power on
One long beep per secondWarm-up finished
Long beep once per second until the fault clearsSensor fault
Three short beeps twice per secondSelf-test running
Long beep once per secondSelf-test finished successfully
Long beep once per second, until the leak is gone or escalatesMild gas leak
Five seconds of beeping with a one-second pause, until the leak is goneHeavy gas leak

After power-up the device runs a self-test that takes about three minutes. The LED ring cycles green → orange → red during it and the gas reading is not valid.

Configuration

Enabling MQTT on the device
  1. Open the device’s web interface in a browser.
  2. Go to Internet and Security → Advanced - Developer Settings.
  3. Tick Enable action execution via MQTT.
  4. Fill the Server field using the formula {MQTT broker IP address}:{port} — for example 192.168.1.10:1883.
  5. Press SAVE. The device reconnects and starts publishing to the broker.

On Gen1 firmware, enabling MQTT disables the Shelly Cloud connection — the two cannot run at the same time. Gen1 devices also do not support MQTT over TLS, so the broker must accept plain MQTT on port 1883. Keep the broker on a trusted local network.

Reading the Device ID

In the web interface go to Settings → Device Info → Device ID. The value needed is the first string of characters, not the value in brackets. It is a Shelly-ID of six or more characters, for example 35FA58. The same identifier appears in the Wi-Fi network the device creates in access-point mode (ShellyGas-35FA58) and forms the MQTT topic prefix shellies/shellygas-35FA58/.

Template setup

The template asks for three import parameters:

Import parameterDefaultValue to enter
Mqtt Broker IP address192.168.0.1IP address of the MQTT broker — not of the Shelly Gas
Mqtt Broker port1883Port the broker listens on
Device ID—The Shelly-ID read above, e.g. 35FA58

The Device ID import parameter fills the module-level deviceID variable, which builds the topic prefix for every topic the module uses. The module subscribes to shellies/# and its listener scripts filter the incoming messages by that prefix.

By default the device publishes an update every 30 seconds. Setting the device parameter mqtt_update_period to 0 switches it to reporting only on change.

Device capabilities

Gas alarm

Gas Alarm is a multi-value switch fed from shellies/shellygas-<deviceID>/sensor/gas. It carries the alarm level the device has already derived from the measured concentration.

TapHome valueMQTT payloadMeaning
No alarmnoneConcentration below 1800 ppm
Mild gas leakmildConcentration at or above 1800 ppm
Heavy gas leakheavyConcentration at or above 3000 ppm
Self TesttestPublished after a successful self-test
Alarm state is unknownunknown or any other payloadThe device cannot state the alarm level

The two thresholds are fixed in the device firmware and cannot be changed.

Gas concentration

Gas Concentration reads the raw value from shellies/shellygas-<deviceID>/sensor/concentration in parts per million, range 0–65535 ppm. It is the same physical measurement as Gas Alarm, before the firmware applies its thresholds.

Use Gas Alarm for alarm logic and Gas Concentration for trends, charts and custom early-warning limits below 1800 ppm. A rule should not re-derive its own alarm level from the ppm value and expect it to match the device — the buzzer and the LED follow the fixed firmware thresholds.

The device publishes -1 on the concentration topic whenever the reading is not valid — during the roughly three-minute warm-up after power-up, and while the sensor is faulted. The template stores that -1 as it is; it is not a TapHome error code.

Self test

The module provides a Self test service action, which publishes to shellies/shellygas-<deviceID>/sensor/start_self_test. The device beeps three short beeps twice per second while the test runs and publishes test on the gas topic when it succeeds, which appears in TapHome as the Self Test value of Gas Alarm.

Known limitations

Mute Active Alarm does not reach the device

The template contains a Mute Active Alarm push button, but in the current template revision it has no effect. The button publishes to the literal topic shellies/shellygas-<deviceid>/sensor/mute — the <deviceid> placeholder is never replaced with the configured Device ID, so the message goes to a topic no real device subscribes to. The other three topics in the same template build their prefix correctly from the deviceID variable.

Do not rely on the Mute Active Alarm button. Muting an active alarm from TapHome will work only once the template is corrected to build the topic from the deviceID variable. The alarm can always be muted on the device itself, using Mute in its web interface — and only while an alarm is actually active.

Troubleshooting

No values arrive in TapHome
  1. Verify MQTT is enabled on the device and the Server field holds the broker address in the form {IP}:{port}
  2. Check that the module endpoint points at the MQTT broker, not at the Shelly Gas IP address
  3. Confirm the Device ID matches exactly what Settings → Device Info → Device ID shows — the first string only, without the value in brackets
  4. Subscribe to shellies/# with an MQTT client (for example MQTT Explorer) and check that messages arrive under shellies/shellygas-<your-id>/
  5. If the device was switched to change-only reporting (mqtt_update_period = 0), run the Self test service action — a successful test publishes on the gas topic
Gas Concentration shows -1

The sensor reading is not valid. Either the device is still warming up — about three minutes after power-up — or the sensor has a fault. A fault shows on the device as a solid yellow LED and a long beep once per second. This template does not read the sensor state topic, so a fault reaches TapHome only as this -1.

Gas Alarm shows “Alarm state is unknown”

This value is the fallback branch of the template. It catches the documented unknown payload and any payload outside the four known values. Check the LED ring on the device to see what state the sensor is actually in.

The device disappeared from Shelly Cloud

Expected on Gen1 firmware — enabling MQTT disables the cloud connection. Reach the web interface over the local network instead, using the device IP address or the mDNS hostname shellygas-<MAC>.local.

How to install in TapHome

Prerequisites

  • Shelly device connected to Wi-Fi (see HTTP connection guide if not done yet)
  • MQTT broker running on your local network (e.g., Mosquitto, Home Assistant, or TapHome built-in broker)
  • TapHome CCU on the same network as the broker

On Gen1 devices, enabling MQTT disables Shelly Cloud. Both cannot run simultaneously. On Gen2/Plus devices this limitation does not apply.

Step 1 — Enable MQTT on the Shelly device

Gen1 devices (Shelly 1, 1PM, 2.5, EM, 3EM, Plug S, RGBW2, Dimmer, TRV…)

  1. Open the Shelly web UI: http://<device-ip>/
  2. Navigate to Internet & Security → Advanced — MQTT
  3. Enable MQTT
  4. Set MQTT Server: <broker-ip>:<port> (e.g., 192.168.1.10:1883)
  5. Optionally set MQTT User and MQTT Password if your broker requires authentication
  6. Click Save — the device will reboot and connect to the broker

Gen2 / Plus devices (Shelly Plus 1, Plus 1PM, Plus 2PM, Plus Plug S, Plus H&T, Pro 3EM…)

  1. Open the Shelly web UI: http://<device-ip>/
  2. Navigate to Settings → MQTT
  3. Enable MQTT
  4. Set Server: <broker-ip>:<port> (e.g., 192.168.1.10:1883)
  5. The Client ID is pre-filled with the device ID (e.g., shellyplus1pm-AABBCCDDEE) — leave as-is unless you have a specific reason to change it
  6. Click Save and reboot the device

To verify MQTT is working, use an MQTT client (e.g., MQTT Explorer) and subscribe to shellies/# (Gen1) or <device-id>/# (Gen2). You should see status messages from the device.

Step 2 — Find the Device ID / MQTT Client ID

Some templates require a Device ID or MQTT Client ID parameter. This is the unique identifier used in MQTT topics.

  • Gen1: found on the label as MAC address (e.g., AABBCCDDEE). Device ID = shelly<model>-<mac>, e.g., shelly1pm-AABBCCDDEE
  • Gen2/Plus: found in the Shelly web UI under Settings → Device Info → Device ID, or on the device label

Step 3 — Configure in TapHome

  1. In TapHome, add a new Packet Parser (MQTT) module
  2. IP Address: enter the MQTT broker IP (e.g., 192.168.1.10)
  3. Port: 1883 (default; use 8883 for TLS)
  4. Device ID / MQTT Client ID: enter the value from Step 2 (if required by the template)
  5. Import the template — TapHome will subscribe to the device topics automatically

Available devices

Shelly Gas MQTT Module
Service Actions
Self testStarts the sensor self-test on the device — the buzzer beeps three times twice per second and Gas Alarm reports Self Test when the test succeeds.
Custom Variables
deviceID (string)Shelly-ID of the Shelly Gas unit — the 6-or-more character string that forms the MQTT topic prefix shellies/shellygas-<deviceID>/ (e.g. 35FA58). Read it in the Shelly web interface under Settings → Device Info → Device ID.
Open the Shelly web interface → Settings → Device Info → Device ID and copy the first string of characters (not the value in brackets). The template asks for it as the 'Device ID' import parameter.

Shelly GAS MQTT

Service Actions
Self test
mqttpublish("shellies/shellygas-"+deviceID+"/sensor/start_self_test","1");
Gas Alarm Multi-value Switch Read-only

Alarm level reported by the sensor — No alarm, Mild gas leak (from 1800 ppm), Heavy gas leak (from 3000 ppm), Self Test, or Alarm state is unknown. The thresholds are fixed in the device firmware and cannot be changed.

enum multi-value switch
Values / States: No alarm · Mild gas leak · Heavy gas leak · Self Test · Alarm state is unknown

Gas Alarm

Read switch state
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/getValue");
# IF response.IsSuccess
#  VAR content := response.Content;
#  VAR responseHeaders := response.Headers;
#  RETURN(PARSEXML(content, "//element1/value1"));
# ELSE
#  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
#  RETURN(NaN);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/getValue", "GET", "some data", "header1:value1", "header2:value2", ...);
# OR
# VAR request := HTTPREQUEST("/example/getValue", "POST", "some data");
# request.headers := { "header1:value1", "header2:value2", ...};
# request.method := "GET";
# request.data := null;
# VAR response := SENDHTTPREQUEST(request);
#
#
# Send TCP, UDP data:
# VAR data1 := BYTECOLLECTION("0a bb ea df 01");
# SENDDATA(data1);
# VAR data2 := "{\"name\":\"John\", \"age\":32}";
# SENDDATA(data2);
# VAR data3 := TOBYTES("{\"name\":\"John\", \"age\":32}", "iso-8859-1");
# SENDDATA(data3);
# Process received TCP or UDP data and set device values in the Listener script
#
#
# Download data from FTP:
# FTPDOWNLOAD("filePath");
Write switch state
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/set/value=" + Mu);
# IF response.IsSuccess = false
#  ADDERROR(response.StatusCode);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/setValue", "GET", "value=" + Mu, "header1:value1", "header2:value2", ...);\r
# Or VAR request := HTTPREQUEST("/example/setValue");
# request.Method := "PUT";
# VAR response := SENDHTTPREQUEST(request);
#r
#
# Send TCP, UDP data:
# VAR data1 := "{\"name\":\"John\", \"age\":" + Mu + "}";
# SENDDATA(data1);
# VAR data2 := TOBYTES("{\"name\":\"John\", \"age\":" + Mu + "}", "iso-8859-1");
# SENDDATA(data2);
# You can process received TCP or UDP data in the Listener script
#
#
# Upload data to FTP:
# FTPUPLOAD("filePath", "somedata=" + Mu, "write"); # use "append" mode to append data to existing file
Listener
# Parse received bytes:
IF(RECEIVEDMSG.TOPIC = "shellies/shellygas-"+deviceID+"/sensor/gas")
 switch(TOSTRING(RECEIVEDMSG.PAYLOAD),
 "none", Mu := 0,
 "mild",Mu := 1,
 "heavy",Mu := 2,
 "test", Mu := 3,
 Mu := 4);
END
Gas Concentration Variable Read-only

Measured combustible gas concentration in parts per million, range 0–65535 ppm. The device reports -1 while the sensor is warming up or faulted.

numeric Unit: ppm

Gas Concentration

Write
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/set/value=" + Va);
# IF response.IsSuccess = false
#  ADDERROR(response.StatusCode);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/setValue", "GET", "value=" + Va, "header1:value1", "header2:value2", ...);\r
# Or VAR request := HTTPREQUEST("/example/setValue");
# request.Method := "PUT";
# VAR response := SENDHTTPREQUEST(request);
#r
#
# Send TCP, UDP data:
# VAR data1 := "{\"name\":\"John\", \"age\":" + Va + "}";
# SENDDATA(data1);
# VAR data2 := TOBYTES("{\"name\":\"John\", \"age\":" + Va + "}", "iso-8859-1");
# SENDDATA(data2);
# You can process received TCP or UDP data in the Listener script
#
#
# Upload data to FTP:
# FTPUPLOAD("filePath", "somedata=" + Va, "write"); # use "append" mode to append data to existing file
Read (module)
# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/getValue");
# IF response.IsSuccess
#  VAR content := response.Content;
#  VAR responseHeaders := response.Headers;
#  RETURN(PARSEXML(content, "//element1/value1"));
# ELSE
#  ADDERROR(response.StatusCode + " (" + response.ReasonPhrase + ")");
#  RETURN(NaN);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/getValue", "GET", "some data", "header1:value1", "header2:value2", ...);
# OR
# VAR request := HTTPREQUEST("/example/getValue", "POST", "some data");
# request.headers := { "header1:value1", "header2:value2", ...};
# request.method := "GET";
# request.data := null;
# VAR response := SENDHTTPREQUEST(request);
#
#
# Send TCP, UDP data:
# VAR data1 := BYTECOLLECTION("0a bb ea df 01");
# SENDDATA(data1);
# VAR data2 := "{\"name\":\"John\", \"age\":32}";
# SENDDATA(data2);
# VAR data3 := TOBYTES("{\"name\":\"John\", \"age\":32}", "iso-8859-1");
# SENDDATA(data3);
# Process received TCP or UDP data and set device values in the Listener script
#
#
# Download data from FTP:
# FTPDOWNLOAD("filePath");
Listener
# Parse received bytes:
IF(RECEIVEDMSG.TOPIC = "shellies/shellygas-"+deviceID+"/sensor/concentration")
 Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD));
END
Mute Active Alarm Push Button

Push button intended to mute an alarm that is currently active. It has no effect in the current template revision — the topic it publishes to is not built from the configured Device ID.

action push button

Mute Active Alarm

Write button state
MQTTPUBLISH("shellies/shellygas-<deviceid>/sensor/mute","1");

# Simple HTTP Request:
# VAR response := SENDHTTPREQUEST("/example/set/value=" + Bp);
# IF response.IsSuccess = false
#  ADDERROR(response.StatusCode);
# END
#
# Set Http request method, body and headers
# VAR response := SENDHTTPREQUEST("/example/setValue", "GET", "value=" + Bp, "header1:value1", "header2:value2", ...);\r
# Or VAR request := HTTPREQUEST("/example/setValue");
# request.Method := "PUT";
# VAR response := SENDHTTPREQUEST(request);
#r
#
# Send TCP, UDP data:
# VAR data1 := "{\"name\":\"John\", \"age\":" + Bp + "}";
# SENDDATA(data1);
# VAR data2 := TOBYTES("{\"name\":\"John\", \"age\":" + Bp + "}", "iso-8859-1");
# SENDDATA(data2);
# You can process received TCP or UDP data in the Listener script
#
#
# Upload data to FTP:
# FTPUPLOAD("filePath", "somedata=" + Bp, "write"); # use "append" mode to append data to existing file
Connection: Packet Parser → MQTT • Hostname: shellygas-{MAC}.local
Possible improvements (6)
  • Sensor state — unknown | warmup | normal | fault — the template does not read it, so a sensor fault does not surface as its own state in TapHome (only indirectly as -1 on the concentration).
  • Self-test state — not_completed | completed | running | pending — the self-test can be started from TapHome, but its progress is not read back.
  • Unmute alarm — Any payload unmutes an active alarm. Not published by the template.
  • Valve state — unknown | closed | opened | not_connected | failure | closing | opening | checking — state of the optional external valve manipulator (11–13 V, 500 mA jack).
  • Valve control — Accepts the literal payloads 'open' or 'close'. The template does not publish it — this template offers no valve control at all.
  • Connection status — Last Will and Testament topic — true on connect, false on disconnect. Could detect an offline sensor.

Sources

Found a problem with this device template?

Tell us what's wrong, what's missing, or how the template should behave. We rely on your feedback to keep the catalog accurate.

Verified by TapHome

Want to use this in your TapHome Core?

Open this template in the Customer Portal to apply it to one of your homes, or to draft a refinement and submit it back to the catalog.

Open in portal