Protocols

Six systems, one pattern: connect the system once on its own page, let it discover what is out there, then bind properties to your devices. This page is the detail for each one.

1.The shape of every protocol

Learn this once and every protocol below is a variation on it.

  1. Connect the system. Once per house, on that protocol's own page. KNX, Ebelong and Modbus need connection settings; Zigbee, Z-Wave and Shelly connect through a service that is already running.
  2. Find the equipment. Either it announces itself (Shelly, Zigbee, Z-Wave), you put it into a pairing mode, or you type in what the documentation says (KNX group addresses, Modbus registers).
  3. Create the device. In Devices, with a room, a name the customer understands and a device type.
  4. Bind its properties. Each property — on_off, brightness, position — is linked to one real thing on the bus. Which properties a type needs is in the device reference.
A house can mix all of these at once. The customer never sees which protocol a device uses — a KNX light and a Zigbee light sit on the same page and work the same way.

2.KNX

The wired bus most installations are built on. Everything is addressed by group address, and the platform speaks to the bus through one gateway.

1 · Connect to the bus

Open KNX Connections and create a connection. Which fields you get depends on the type you pick:

  • IP / Ethernet (KNXnet/IP) — the usual choice. IP Address of the gateway, Port (3671), and Local IP Address, which is this server's own address on that network.
  • USB — USB Port, the device path such as /dev/ttyUSB0.
  • Serial / TP-UART — Serial Port and Baud Rate (19200 for TP-UART).
  • Always: Physical Address in X.Y.Z form — the address this server takes on the bus, which must not collide with any real device — and Auto-connect on start, which you want on for a finished installation.

Save, then press Connect. The row shows whether the bus is live.

If the serial port is already in use the connection fails — something else on the machine is holding it. On a multi-network-card server, the local IP address matters: get it wrong on a tunnel connection and the gateway's replies go nowhere, so the link looks fine and dies about once a minute.

2 · Bring in the group addresses

  1. In ETS, export the project's group addresses to an XML file.
  2. Open KNX Group Addresses and use Import XML.
  3. Choose whether to skip or overwrite addresses that already exist. Skipping is the default and the safe choice on a second import.
  4. The import keeps the main/middle group structure from the file, so the addresses stay organised the way the ETS project was.
Several ETS export shapes are recognised automatically, including ETS5+. If an address arrives without a recognisable datapoint type it is parked under a placeholder type — searching for that placeholder afterwards is a quick way to find everything that needs its DPT set by hand.

3 · Define what each device type needs

KNX Property Types is where you say "a dimmer has an on/off, a brightness and a status". For each property type you set its key, its datapoint type, whether it is required, and whether it has a separate status address. You do this once per device type, not per device.

4 · Bind the device

  1. In Devices, add the device and pick its type.
  2. Add a property, choose KNX as the protocol.
  3. Pick the Group address — the object you write to — from the tree.
  4. If the property has a status address, pick that too. This is the object the actuator reports back on.
Binding only the command address is the single most common commissioning mistake. The light will switch, but the panel will show whatever it last sent rather than what the actuator actually did — so a light switched at the wall stays wrong on every screen in the house.

Things the platform already handles for you

  • Two-byte temperature values are decoded with the correct byte order, so a 20.5 °C reading cannot come back as 2.68.
  • A thermostat that is switched off and echoes its frost-protection setpoint (3 °C or 37 °C) does not overwrite the customer's comfort setpoint.
  • On/off telegrams are repeated once, because a busy bus occasionally drops one.
  • Gateways that accept a tunnel but ignore keepalives no longer get torn down every minute — the connection defaults to TCP.

3.Z-Wave

Wireless, mains or battery, with a USB controller stick. Pairing is done in the Z-Wave control panel; the platform then adopts what that panel found.

1 · The control panel

Open Z-Wave Discovery. The Control panel tab embeds the Z-Wave management application that owns the USB stick — that is where you include and exclude devices. Everything about the radio network lives there: inclusion, exclusion, healing, secure pairing.

