ok so this is half a convenience thing and half me wanting to learn the API.
Our analytics office and the dock lights next to it are switched by an ESP32 relay board that reports to Hermetry over MQTT. There’s a board with a switch card on it and that works fine from the browser. I spend the whole day in a terminal on Ubuntu though and I want a keyboard shortcut that toggles the office lights without opening the board.
What I tried: I took the device’s access token from the Credentials drawer and posted to the device HTTP endpoint:
curl -X POST "https://<device host>/api/v1/telemetry"
-H "Authorization: Bearer <ACCESS_TOKEN>"
-H "Content-Type: application/json"
-d '{"light": false}'It answers 200, and for a moment the switch card shows Off, but the lights stay on and a few seconds later the card flips back to On when the ESP32 reports again. So I’m clearly talking to the wrong thing. Which endpoint is the right one to make the device actually do something?
Posting telemetry with the device token is you pretending to be the device. Hermetry just stores what “the device” says. You want a command going the other way.
right, that explains the card flipping back. so is it /api/v1/rpc? the device HTTP page lists that one
That one is for the device side, it waits for commands. I think you need an API key instead of the device token, I did something like this with python requests a while ago but I don’t remember the path.
We do exactly this for the line lights at our plant, from a little script on the supervisor’s PC. It’s the Commands API with an API key.
Your switch card already sends a command, and boards can only send commands that are in the device profile’s Commands catalogue at the Basic tier. So the method exists. To see its exact name and params, ask the API with the same key you’re about to create: GET /tenant/<tenantId>/api/iot/devices/<deviceId>/rpc-commands lists what a control may send to that device.
Create the key under API Keys: give it the permission to send basic commands and to read commands, put your desktop’s address in the IP allowlist, and pick an expiry. Then:
#!/bin/sh
# ~/bin/office-lights (chmod 700)
KEY=$(cat ~/.config/hermetry/key)
curl -s -X POST "https://<your host>/tenant/<tenantId>/api/iot/devices/<deviceId>/rpc"
-H "Authorization: Bearer $KEY"
-H "Content-Type: application/json"
-d "{"method":"light.set","params":{"on":$1},"timeoutMs":10000}"A two-way command with a timeout of 30 seconds or less waits and answers 200 with the status, so you see SUCCESSFUL or the error in the terminal. Bind office-lights true and office-lights false to two shortcuts and you’re done. An API key can only send methods that are in the catalogue, which is what you want here anyway.
Docs: Commands API.
Keys expire after 90 days by default (a year at most), so put a reminder somewhere or your shortcut dies quietly in three months. And keep the key file chmod 600, not in your dotfiles repo.
Works. My only snag: the catalogue doesn’t have light.set, our integrator called it relay.set with a param called state (0 or 1). The rpc-commands call showed it straight away. First binding was Super+L which of course locks the screen, it’s on Super+F9 now.
+1, saving this for the garage door at home
Nice. We added an “are you sure” prompt to ours for the dock lights after someone switched them off with a driver still reversing in.
- You must be logged in to reply to this topic.
Join the conversation
Sign in to ask and answer, like helpful posts and mark the reply that solved your problem. Every contribution earns points and levels.