Local-LAN driver for the Loxone Miniserver, Miniserver Compact, and Miniserver Go controllers. GEM reads the Loxone structure file (LoxAPP3.json) to enumerate every control, then dispatches commands through the documented /jdev/sps/io/{uuid}/{action} endpoint.
Prerequisites
- Miniserver firmware 9.x or later, reachable on the LAN.
- A Loxone user with web-service rights. The default
admin user works; in production, create a dedicated automation user.
- HTTP basic auth enabled on the Miniserver, or GEM running on the same trusted network. Token-based auth (Miniserver 9+) is honored by the Miniserver but not yet negotiated by this driver.
- TCP port 80 (HTTP) or 443 (HTTPS) open between GEM and the Miniserver. Miniservers on Loxone Cloud DNS still expose the same API on the LAN side.
Setup
- Add a device in GEM with driver
loxone_miniserver.
- Fill in the device attributes:
ip — Miniserver IP, e.g. 192.168.1.50.username — Loxone web-service user.password — that user's password (stored encrypted).port (optional) — defaults to 80.use_https (optional) — set when the Miniserver is reverse-proxied or has a Loxone-issued certificate. Self-signed certs are accepted.status_interval (optional) — poll cadence in ms, default 4000.
- Save and reload the device. Watch the server log for
loxone miniserver connected: … and loxone miniserver controls: <count> to confirm the structure file loaded.
- Run the
get_devices command from the device's Test Commands page (or the Script Console) to print every Loxone control with its UUID, room, category, and type.
- For each Loxone control you want to expose, create a zone under the appropriate subsystem (lights, shades, climate, …) and set
zone.address to the Loxone control UUID, e.g. 0f1a3c5b-0007-1234-ffff8b0a3c5d1234. The driver will populate zone.control_type automatically on the next status poll.
Attributes
Device
| Name | Required | Description |
|---|
ip | yes | Miniserver IP address. |
username | yes | Loxone user with web-service rights. |
password | yes | Stored encrypted by GEM's secure-attribute system. |
port | no | Defaults to 80 (or 443 with use_https). |
use_https | no | Default false. Set to true when the Miniserver is reverse-proxied or has a TLS cert. |
status_interval | no | Status poll cadence in ms, default 4000. |
Zone
| Name | Required | Description |
|---|
address | yes | Loxone control UUID (32-hex with embedded dashes — copy from get_devices output). |
control_type | no | Auto-populated from the structure file. Used to pick the right action verb. |
Loxone control UUIDs look like 0f1a3c5b-0007-1234-ffff8b0a3c5d1234. Use them verbatim. The Miniserver's structure file lists every control's UUID in the controls map of LoxAPP3.json; get_devices prints them in a flat list with the room and category attached for easy zone creation.
Commands
| Command | Args | Notes |
|---|
on / off | address | Switch / dimmer / EIB outputs. Maps to On / Off. |
pulse | address | Impulse switches and scene triggers. Maps to Pulse. |
open / close / stop | address | Jalousie / blind / shade. Maps to FullUp / FullDown / Stop for those types; On / Off / Stop for switch-like controls. |
set_level | address, level (0–100) | Dimmer / analog. The level value is sent verbatim as the action token. |
set_value | address, value | Generic analog setpoint (e.g. thermostat target temperature). |
get_state | address | Reads one control's current value. |
get_devices | — | Re-downloads LoxAPP3.json and lists every control with its UUID, room, category, type. |
Known limitations
- Token-based auth not implemented. This driver uses HTTP basic auth, which every Miniserver supports as long as you haven't disabled it. Token auth (per-user JWTs negotiated via
jdev/sys/keyexchange and jdev/sys/getkey2) is on the roadmap.
- No WebSocket state push. State changes are picked up by polling. For zones that fire frequently, lower
status_interval or wire those controls through attribute_trigger rules upstream of the Miniserver.
- Complex control types (IRoomControllerV2, AalSmartAlarm, EnergyManager) are returned by
get_devices but only the basic Switch / Dimmer / Jalousie verbs are wired through the GEM verb mapper. Use set_value with the literal Loxone action string when you need a verb the mapper doesn't know.
- Cloud DNS / remote access is unsupported in this driver. Run GEM on the same LAN as the Miniserver, or terminate Loxone Cloud DNS on a reverse proxy and point
ip at the proxy.
Troubleshooting
loxone miniserver missing credentials — the username or password attribute hasn't been set on the device row. Re-enter them from the device admin page.loxone code 401 / 403 — bad credentials, or the user lacks web-service rights. Verify in Loxone Config under Users → User Management.loxone code 500 on a command — usually means the action verb isn't valid for that control type. Run get_state against the same address to see what type it is, then pick a matching verb (e.g. don't send On to a Jalousie).loxapp3.json missing controls map — the structure file came back empty or in an unexpected shape, almost always a firmware mismatch. Confirm the Miniserver is on firmware 9 or newer.http request error: ECONNREFUSED — port mismatch or the Miniserver is reachable only via HTTPS; toggle use_https and/or set port.