Protocolo Edge — contrato compartido (firmware / app / clientes)
Fuente única para no divergir entre Electron/RN, desktop legacy y firmware.
Versión alineada a Edge ≥ 0.3.7. Seguridad de transporte: docs/SECURITY.md.
Transportes
| Canal | Dirección | Notas |
|---|---|---|
| MQTT | App ↔ broker ↔ Edge | Preferido en planta (LAN). Topics abajo. |
| USB Serial | App ↔ Edge | 115200 8N1. CLI línea a línea. DevKit CDC a veces mudo → usar MQTT/BT. |
| BT SPP | App ↔ Edge | Solo esp32dev (Classic). Nombre VF-XXXXXX. PIN desde UnitCred (USB cred show). |
| BLE NUS | App ↔ Edge | Solo Guition (Nordic UART). Nombre VF-XXXXXX. Passkey desde UnitCred. |
Quién usa qué (producto):
- VarioField (RN/Electron): MQTT + BT preferidos; USB para debug/Flasher.
- Flasher / PlatformIO: USB download.
- SoftAP
SAJ-<MAC6>: acceso de campo sin STA (password por unidad; ver SECURITY).
Todos los canales alimentan el mismo CliEngine (mismas líneas de comando/respuesta).
Identidad por placa (FW ≥ 0.3.8; credencial ≥ ADR-026)
Al primer boot se genera un serial estable desde el MAC del chip. El secreto de radio (B-1) es independiente del MAC:
| Campo | Ejemplo |
|---|---|
id / mDNS / MQTT node | vf-7cf194 |
| BT SPP / BLE name | VF-7CF194 (bt status reporta este nombre, sin PIN) |
| SoftAP SSID | SAJ-7CF194 (público, desde MAC; id set no lo cambia) |
| SoftAP pass / BT PIN / BLE pk | UnitCred CSPRNG. USB cred show |
| CLI | id · id set <slug> · id reset · cred status|show|rotate CONFIRM |
id set no rota el secreto. cred show / cred rotate solo por USB físico.
MQTT topics
Root: saj/pdm30/<edge_id>/… donde <edge_id> es el serial (vf-……).
| Topic | Quién publica | Payload |
|---|---|---|
…/cmd | App | Línea CLI UTF-8 (una orden) |
…/rsp | Edge | Línea(s) de respuesta CLI |
…/telemetry | Edge | JSON ~1 Hz si stream on |
…/status | Edge | LWT / online (si habilitado) |
Descubrir el id: wifi status / id en CLI, o mDNS vf-….local.
Broker de lab: auth + ACL vía desktop_app/scripts/setup_mosquitto.sh (ACL saj/pdm30/# cubre todos los nodos).
CLI — comandos
Formato: texto, tokens separados por espacio. Respuestas típicas: OK …, ERR: …, prompts >.
Lectura / diagnóstico
| Comando | Efecto |
|---|---|
help | Lista comandos |
ping / status | Lee status/freq/amp/vdc → Link OK o PING FAIL … |
raw <addr> | FC03 un holding (hex o dec) |
pget <id> | Lee param por ID (F0.00 / P0-00) solo del profile activo (registry IVfdDriver) |
r0/r1 <ii> | PDM P0/P1 por índice |
dump | Dump CSV según profile |
rs485 status | Pines DE/guard (DevKit) |
profile get|list | Drive profile activo |
wifi status / mqtt status / bt status | Estado de red/BT |
Escritura / operación (impacto físico)
| Comando | Efecto |
|---|---|
pset <id> <eng> | Escribe param (ingeniería) |
wraw <addr> <uint> | FC06 crudo |
w0/w1 | PDM write |
start / stop / estop / reset | Marcha / paro / paro libre / reset falta |
set <pct> | Consigna % frecuencia (reg familia) |
Configuración Edge
| Comando | Efecto |
|---|---|
profile set saj.pdm30|saj.pdh30 | Activa + NVS save (≥0.3.7). profile list deriva del registry, no de un string fijo. |
slave <id> | Slave Modbus |
wifi … / mqtt … / bt … | Red / broker / BT |
mqtt trust local|none | GRANT. local solo USB. Default none: el Edge no se suscribe a cmd. mqtt set borra la confianza. |
cred status | Estado de la credencial de unidad, sin secretos |
cred show | USB físico: ssid/pass/btpin/blepk/d0c. Otro canal → ERR: forbidden |
cred rotate CONFIRM | USB físico: nuevo secreto, reinstala SoftAP, limpia bonds. No borra d0c_seq/d0c_chain/d0c_last. Cierra una sesión D0-C abierta. |
d0c open <token> | USB físico. Abre sesión de puesta en marcha (900 s / idle 120 s). Variador debe estar parado. |
d0c close | USB físico. Cierra y emite D0C-END. |
d0c status | Todos los canales: open=0|1 seq=<n> left=<s> writes=<n> — sin token. |
stream on|off | Telemetría JSON |
rs485 de|guard|settle|swaptrx | Diagnóstico RS485 DevKit |
Telemetría JSON
Ejemplo (stream on):
{"freq":0.00,"amp":0.00,"vdc":0.0,"vout":0.0,"pset":2.0,"pfb":0.0,"status":"stop"}
| Campo | Unidad / notas |
|---|---|
freq | Hz (reg 0x1001, raw/100) |
amp | A (raw/100) |
vdc / vout | V (heurística bus) |
pset | bar — PDM 0x0000 / PDH 0xF000 (≥0.3.7) |
pfb | bar — 0x1010 |
status | run | rev | stop | unknown |
Drive profiles
| ID | Mapa | Consigna presión |
|---|---|---|
saj.pdm30 | P0/P1 group_direct | P0-00 |
saj.pdh30 | F-style + D0/E0 | F0.00 |
Detalle: docs/PDH_VS_PDM.md. Catálogos: drive_profiles/.
Errores
ERR: Timeout/CRC error/Busy— ModbusERR: unknown— comando inválidoERR: forbidden— comando no autorizado en este canal (A-1 / BL-01). Uniforme: no distingue "no existe" de "no podés". AuditoríaCMD-DENY cmd= sub= ch=sin argumentos.ERR: forbidden— tambiéncred show/rotate/d0c open|closefuera de USB (ADR-026/027)ERR: D0 denied — safety-related register 0xADDR— denylist D0 (no reintentar: no es fallo de bus)ERR: D0 denied — register 0xADDR not in profile <id>— fuera del catálogo del driver activoERR: D0 denied — no drive profile activeERR: D0C unavailable — credential not ready/ERR: D0C denied/ERR: D0C already openERR: D0C denied — drive running/ERR: D0C denied — status unread/ERR: D0C closingERR: D0C open — start not allowed/ERR: D0C open — set not allowedPING FAIL step N: … rx_len=K— link VFD- Pérdida de MQTT/USB no auto-
estop(ver SECURITY)
Auditoría (broadcast Serial + MQTT): D0-DENY …, D0C-BEGIN …, D0C-W …, D0C-END …. Nunca incluyen el token ni usk.
start / set se rechazan con sesión D0-C abierta. stop / estop siguen disponibles.
Evolución
Cambios breaking (topics, JSON fields, semántica de comandos) → bump de versión de firmware + nota en este archivo + release notes.