README
¶
mygekko-mqtt
A bridge that connects MyGEKKO home automation systems to MQTT, enabling integration with Home Assistant, Node-RED, and other MQTT-based systems.
Features
- Polls MyGEKKO API and publishes status values to MQTT
- Subscribes to MQTT commands and forwards them to MyGEKKO
- Automatic field definition loading from MyGEKKO API
- History-based deduplication (only publishes changed values)
- JSON publishing with timestamps for each item
- Supports both TCP (TLS) and Unix socket MQTT connections
- MQTT Last Will and Testament (LWT) for online/offline status
- Configurable polling intervals
- Throttled and coalesced blind move commands (MyGEKKO crashes on rapid moves); direct commands go through instantly
- Optional HTTP listener for push updates from MyGEKKO (e.g. blind positions while moving)
- Configuration in the style of OpenBSD daemons, with macros,
includeand a syntax check (-n) - Structured logging with configurable log levels
- Security sandboxing (chroot, privilege dropping, OpenBSD unveil and pledge)
Requirements
- Go 1.24.0
- MyGEKKO device with API access
- MQTT broker (Mosquitto, etc.)
Installation
make build
Cross-compilation
make build-all # All platforms
make build-linux # Linux amd64 + arm64
make build-openbsd # OpenBSD amd64
make build-darwin # macOS amd64 + arm64
Or manually:
CGO_ENABLED=0 go build -ldflags="-s -w" -o mygekko-mqtt
Configuration
The configuration is a file in the style of OpenBSD daemons (pf.conf,
httpd.conf): one statement per line, blocks in braces, # comments,
macros and include. The full reference is
mygekko-mqtt.conf(5) (mandoc -l mygekko-mqtt.conf.5).
The default path is /etc/mygekko-mqtt.conf.
install -m 600 mygekko-mqtt.conf.sample /etc/mygekko-mqtt.conf
mygekko-mqtt -n # check the configuration and exit
Since the file holds passwords, it and every included file must be owned by root (or the user running the bridge) and must not be group writable or accessible by others; otherwise the bridge refuses to start.
Example
include "/etc/mygekko-mqtt.secrets" # defines $gekko_password, $mqtt_password
log level info
chroot /var/empty
user _mygekko
group _mygekko
mygekko mygekko.example.lan {
username admin
password $gekko_password
name myGEKKO # optional, else read from the API
poll blinds every 5s
poll { hotwater_systems roomtemps vents } every 20s
command interval 20s
throttle blinds { P S } # the default
}
mqtt unix:///var/run/mosquitto/mosquitto.sock {
root mygekko
client id mygekko-mqtt
username mqttuser
password $mqtt_password
}
push listen on 192.168.1.5 port 8080 {
path /r14 blinds item14 positionLevel
}
Statements
| Statement | Meaning |
|---|---|
log level debug|info|warn|error |
Log level (default info). |
chroot DIR, user NAME, group NAME |
Sandbox, applied after all connections are established. |
mygekko HOST { … } |
MyGEKKO host name or IP address (ip:port for a non-standard port). Required. |
username, password |
MyGEKKO API credentials. Required. |
name NAME |
Gekko name in the MQTT topics. Read from the API if omitted; setting it keeps the topics stable if the bridge starts while MyGEKKO is still booting. |
poll LIST every DURATION |
Categories polled every DURATION. At least one is required; each category may be polled by one statement only. |
command interval DURATION |
Minimum gap between throttled set commands (default 20s). |
throttle CATEGORY LIST |
Payload prefixes that are throttled for a category. Without any throttle statement: throttle blinds { P S }. |
no throttle |
Throttle nothing. |
mqtt URL [{ … }] |
Broker: tcp://host[:port], ssl://host[:port] or unix:///path. Required. |
root TOPIC |
Topic root (default mygekko). |
client id ID |
Client ID (default mygekko-mqtt). |
username, password |
Broker credentials. |
push listen on ADDRESS port PORT { … } |
HTTP listener for push updates from MyGEKKO, see below. |
path PATH CATEGORY ITEM FIELD |
Maps a request path to the field the posted value belongs to. |
Durations are a number of seconds or numbers with units: 500ms, 5s,
2m, 1h30m. Lists are a single word or words in braces: { a b }.
Macros are defined as name = value and used as $name. As in pf.conf, a
quoted macro value is split into words again, so a password containing
spaces is written directly in quotes (password "a b") rather than through
a macro.
Migrating from config.toml
Earlier versions read config.toml. The settings map as follows:
log_level → log level; [mygekko] host → mygekko HOST { … };
interval_items with interval = 5.0 → poll { … } every 5s;
main_items with interval_rounds = 4 → poll { … } every 20s
(interval × rounds); command_interval = 20.0 → command interval 20s;
[mygekko.throttle_prefixes] → one throttle CATEGORY { … } per entry;
[mqtt] url → mqtt URL { … }; client_id → client id;
[sandbox] → top-level chroot, user, group.
Security Sandboxing
With chroot, user and group the bridge chroots and drops privileges
(including the supplementary groups) after establishing all network
connections (MyGEKKO API, MQTT, push listener), so DNS resolution works
normally. Without group, the user's primary group is used.
On OpenBSD it then hides the whole file system with unveil and restricts
itself to the stdio inet pledges, plus unix for a broker on a Unix socket
— also without chroot and user. After sandboxing, only the existing
sockets and new HTTP connections to the MyGEKKO IP resolved at startup are
used. A violated promise kills the bridge with SIGABRT; the missing promise
is logged in /var/log/messages.
Running
# Using the default /etc/mygekko-mqtt.conf
./mygekko-mqtt
# Specify the config file path
./mygekko-mqtt -f /usr/local/etc/mygekko-mqtt.conf
# Only check the configuration
./mygekko-mqtt -n -f mygekko-mqtt.conf
The application follows a "let it crash" philosophy - on errors, it exits with a specific code and should be restarted by a supervisor (systemd, runit, Docker, etc.).
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Clean shutdown |
| 1 | Configuration or bridge initialization error |
| 2 | User/group lookup error |
| 3 | Sandbox error (chroot/setgroups/setuid/unveil/pledge) |
| 4 | MyGEKKO connection error (name or definitions, including an empty name or no definitions while MyGEKKO is still starting up) |
| 5 | MQTT connection error |
| 6 | MQTT publish error |
| 7 | MQTT subscribe error |
| 10 | MQTT connection lost |
| 11 | MyGEKKO connection lost during polling |
| 12 | HTTP push listener error (bind failed, or a path names an unknown category or field) |
Note: an invalid set topic or a failed SetValue command (formerly exit codes 8
and 9) is now logged and skipped instead of terminating the bridge, so a single
bad command no longer drops the other commands still queued behind it.
MQTT publishes and subscriptions give up after 30 seconds if the MQTT client stops completing requests (exit code 6/7) — paho can hand out tokens that never complete, and an unbounded wait would hang the bridge silently. Incoming set commands are queued without ever blocking the MQTT receive callback; a full queue drops the command with a warning.
Systemd Service
[Unit]
Description=MyGEKKO MQTT Bridge
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/mygekko-mqtt
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
Runit Service
Create /etc/sv/mygekko-mqtt/run:
#!/bin/sh
exec /usr/local/bin/mygekko-mqtt 2>&1
Installation on OpenBSD
Create service user
useradd -s /sbin/nologin -d /var/empty -g =uid -c "MyGEKKO MQTT" _mygekko
Copy binary and config
cp mygekko-mqtt-openbsd-amd64 /usr/local/bin/mygekko-mqtt
chmod 755 /usr/local/bin/mygekko-mqtt
install -o root -g wheel -m 600 mygekko-mqtt.conf.sample /etc/mygekko-mqtt.conf
vi /etc/mygekko-mqtt.conf
mygekko-mqtt -n
The sample already contains the sandbox settings:
chroot /var/empty
user _mygekko
group _mygekko
rc.d with tower
contrib/openbsd/mygekko_mqtt runs the
bridge under tower, which restarts it
after an error (with a growing wait, e.g. while MyGEKKO is still booting)
but not after a configuration or sandbox error (exit codes 0-3), and sends
its output to syslog:
install -m 755 contrib/openbsd/mygekko_mqtt /etc/rc.d/mygekko_mqtt
rcctl enable mygekko_mqtt
rcctl start mygekko_mqtt
rcctl check mygekko_mqtt
rc.d without a supervisor
rc.d does not restart a daemon that exits. Create /etc/rc.d/mygekkomqtt:
#!/bin/ksh
daemon="/usr/local/bin/mygekko-mqtt"
daemon_flags=""
. /etc/rc.d/rc.subr
rc_bg=YES
rc_cmd $1
chmod 755 /etc/rc.d/mygekkomqtt
rcctl enable mygekkomqtt
rcctl start mygekkomqtt
Runit (alternative)
mkdir -p /etc/sv/mygekko-mqtt
cat > /etc/sv/mygekko-mqtt/run << 'EOF'
#!/bin/sh
exec /usr/local/bin/mygekko-mqtt 2>&1
EOF
chmod 755 /etc/sv/mygekko-mqtt/run
ln -s /etc/sv/mygekko-mqtt /var/service/
MQTT Topics
Published Topics (Status)
{root}/{gekkoname}/online # "true"/"false" (retained, LWT)
{root}/{gekkoname}/{category}/{item}/get/{field} # Individual field values
{root}/{gekkoname}/{category}/{item}/get/json # JSON with all fields + timestamp
{root}/{gekkoname}/{category}/get/time # Polling timestamp per category
The online topic uses MQTT Last Will and Testament (LWT): it is set to "true" (retained) on connect and the broker automatically publishes "false" if the client disconnects unexpectedly.
Example:
mygekko/MyHome/online -> true (retained)
mygekko/MyHome/blinds/item0/get/positionLevel -> 50
mygekko/MyHome/blinds/item0/get/rotationLevel -> 45.5
mygekko/MyHome/blinds/item0/get/json -> {"currentState":0,"positionLevel":50,"rotationLevel":45.5,...,"timestamp":1705123456}
Subscribed Topics (Commands)
{root}/{gekkoname}/{category}/{item}/set
Example:
mygekko/MyHome/blinds/item0/set <- "P50" # Set position to 50%
Command throttling
MyGEKKO crashes when blind moves arrive too quickly after one another, so set commands are split into two classes:
| Class | Which commands | Behaviour |
|---|---|---|
| Throttled | Categories with a throttle statement, payload matching one of its prefixes. Default: blinds with P… (position) and S… (angle). |
One at a time, at least command interval apart (default 20 s). Coalesced per item: a newer command for the same item replaces the one still waiting, so a script setting positions for several blinds sends at most one command per blind. |
| Immediate | Everything else: categories without a throttle statement, and for blinds the direct commands -2/-1/0/1/2/T (hold down/down/stop/up/hold up/toggle). |
Sent as soon as possible, even interrupting an active throttle wait — a STOP never waits behind a position move. |
The MQTT receive path never blocks on MyGEKKO: commands are queued, and if a queue is ever full the command is dropped with a warning instead of stalling the connection.
Example with blinds (throttling at its default):
mygekko/MyHome/blinds/item0/set <- "P50" # throttled: queued, spaced by command interval
mygekko/MyHome/blinds/item0/set <- "P75" # replaces the waiting P50 for item0
mygekko/MyHome/blinds/item0/set <- "0" # STOP: sent immediately, preempts the wait
mygekko/MyHome/roomtemps/item2/set <- "21.5" # no rule for roomtemps: immediate
Push updates from MyGEKKO
MyGEKKO can POST a value to a URL when something happens — for blinds, the current position once per second while they move:
POST /r14 HTTP/1.1
Content-Type: application/json
Content-Length: 2
10
With a push block the bridge listens for these requests and publishes the
value right away, instead of waiting for the next poll:
push listen on 192.168.1.5 port 8080 {
path /r14 blinds item14 positionLevel
}
The request path is opaque (whatever is configured on the MyGEKKO side), so
path maps it to the category, item and field the value belongs to. The
value goes through the same history-based deduplication as polled values and
is published to {root}/{gekkoname}/blinds/item14/get/positionLevel; the JSON
topic is left to the poller. Unknown paths get a 404 and a warning,
unparsable bodies a 400. Mappings are checked against the field definitions
at startup (exit code 12 on error, as for a failed bind).
MyGEKKO does not necessarily report the final position, so polling stays on — but the poll duration of the category can be raised once pushes are configured. The listener is bound before the sandbox is applied and keeps working inside the chroot and under pledge. Bind it to the LAN interface only: there is no authentication.
Development
Running Tests
make test
Installing and manual pages
make install # binary to $(PREFIX)/bin, mygekko-mqtt.8 and mygekko-mqtt.conf.5 to $(MANDIR)
make man # check the manual pages with mandoc and display them
PREFIX defaults to /usr/local and MANDIR to $(PREFIX)/man; FreeBSD 14
and later keep manual pages in share/man:
make install MANDIR=/usr/local/share/man. For a router, build with
make build-openbsd on the workstation and copy the binary and the manual
pages by hand.
License
MIT