2 · Adopt a node

  1. Pair the physical device from the Control panel tab, as the device's own instructions describe.
  2. Switch to Platform discovery and press Refresh nodes.
  3. The node appears with its ID, manufacturer and product, and a count of what it can do.
  4. Press Create Device, give it a name, a room and a device type, and tick the values you want to use.
Values are grouped by command class — the Z-Wave term for a capability such as binary switch, multilevel switch or battery — and can be filtered by endpoint, which is how a two-gang module presents its two channels. Values the device reports but cannot accept are shown as read-only and cannot be used for control.
After the server restarts, give Z-Wave about 30 seconds before expecting nodes to appear. The list is built from what the network reports, not from a stored file, so an empty list straight after a reboot is normal.

Removing a node

Remove asks the controller to exclude the node and clears its values from the platform. The controller itself — node 1 — cannot be removed. Removing a node does not delete the device you built on it, so tidy that up in Devices afterwards.

4.Zigbee

Wireless and cheap, ideal for sensors and retrofit switches. Devices join through a coordinator — either a USB stick or the coordinator built into some of our panels.

Pair and adopt

  1. Open Zigbee. The badge at the top shows whether pairing is open.
  2. Press Pair new device. Pairing stays open for two minutes and the button becomes Stop pairing.
  3. Put the device into its own pairing mode — usually holding a button until it blinks.
  4. When it appears in the list, press Adopt.
  5. Give it a name, a room and a device type, and tick which of its reported values to link.
Pair devices roughly where they will live, or at least pair the mains-powered ones first: they become the repeaters that battery sensors at the edge of the house depend on.

Things that are handled for you

  • Zigbee brightness runs 0–254 and the platform works in percent. The conversion is automatic — bind the value and ignore the difference.
  • Door and window sensors report the opposite of what the platform means by open. That is corrected on the way in, so a closed door reads closed. Do not add an inversion on top.
  • Diagnostic values such as link quality are not offered as properties, so the device list stays about the device rather than the radio.
Removing a device from the Zigbee page unlinks it from the platform but does not necessarily remove it from the radio network. If you are replacing hardware, remove it from the network properly, or it will keep trying to rejoin.

5.Shelly

Wi-Fi relays, dimmers, covers and meters. There is nothing to connect: a Shelly on the house network either announces itself or is added by its IP address.

Adopt a device

  1. Put the Shelly on the house Wi-Fi with its own app or web page first.
  2. Open Shelly. Devices that announce themselves are already listed.
  3. If one is missing, type its IP address and press Add by IP. That works for every generation and does not need a message broker.
  4. Press Adopt, then set name, room and device type and tick the components to link.

Generations and channels

  • Gen 1 and Gen 2 (Plus / Pro) speak differently on the wire. Both are supported and the difference does not change how you commission them.
  • A multi-channel device presents one component per channel. The first channel is the plain property and further channels carry a number — on_off, on_off_1, on_off_2.
  • Energy figures from first-generation meters are converted to the same units the newer ones report, so a mixed installation adds up.
Give every Shelly a fixed address in the router before adopting it. A device added by IP that later moves to a different address stops responding, and it is an easy fault to misread as a dead relay.

6.Ebelong

A wireless RF system with battery-free kinetic switches, reached through a serial module plugged into the server.

1 · The connection profile

  1. Open Ebelong Discovery.
  2. Create a connection profile: a name, the Serial Port the RF module is on, and the Baud Rate (9600).
  3. Press Activate. Only one profile is active at a time, and the banner at the top names it.

2 · Find the devices

  • Search Unbound Devices looks for about ten seconds and finds devices that have never been bound.
  • Manual Discovery (All Devices) runs for thirty seconds and finds devices that are already bound. While it runs, press each physical switch two or three times — that press is what makes the device identify itself.

3 · Create the device

  1. On the discovered row press Prepare Properties. This works out what that hardware model can do.
  2. Then press Create Device and give it a name, a room and an icon. The device ID is filled in for you.
  3. For a whole house of identical modules, Auto-create discovered builds them all at once and you rename them afterwards.
