--- title: "Shelly Gas MQTT" description: "Gas alarm state and concentration in ppm from a Shelly Gas CNG or LPG detector over MQTT, plus a sensor self-test action. TapHome template." url: "https://taphome.com/en/compatibility/shelly-gas-mqtt/" language: en lastmod: 2026-10-08 generator: hugo ai: topics: ["mqtt","sensor","wifi","gas-detection","safety"] questions: ["How to integrate Shelly Gas with TapHome via MQTT?","What does the Shelly Gas MQTT TapHome template monitor?","How to enable MQTT on a Shelly Gas and find its Device ID?","At what ppm does the Shelly Gas alarm trigger?","Why does the Shelly Gas concentration show -1 in TapHome?","Where should a Shelly Gas CNG or LPG unit be mounted?"] --- # Shelly Gas MQTT Communication: Packet Parser → MQTT - [Shelly Gas Product Page](https://www.shelly.com/en/products/shop/shelly-gas) > Network address > > With the MQTT broker built into TapHome, enter `127.0.0.1` as the broker address in TapHome. In the device, enter the IP address of the TapHome Core and give the Core an IP reservation in the router. > > [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/) ## Integration guide 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. > [!NOTE] > 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. > [!WARNING] > 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. | Variant | Gas detected | Behaviour in air | Recommended placement | |---------|--------------|------------------|-----------------------| | Shelly Gas CNG | Compressed natural gas (methane) | Lighter than air, collects at the ceiling | 0.3–1 m below the ceiling, vertically, and 1.5 m from the gas source | | Shelly Gas LPG | Liquefied petroleum gas (propane / butane) | Heavier than air, collects at floor level | 0.3 m above the floor, within 1.5 m of the gas source | > [!WARNING] > 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 | Parameter | Value | |-----------|-------| | Power supply | 110–230 V ±10 %, 50/60 Hz AC | | Power consumption | < 3 W | | Alarm sensitivity | 6 % LEL (lower explosive limit) | | Sound level | ≥ 70 dB | | Wi-Fi | 802.11 b/g/n, 2400–2484 MHz | | Range | up to 50 m outdoors, up to 30 m indoors | | Operational temperature | −10 °C to +50 °C | | Valve manipulator jack output | 11–13 V, 500 mA (external accessory, not controlled by this template) | | Dimensions | 89.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 ring | Meaning | |----------|---------| | Solid green | Sensor in normal operation | | Solid yellow | Sensor fault | | Flashing red | Alarm | | Flashing red / yellow / green in sequence | Sensor warming up | | Buzzer pattern | Event | |----------------|-------| | Two short beeps per second | Warm-up started after power on | | One long beep per second | Warm-up finished | | Long beep once per second until the fault clears | Sensor fault | | Three short beeps twice per second | Self-test running | | Long beep once per second | Self-test finished successfully | | Long beep once per second, until the leak is gone or escalates | Mild gas leak | | Five seconds of beeping with a one-second pause, until the leak is gone | Heavy gas leak | After power-up the sensor warms up for about three minutes. The LED ring flashes red / yellow / green in sequence during this time 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. > [!WARNING] > 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 parameter | Default | Value to enter | |------------------|---------|----------------| | Mqtt Broker IP address | `192.168.0.1` | IP address of the MQTT broker — **not** of the Shelly Gas | | Mqtt Broker port | `1883` | Port 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-/sensor/gas`. It carries the alarm level the device has already derived from the measured concentration. | TapHome value | MQTT payload | Meaning | |---------------|--------------|---------| | No alarm | `none` | Concentration below 1800 ppm | | Mild gas leak | `mild` | Concentration at or above 1800 ppm | | Heavy gas leak | `heavy` | Concentration at or above 3000 ppm | | Self Test | `test` | Published after a successful self-test | | Alarm state is unknown | `unknown` or any other payload | The 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-/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. > [!TIP] > 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. > [!NOTE] > 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-/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-/sensor/mute` — the `` 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. > [!WARNING] > 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-/` 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-.local`. ## How to install in TapHome ### Prerequisites - Shelly device connected to Wi-Fi (2.4 GHz), e.g. through the Shelly app or the device's own access point - 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 > [!WARNING] > 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:///` 2. Navigate to **Internet & Security** → **Advanced — MQTT** 3. Enable **MQTT** 4. Set **MQTT Server**: `:` (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:///` 2. Navigate to **Settings** → **MQTT** 3. Enable **MQTT** 4. Set **Server**: `:` (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 With the TapHome built-in broker, `` is the IP address of the TapHome Core. Give the Core an IP reservation in the router, otherwise the device loses the broker when the router changes the address → [Network Preparation](https://taphome.com/en/docs/setup/network-preparation/). > [!TIP] > To verify MQTT is working, use an MQTT client (e.g., MQTT Explorer) and subscribe to `shellies/#` (Gen1) or `/#` (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-`, 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:** `127.0.0.1` for the TapHome built-in broker (the control unit connects to itself, the address never changes); for an external broker its IP address (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 3 These devices appear in TapHome after import. Shelly Gas MQTT Module Service Actions | | | |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------| | Self test | Starts 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. Service Actions Self test ```taphome 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 Read switch state ```taphome # 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 ```taphome # 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 ```taphome # 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 Write ```taphome # 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) ```taphome # 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 ```taphome # Parse received bytes: IF(RECEIVEDMSG.TOPIC = "shellies/shellygas-"+deviceID+"/sensor/concentration") Va := todouble(TOSTRING(RECEIVEDMSG.PAYLOAD)); END ``` Mute Active Alarm Push Button Read and write 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 Write button state ```taphome MQTTPUBLISH("shellies/shellygas-/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. ## Import parameters Enter these values when you import the XML. | Asked in the app | Default | |------------------------|-----------------| | Mqtt Broker IP address | `192.168.0.1` | | Mqtt Broker port | `1883` | | Device ID | Enter at import | ## Sources - Shelly Gen1 API Reference [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/) 2026-03-12 - Home Assistant Shelly Integration [www.home-assistant.io](https://www.home-assistant.io/integrations/shelly/) 2026-03-12 - Shelly Gas — Device-Specific MQTT API [shelly-api-docs.shelly.cloud](https://shelly-api-docs.shelly.cloud/gen1/#shelly-gas) 2026-08-25 - Shelly Gas — Knowledge Base Specification [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-gas) 2026-08-25 - Shelly Gas Sensor PPM Threshold [support.shelly.cloud](https://support.shelly.cloud/en/support/solutions/articles/103000226300-shelly-gas-sensor-ppm-threshold) 2026-08-25 - Shelly Gas User and Safety Guide [kb.shelly.cloud](https://kb.shelly.cloud/knowledge-base/shelly-gas) 2026-08-25 [PDF](https://taphome.com/compatibility/devices/shelly-gas-mqtt/manufacturer/user-guide.pdf) Manufacturer documents are © their respective owners. They are provided as published by the manufacturer, for reference only. ## Related Documentation - [MQTT Integration](https://taphome.com/en/compatibility/mqtt-guide/) - [Packet Parser (HTTP, TCP, UDP, FTP, MQTT)](https://taphome.com/en/docs/integration/packet-parser/) - [Packet parser functions](https://taphome.com/en/docs/script/packet-parser/) - [Parsing functions](https://taphome.com/en/docs/script/parsing-functions/) - [MQTT Broker](https://taphome.com/en/docs/integration/packet-parser/mqtt-broker/) - [Listener scripts](https://taphome.com/en/docs/script/listener-scripts/)