# V-BLACK Command Protocol Manual (nRF52)
# Date: 2026-01-19 | Transport: BLE NUS

introduction:
  rx_char: Commands (Write)
  tx_char: Data/Responses (Notify)
  mandatory_step: Send PROG_ON before any W or R command

global_commands[5]{cmd, description, response}:
  PROG_ON, Enable Program Mode / Stop Alarm, PROG_MODE: ON
  PROG_OFF, Exit Program Mode / Save Data, PROG_MODE: OFF
  RESET, Reset alarm output and counters, INFO: Uscita allarme resettata (BT).
  CALI, Toggle Diagnostic RAW Mode, --- MODALITA CALIBRAZIONE ATTIVA ---
  FACTORY, Restore factory defaults, FACTORY RESET DONE

write_parameters[7]{id, name, range, default, desc}:
  W1, Min Threshold, 0-2000, 1200, Impact sensitivity (100-500 high)
  W2, Max Threshold, 0-4095, 4000, Upper noise filter
  W3, Pulse Count, 1-50, 2, Pulses for alarm trigger
  W4, Time Window, 10-1000, 40, Analysis cycle in ms
  W20, Gain (Wiper), 0-255, 128, Digital pot (0:max)
  W11, Min Pulse Dur, 0-1000, -, Advanced/Reserved
  W12, Max Pulse Dur, 0-1000, -, Advanced/Reserved

read_commands[3]{cmd, response_format, meaning}:
  R1, PARAM: W1=<val>, Read Min Threshold
  R2, PARAM: W2=<val>, Read Max Threshold
  R20, PARAM: W20=<val>, Read Gain (Wiper)

notifications:
  heartbeat: {format: "SENSOR:<val>", interval: 500ms, ideal_rest: 2067}
  alarms[3]{msg, cause}:
    ALARM: TRIGGERED, Vibration threshold met
    ALARM: TAMPER, Wire cut/short (0 or 4095)
    INFO: Allarme resettato automaticamente, Siren timeout (5s)
  errors:
    - ERRORE: I comandi 'W' sono accettati solo in modalità programmazione.
    - ERRORE: ID Sconosciuto
    - ERRORE: Formato comando non valido