mygekko-mqtt

command module
v0.0.0-...-6f4836f Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 24 Imported by: 0

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, include and 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

Documentation

The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL