Integration with Shelly

In DOMIQ we advocate for cable building automation installations, which ensures high reliability of data transmission

However, there are use cases, when making a cable installation is not (longer) possible. To face such situations we decided to add integration with Shelly devices.

1, Communication #

Shelly devices allows integration over HTTP API or using the MQTT standard. Considering the fact, that HTTP API requires constant data polling, we decided to use the MQTT which is bidirectional by default.

For the purposes of integration with Shelly, we made our own implementation of the MQTT broker. In its current form, the broker is partially compatible (not yet fully compatible) with the MQTT 3.1.1 standard. At this stage, it handles communication with QoS equal to 0 and requires the Clean Session option enabled for each connection. More information on the MQTT standard is available on the Internet.

1.2 Configuration #

The very first step is the correct configuration of Shelly modules.

1.2. Network Settings #

Shelly modules work in Access Point mode by default – so each module creates its own local WiFi. The first step is to disable Access Point mode and connect Shelly module to your local WiFi.

1. Connect to a network created by a Shelly module.
2. Open the web UI in the web browser (see Shelly user manual for the default IP address).
3. In the Internet & Security (gen. 1 devices) or in the Networks section (gen. 2 devices) enter network settings that allow the module to connect to your local WiFi. We recommend setting a static IP address or creating IP bin- ding based on module’s MAC address (this has to be done in the router settings).
4. Save settings and reopen web UI using the IP in your network.

1.3. MQTT Settings #

The next step is configuration of a MQTT server, to which the Shelly module will connect. The configuration description applies to the Shelly interface. The configuration is slightly different for Shelly 1st and 2nd generation devices, so we will describe configuration separately.

Gen. 1 Devices

1. Navigate Internet & Security -> Advanced – Developer Settings.
2. Check the Enable MQTT option.
3. Fill the following fields of the form:
   • Server – Enter the IP address of your Base module and the default MQTT port – 1883 separated with colon. Example: 192.168.1.100:1883
   • Enable the Use custom MQTT prefix option and in the field below enter a name of your Shelly module. The entered name must be unique in the entire installation.
   • Enable the Clean Session option.
   • Set the Max QoS to 0.
4. Click the Save button to save changes. To apply changes a reboot is required (you’ll be notified about that by the Shelly intefrace).
5. Shelly module is now ready to use.

Gen. 2 devices

1. Navigate Networks -> Mqtt.
2. Enable the Enable option.
3. Fill the following fields of the form:
   • Connection type: MQTT
   • In the next field enter a name of your Shelly module. The entered name must be unique in the entire installation.
   • Enable the RPC status notifcations over MQTT.
   • In the textfield below, enter the IP address of your Base module and the default MQTT port – 1883 separated with colon. Example: 192.168.1.100:1883
4. Click on the Apply button to confirm the changes.
5. Shelly module is now ready to use.

1.4. Additional Settings #

At this stage, the Shelly module is ready to be controlled by the DOMIQ/Base. Other settings such as input type, schedules, etc. should be configured as needed.

3. DOMIQ/Base configuration #

In DOMIQ/Base’s configurator navigate to the Settings tab and then enable MQTT and Shelly options. Next save the Settings tab and reboot the module.

After rebooting, Base is ready to control Shelly devices. Shelly modules will automatically connect to Base – no addi- tional actions are required. Parameters read from Shelly modules will automatically appear in the State tab.

4. Commands and State #

As mentioned before, there are two generations of Shelly devices. Apart from the hardware differences, they also use different integration protocol. The integration protocol used by the gen. 2 devices is unified for all modules, while the first generation of devices vary a lot in terms of parameters that can be read as well as commands that can be sent to modules. We have divided the description of the operation of modules of both generations into descriptions of individual devices.

4.1. General Guidelines #

• All the described commands and state identifiers represent a generalized syntax and contains fragments that have to be replaced with data specific for a particular Shelly module. Those fragments are enclosed in angle brackets: <dowolna_nazwa>
  Example: SHELLY.<nazwa>.relay.<0-1>=<komenda>
• Relays numbering in Shelly starts at 0. So when a module has only one relay then its index is 0.
• The same rule applies to binary inputs. Binary inputs can be used to connect wall switches, motion sensors and other devices that are capable to control the input contacts.

In the Base module we implemented support for the following Shelly devices:

Generation 1:

1. 1/1PM/1L
2. 2/2.5
3. Plug/PlugS
4. Dimmer 1/2
5. RGBW2 (only the White mode)
6. Uni
7. TRV
8. Vintage
9. H&T
10. Smoke
11. Flood
12. Door/Window 1/2
13. Motion
14. Sense
15. Button1
16. I3
17. Gas
18. EM
19. 3EM

