---
title: "Shelly and KNX: map relays, covers and lights to group addresses"
description: "Control Shelly relays, covers and lights from the KNX bus with Link’nX: group address and DPT for on/off, toggle, cover position and brightness."
canonical: https://wiki.can-nx.com/en/guides/link-shelly-knx/
language: en
product: Link’nX
audience:
  - administrateur
  - installateur
context: "Link’nX web: KNX gateway table of a declared Shelly device, Actions tab"
---

# Shelly and KNX: map relays, covers and lights to group addresses

Context: Link’nX web: KNX gateway table of a declared Shelly device, Actions tab

The Shelly gateway table in Link’nX maps the group addresses of your KNX project to the relays, covers and lights of a Shelly device: on/off, toggle, open, stop, position and brightness. A KNX push button can then control the device directly, and a KNX action lets you use it in a scenario.

Intended for the installer or administrator who has the project’s KNX addresses. For the states and measurements returned by the device, follow [the Shelly feedback guide](https://wiki.can-nx.com/en/guides/link-shelly-feedback/).

## Before you start

- The device is [declared in Link’nX](https://wiki.can-nx.com/en/guides/link-shelly-device/).
- The actual channel and the device mode are identified. The relays offered are numbered **0 to 3**, the covers **0 to 1** and the lights **0 to 1**: this numbering is the same for every model, and your device does not necessarily have each of these channels.
- For a Gen1 cover or dimmer, have support confirm the suitable commands and feedback before activating them.
- To set a cover’s position, the device is correctly prepared and calibrated. The manufacturer’s calibration steps are not described here.

## Open the device’s gateway table

1. Select the project and the gateway, then open **Smart Home → Shelly**.
2. On the device’s row, click the two opposite arrows, **Gateway mode configuration**.

The table applies to this device only. Its common behavior (filters, address format, disabling a row) is described in [KNX entry and saving](https://wiki.can-nx.com/en/guides/link-gateway-table/).

## Map the KNX commands

1. In **Actions**, locate the function and the channel number using the table below. The table shows **Name**, **DPT**, **Address** and **Active**; the name and DPT are fixed.
2. In **Address**, fill in the KNX group address planned for the function, for example `1/3/20` if this fictitious example matches your address plan.
3. Check **Active**. Only activate the rows that correspond to your hardware.
4. Click the floppy disk at the bottom right and wait for **Succès — Données sauvegardées avec succès !** (Success — Data saved successfully!).

In the labels, the number is the channel number: **Relay 0 — on/off** and **Relay 1 — on/off** control two different channels. The list shows one row per channel, not a collective “Relay 0 to 3” row. The DPT in the table must match that of the KNX device’s object.

| Rows offered | DPT | Value and requested effect |
| --- | --- | --- |
| **Relay 0 to 3 — on/off** | 1.001 | 1 requests on, 0 off |
| **Relay 0 to 3 — toggle** | 1.017 | Each telegram requests that the state be inverted, including a telegram at 0; this is not a “switch on” command |
| **Cover 0 or 1 — open/close** | 1.008 | 0 requests open/up, 1 close/down |
| **Cover 0 or 1 — stop** | 1.017 | Each telegram requests a stop |
| **Cover 0 or 1 — set position** | 5.001 | KNX percentage: **0 = open**, **100 = closed**; 25 means a closing setpoint of 25% |
| **Light 0 or 1 — on/off** | 1.001 | 1 requests on, 0 off |
| **Light 0 or 1 — set brightness** | 5.001 | Percentage from 0 to 100; brightness and the on/off command are two separate functions |

## Map the status feedback

Open the **second tab**, marked with a speech bubble, and follow [the Shelly measurements and states guide](https://wiki.can-nx.com/en/guides/link-shelly-feedback/). Save each tab before switching to another.

## Control Shelly from a scenario

**Actions → Add** offers no dedicated **Shelly** type, and this interface has no Shelly event trigger. Use a KNX action that writes to the address mapped above. The Shelly declaration does not create this action automatically.

1. Open **Actions → Add**, choose **KNX** and fill in the action’s required **Name**, 64 characters maximum.
2. Fill in **Group Address**, **DPT** and **Value** according to the Shelly mapping and the intended command. Click **ADD TO THE ACTION GROUP**, check the row under **Added actions :**, then save with the floppy disk. The [KNX action guide](https://wiki.can-nx.com/en/guides/link-action-knx/) details these fields.
3. In the [scenario form](https://wiki.can-nx.com/en/guides/link-compose-scenario/), fill in its **Name**, choose at least one trigger and select the saved KNX action. Click **Add action** and check its card before [saving the scenario](https://wiki.can-nx.com/en/guides/link-scenario-save/). To use the prepared value, keep the action’s default value.
4. A newly created scenario is disabled: [enable it in the list](https://wiki.can-nx.com/en/guides/link-run/) when its configuration is ready for automatic start.

## Check the result

1. Return to the list, reopen the gateway and check the saved addresses and **Active** boxes.
2. Send each command from the bus, for example with a push button or the ETS group monitor, and watch the relay, cover or lamp. Do the same after saving a scenario: the save confirms the configuration, watching the device confirms the command’s effect.

## Troubleshooting

- The relay toggles twice on each press: check whether the button sends one telegram on press and another on release. With a Shelly toggle, these two telegrams may request two inversions. Have the installer adjust what the button sends, or choose the on/off function to set the state explicitly. Changing the DPT at random does not fix this behavior.
- The brightness is set but the lamp stays off: also map and send the **on/off** function of the same channel, because a brightness setting is not enough to guarantee that the light switches on. Brightness does not have the cover’s inverted direction, where 100 means closed.
- A command or a measurement is missing: follow [the Shelly feedback troubleshooting](https://wiki.can-nx.com/en/guides/link-shelly-feedback/).

For native button reporting, an additional channel, a relay-specific timer or a function missing from the table, contact support@can-nx.com with the model and the goal, rather than resorting to an invented URL or vendor command.

French labels: **Configuration de la partie passerelle**, **Actions**, **Relais 0 — marche/arrêt**, **Relais 0 — bascule**, **Volet 0 — ouvrir/fermer**, **Volet 0 — stop**, **Volet 0 — régler la position**, **Lumière 0 — marche/arrêt**, **Lumière 0 — régler la luminosité**. The numbers remain the channel numbers; the message of the common table remains **Données sauvegardées avec succès !**.