username/esp32-hacking
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity

docs: Add Pi-side tool prerequisites, build notes to INSTALL.md

Browse Source 
Document esp-ctl install, standalone tool symlinks, HMAC auth setup,
watch daemon setup, and CMakeLists.txt REQUIRES caveat.
This commit is contained in:
user
2026-02-04 21:12:14 +01:00
parent fa589b0238
commit 7511814976
1 changed files with 66 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/INSTALL.md
View File

@@ -54,6 +54,8 @@ idf.py build
Build output goes to `build/` (excluded by `.gitignore`). External component `esp_csi_gain_ctrl` is fetched automatically to `managed_components/`. Build output goes to `build/` (excluded by `.gitignore`). External component `esp_csi_gain_ctrl` is fetched automatically to `managed_components/`.
**Note on CMakeLists.txt:** The `main` component uses no explicit `REQUIRES` — ESP-IDF auto-includes all components (including `mbedtls` for HMAC auth). Adding `REQUIRES <component>` overrides this and breaks the build unless all dependencies are listed.
## Flash ## Flash
### Connect ESP32 ### Connect ESP32
@@ -84,6 +86,70 @@ Exit monitor with `Ctrl+]`.
idf.py -p /dev/ttyUSB0 flash monitor idf.py -p /dev/ttyUSB0 flash monitor
``` ```
## Pi-Side Tools
### Prerequisites
| Component | Version | Install |
|-----------|---------|---------|
| Python | 3.10+ | System |
| esp-ctl | 0.1.0 | `pip install -e ~/git/esp-ctl` |
| requests | ≥2.28 | (esp-ctl dependency) |
| pyyaml | ≥6.0 | (esp-ctl dependency) |
### Install esp-ctl
```bash
cd ~/git/esp-ctl
pip install --break-system-packages -e .
# Optional extras
pip install --break-system-packages -e '.[serial]' # pyserial for serial monitor
pip install --break-system-packages -e '.[discover]' # zeroconf for mDNS discovery
```
### Standalone Tools (esp32-hacking)
Symlinked to `~/.local/bin/`:
| Tool | Source | Purpose |
|------|--------|---------|
| `esp-cmd` | `tools/esp-cmd` | Single device commands |
| `esp-fleet` | `tools/esp-fleet` | Fleet-wide commands |
| `esp-ota` | `tools/esp-ota` | OTA firmware update |
All three import `esp_ctl.auth.sign_command` for HMAC auth support — `esp-ctl` must be installed.
```bash
ln -sf ~/git/esp32-hacking/tools/esp-cmd ~/.local/bin/
ln -sf ~/git/esp32-hacking/tools/esp-fleet ~/.local/bin/
ln -sf ~/git/esp32-hacking/tools/esp-ota ~/.local/bin/
```
### HMAC Auth Setup
```bash
# Set secret on device
esp-ctl cmd amber-maple.local "AUTH mysecretkey123"
# Add to environment so all tools auto-sign
echo 'export ESP_CMD_SECRET="mysecretkey123"' >> ~/.bashrc.secrets
source ~/.bashrc.secrets
```
### Watch Daemon Setup
```bash
# Download OUI database (one-time)
esp-ctl oui --update
# Edit config
vim ~/.config/esp-ctl/watch.yaml
# Run daemon (listens on :5500, enriches + stores probes/BLE/alerts)
esp-ctl watch
```
## Deployed Devices ## Deployed Devices
| Name | IP | Location | Notes | | Name | IP | Location | Notes |