Generation 2:

1. Plus 1/1 PM
2. Plus 2 PM
3. Plus I4
4. Pro 1/1 PM
5. Pro 2/2 PM
6. Pro 4 PM

4.2. Generation 1: #

4.2.1. 1/1PM/1L #

Actor module with one relay and one binary input. Shelly1PM also includes energy metering.

4.2.2. 2.5 #

The module is equipped with two relays with power measurement and two binary inputs. It can operate in roller shutter mode or as two independent relays.

Roller shutter mode

Relay mode

4.2.3. Plug/PlugS #

Controlled outlet with energy metering.

4.2.4. Dimmer 1/2 #

Lighting control module with dimming option. The module is also equipped with a binary input.

• C.SHELLY.salonsufit.light.0=100;ramp:3
  Turn the light named salonsufit on to 100%. A fade time of 3 seconds will be used.

4.2.5. RGBW2 (only White mode) #

Four-channel LED driver (12/24V). Each channel can be controlled independently. Module is also equiped with a single binary input.

4.2.6. Uni #

Module with two binary inputs and two potential-free outputs.

4.2.7. TRV #

Smart thermostatic radiator valve.

4.2.8. Vintage #

Dimmable LED bulb.

4.2.9. H&T #

Wireless air temperature and humidity sensor.

4.2.10. Smoke #

Wireless smoke detector.

4.2.11. Flood #

Wireless flood sensor.

4.2.12. Door/Window 1/2 #

Wireless door/window opening sensor with sunlight measurement and motion detection (vibration measurement).

4.2.13. Motion #

Wireless motion sensor with sunlight measurement.

4.2.14. Sense #

Wireless measuring device equipped with sensors: temperature, humidity, sunlight, motion detector. Additionally, it allows you to emit IR codes to any multimedia devices. IR code emission is not available via MQTT protocol integration, but is available via the Shelly application, HTTP API or device configuration interface.

4.2.15. Button1 #

Wireless button with 4 different press types: short, 2x short, 3x short, long. The button response time in battery mode is approximately 2s and approximately 100ms in USB power mode.

4.2.16. i3 #

Three-channel binary input module with detection of various types of button presses.

4.2.17. Gas #

LPG or CNG gas detector.

4.2.18. EM #

Dual-channel energy meter. The module is also equipped with a single low-current output.

4.2.19. 3EM #

Three-phase electricity meter.

4.3. Generation 2 #

The “Plus” Series #

The Plus series consists of 2nd generation modules intended for installations in electrical boxes.

4.3.1. Plus 1/1 PM #

Actor module with one relay and one binary input. Shelly Plus 1PM also includes energy metering. Module 1 PM is additionally equipped with an energy meter.

• C.SHELLY.test.relay.0=on;flip:0.1
  The relay will be turned on for 100ms.
• C.SHELLY.test.relay.0=0;flip:2
  The relay will be turned off for 2 seconds.

4.3.2. Plus 2 PM #

The module is equipped with two relays with power measurement and two binary inputs. It can operate in roller shutter mode or as two independent relays.

Roller shutter mode

Relay mode

• C.SHELLY.test.relay.0=on;flip:0.1
  The relay will be turned on for 100ms.
• C.SHELLY.test.relay.0=0;flip:2
  The relay will be turned off for 2 seconds.

4.3.3. l4 #

Four binary input module.

“Pro” Module Series #

The Pro series modules are designed for installation in distribution cabinets. They are equipped with WiFi wireless connectivity and an Ethernet connector.

4.3.4. Pro 1/Pro 1PM #

Distribution module equipped with one relay and two binary inputs. The PM version is also equipped with an electricity meter.

• C.SHELLY.test.relay.0=on;flip:0.1
  The relay will be turned on for 100ms.
• C.SHELLY.test.relay.0=0;flip:2
  The relay will be turned off for 2 seconds.

4.3.5. Pro 2 #

Distribution module equipped with two relays and two binary inputs.

4.3.6. Pro 2 PM #

Din-mounted module with two relays with energy metering and two binary inputs. Module can operate in two distinct modes: Relay and Roller Shutter.

Commands, state parameters and events are identical as for Plus 2 PM module.

4.3.7. Pro 4 PM #

Din-mounted module with four relays with energy metering and four binary inputs. Each relay also has an electricity meter.

Commands, state parameters and events are identical as for Plus 1/1 PM module, with the difference that the numbering range of relays and inputs is from 0-3.