Reply To: Switching the office lights relay from a terminal on my Ubuntu desktop

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.