Documentación técnica

Instalar, integrar y diagnosticar

Guías de instalación en planta y la referencia del contrato de integración: registros Modbus, comandos y telemetría.

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

CanalDirecciónNotas
MQTTApp ↔ broker ↔ EdgePreferido en planta (LAN). Topics abajo.
USB SerialApp ↔ Edge115200 8N1. CLI línea a línea. DevKit CDC a veces mudo → usar MQTT/BT.
BT SPPApp ↔ EdgeSolo esp32dev (Classic). Nombre VF-XXXXXX. PIN desde UnitCred (USB cred show).
BLE NUSApp ↔ EdgeSolo 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:

CampoEjemplo
id / mDNS / MQTT nodevf-7cf194
BT SPP / BLE nameVF-7CF194 (bt status reporta este nombre, sin PIN)
SoftAP SSIDSAJ-7CF194 (público, desde MAC; id set no lo cambia)
SoftAP pass / BT PIN / BLE pkUnitCred CSPRNG. USB cred show
CLIid · 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-……).

TopicQuién publicaPayload
…/cmdAppLínea CLI UTF-8 (una orden)
…/rspEdgeLínea(s) de respuesta CLI
…/telemetryEdgeJSON ~1 Hz si stream on
…/statusEdgeLWT / 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

ComandoEfecto
helpLista comandos
ping / statusLee 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
dumpDump CSV según profile
rs485 statusPines DE/guard (DevKit)
profile get|listDrive profile activo
wifi status / mqtt status / bt statusEstado de red/BT

Escritura / operación (impacto físico)

ComandoEfecto
pset <id> <eng>Escribe param (ingeniería)
wraw <addr> <uint>FC06 crudo
w0/w1PDM write
start / stop / estop / resetMarcha / paro / paro libre / reset falta
set <pct>Consigna % frecuencia (reg familia)

Configuración Edge

ComandoEfecto
profile set saj.pdm30|saj.pdh30Activa + 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|noneGRANT. local solo USB. Default none: el Edge no se suscribe a cmd. mqtt set borra la confianza.
cred statusEstado de la credencial de unidad, sin secretos
cred showUSB físico: ssid/pass/btpin/blepk/d0c. Otro canal → ERR: forbidden
cred rotate CONFIRMUSB 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 closeUSB físico. Cierra y emite D0C-END.
d0c statusTodos los canales: open=0|1 seq=<n> left=<s> writes=<n> — sin token.
stream on|offTelemetría JSON
rs485 de|guard|settle|swaptrxDiagnó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"}
CampoUnidad / notas
freqHz (reg 0x1001, raw/100)
ampA (raw/100)
vdc / voutV (heurística bus)
psetbar — PDM 0x0000 / PDH 0xF000 (≥0.3.7)
pfbbar — 0x1010
statusrun | rev | stop | unknown

Drive profiles

IDMapaConsigna presión
saj.pdm30P0/P1 group_directP0-00
saj.pdh30F-style + D0/E0F0.00

Detalle: docs/PDH_VS_PDM.md. Catálogos: drive_profiles/.

Errores

  • ERR: Timeout / CRC error / Busy — Modbus
  • ERR: unknown — comando inválido
  • ERR: forbidden — comando no autorizado en este canal (A-1 / BL-01). Uniforme: no distingue "no existe" de "no podés". Auditoría CMD-DENY cmd= sub= ch= sin argumentos.
  • ERR: forbidden — también cred show/rotate / d0c open|close fuera 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 activo
  • ERR: D0 denied — no drive profile active
  • ERR: D0C unavailable — credential not ready / ERR: D0C denied / ERR: D0C already open
  • ERR: D0C denied — drive running / ERR: D0C denied — status unread / ERR: D0C closing
  • ERR: D0C open — start not allowed / ERR: D0C open — set not allowed
  • PING 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.

Fuente en el repositorio: docs/PROTOCOL.md