Shelly Coffee Timer

A safety-first home-automation project that turns a Shelly Plug S Gen3 into a timed coffee-maker controller. Every on-state is a countdown timer — the plug can never be left on indefinitely. The device runs autonomously with an mJS state machine and a connectivity watchdog, takes commands over a local MQTT broker (mTLS) with a cloud bridge for off-LAN access, and is also controllable directly over Wi-Fi (local HTTP). Clients: an Android app, a web page, or curl.

Live web control: https://laffs2k5.github.io/shelly-coffee-timer/

Documentation: Specification · Architecture · AI Test Guide · Regression Checklist

This is v2 — local MQTT broker + cloud bridge + connectivity watchdog, validated on hardware. The v1 release used Adafruit IO; that design is archived in docs/archive/ (frozen at the adafruit-final tag). v2 design: specs 11–12 and Architecture.

Hardware

• Shelly Plug S Gen3 — smart plug with mJS scripting, MQTT, and local HTTP
• Any drip coffee maker with a physical on/off switch (left in the "on" position; the plug controls power)

Repo structure

shelly-coffee-timer/
├── app/               Android app (Kotlin/Compose) with notification service
├── device/            mJS script for the Shelly (coffee.js)
├── web/               HTML control page (GitHub Pages)
├── scripts/           Bash utilities (feed setup, REST/MQTT testing)
├── docs/spec/         Specification documents (00–03, 05–12 + INDEX; 04 archived)
├── docs/              Architecture overview, test guides
├── docs/archive/      v1 (Adafruit) docs + v2 build/validation record
├── .github/workflows/ CI/CD: APK build, release, GitHub Pages deploy
├── .env.example       Template for credentials
└── CLAUDE.md          AI assistant context

Quick start

Device setup

1. cp .env.example .env and fill in your broker hosts, credentials, and Shelly IP; source .env
2. Point the Shelly's MQTT at your local broker over mTLS (Mqtt.SetConfig via RPC — see doc 11 §5)
3. Upload the device script: scripts/build-device.sh produces device/coffee.min.js; flash it via RPC (Script.PutCode) or paste into the Shelly web UI
4. Verify connectivity with the test scripts in scripts/

Android app

1. Install the APK — grab it from the latest release or build app/ in Android Studio
2. In Settings, enter the Shelly IP (HTTP-direct), local broker host, device ID, and cloud broker host + user/pass
3. For the local-broker mTLS path: import your client .p12 and your broker's private-CA public cert (.crt/.pem) — both via the Import buttons in Settings. (HTTP-direct and cloud work without these.)

Nothing identity-specific is baked into the APK — the official released build is fully functional once you enter settings and import the CA + .p12 at runtime. No rebuild needed.

Web control

• Visit https://laffs2k5.github.io/shelly-coffee-timer/ and enter your cloud MQTT (EMQX) credentials — they persist in the browser only
• Or open web/index.html locally in a browser

Credentials

All secrets live in .env, which is gitignored. This repo is public — never commit real API keys. See doc 10 §7 for the full credentials policy.

License

ISC