diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md index 30ae705..e4e9bea 100644 --- a/docs/CHEATSHEET.md +++ b/docs/CHEATSHEET.md @@ -213,7 +213,7 @@ Sensors register their hostname via mDNS on boot. ## HMAC Command Authentication ```bash -# Set auth secret on device +# Set auth secret on device (requires existing auth or serial access) esp-ctl cmd amber-maple.local "AUTH mysecretkey123" # Set env var so all tools sign commands automatically @@ -221,13 +221,37 @@ export ESP_CMD_SECRET="mysecretkey123" # add to ~/.bashrc.secrets # All esp-cmd/esp-ctl/esp-fleet/esp-ota commands auto-sign when ESP_CMD_SECRET is set # Unsigned commands are rejected with "ERR AUTH required" - -# To disable auth, use FACTORY reset via serial or NVS erase ``` Protocol: `HMAC:<32hex>::` — first 32 hex chars of HMAC-SHA256(secret, `:`). Replay window: +/-5s from device uptime. +### Serial Console (physical access) + +Connect via USB serial (921600 baud) for auth management without network auth: + +```bash +# Connect to serial console +idf.py -p /dev/ttyUSB0 monitor # or: screen /dev/ttyUSB0 921600 + +# Serial commands (type directly): +AUTH # Show full secret (unredacted) +AUTH # Set new secret (8-64 chars) +AUTH OFF # Clear secret (disable auth) +STATUS # Basic device info +HELP # List serial commands +``` + +### Provisioning Tool + +```bash +esp-provision # Auto-generate secret, set via serial +esp-provision mysecretkey123 # Set specific secret via serial +esp-provision --serial # Set via serial console (device running) +esp-provision --generate-only # Just print a random secret +esp-provision -p /dev/ttyACM0 # Use different serial port +``` + ## OUI Vendor Lookup ```bash