/**
 * Resound — control-bus protocol shared by the S3 hub (I2C master) and the
 * source Boards B/C (I2C slaves). Included by both hub_s3.cpp and board_source.cpp.
 *
 * Bus: I2C. Hub = master. Each source board = a slave at a fixed address.
 *   S3:  SDA=GPIO15  SCL=GPIO16   (board expansion header)
 *   B/C: SDA=GPIO32  SCL=GPIO33   (free pins; I2S=19/18/22, touch=4/27)
 *   Shared GND + two ~4.7k pull-ups (SDA->3V3, SCL->3V3).
 */
#pragma once
#include <stdint.h>

#define HUB_I2C_ADDR_JBL    0x10
#define HUB_I2C_ADDR_CARDO  0x11
#define HUB_I2C_ADDR_GUEST  0x12   // antenna board: source for an occasional guest speaker

// Master -> slave WRITE: first byte = command, then args (little-endian).
#define HUB_CMD_SET_DELAY   0x01   // arg: uint16 delay_ms (0..HUB_MAX_DELAY_MS)
#define HUB_CMD_SET_VOLUME  0x02   // arg: uint8  volume (0..100)
#define HUB_CMD_GET_STATUS  0x10   // master then issues a READ of HUB_STATUS_LEN bytes

#define HUB_MAX_DELAY_MS    200

// Slave -> master status payload (returned on the read after HUB_CMD_GET_STATUS):
//   [0] connected (0/1)
//   [1] delay_ms low byte
//   [2] delay_ms high byte
//   [3] volume (0..100)
//   [4] scanning (0/1)         (Phase 3)
//   [5] scan device count      (Phase 3)
//   [6] has a saved/selected device (0/1)   (Phase 3)
#define HUB_STATUS_LEN      7

// --- Phase 3: speaker discovery / selection -------------------------------
// The source board runs a BT inquiry scan (audio pauses during a scan),
// collects nearby audio sinks (name+MAC), and connects to a chosen one.
#define HUB_CMD_SCAN_START   0x03  // write: clear list + begin a fresh discovery scan
#define HUB_CMD_SCAN_STOP    0x04  // write: cancel scanning
#define HUB_CMD_SELECT       0x05  // write [uint8 index]: connect to scan item + persist (NVS)
#define HUB_CMD_FORGET       0x06  // write: forget saved device (disconnect + erase)
#define HUB_CMD_GET_SCANITEM 0x14  // write [uint8 index]; THEN read HUB_SCANITEM_LEN bytes
#define HUB_CMD_GET_CURNAME  0x15  // read HUB_NAME_MAX bytes: current/selected device name (NUL-padded)

#define HUB_MAX_SCAN         12     // max devices reported
#define HUB_NAME_MAX         24     // max device-name length carried over the bus

// Scan-item payload (fixed length), returned on the read after GET_SCANITEM[index]:
//   [0] valid (0/1 — 0 if index >= count)
//   [1] rssi (int8)
//   [2..7] MAC (6 bytes)
//   [8] name length (<= HUB_NAME_MAX)
//   [9 ..] name bytes
#define HUB_SCANITEM_LEN    (9 + HUB_NAME_MAX)   // 33