Device IDs look like B0:36:01:04, and a multi-channel module addresses its outputs by channel number — 1 to 6 depending on the model. If you bind properties by hand in Devices, those two fields are what you fill in.
Prepare Properties must run before the device can be created — the create button stays disabled until it has. If a device does not appear in either search, it is either out of range of the RF module or its battery is flat.

7.Modbus

For plant: heat pumps, ventilation units, energy meters and industrial controllers. Nothing is discovered — every point comes from the equipment's datasheet.

Modbus is not switched on by default on a new installation. If you need it for a project, ask us to enable it before you commission the site.

1 · Connect

  • Modbus TCP — Host and Port (502).
  • Modbus RTU / ASCII — Serial Port, Baud Rate (9600), Data Bits (8), Stop Bits (1) and Parity (none). These must match the equipment exactly.
  • Both: a default Unit ID (1–247) and a Timeout in milliseconds.

2 · Add points from the datasheet

Each point is one register or coil. Choose what kind it is:

  • Digital Input — a read-only bit, such as an alarm contact.
  • Digital Output — a bit you can also write, such as an enable.
  • Analog Input — a read-only number, such as a measured temperature.
  • Analog Output — a number you can also write, such as a setpoint.

Then give it a name, the Slave ID of the equipment, the address, and for analog points the data type — 16-bit, 32-bit, floating point, or a single bit inside a register with its bit index.

The Datasheet address checkbox is the trap on this protocol. Vendor documentation usually numbers registers from 1, while the wire numbers them from 0. Tick the box when you are typing the number straight from the datasheet. Get it wrong and you will read a neighbouring register — often a plausible-looking value, which is what makes it so expensive to find.
32-bit values and floats span two registers, and equipment disagrees about the order of those halves. If a temperature reads as an absurd number, try another word order before suspecting the wiring.

3 · Polling

Read-only points are polled on an interval you choose, from one second to a minute. Poll fast only what the customer actually watches change; a heat-pump status every 30 seconds is plenty, and slow polling keeps a serial line usable.

There are starting templates for common cases — a basic HVAC unit and an energy meter — which create a sensible set of points you then correct against the real datasheet.

8.Wi-Fi devices over HTTP or MQTT

Anything with a web API or an MQTT topic can be driven directly, without a bridge — Tasmota, ESPHome, a relay board, a projector screen.

  • HTTP — you give the device a set of command templates: a URL, optionally a body, with placeholders the platform fills in with the value being sent.
  • MQTT — you give it command topics and status topics and the platform publishes and subscribes accordingly.
  • Either way the device then behaves like any other: it gets a type, it appears on the panel, and it works in scenes and flows.
This is also the escape hatch for equipment nobody supports. If it can be switched with a web request, it can be a device in the system.

9.Mixing protocols in one house

Normal, and usually the right answer.

  • KNX for everything wired at first fix — lighting circuits, blinds, heating valves.
  • Zigbee or Z-Wave for what was decided after the plaster went on.
  • Shelly behind an existing switch where pulling a cable is not an option.
  • Modbus for plant that already has its own controller.

Scenes and automations do not care. A flow can take a Zigbee motion sensor as its trigger and drive a KNX light and a Shelly relay in the same breath.

10.When a device will not respond

Work down this list — it is ordered by how often each one is the answer.

  1. Try it from the device page in Installer Studio. If it works there, the problem is the scene, flow or panel you were using — not the device.
  2. Check the protocol's own page. The connection must be live. A disconnected KNX gateway or an inactive Ebelong profile makes every device on it silent at once — if a whole protocol is dead, start here.
  3. Check the binding. Is the property bound to the right address, and is the status address filled in? A device that switches but never updates is a missing status address almost every time.
  4. Check the direction. A blind that runs the wrong way, a contact that reads inverted — set the reverse flag on that property rather than rewiring.
  5. Check the hardware. Battery devices go quiet, Wi-Fi devices change address, RF devices sit out of range. The system can only report what reaches it.
Take a backup from the portal before a long commissioning session. If an experiment goes wrong, restoring is faster than remembering what you changed.