Config.h

// SPDX-License-Identifier: GPL-3.0-or-later
// Copyright (C) 2026 Dobrev IT Ltd
//
// This file is part of RetiMesh Node.
//
// RetiMesh Node is free software: you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the
// Free Software Foundation, either version 3 of the License, or (at your
// option) any later version.
//
// RetiMesh Node is distributed in the hope that it will be useful, but
// WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
// Public License for more details.
//
// You should have received a copy of the GNU General Public License along
// with RetiMesh Node. If not, see <https://www.gnu.org/licenses/>.

// ============================================================================
//  Config.h — compile-time configuration for the RetiMesh Node
//
//  Everything here can be overridden from platformio.ini build_flags
//  (every #define is guarded by #ifndef).
// ============================================================================
#pragma once

#include <Arduino.h>

// ---------------------------------------------------------------------------
// Board selection. One header per board under boards/ defines the pin map and
// the capability flags (HAS_SD, HAS_PMU, HAS_GPS, ...); everything below is
// guarded by #ifndef, so a board header wins and anything it leaves out falls
// back to the general default. Pass -DBOARD_TBEAM (or another BOARD_*) from
// platformio.ini; without one, the T3-S3 is assumed.
// ---------------------------------------------------------------------------
#if defined(BOARD_TBEAM)
  #include "boards/tbeam.h"
#elif defined(BOARD_TBEAM_SUPREME)
  #include "boards/tbeam_supreme.h"
#elif defined(BOARD_HELTEC_V3)
  #include "boards/heltec_v3.h"
#elif defined(BOARD_HELTEC_WS)
  #include "boards/heltec_ws.h"
#elif defined(BOARD_HELTEC_WB)
  #include "boards/heltec_wb.h"
#elif defined(BOARD_HELTEC_WP)
  #include "boards/heltec_wp.h"
#elif defined(BOARD_HELTEC_V4)
  #include "boards/heltec_v4.h"
#elif defined(BOARD_T3S3_SX1280_PA)
  #include "boards/t3s3_sx1280_pa.h"
#elif defined(BOARD_T3S3_SX1280)
  #include "boards/t3s3_sx1280.h"
#elif defined(BOARD_TDECK)
  #include "boards/tdeck.h"
#elif defined(BOARD_THINKNODE_M9)
  #include "boards/thinknode_m9.h"
#else
  #include "boards/t3s3.h"
#endif

// ---------------------------------------------------------------------------
// Local-link capabilities: what the PCB puts on its USB connector. These come
// from boards.json — the one registry of board facts — through
// tools/board_caps.py, which turns the env's "local_link" block into -D flags
// at build time and refuses to build when they contradict the framework's own
// USB flags in platformio.ini. The defaults below are what a build with no
// entry (the host-native test env) gets: nothing.
//
//   BOARD_USB_NATIVE        the MCU's own USB D+/D- reach the connector
//   BOARD_USB_NCM           ...and the silicon can present CDC-NCM there
//   BOARD_USB_BRIDGE        "CP2102", "CH9102", ... or "none"
//   BOARD_BRIDGE_AUTO_RESET the bridge's DTR/RTS reach EN/IO0 (esptool resets it)
//   BOARD_UART_NETWORK      the UART behind the bridge may carry PPP
//   BOARD_UART_INSTANCE     which UART the bridge sits on (0 on every board so far)
//   BOARD_UART_BAUDS        the rates the registry lists for it, comma-separated
//   BOARD_UART_MAX_BAUD     the highest of them tried on this board's hardware
// ---------------------------------------------------------------------------
#ifndef BOARD_USB_NATIVE
  #define BOARD_USB_NATIVE        0
#endif
#ifndef BOARD_USB_NCM
  #define BOARD_USB_NCM           0
#endif
#ifndef BOARD_USB_BRIDGE
  #define BOARD_USB_BRIDGE        "none"
#endif
#ifndef BOARD_BRIDGE_AUTO_RESET
  #define BOARD_BRIDGE_AUTO_RESET 0
#endif
#ifndef BOARD_UART_NETWORK
  #define BOARD_UART_NETWORK      0
#endif
#ifndef BOARD_UART_INSTANCE
  #define BOARD_UART_INSTANCE     0
#endif
#ifndef BOARD_UART_BAUDS
  #define BOARD_UART_BAUDS        115200
#endif
#ifndef BOARD_UART_MAX_BAUD
  #define BOARD_UART_MAX_BAUD     115200
#endif
// Whether this build drives USB networking: the board can present NCM and
// the OTG stack owns the peripheral (ARDUINO_USB_MODE 0, set by
// tools/board_caps.py from the same registry facts). One derived fact, so no
// file has to know both halves. See docs/local-link.md and UsbNcm.h.
#if BOARD_USB_NCM && defined(ARDUINO_USB_MODE) && (ARDUINO_USB_MODE == 0)
  #define HAS_USB_NCM 1
#else
  #define HAS_USB_NCM 0
#endif
// Whether this build drives PPP over the bridge UART: every board whose
// registry entry says the UART may carry it does, because the core's
// prebuilt lwIP carries the PPP client on every chip. See PppUart.h.
#if BOARD_UART_NETWORK
  #define HAS_PPP 1
#else
  #define HAS_PPP 0
#endif
// ---------------------------------------------------------------------------
// Serial byte-stream link (UartLink.h)
// ---------------------------------------------------------------------------
// A UART carrying HDLC frames and knowing nothing of Reticulum, so the serial
// RNS interface and the later remote-radio link can both sit on it rather than
// each writing a UART of their own (roadmap 2.2).
//
// Off unless a board names a free port, and deliberately no board does yet.
// Which UART is free is a per-board fact with three claimants already — the
// bridge UART is the console's and PPP's (BOARD_UART_INSTANCE, arbitrated in
// PppArbiter.h), and UART1 is the GNSS receiver's on every board that has one
// (Gps.cpp constructs HardwareSerial(1)) — and the pins for whatever is left
// are a wiring question a bench answers, not one this file can. Naming a port
// here without that answer would claim a link that does not exist.
//
// Costing nothing until then is the point: everything behind HAS_SERIAL_LINK
// compiles out, so the driver is infrastructure for issues 10 and 18 rather
// than weight every board carries. docs/serial.md says what enabling it needs.
#ifndef BOARD_SERIAL_UART
  #define BOARD_SERIAL_UART   -1          // -1 = this board has no free UART
#endif
#ifndef PIN_SERIAL_LINK_RX
  #define PIN_SERIAL_LINK_RX  -1
#endif
#ifndef PIN_SERIAL_LINK_TX
  #define PIN_SERIAL_LINK_TX  -1
#endif
#if BOARD_SERIAL_UART >= 0 && PIN_SERIAL_LINK_RX >= 0 && PIN_SERIAL_LINK_TX >= 0
  #define HAS_SERIAL_LINK 1
#else
  #define HAS_SERIAL_LINK 0
#endif
// The transmit queue's bound, in frames and in bytes. Both are checked on
// every push and either one running out is the queue being full: a link is as
// likely to be held up by many small frames as by a few large ones, and a
// bound that only counted one of them would be no bound at all in the other
// direction. Sized to hold a handful of full-MTU frames — enough to ride out a
// scheduling hiccup, not enough to hide a wire that has stopped working.
#ifndef SERIAL_LINK_TX_FRAMES
  #define SERIAL_LINK_TX_FRAMES   8
#endif
#ifndef SERIAL_LINK_TX_BYTES
  #define SERIAL_LINK_TX_BYTES    (4 * RNS_MTU)
#endif
// The driver's own receive ring, given to the UART driver at install. What
// does not fit while the reader is behind is lost on the wire and the far end
// resynchronises, which is the same bargain PPP's ring makes above.
#ifndef SERIAL_LINK_RX_RING
  #define SERIAL_LINK_RX_RING     2048
#endif
#ifndef SERIAL_LINK_TASK_STACK
  #define SERIAL_LINK_TASK_STACK  3072
#endif

// PPP over the bridge UART (PppUart.h). The receive ring is the UART
// driver's own, sized here; what does not fit while the reader is behind is
// dropped and PPP retransmits — the radio never waits for the serial port.
// The transmit queue holds one largest frame (an escaped 1500-byte packet is
// a little over 3 KB) with room to spare; a frame that does not fit is
// dropped whole. The default speed is the console's, so that switching PPP
// on changes nothing a host already relies on; a faster one has to be
// qualified per board (boards.json uart.tested_max_baud).
#ifndef PPP_RX_RING_BYTES
  #define PPP_RX_RING_BYTES   4096
#endif
#ifndef PPP_TX_QUEUE_BYTES
  #define PPP_TX_QUEUE_BYTES  8192          // five frames at PPP's MTU; internal RAM
#endif
#ifndef PPP_BAUD_DEFAULT
  #define PPP_BAUD_DEFAULT    115200
#endif
// There is no smaller pair for the console alone. A board that carries PPP
// carries these sizes from boot whether the switch is on or off, because the
// core fixes them before it installs the UART driver and they cannot be
// resized afterwards (main.cpp, PppUart.h). What the switch gives back is the
// interface and the reader task, not the ring.

// ---------------------------------------------------------------------------
// The maintenance console (Maintenance.h) and its network transport
// (ConsoleServer.h)
//
// The console over a socket is what lets a node be configured from a
// distance without a resident web server: measured on a Heltec Wireless
// Stick, the portal and the resolver beside it cost about 22 KB of
// byte-addressable RAM ("http + dns" in the boot bill, with mDNS billed
// separately at 6 368 B) against 272 B for the Reticulum TCP listener, on a
// board that finishes booting with about 27 KB. Same parser, same settings rules, same refusals
// as the cable — a second transport, not a second implementation.
// ---------------------------------------------------------------------------
#ifndef CONSOLE_TCP_PORT
  #define CONSOLE_TCP_PORT       4243     // beside the Reticulum transport's 4242
#endif
// One caller at a time, and not a setting: the transport holds one client
// slot (ConsoleServer.cpp), so a second would be dead RAM and a macro that
// raised it would be a knob that turns nothing. This is a configuration
// channel rather than a service — two operators changing settings at once is
// a race nobody asked for.
// One for whatever a network transport brings, and one kept back for a caller
// the transport authenticated itself — today that is a command arriving as an
// LXMF message. They are not interchangeable: the TCP console claims its slot
// on connect, before any password, so a single client sitting idle on the
// access point would otherwise deny the one recovery path a node has when its
// cable is dead (RnsAdmin.h, Maintenance.h).
#define MAINT_NET_SESSIONS       2
#define MAINT_RESERVED_SESSIONS  1
// Guessing the admin password over the air. Counted for the node, not the
// connection (Maintenance.h).
#ifndef MAINT_AUTH_MAX_FAILURES
  #define MAINT_AUTH_MAX_FAILURES 3
#endif
#ifndef MAINT_AUTH_LOCKOUT_MS
  #define MAINT_AUTH_LOCKOUT_MS   30000
#endif

// ---------------------------------------------------------------------------
// Firmware version — single-sourced from the git tag by CI
// (PLATFORMIO_BUILD_FLAGS=-DFW_VERSION=\"v1.2.3\"). A build CI did not version
// asks git instead (tools/fw_version.py): `git describe --always --dirty`, so
// a node can say which commit it runs and a bench of them can be told apart.
// "dev" survives only where git cannot answer at all — a source tarball, or a
// container without the binary.
// ---------------------------------------------------------------------------
#ifndef FW_VERSION
  #define FW_VERSION        "dev"
#endif
#define FW_NAME             "RetiMesh Node"

// ---------------------------------------------------------------------------
// Wi-Fi SoftAP
// ---------------------------------------------------------------------------
// SSID = AP_SSID_PREFIX + "-" + last three octets of the factory MAC,
// e.g. "retimesh-A1B2C3", so several nodes in range never collide.
// Define AP_SSID to force a fixed name instead.
#ifndef AP_SSID_PREFIX
  #define AP_SSID_PREFIX    "retimesh"
#endif
#ifndef AP_PASSWORD
  #define AP_PASSWORD       ""              // empty = open network
#endif
// SoftAP WPA3 (SAE) needs ESP-IDF 5, which the core 3.x toolchain brings. The
// gate stays on the IDF version rather than being assumed true because the
// earlier core 2.x (IDF 4.4) rejected the auth mode outright (verified:
// esp_wifi_set_config -> ESP_ERR_INVALID_ARG, AP stays WPA2), and a build on
// such a core must go on saying so rather than offering what it cannot do.
#include <esp_idf_version.h>
#define WPA3_SOFTAP_SUPPORTED (ESP_IDF_VERSION_MAJOR >= 5)

// Default security when no setting is stored: 0 open, 1 WPA2,
// 2 WPA2+WPA3 mixed, 3 WPA3-only. Ignored unless AP_PASSWORD has >= 8 chars.
#ifndef AP_SECURITY_DEFAULT
  #define AP_SECURITY_DEFAULT 1
#endif
#ifndef AP_CHANNEL
  #define AP_CHANNEL        6
#endif
#ifndef AP_MAX_STATIONS
  #define AP_MAX_STATIONS   8
#endif
// SoftAP beacon interval, in 802.11 time units (1 TU = 1.024 ms, so 400 TU is
// about 410 ms). The Arduino core hardcodes 100 TU inside WiFi.softAP() — ten
// beacons a second at the lowest basic rate, around the clock, usually for
// nobody — and rebuilds that config on every call, which is why the value is
// applied by a read-modify-write after softAP() (WifiManager::startAccessPoint)
// and lives nowhere else. 4x less beacon airtime and current; the cost is a
// phone taking a moment longer to see the network in a scan list. A build
// default rather than a runtime setting, deliberately.
#ifndef WIFI_AP_BEACON_TU
  #define WIFI_AP_BEACON_TU 400
#endif
// Default Wi-Fi TX power ceiling, dBm — wifi.tx_power's default, one global
// ceiling for the AP and the station together (the chip has one radio). 14 is
// plenty for the AP-as-maintenance-portal case of a phone at arm's length; a
// node genuinely bridging a LAN at range turns it up (setting bounds 2-20,
// SettingsRules).
#ifndef WIFI_TX_POWER_DBM
  #define WIFI_TX_POWER_DBM 14
#endif
// How many AP beacon intervals a dozing station sleeps between wakes —
// wifi.sta_listen_interval's default, which is also the driver's own default.
// The driver consults it only under WIFI_PS_MAX_MODEM (the battery profile).
#ifndef WIFI_STA_LISTEN_INTERVAL
  #define WIFI_STA_LISTEN_INTERVAL 3
#endif
// AP idle auto-off — wifi.ap_idle_off / wifi.ap_idle_minutes' defaults. With
// the switch on, an access point that has stood empty for the configured
// minutes is taken down until something wakes it: the button, SET
// links.wifi_ap on or WIFI ON at the console (either wakes even when the
// switch is already on — but WIFI ON writes both Wi-Fi switches, so on a
// node that keeps its station off it also restarts), or an admin message.
// Off by default, deliberately: the AP is usually the only management path
// on an unattended node, and a policy bug that keeps it down is a site
// visit — the operator opts in per node. Bounds (1-1440 min) live in
// SettingsRules.
// What kind of node this is, when nobody has said: 0 not set, 1 carried,
// 2 transport (Power::Role). Not set is deliberately the default and is
// deliberately not guessed from the board class — a handheld on a desk and a
// relay on a mast are the same board, and the only difference is what its
// operator did with it. A node that has never been told behaves exactly as
// every node did before the setting existed, which is what makes the upgrade
// a no-change. Bounds live in SettingsRules; a board or a future preset may
// override this, and later firmware may add roles above 2.
#ifndef NODE_ROLE_DEFAULT
  #define NODE_ROLE_DEFAULT 0
#endif
#ifndef AP_IDLE_OFF_DEFAULT
  #define AP_IDLE_OFF_DEFAULT 0
#endif
#ifndef AP_IDLE_MINUTES
  #define AP_IDLE_MINUTES 10
#endif
// How long a runtime access-point teardown holds off after the change that
// asked for it, so the reply — an HTTP 200 to a browser on the AP itself, a
// console OK — leaves before the link it rides goes away. The same job
// RESTART_ACK_DELAY_MS does for a restart's acknowledgement, folded into the
// one teardown path (WifiManager's convergence) so no caller can shorten it.
// Invariant (WifiManager.h holds the static_assert): the grace must exceed
// the idle-gate cadence (_apIdleGate, 1 s), so at least one policy ask lands
// inside every grace — that ask is what re-reads the station count and lets a
// station that associated during the grace cancel the staged teardown. At
// 700 ms the teardown beat the next ask in a healthy loop and cut such a
// station off; 1200 ms still reads as instant and covers the async reply
// many times over.
#ifndef AP_STOP_GRACE_MS
  #define AP_STOP_GRACE_MS 1200
#endif

// Admin password protecting the settings API/page (HTTP Basic Auth,
// user "admin"). Change it from the settings page; stored in NVS.
#ifndef ADMIN_PASSWORD_DEFAULT
  #define ADMIN_PASSWORD_DEFAULT "retimesh"
#endif
#define NVS_NAMESPACE       "retimesh"

// ---------------------------------------------------------------------------
// Diagnostics (see Diag.h). The boot counter lives in its own NVS namespace so
// a settings reset does not erase the restart history a soak run is built on.
// ---------------------------------------------------------------------------
#define DIAG_NVS_NAMESPACE  "retimesh-diag"     // max 15 chars
#define DIAG_STACK_WARN_B   768                 // headroom below this: name the task
#define DIAG_HEAP_WARN_B    20480               // internal heap low-water below this

// A classic ESP32 splits its internal memory, and much of what the heap
// reports is 32-bit-only IRAM that cannot hold a buffer or a stack. With PSRAM
// there is somewhere else to put things; without it, the byte-addressable half
// is all a node has, and on a Wireless Stick that is about 213 KB against
// 200 KB spent before it has finished starting.
//
// A class rather than a board: today it selects the Wireless Stick alone — the
// Wireless Bridge is the same silicon with 8 MB of PSRAM, and the T-Beam's
// board file brings 4 MB — and it will select the next board like it without
// anybody remembering to add one.
#if defined(CONFIG_IDF_TARGET_ESP32) && !defined(BOARD_HAS_PSRAM)
  #define BOARD_DRAM_TIGHT 1
#else
  #define BOARD_DRAM_TIGHT 0
#endif

// Whether a board starts mDNS by default. It answers <hostname>.local and
// advertises the RNS port: a convenience, not a service anything depends on,
// and 6 368 B of byte-addressable RAM measured with Diag::cost(). On a board
// with ten kilobytes left it is the largest single thing that can be declined
// while still being a node, so the tight ones start without it. It stays a
// setting either way (docs/hardware.md).
#ifndef MDNS_ENABLED_DEFAULT
  #define MDNS_ENABLED_DEFAULT (BOARD_DRAM_TIGHT ? 0 : 1)
#endif

#ifndef MDNS_HOSTNAME
  // Fallback only. The name a node actually answers to is derived from its
  // access-point name — see WifiManager::deriveHostname() — so that two nodes
  // on one network do not both claim the same one. This is what is used when
  // an operator has renamed the AP to something with no usable characters in
  // it at all.
  #define MDNS_HOSTNAME     "retimesh"
#endif

// AP address 10.42.0.1 — "42" as a nod to the transport port.
#define AP_IP               IPAddress(10, 42, 0, 1)
#define AP_NETMASK          IPAddress(255, 255, 255, 0)

// ---------------------------------------------------------------------------
// Network services
// ---------------------------------------------------------------------------
#ifndef HTTP_PORT
  #define HTTP_PORT         80
#endif
#ifndef RNS_TCP_PORT
  #define RNS_TCP_PORT      4242
#endif
#ifndef RNS_MAX_CLIENTS
  // Two on a board with no room to spare: past the cap a client is refused,
  // which an operator sees and which costs the node nothing (see
  // RetiTransportServer). Contrast AUTOIF_MAX_PEERS below, which evicts.
  #define RNS_MAX_CLIENTS   (BOARD_DRAM_TIGHT ? 2 : 4)   // simultaneous Sideband/RNS peers
#endif

// ---------------------------------------------------------------------------
// RNS AutoInterface (IPv6 link-local peering on the access point and the LAN)
// ---------------------------------------------------------------------------
#ifndef HAS_AUTOINTERFACE
  #define HAS_AUTOINTERFACE 1
#endif
#ifndef AUTOIF_GROUP_ID
  #define AUTOIF_GROUP_ID   "reticulum"     // RNS default group id
#endif
// One slot per peer, and a peer is a link-local address rather than a node: a
// neighbour reachable both over this node's access point and over the LAN
// occupies two. Eight was the count of a bench where every node was an AP
// client of the next; a room of them on one LAN needs a slot each, in both
// directions, with the phones and laptops that are the point of the exercise.
#ifndef AUTOIF_MAX_PEERS
  #define AUTOIF_MAX_PEERS  24
#endif

// The most interfaces Transport can hold at once: the radio, one per client on
// :4242, one per AutoInterface peer. Snapshot buffers are sized from this, so
// a listing shows every interface instead of the first few.
#define RNS_MAX_INTERFACES  (1 + RNS_MAX_CLIENTS + AUTOIF_MAX_PEERS)

// An interface name has to hold the longest one this node builds,
// "WiFi/255.255.255.255:65535", with room to spare. RNS derives an
// interface's identity by hashing its name, so a name that gets truncated
// is two interfaces that Transport cannot tell apart.
#define INTERFACE_NAME_MAX  32

// ---------------------------------------------------------------------------
// Reticulum sizes
// ---------------------------------------------------------------------------
// RNS.Reticulum.MTU — the largest packet a Reticulum instance emits.
#define RNS_MTU             500

// Physical LoRa framing (RNode-compatible, see LoRaRadio.cpp):
// each RF frame is 1 header byte + up to 254 payload bytes.
#define LORA_FRAME_MAX      255
#define LORA_HEADER_LEN     1
#define LORA_FRAG_PAYLOAD   (LORA_FRAME_MAX - LORA_HEADER_LEN)   // 254
#define LORA_FLAG_SPLIT     0x01
#define LORA_SEQ_UNSET      0xFF

// ---------------------------------------------------------------------------
// LoRa radio on SPI. The pin map comes from the board header; these are the
// fallbacks for a board that does not define one. Both the SX1262 lines
// (DIO1/BUSY) and the SX127x line (DIO0) exist because LoRaRadio::begin()
// probes for either transceiver.
// ---------------------------------------------------------------------------
#ifndef LORA_SPI_BUS
  #define LORA_SPI_BUS      FSPI            // general-purpose bus on the ESP32-S3
#endif
#ifndef PIN_LORA_SCK
  #define PIN_LORA_SCK      5
#endif
#ifndef PIN_LORA_MISO
  #define PIN_LORA_MISO     3
#endif
#ifndef PIN_LORA_MOSI
  #define PIN_LORA_MOSI     6
#endif
#ifndef PIN_LORA_CS
  #define PIN_LORA_CS       7
#endif
#ifndef PIN_LORA_RST
  #define PIN_LORA_RST      8
#endif
#ifndef PIN_LORA_BUSY
  #define PIN_LORA_BUSY     34
#endif
#ifndef PIN_LORA_DIO1
  #define PIN_LORA_DIO1     33
#endif
#ifndef PIN_LORA_DIO0
  #define PIN_LORA_DIO0     9               // SX127x only
#endif

// PHY defaults — the running values live in NVS (see Settings.h) and are
// editable from the settings page. They MUST match every other node on
// the channel (including real RNodes — configure the RNode side alike).
#ifndef RF_FREQ_MHZ
  // 869.525, not 869.410. The 10 % sub-band is 869.4-869.65, and a channel is
  // not a point: at the default 125 kHz, 869.410 spans 869.3475-869.4725 and
  // so reaches into the unallocated gap below 869.4. The node's own limiter
  // then holds it to 0.1 % and says the channel is not allocated to this kind
  // of device — the firmware was already warning about the default it shipped
  // with. 869.525 sits centred in the 10 % band with room either side.
  #define RF_FREQ_MHZ       869.525         // EU868 SRD, centred in the 10 % sub-band
#endif
#ifndef RF_BW_KHZ
  #define RF_BW_KHZ         125.0
#endif
#ifndef RF_SF
  #define RF_SF             8
#endif
#ifndef RF_CR
  #define RF_CR             5               // 4/5
#endif
#ifndef RF_TX_DBM
  #define RF_TX_DBM         7               // SX1262 max 22, SX1276 max 17
#endif
#ifndef RF_PREAMBLE_SYMS
  #define RF_PREAMBLE_SYMS  18              // RNode's LORA_PREAMBLE_SYMBOLS_MIN
#endif
// Duty-cycled receive: let the transceiver sleep between preamble samples
// instead of listening continuously. Off by default and deliberately so — a
// transport node's one job is to be listening, and the saving is worth having
// only where the channel makes the sleep long enough to be real. It is an
// SX1262-only mode (RadioCaps::Caps::rxDutyCycle) and at the shipped
// SF8/125 kHz channel it does not engage at all; docs/configuration.md gives
// the rule for when it does.
#ifndef RF_RX_DUTY_CYCLE
  #define RF_RX_DUTY_CYCLE  0
#endif
// 0x12 is the classic SX127x "private network" sync word; RadioLib
// translates it to the equivalent SX126x two-byte value (0x1424).
#ifndef RF_SYNCWORD
  #define RF_SYNCWORD       0x12
#endif
// T3-S3 SX1262 modules have a TCXO fed from DIO3. Set to 0.0 for
// plain-crystal modules (begin() fails with -706/-707 when this is wrong).
// Set by a board header carrying a 2.4 GHz module; see LoRaRadio::begin().
#ifndef RF_MODEM_SX1280
  #define RF_MODEM_SX1280   0
#endif
// Set by a board header carrying an LR1110. Declared rather than probed, for
// the same reason the SX1280 is and one more: this part will not receive or
// transmit at all until it is told how its antenna switch is wired, and that
// table is a fact about the board (LR11X0_RF_SWITCH_TABLE below). A probe that
// found the chip and stopped there would report a working radio that is deaf.
#ifndef RF_MODEM_LR1110
  #define RF_MODEM_LR1110   0
#endif

// Boards with a transmit/receive switch in front of the antenna name its pins;
// RadioLib steers them. Without one the radio is wired straight through.
#ifndef HAS_RF_SWITCH
  #define HAS_RF_SWITCH     0
#endif

// An amplified front end that has to be powered and steered before the radio
// can do anything (src/radio/LoRaFem.h). Distinct from HAS_RF_SWITCH, which is
// a bare transmit/receive switch RadioLib drives by itself, and from HAS_PA,
// which only says an amplifier is in the path.
#ifndef HAS_LORA_FEM
  #define HAS_LORA_FEM      0
#endif

// True where the board puts a power amplifier after the transceiver. It does
// not change what the chip may be driven at — the driver's own maximum still
// applies — but it does change what leaves the antenna, which is the operator's
// to account for. Reported through the API so the settings page can say so.
#ifndef HAS_PA
  #define HAS_PA            0
#endif

// A single timed transmission at boot, to prove the IRQ line is the one the
// board actually uses. Off everywhere it is not needed: it costs airtime.
//
// Where it is on, it runs once per firmware image rather than once per boot:
// the verdict is kept in NVS under RADIO_NVS_NAMESPACE, keyed to the running
// binary itself (the ELF SHA-256 in its application descriptor, not the
// version string it prints), so a node brown-out looping on a flat battery
// does not re-pay a transmission its own image has already made. A new image
// proves itself again — the pin map the test is about is the image's. See
// src/radio/RadioSelfTestPolicy.h.
//
// Its own namespace, and the key belongs with it: this is not a setting (a
// settings reset must not clear it) and it is not restart history either.
#ifndef RADIO_SELFTEST_ON_BOOT
  #define RADIO_SELFTEST_ON_BOOT 0
#endif
#define RADIO_NVS_NAMESPACE      "retimesh-rf"   // max 15 chars
#define RADIO_SELFTEST_NVS_KEY   "irq"

#ifndef RF_TCXO_VOLTAGE
  #define RF_TCXO_VOLTAGE   1.8
#endif
// The T3-S3 routes its RF switch from DIO2.
#ifndef RF_DIO2_AS_SWITCH
  #define RF_DIO2_AS_SWITCH true
#endif

// ---------------------------------------------------------------------------
// microSD on its own SPI bus. Boards without a slot set HAS_SD 0 and the
// whole driver compiles out.
// ---------------------------------------------------------------------------
#ifndef HAS_SD
  #define HAS_SD            1
#endif
#ifndef PIN_SD_MOSI
  #define PIN_SD_MOSI       11
#endif
#ifndef PIN_SD_MISO
  #define PIN_SD_MISO       2
#endif
#ifndef PIN_SD_SCK
  #define PIN_SD_SCK        14
#endif
#ifndef PIN_SD_CS
  #define PIN_SD_CS         13
#endif
// Which SPI host the card sits on. HSPI on every board that gives the slot
// wires of its own, which was every board until the T-Deck put the card, the
// panel and the radio on one bus and left no second host to put it on. A
// board that shares says so here; the driver reads it rather than assuming.
#ifndef SD_SPI_BUS
  #define SD_SPI_BUS        HSPI
#endif
#define SD_SPI_HZ           20000000
// How often the slot is looked at is no longer one number: it depends on what
// the last look found, and the ladder lives in sys/SdPollPolicy.h.
#define SD_PARTIAL_PERCENT  50            // volume < 50 % of the card => "partial"
#define SD_MOUNT_ATTEMPTS   6             // boot: the first mount after SPI init often fails
#define SD_MOUNT_RETRY_MS   100           // ~0.6 s of retries before giving up

// Web-layer snapshots of the Reticulum path table. Each row is read back
// through microStore (flash or SD), so this is deliberately unhurried.
#define SNAPSHOT_INTERVAL_MS  5000
#define SNAPSHOT_MAX_PATHS    64
// How often dead paths are swept out, which is a slower clock than the reading
// is refreshed on: the reading is capped and cheap, the sweep walks the whole
// table. It is also the ceiling the pass scheduler is held to — a pass carrying
// a minute's clock has to come round at least once a minute or that clock is
// not honoured at all (Rns::nextIntervalMs) — so the firmware and the host
// tests that drive that scheduler read the same figure from here rather than
// each writing 60000 out for itself.
#define SNAPSHOT_SWEEP_INTERVAL_MS 60000
#define SD_LOG_MAX_BYTES    (1024UL * 1024UL)

// ---------------------------------------------------------------------------
// Display — SSD1306 128x64 on I2C by default (0x3C; the board names the pins)
// ---------------------------------------------------------------------------
#ifndef HAS_DISPLAY
  #define HAS_DISPLAY       1
#endif

// What kind of glass, which is a different question from how big. The size
// decides the layout; the kind decides which driver is built and what an
// update costs — an e-paper panel of the same dimensions is not a slower
// OLED, it is a panel that has to be told how rarely it may be written.
// A board declares this in its own header; anything that does not say has
// the OLED every board so far has had.
#define DISPLAY_KIND_OLED   1
#define DISPLAY_KIND_EINK   2
// A colour TFT, which is neither of the others in the way that matters here:
// an update costs a burst of SPI rather than a kilobyte of I2C or a second of
// the panel's life, and the panel has a backlight — so "off" is a real state
// that saves real current, unlike an e-paper film that keeps its image.
#define DISPLAY_KIND_TFT    3
#ifndef DISPLAY_KIND
  #define DISPLAY_KIND      DISPLAY_KIND_OLED
#endif
// Which OLED controller, for a board whose DISPLAY_KIND is the OLED. Not the
// same question as the kind: both parts here are 128x64 monochrome panels on
// I2C, drawn with the same GFX calls, and they differ in how the buffer
// reaches the glass. The SH1106 has 132 columns of RAM with the panel wired to
// the middle 128 and no horizontal addressing mode, so the SSD1306's driver
// writes it two columns out of place and wraps the rest. The probe cannot tell
// them apart: an acknowledgement at whatever address the board names says a
// part is there and nothing about which controller it is. So the board says —
// both the controller here and the address in OLED_ADDR, which differs
// between boards and, on the T-Beam Supreme, is not the usual one.
#define OLED_CONTROLLER_SSD1306 1
#define OLED_CONTROLLER_SH1106  2
#ifndef OLED_CONTROLLER
  #define OLED_CONTROLLER   OLED_CONTROLLER_SSD1306
#endif
// The panel's pair, which a board with an OLED names in its own header. There
// is no default pair, and -1 is what "no such bus" reads as — I2cReg::mainBus()
// does not start a bus on pin -1 and hosts() does not list one. The default used to be 18/17, the T3-S3's
// pair, and the two boards that name none inherited it: the Wireless Bridge,
// which has no panel, and the Wireless Paper, whose panel is on SPI. Through
// PIN_I2C_* below that handed each a general bus on pins it uses for something
// else, and the first STATUS after boot scans that bus — on the Bridge, GPIO 18
// is the radio's chip select and GPIO 17 the D0WDQ6's PSRAM clock, and the scan
// panicked the node into a restart loop that came out of it with no PSRAM.
#ifndef PIN_OLED_SDA
  #define PIN_OLED_SDA      -1
#endif
#ifndef PIN_OLED_SCL
  #define PIN_OLED_SCL      -1
#endif
#if HAS_DISPLAY && DISPLAY_KIND == DISPLAY_KIND_OLED && (PIN_OLED_SDA < 0 || PIN_OLED_SCL < 0)
  #error "an OLED board must name its panel's pins (PIN_OLED_SDA/PIN_OLED_SCL) in its header; a board with no panel sets HAS_DISPLAY 0"
#endif
// The board's general-purpose I2C — the bus that carries whatever is not the
// panel: a charger, an accelerometer, a touch controller, a keyboard. Most
// boards here have no such bus and only the panel's, and on those the two
// names are the same pair of wires: one bus, named twice. Boards that route a
// second pair say so in their own header.
//
// Named unconditionally, and not only where something sits on it, because
// I2cReg::mainBus() is what starts it and that has to compile everywhere —
// including on the boards where nothing ever calls it.
#ifndef PIN_I2C_SDA
  #define PIN_I2C_SDA       PIN_OLED_SDA
#endif
#ifndef PIN_I2C_SCL
  #define PIN_I2C_SCL       PIN_OLED_SCL
#endif
// Nothing may start this bus on a pin the board has already given to something
// that dies when it is clocked: the radio's SPI and control lines, and on a
// classic ESP32 with PSRAM the PSRAM's chip select and clock — GPIO 16 and 17
// on the D0WD parts, read from the core's sdkconfig rather than restated here.
// Wire.begin() takes the pins over from whatever held them, so a clash is not
// a bus with nothing on it; it is the radio or the heap failing underneath a
// console command. Refused here, so a header that clashes does not compile.
#define RM_PIN_IS_RADIO(p) ((p) >= 0 && ((p) == PIN_LORA_SCK || (p) == PIN_LORA_MISO || \
    (p) == PIN_LORA_MOSI || (p) == PIN_LORA_CS || (p) == PIN_LORA_RST ||              \
    (p) == PIN_LORA_DIO0 || (p) == PIN_LORA_DIO1 || (p) == PIN_LORA_BUSY))
#if RM_PIN_IS_RADIO(PIN_I2C_SDA) || RM_PIN_IS_RADIO(PIN_I2C_SCL)
  #error "PIN_I2C_SDA/PIN_I2C_SCL name one of the radio's pins; a board with no general I2C bus leaves them -1"
#endif
#if defined(CONFIG_IDF_TARGET_ESP32) && defined(BOARD_HAS_PSRAM) && defined(CONFIG_D0WD_PSRAM_CLK_IO) && \
    (PIN_I2C_SDA == CONFIG_D0WD_PSRAM_CS_IO || PIN_I2C_SDA == CONFIG_D0WD_PSRAM_CLK_IO || \
     PIN_I2C_SCL == CONFIG_D0WD_PSRAM_CS_IO || PIN_I2C_SCL == CONFIG_D0WD_PSRAM_CLK_IO)
  #error "PIN_I2C_SDA/PIN_I2C_SCL name the PSRAM's chip select or clock (CONFIG_D0WD_PSRAM_CS_IO/CLK_IO)"
#endif
#undef RM_PIN_IS_RADIO
// Panels on a switched rail need it brought up before they are probed, and it
// is active low on every board that has one so far.
#ifndef HAS_DISPLAY_VEXT
  #define HAS_DISPLAY_VEXT  0
#endif
#ifndef PIN_OLED_RST
  #define PIN_OLED_RST      -1
#endif

#ifndef OLED_ADDR
  #define OLED_ADDR         0x3C
#endif
#ifndef OLED_ROTATION
  #define OLED_ROTATION     0               // 0..3, quarter turns
#endif
// Panel geometry. A board with a different panel says so here and everything
// downstream follows from it — see DisplayLayout.h, which turns these into the
// text grid, the chrome and the refresh interval each page is drawn against.
// An SSD1306 reports nothing about its own size, so the board is what knows.
#ifndef DISPLAY_WIDTH
  #define DISPLAY_WIDTH     128
#endif
#ifndef DISPLAY_HEIGHT
  #define DISPLAY_HEIGHT    64
#endif
// Panels too small for the full page set. A macro as well as the constexpr in
// DisplayLayout.h because the page enum itself has to change, not only what is
// drawn — a page that cannot work on this panel should not be in the cycle at
// all, costing a button press to reach and another to leave.
#if DISPLAY_WIDTH < 96
  #define DISPLAY_COMPACT   1
#else
  #define DISPLAY_COMPACT   0
#endif
// BOOT button (GPIO 0, active low) doubles as the display navigation key:
// short press = next page, long press = blank/wake the panel.
#ifndef PIN_BUTTON
  #define PIN_BUTTON        0
#endif
// A second button, where the case has one. Boards without it say nothing and
// everything that reads it compiles out.
#ifndef HAS_BUTTON2
  #define HAS_BUTTON2       0
#endif
#ifndef PIN_BUTTON2
  #define PIN_BUTTON2       -1
#endif
// A piezo sounder on a PWM channel, where one is fitted.
// What makes the sound. Two very different parts answer the same two events: a
// piezo on a PWM pin, and a speaker behind an I2S amplifier. A board names
// which it has — they share no pin, no peripheral and no way of being driven,
// so probing would be two drivers' worth of guessing to save a board one line.
#define BUZZER_KIND_PWM     1
#define BUZZER_KIND_I2S     2
#ifndef HAS_BUZZER
  #define HAS_BUZZER        0
#endif
#ifndef BUZZER_KIND
  #define BUZZER_KIND       BUZZER_KIND_PWM
#endif
// Whether the sounder starts switched on, which is decided by what it costs.
// A piezo is a PWM channel and a timer — free, so it ships on and the node
// keeps chirping as it always did. A speaker behind an I2S amplifier is a task
// and a DMA ring, about 5.4 KB of internal RAM, which on the board that has one
// is a quarter of what it has spare and enough to stop the portal serving. That
// ships off, and turning it on is a choice made knowing the trade.
// Task stacks that were guessed generously and have now been measured.
//
// Both were 8 KB, which is what you write when you do not know. What the
// console's STACKS command reports is the least each has ever had left, and on
// two boards over a day's use they never came close — but a high-water mark is
// "worst seen", never "worst possible", so these are cut with the margin the
// consequence deserves rather than to the observation.
//
// The card's poller: 1.6 KB used of 8 KB, and the biggest thing on its stack is
// the 512-byte sector it reads to notice a card being pulled. Its deepest path
// is not that, though — it is a format, which runs on this task and which
// nothing has exercised while anybody was measuring. FatFS takes its format
// work buffer from the heap (ff_memalloc, ffconf.h) so that part is not stack,
// but the call depth beneath it is unmeasured.
//
// And this stack has a history, recorded where it was raised: at 4 KB the FAT
// layer tripped the canary on core 0 — mount probes and a rename on log
// rotation, which are not what idles here and are exactly what a measurement
// taken while nothing is happening will miss. The probe path has been rewritten
// since and the figure today is 1.6 KB, but "it crashed at 4 KB once" outranks
// "it uses 1.6 KB this week": one is a bound, the other is a sample.
//
// So 6 KB, not the 4 the measurement alone would allow. Half as much again as
// the size that is known to have failed, nearly four times what has been seen,
// and it still gives 2 KB back. Getting this wrong costs somebody a corrupted
// card in the middle of formatting it.
#ifndef SD_TASK_STACK
  #define SD_TASK_STACK     6144
#endif
// The radio: 2.6 KB used of 8 KB. Worth knowing that the packet does not set
// this — the transmit frame is a member of LoRaRadio, not a local, so the size
// of a LoRa frame never lands on this stack. What lands on it is call depth:
// RadioLib, the SPI transaction under it, and the receive path pushing into the
// ring. That is not derivable the way a buffer is, so the margin is empirical:
// 6 KB leaves more spare than the whole of what has ever been used.
//
// It is also the stack that has moved. It read 1.7 KB used this morning and
// 2.6 KB by the evening on the same firmware, which is the argument for
// watching STACKS over a soak rather than trusting one afternoon's figure.
#ifndef RADIO_TASK_STACK
  #define RADIO_TASK_STACK  6144
#endif

#ifndef SOUND_ENABLED_DEFAULT
  #if BUZZER_KIND == BUZZER_KIND_I2S
    #define SOUND_ENABLED_DEFAULT 0
  #else
    #define SOUND_ENABLED_DEFAULT 1
  #endif
#endif
// Percent. Only the speaker can act on it: a piezo is driven at the one
// amplitude its PWM channel produces, so the setting is offered where it means
// something and refused where it does not.
#ifndef SOUND_VOLUME_DEFAULT
  #define SOUND_VOLUME_DEFAULT 40
#endif
// The I2S speaker's pins, meaningless on a PWM board.
#ifndef PIN_I2S_BCLK
  #define PIN_I2S_BCLK      -1
#endif
#ifndef PIN_I2S_LRCLK
  #define PIN_I2S_LRCLK     -1
#endif
#ifndef PIN_I2S_DOUT
  #define PIN_I2S_DOUT      -1
#endif
#ifndef PIN_BUZZER
  #define PIN_BUZZER        -1
#endif
// A capacitive touch layer over the panel. Two controllers are driven, and
// they are not alike enough to probe for: the CHSC6X holds one report and
// answers only while a finger is down, the GT911 is register-mapped and
// answers always. A board names which it carries.
// A clock the board keeps running for itself. Off unless a board says
// otherwise: a node without one counts from the epoch until its receiver has a
// fix, and every board here did that until the first one turned up carrying a
// PCF8563. The pins default to the board's general I2C, which is where such a
// part sits on every board that has one — it is a slow device with nothing to
// gain from a bus of its own.
#ifndef HAS_RTC
  #define HAS_RTC           0
#endif
#ifndef RTC_ADDR
  #define RTC_ADDR          0x51            // the PCF8563's, and it is not strappable
#endif
#ifndef PIN_RTC_SDA
  #define PIN_RTC_SDA       PIN_I2C_SDA
#endif
#ifndef PIN_RTC_SCL
  #define PIN_RTC_SCL       PIN_I2C_SCL
#endif

#define TOUCH_KIND_CHSC6X   1
#define TOUCH_KIND_GT911    2
#ifndef HAS_TOUCH
  #define HAS_TOUCH         0
#endif
#ifndef TOUCH_KIND
  #define TOUCH_KIND        TOUCH_KIND_CHSC6X
#endif
// Whether the controller already reports in the frame the panel is shown in.
// Most do not: they answer in the glass's own portrait coordinates and the
// shell turns each point the same way it turned the picture. One board's
// controller is configured for the mounted orientation and needs no turning at
// all, and turning it anyway sends every tap to a different corner — which
// looks exactly like a touch layer that is not working.
#ifndef TOUCH_PRE_ROTATED
  #define TOUCH_PRE_ROTATED 0
#endif
// Whether the controller counts a coordinate from the opposite edge to the
// panel. A mirrored axis is not a rotation and cannot be corrected by one: it
// puts every press at the reflection of the finger, so the top half of the
// glass presses the bottom half's controls and the middle very nearly works.
// It is also invisible without measuring, because the shell has no way to know
// where the finger really was.
#ifndef TOUCH_MIRROR_X
  #define TOUCH_MIRROR_X    0
#endif
#ifndef TOUCH_MIRROR_Y
  #define TOUCH_MIRROR_Y    0
#endif

// A physical keyboard, where the board has one. Not a matrix this firmware
// scans — on every board here it is a second microcontroller that scans it
// and answers on I2C, so what varies is the address and the bus, not the
// wiring. See src/ui/Keypad.h.
#ifndef HAS_KEYPAD
  #define HAS_KEYPAD        0
#endif
// How the controller answers. Two protocols, and no way to tell them apart
// safely by trying: a bare read against a register-addressed part returns
// whatever register its pointer happens to be sitting on.
//   BARE  — read one byte; it is the key, or zero for none.
//   REG8  — write the key register, repeated start, read one byte.
#define KEYPAD_KIND_BARE    1
#define KEYPAD_KIND_REG8    2
#ifndef KEYPAD_KIND
  #define KEYPAD_KIND       KEYPAD_KIND_BARE
#endif
#ifndef KEYPAD_ADDR
  #define KEYPAD_ADDR       0x55
#endif
#ifndef KEYPAD_KEY_REG
  #define KEYPAD_KEY_REG    0x01
#endif
// The rate the keyboard's own controller brings its slave up at, where that
// differs from the bus it shares. On a board where the keyboard has a bus to
// itself this is that bus's whole speed.
#ifndef KEYPAD_HZ
  #define KEYPAD_HZ         I2C_HZ
#endif
#ifndef PIN_KEYPAD_LED
  #define PIN_KEYPAD_LED    -1
#endif
#ifndef PIN_KEYPAD_SDA
  #define PIN_KEYPAD_SDA    PIN_I2C_SDA
#endif
#ifndef PIN_KEYPAD_SCL
  #define PIN_KEYPAD_SCL    PIN_I2C_SCL
#endif
#ifndef PIN_KEYPAD_INT
  #define PIN_KEYPAD_INT    -1
#endif

// A trackball: four direction lines, active low, one edge per detent. The
// click is PIN_BUTTON, because on the board that has one they are the same
// pin. Read in Keypad.cpp alongside the keyboard, since both are navigation.
#ifndef HAS_TRACKBALL
  #define HAS_TRACKBALL     0
#endif
#ifndef PIN_TRACKBALL_UP
  #define PIN_TRACKBALL_UP    -1
#endif
#ifndef PIN_TRACKBALL_DOWN
  #define PIN_TRACKBALL_DOWN  -1
#endif
#ifndef PIN_TRACKBALL_LEFT
  #define PIN_TRACKBALL_LEFT  -1
#endif
#ifndef PIN_TRACKBALL_RIGHT
  #define PIN_TRACKBALL_RIGHT -1
#endif

// How the panel's backlight is driven. A plain LED on a PWM channel on every
// board so far; the T-Deck puts a one-wire dimmer chip there instead, whose
// brightness is stepped by pulses rather than set by a duty cycle. See
// TftPanel.cpp — the difference is entirely inside applyBacklight().
#define BACKLIGHT_KIND_PWM     1
#define BACKLIGHT_KIND_AW9364  2
#ifndef BACKLIGHT_KIND
  #define BACKLIGHT_KIND    BACKLIGHT_KIND_PWM
#endif
// Whether the backlight lights when its pin is low. A board that sinks the
// LED's return through the transistor rather than driving its gate inverts the
// duty cycle, and nothing else about it changes.
#ifndef BACKLIGHT_ACTIVE_LOW
  #define BACKLIGHT_ACTIVE_LOW 0
#endif

// Which way up the board is held, in quarter turns, when nothing can tell.
// The colour shell turns the frame in the controller's MADCTL and a board with
// an accelerometer keeps that up to date; a board without one has no way to
// know and would otherwise sit at zero, which is the controller's portrait —
// wrong on any board whose glass is mounted landscape. So the board says how
// it is built and the shell starts there, and the accelerometer, where there
// is one, moves it from that starting point rather than to it.
#ifndef DISPLAY_ROTATION
  #define DISPLAY_ROTATION  0
#endif

// Whether the panel's glass is fitted inverted. On the colour boards so far it
// is, and the driver sent INVON unconditionally because of it — without which
// white came out black and a "dark" panel glowed. It is a property of how the
// glass is bonded rather than of the controller, so a board that is built the
// other way says so: sending INVON there turns a dark theme into a light one,
// which reads on the bench as wrong colours (white and yellow where the
// design is near-black and blue) and as text that has vanished into a
// background it no longer contrasts with.
#ifndef DISPLAY_INVERT
  #define DISPLAY_INVERT    1
#endif

// The main I2C bus rate. 400 kHz everywhere the parts on the bus allow it;
// a board whose slowest resident wants less says so, because the rate is a
// fact about the wire rather than about any one driver on it.
#ifndef I2C_HZ
  #define I2C_HZ            400000
#endif

// A load switch in front of the whole peripheral rail, where the board has
// one: the radio, the card, the panel and the buses are dead until it is
// driven. Not a PMU — there is no chip to talk to — so it is raised in
// setup() before anything touches a bus. See main.cpp.
#ifndef HAS_BOARD_POWER
  #define HAS_BOARD_POWER   0
#endif
#ifndef PIN_BOARD_POWER
  #define PIN_BOARD_POWER   -1
#endif
#ifndef BOARD_POWER_ACTIVE
  #define BOARD_POWER_ACTIVE HIGH
#endif
// How long the rail is given before anything behind it is addressed.
#ifndef BOARD_POWER_SETTLE_MS
  #define BOARD_POWER_SETTLE_MS 100
#endif

// Whether the transceiver, the panel and the card sit on one SPI bus. Where
// they do, their chip selects have to be idled together before any driver
// starts — see BoardInit.cpp for why that cannot be left to each driver's own
// begin(). Sharing is safe otherwise: the Arduino core's per-bus mutex is
// taken by beginTransaction, and no driver here attaches a hardware select.
#ifndef SPI_BUS_SHARED
  #define SPI_BUS_SHARED    0
#endif

// Boards that route the chip's own USB pins (GPIO 19/20 on an S3) to something
// else. The pad has to be released or it drives the pins alongside whatever the
// board put there — an I2C bus, in the case that brought this in. Only safe on
// a board whose console is a bridge rather than the chip's own USB, which is
// exactly the kind of board that needs the pins. See BoardInit.cpp.
#ifndef HAS_USB_PAD_CONFLICT
  #define HAS_USB_PAD_CONFLICT 0
#endif
// The backlight's floor, percent: below this a panel is dark while
// believing itself on, and going dark is the sleep timer's job. The funnel
// refuses less, the slider cannot ask for less, and the NVS load clamps —
// every door, one number.
#ifndef BRIGHTNESS_FLOOR_PCT
  #define BRIGHTNESS_FLOOR_PCT 5
#endif

// Whether the WiFi link starts enabled on a factory-fresh node. Headless
// field boards (no glass, battery-first) set 0 in their header: with the
// link off the WiFi driver is never started at all (WifiManager::begin),
// and the operator turns it on over USB or the console when wanted.
#ifndef WIFI_ENABLED_DEFAULT
  #define WIFI_ENABLED_DEFAULT 1
#endif
// A BQ25896 charge manager on the main I2C: honest charging state, and ship
// mode as the power-off the case's button undoes.
#ifndef HAS_BQ25896
  #define HAS_BQ25896       0
#endif
// An accelerometer on the main I2C: the panel follows the hand, and a board
// with a magnetometer beside it can say which way it is pointing rather than
// only which way is down. Two parts, named rather than probed for — they share
// no register, no chip id and no address, so a probe would be two drivers'
// worth of guessing to save a board one line.
#define IMU_KIND_DA217      1
#define IMU_KIND_QMI8658    2
#ifndef HAS_IMU
  #define HAS_IMU           0
#endif
#ifndef IMU_KIND
  #define IMU_KIND          IMU_KIND_DA217
#endif
#ifndef IMU_ADDR
  #define IMU_ADDR          0x6B          // the QMI8658's, SDO high; the DA217 is probed
#endif
// Which wires the part is on. The same QMI8658 turns up on I2C on one board
// and on SPI on the next — the T-Beam Supreme puts it on the card's bus with a
// select of its own — and that is a wiring fact, not a different part: the
// registers, the chip id and the configuration are identical either way, so
// only the three transport calls in Imu.cpp change.
#define IMU_TRANSPORT_I2C   1
#define IMU_TRANSPORT_SPI   2
#ifndef IMU_TRANSPORT
  #define IMU_TRANSPORT     IMU_TRANSPORT_I2C
#endif
// The select, and the bus it is on. The defaults are the card's because the
// one board that wires an SPI accelerometer shares the card's host with it —
// which is also why BoardInit idles this select before either driver starts. A
// board that wires them apart names its own three pins here, the way the
// shared-bus boards name the panel's and the card's (boards/tdeck.h).
#ifndef PIN_IMU_CS
  #define PIN_IMU_CS        -1
#endif
#ifndef IMU_SPI_BUS
  #define IMU_SPI_BUS       SD_SPI_BUS
#endif
#ifndef PIN_IMU_SCK
  #define PIN_IMU_SCK       PIN_SD_SCK
#endif
#ifndef PIN_IMU_MISO
  #define PIN_IMU_MISO      PIN_SD_MISO
#endif
#ifndef PIN_IMU_MOSI
  #define PIN_IMU_MOSI      PIN_SD_MOSI
#endif
// A select is the only thing that addresses a part on SPI, so a board that
// names the transport and not the pin has said nothing at all.
#if HAS_IMU && IMU_TRANSPORT == IMU_TRANSPORT_SPI && \
    (PIN_IMU_SCK < 0 || PIN_IMU_MISO < 0 || PIN_IMU_MOSI < 0)
  #error "an SPI accelerometer needs its three bus pins: the defaults are the card's, and this board has no card to borrow them from"
#endif
#if HAS_IMU && IMU_TRANSPORT == IMU_TRANSPORT_SPI && PIN_IMU_CS < 0
  #error "an SPI accelerometer needs PIN_IMU_CS — the select is what addresses it"
#endif
// The DA217 has no SPI interface at all, so this pairing is a board header
// that says two things which cannot both be true; caught here rather than in
// a driver that would quietly talk to nothing.
#if HAS_IMU && IMU_KIND == IMU_KIND_DA217 && IMU_TRANSPORT == IMU_TRANSPORT_SPI
  #error "the DA217 is an I2C part: IMU_KIND_DA217 with IMU_TRANSPORT_SPI cannot be right"
#endif
// How the part is soldered down relative to the panel. A board says this, not
// the driver: the same part turns up rotated or flipped on the next board, and
// a sign hidden in the driver would then be wrong for one of them with nothing
// naming which. Getting it wrong is visible rather than subtle — the panel
// rotates the correct amount the wrong way, so tipping the board on its side
// shows the picture upside down while the upright flips stay right.
// Whether the panel should follow the hand at all. Separate from owning an
// accelerometer, because they are separate facts: a handheld with a keyboard is
// meant to be held one way round, and turning its picture when it tips is a
// misfeature rather than a courtesy. Defaults to whether the board has the part,
// which is what every board did before the question could be asked.
#ifndef DISPLAY_AUTO_ROTATE
  #define DISPLAY_AUTO_ROTATE HAS_IMU
#endif
#ifndef IMU_INVERT_X
  #define IMU_INVERT_X      0
#endif
#ifndef IMU_INVERT_Y
  #define IMU_INVERT_Y      0
#endif
#ifndef IMU_INVERT_Z
  #define IMU_INVERT_Z      0
#endif
// A magnetometer, for the other half of a heading. Tilt correction wants an
// accelerometer, so a board that names this should name HAS_IMU too — a
// magnetometer on its own is only honest while the board is held level.
#ifndef HAS_COMPASS
  #define HAS_COMPASS       0
#endif
#ifndef COMPASS_ADDR
  #define COMPASS_ADDR      0x7C          // the QMC6309's, inside the reserved block
#endif
// Which of QST's magnetometers it is. They share a register map and disagree
// about the bits inside it and about the counts per microtesla, so the driver
// is one file and the numbers are two sets (src/sys/QmcMag.h). The default is
// the QMC6309, because that is the part the first board here carried and a
// board that says nothing should keep behaving as it did.
#define COMPASS_KIND_QMC6309 0
#define COMPASS_KIND_QMC6310 1
#ifndef COMPASS_KIND
  #define COMPASS_KIND      COMPASS_KIND_QMC6309
#endif
#if HAS_COMPASS && COMPASS_KIND != COMPASS_KIND_QMC6309 && \
                   COMPASS_KIND != COMPASS_KIND_QMC6310
  #error "COMPASS_KIND must be COMPASS_KIND_QMC6309 or COMPASS_KIND_QMC6310"
#endif
// Whether this board suspends its magnetometer when the glass goes dark.
//
// Stated as the behaviour and not as a claim about consumers, because the
// obvious claim would be false: **no board here displays a bearing.** Nothing
// in src/ui reads the compass, and its only readers on every board are the
// console and the status API. So the honest reading of the two values is:
//
//   1  the part sleeps with the screen. The ThinkNode M9's value, and it is
//      there because that is what the M9 has always done — a handheld on a
//      cell, blanking every twenty seconds, whose standby current with a
//      magnetometer converting at 200 Hz has never been measured. Changing it
//      is a power question with a bench answer, not a tidy-up, and a caller
//      polling /api/status on a dark M9 is told "asleep" (docs/api.md says so).
//   0  the part runs whatever the screen is doing. The T-Beam Supreme's value:
//      a mains-or-solar gateway with a fixed panel, where suspending would
//      hand "asleep" to every caller the compass has.
//
// Defaults to 1, so a board that says nothing keeps the shipped behaviour.
// PeripheralPolicy.h holds the rule this feeds; nothing in this file decides
// anything with it.
#ifndef COMPASS_FOLLOWS_SCREEN
  #define COMPASS_FOLLOWS_SCREEN 1
#endif
// A board with no glass cannot have a page that reads the heading, so the
// default would suspend its magnetometer for whatever the screen state of a
// screenless node is taken to be — and leave it there. Caught here rather than
// discovered as a compass that reports "asleep" for ever.
#if HAS_COMPASS && COMPASS_FOLLOWS_SCREEN && !HAS_DISPLAY
  #error "COMPASS_FOLLOWS_SCREEN on a board with no display: no page can read a \
heading there, so say COMPASS_FOLLOWS_SCREEN 0 and let the console and the API have it"
#endif

// The air around the node rather than the node: temperature, pressure and
// humidity from a BME280 where a board carries one. Named ENV rather than
// BME280 because the capability is the reading and not the part, the way
// HAS_IMU is; ENV_KIND names the part, and there is one.
//
// The address is strappable by SDO and both values are in the wild: 0x76 with
// it low, 0x77 with it high, and the T-Beam Supreme's is high. Not probed
// across the pair the way the accelerometer's is, because on that board 0x77
// is what the bus scan found and a probe that guesses is a probe that can pick
// a neighbour — this bus has three parts on it.
#define ENV_KIND_BME280     1
#ifndef HAS_ENV
  #define HAS_ENV           0
#endif
#ifndef ENV_KIND
  #define ENV_KIND          ENV_KIND_BME280
#endif
#ifndef ENV_ADDR
  #define ENV_ADDR          0x76
#endif
// A second address to try when the first does not answer, or -1 for a board
// that must not go looking. Off by default, and the default is the important
// half: the T-Beam Supreme knows its part is at 0x77 and says so, on a bus
// with three devices where a probe that wandered could pick a neighbour —
// which is the reasoning already written in that board's header, and this
// keeps it true by leaving probing switched off unless a board asks.
//
// A board asks when it genuinely does not know. The Heltec V4's sensor arrives
// on a plug-in module, so the SDO strap belongs to the module rather than to
// the board, and both values are in the wild. What makes the search safe there
// is that it is not a scan: exactly two addresses are tried, each one has to
// return a BME280's chip id (Bme280::identify) *and* give up a calibration
// block whose t1 is non-zero, and anything less is left off and named in the
// log rather than half-driven.
#ifndef ENV_ADDR_ALT
  #define ENV_ADDR_ALT      (-1)
#endif
// A second environmental part on the same bus, alongside the barometer.
//
// The Heltec V4's expansion carries a GXHT3V — a clone of Sensirion's SHTC3 —
// beside its BME280, and the two measure the same two quantities. Both are
// published rather than one being chosen here: two readings a little apart is
// the most useful thing that board can say about its own measurements, and a
// firmware that picked a winner would throw that away (Environment.h).
//
// Which family is not declared, only that there is one. The driver probes an
// SHTC3 at 0x70 first, because that is what the bench unit answers at, and
// then an SHT3x at 0x44 and 0x45 — so a different expansion module drops in
// without a build flag. Every candidate has to produce a checksummed reply
// before it is accepted (SensirionRhtMath.h), which is what keeps a probe at
// 0x70 from mistaking an I2C multiplexer for a sensor.
#ifndef HAS_ENV2
  #define HAS_ENV2          0
#endif
#ifndef PIN_ENV_SDA
  #define PIN_ENV_SDA       PIN_I2C_SDA
#endif
#ifndef PIN_ENV_SCL
  #define PIN_ENV_SCL       PIN_I2C_SCL
#endif
// One conversion every half minute. The air does not move faster than that in
// any way this reports on, the part sleeps in between, and the cadence is what
// keeps a shared bus quiet: the panel is on it, and the reading is worth
// nothing measured against a frame that did not draw.
#ifndef ENV_SAMPLE_MS
  #define ENV_SAMPLE_MS     30000
#endif

// Whether this board suspends its accelerometer when the glass goes dark, in
// the same shape as COMPASS_FOLLOWS_SCREEN above. Two things make it worth
// doing: a panel that turns itself from the part, and a magnetometer that
// needs gravity to level a heading *and is itself suspended with the screen* —
// that second clause is what makes the demand for gravity go dark too. A
// compass that keeps running with the glass off wants gravity with the glass
// off, so it holds the accelerometer up with it, which is why the derivation
// below reads the compass's fact rather than merely HAS_COMPASS.
#ifndef IMU_FOLLOWS_SCREEN
  #define IMU_FOLLOWS_SCREEN (DISPLAY_AUTO_ROTATE || \
                              (HAS_COMPASS && COMPASS_FOLLOWS_SCREEN))
#endif
// The LVGL shell on colour boards: set by the env, because it is a build
// decision (the toolkit is a library dependency), not a board fact.
#ifndef HAS_LVGL_UI
  #define HAS_LVGL_UI       0
#endif
// Boards that wire an indicator LED name it here. Nothing drives it yet; it is
// claimed at boot and held off so the pin is not left floating.
// LEDs, where the board has them (Leds.h): -1 for none. Boards whose LEDs
// light on LOW say so with LED_ACTIVE_HIGH 0.
#ifndef PIN_STATUS_LED
  #define PIN_STATUS_LED    -1
#endif
#ifndef PIN_WIFI_LED
  #define PIN_WIFI_LED      -1
#endif
#ifndef PIN_LORA_LED
  #define PIN_LORA_LED      -1
#endif
#ifndef PIN_BLE_LED
  #define PIN_BLE_LED       -1               // a lamp labelled for Bluetooth: claimed, kept dark
#endif
#ifndef LED_ACTIVE_HIGH
  #define LED_ACTIVE_HIGH   1
#endif
#define BUTTON_POLL_MS      20
#define BUTTON_LONG_MS      1500
#define DISPLAY_PAGE_TIMEOUT_MS 30000     // back to the status page when idle
#define DISPLAY_SLEEP_MS    60000         // panel off after this much button inactivity

// How long a subscribed task may go without reporting progress before the
// watchdog resets the node (Watchdog.h). One timeout covers every task, so it
// clears the slowest honest pass by a wide margin rather than being tuned to
// catch a hang quickly: an e-paper full refresh is seconds, and a Reticulum
// pass that writes its store and verifies a signature is seconds. Thirty is
// far above both and far below the hours a hung node would otherwise sit
// there. A card format is longer than any timeout worth having and is handled
// by Watchdog::pause() instead.
#ifndef WATCHDOG_TIMEOUT_S
  #define WATCHDOG_TIMEOUT_S  30
#endif

// How many times a node restarts itself trying to start a task it cannot run
// without, before it gives up and stays up degraded. Restarting is usually
// enough — the stack that failed is a contiguous block and a fresh heap has
// one — but a board that genuinely cannot fit it must not spend its life
// rebooting: a node that is up and half-working can still be reached and told
// something, and one in a boot loop cannot.
#ifndef REQUIRED_TASK_RETRIES
  #define REQUIRED_TASK_RETRIES  3
#endif

// ---------------------------------------------------------------------------
// Beacons / neighbour discovery (see LoRaRadio.h). Interval in seconds,
// 0 disables. Matches RNS's RNodeInterface `id_interval` semantics closely
// enough that an RNode's `id_callsign` shows up in our neighbour table.
// ---------------------------------------------------------------------------
#ifndef BEACON_INTERVAL_S
  #define BEACON_INTERVAL_S 0             // off by default: announces do this job
#endif
// Reticulum announces of this node's lxmf.delivery and nomadnetwork.node
// destinations, in seconds (0 = off). Sent on LoRa and to Wi-Fi clients; on
// boot as well. retimesh.node exists but is not announced (RnsTransport.cpp).
#ifndef ANNOUNCE_INTERVAL_S
  #define ANNOUNCE_INTERVAL_S 600
#endif
#define ANNOUNCE_BOOT_DELAY_MS 6000
// A neighbour that has just appeared knows nothing about this node, and the
// periodic announce can be a whole announce_interval away — ten minutes by
// default, which reads as a dead node. Announce shortly after one registers,
// with enough of a gap that a handful arriving together share one announce.
#define ANNOUNCE_ON_PEER_DELAY_MS 2000
#define ANNOUNCE_MAX_LEN    256
#define BEACON_MAX_LEN      64            // printable payload bytes
// RetiMesh beacons are valid Reticulum packets: a broadcast to the PLAIN
// destination "retimesh.beacon" (hash = RNS.Destination.hash(None,
// "retimesh", "beacon")). RNS peers accept and silently drop them
// instead of counting a protocol violation, and any RNS program that
// registers that destination receives them. Header = flags, hops, hash,
// context = 19 bytes, followed by the printable beacon text.
#define RNS_BEACON_FLAGS    0x08          // header type 1, broadcast, PLAIN, DATA
#define RNS_BEACON_HDR_LEN  19
#define RNS_BEACON_DEST_HASH { 0xC8, 0x03, 0xD3, 0x5E, 0x39, 0xD0, 0xAA, 0x7A, \
                               0xCD, 0xE2, 0x21, 0xBB, 0x16, 0x7F, 0x05, 0x3E }
#define BEACON_HELLO_DELAY_MS 3000        // boot probe
#define MAX_NEIGHBORS       16
#define NEIGHBOR_STALE_MS   (3UL * 60UL * 1000UL)

// ---------------------------------------------------------------------------
// Power / battery. Boards with a power-management chip (HAS_PMU) read the
// cell through it; the rest use an ADC divider (HAS_BATTERY_ADC).
// ---------------------------------------------------------------------------
#ifndef HAS_PMU
  #define HAS_PMU           0
#endif
#ifndef HAS_GPS
  #define HAS_GPS           0
#endif
// Optional receiver control lines, -1 where a board has none — the same
// convention the battery divider's enable uses, so every optional pin in the
// tree is expressed one way.
#ifndef PIN_GPS_EN
  #define PIN_GPS_EN        -1
#endif
#ifndef GPS_EN_ACTIVE
  #define GPS_EN_ACTIVE     LOW
#endif
#ifndef PIN_GPS_RST
  #define PIN_GPS_RST       -1
#endif
// Which level holds the receiver in reset. Low on every module here so far —
// the line is /RST and releasing it means driving it high, which is what the
// driver did unconditionally. One board wires the opposite sense, and there
// driving it high is not "released", it is "held in reset for ever": the
// receiver is powered, the UART is open and not one sentence arrives.
#ifndef GPS_RST_ACTIVE
  #define GPS_RST_ACTIVE    LOW
#endif
#ifndef PIN_GPS_STANDBY
  #define PIN_GPS_STANDBY   -1
#endif
// Whether the receiver on this board speaks u-blox's binary protocol. Only
// u-blox parts do, and this tree carries three makes: a u-blox MIA-M10Q on the
// T-Deck Plus and a u-blox NEO-6M/8M on the T-Beam, against a Quectel L76K on
// the Heltec V4's expansion kit and an ATGM336H on the ThinkNode M9. Sending a
// UBX frame to either of the last two is sending a Quectel or a CASIC part a
// message it has never heard of, so this is a per-board fact and not a default
// to be optimistic about.
#ifndef GPS_UBX
  #define GPS_UBX           0
#endif

// How this board's receiver is asked to nap, resolved once here rather than
// re-derived from three pin macros wherever the question comes up.
//
// The order is by what costs least and risks least, not by what is most
// interesting. A standby line is a pin write to a part designed for exactly
// this and is the same gesture on either module that has one. A switched rail
// is a real cut and the T-Beam's PMU already does it — its receiver keeps its
// almanac on the board's backup cell, so a wake is still a warm start. A UBX
// message is last because it is the one that can be silently ignored, and it
// is reached only where nothing else exists: the T-Deck Plus has no enable
// line, no standby line and no switched rail, so its receiver's own protocol
// is the only off-switch on that board.
//
// GPS_NAP_NONE is not a failure. It means the duty policy still runs and still
// decides, and the driver simply has nothing to send — which is the honest
// state for a board whose receiver is hard-wired on.
#define GPS_NAP_NONE        0
#define GPS_NAP_STANDBY     1
#define GPS_NAP_RAIL        2
#define GPS_NAP_PMREQ       3
#ifndef GPS_NAP
  #if !HAS_GPS
    #define GPS_NAP         GPS_NAP_NONE
  #elif PIN_GPS_STANDBY >= 0
    #define GPS_NAP         GPS_NAP_STANDBY
  #elif HAS_PMU
    #define GPS_NAP         GPS_NAP_RAIL
  #elif GPS_UBX
    #define GPS_NAP         GPS_NAP_PMREQ
  #else
    #define GPS_NAP         GPS_NAP_NONE
  #endif
#endif
#ifndef HAS_BATTERY_ADC
  #define HAS_BATTERY_ADC   1
#endif
// One battery reader per board: Power.cpp reads through the PMU when there is
// one, but its shared sample gate would be primed by the ADC path's begin(),
// leaving the PMU cache unread for the first interval — a PMU board must set
// HAS_BATTERY_ADC to 0 (the default is 1).
#if HAS_PMU && HAS_BATTERY_ADC
  #error "HAS_PMU and HAS_BATTERY_ADC are mutually exclusive: the PMU is the battery reader; set HAS_BATTERY_ADC 0"
#endif
#ifndef BOARD_NAME
  #define BOARD_NAME        "unknown board"
#endif
#ifndef PIN_BATTERY_ADC
  #define PIN_BATTERY_ADC   1
#endif
// How much current the PMU may draw from VBUS. This caps what is left for the
// cell once the running node has taken its 120-250 mA, so a low ceiling is why
// a flat cell gains slowly. It stays at 500 mA because that is all an unknown
// USB source is obliged to supply, and drawing more can brown out a laptop
// port. A board or build that knows its supply can raise it — AXP2101 steps
// are 500, 900, 1000, 1500 and 2000 mA; an AXP192 tops out at 500. The input
// *voltage* limit is set alongside it either way, so the chip throttles itself
// if the supply turns out to be weaker than the ceiling allows.
#ifndef PMU_VBUS_LIMIT_MA
  #define PMU_VBUS_LIMIT_MA 500
#endif

// Which of the chip's regulators feed what. A rail is a wiring fact rather
// than a chip fact: two boards here carry the same AXP2101 and route it
// differently — the T-Beam hangs the transceiver off ALDO2 and the receiver
// off ALDO3, the T-Beam Supreme hangs the transceiver off ALDO3 and the
// receiver off ALDO4 — so applying one board's map to the other powers a
// sensor rail and leaves the radio dark, which reads on the bench as a
// transceiver that is not fitted. These were literals in Pmu.cpp when one
// board had a PMU; the defaults are that board's, so it is unchanged.
//
// PMU_RAIL_NONE is a rail the board does not have. It is deliberately outside
// XPowersPowerChannel_t: a rail nobody names is left exactly as the chip
// powered up, which is the difference between "we do not switch the card's
// supply" and "we switch it off".
//
// The AXP192 (T-Beam v1.1) keeps its own names in Pmu.cpp. It is a different
// part with a different set of regulators, and one board carries it.
#define PMU_RAIL_NONE       0xFF
#ifndef PMU_RAIL_RADIO
  #define PMU_RAIL_RADIO    XPOWERS_ALDO2
#endif
#ifndef PMU_RAIL_GPS
  #define PMU_RAIL_GPS      XPOWERS_ALDO3
#endif
#ifndef PMU_RAIL_DISPLAY
  #define PMU_RAIL_DISPLAY  XPOWERS_DCDC1
#endif
// The rails no board needed until one arrived with them: the I2C sensors and
// the clock on one, the card slot on another, and the socket a plug-in radio
// module sits in on a third. Absent unless a board names them.
#ifndef PMU_RAIL_SENSORS
  #define PMU_RAIL_SENSORS  PMU_RAIL_NONE
#endif
#ifndef PMU_RAIL_CARD
  #define PMU_RAIL_CARD     PMU_RAIL_NONE
#endif
#ifndef PMU_RAIL_MODULE
  #define PMU_RAIL_MODULE   PMU_RAIL_NONE
#endif

// Boards halve the cell into the ADC unless they say otherwise; one that
// divides deeper says so, and says at what attenuation the result is readable.
#ifndef BATTERY_DIVIDER_RATIO
  #define BATTERY_DIVIDER_RATIO 2.0f
#endif
// The enable line for a divider that is only connected while it is held. A
// board without one reads a divider that is always there; a board with one
// that is not driven reads a plausible number that is not the battery.
#ifndef PIN_BATTERY_ADC_EN
  #define PIN_BATTERY_ADC_EN  -1
#endif
#ifndef BATTERY_ADC_EN_ACTIVE
  #define BATTERY_ADC_EN_ACTIVE HIGH
#endif
// 11 dB reads to about 3.1 V, which suits a divider that halves. A deeper one
// needs less attenuation to keep the reading in range.
#ifndef BATTERY_ADC_ATTEN
  #define BATTERY_ADC_ATTEN   ADC_11db
#endif
#define BATTERY_MIN_V       3.0f            // below: no cell attached (USB bench)
#define BATTERY_MAX_V       4.35f
#define BATTERY_SAMPLE_MS   10000
// How long a held reading stays believable once the converter stops answering.
// The divider on some boards is an ADC2 pin, which loses arbitration to the
// radio and the Wi-Fi stack now and then, so a missed sample is ordinary and
// keeping the last figure is right. A converter that has answered nothing for
// minutes is a different thing, and the node then has no idea what the cell is
// doing — which is worth saying rather than covering with the last number it
// happened to see. Comfortably longer than any contention, far shorter than a
// cell takes to discharge.
#define BATTERY_STALE_MS    300000          // five minutes
#define DISPLAY_SLEEP_BATTERY_MS 20000

// ---------------------------------------------------------------------------
// Optional manual cap on the hourly transmit budget, in whole percent. The
// allowance normally comes from the sub-band the channel sits in (Airtime.h
// carries the EU 863-870 plan), and this only ever tightens it further; 0
// means "whatever the band allows". It is the operator's own limit for a
// channel outside that plan, where the local rules are theirs to know.
#ifndef RF_DUTY_CYCLE_PCT
  #define RF_DUTY_CYCLE_PCT 0
#endif

// CSMA: DIFS + a contention window sized from recent channel use, as in
// RNode. The slot length and window bands come from Airtime.h.
// ---------------------------------------------------------------------------
#define CSMA_MAX_WAIT_MS    5000            // give up deferring after this
#define CSMA_CAD_RETRY_MS   50              // pause between channel probes

// ---------------------------------------------------------------------------
// PSRAM. The core routes only malloc() > 4 KB to PSRAM by default; almost
// nothing here is that large, so internal RAM fills up while 2 MB sit idle.
// Allocations above this threshold prefer PSRAM instead (ISR code never
// allocates, so it is safe); ring buffer storage goes there explicitly.
// ---------------------------------------------------------------------------
#ifndef PSRAM_MALLOC_THRESHOLD
  #define PSRAM_MALLOC_THRESHOLD 128      // measured: 512 B -> +28 KB internal, 128 B -> +42 KB
#endif

// ---------------------------------------------------------------------------
// Ring buffers bridging TCP <-> LoRa (created in main.cpp)
//
// Storage goes to PSRAM where the board has any and to internal RAM where it
// does not, which makes the size two different questions rather than one: 24 KB
// is nothing out of two megabytes of PSRAM, and it is more than a tenth of
// everything a Heltec Wireless Stick has. Measured, once the boot log started
// billing each subsystem (Diag.h): 26916 B on the Stick, 26124 B on a Heltec
// V3, on boards that finish booting with 4.5 KB and 51 KB respectively.
//
// Each ring holds whole RNS packets — NOSPLIT, RNS_MTU 500 plus framing — so
// 8192 B is about sixteen packets and 4096 B about eight. Eight is seconds of
// backlog at LoRa speeds, by which time a packet is stale and the sender has
// given up on it anyway; the value is here rather than inline so a board that
// wants another can say so in platformio.ini. A ring that turns out to be too
// small says so instead of hiding it: the send fails, "LoRa TX ring full" is
// logged, and lora_rx_drop_ring counts it in /api/status.
// ---------------------------------------------------------------------------
#ifndef RING_BYTES
  #ifdef BOARD_HAS_PSRAM
    #define RING_BYTES      8192
  #else
    #define RING_BYTES      4096
  #endif
#endif
#define TX_RING_BYTES       RING_BYTES        // TCP  -> LoRa direction
#define RX_RING_BYTES       RING_BYTES        // LoRa -> TCP  direction
#define TCP_IN_RING_BYTES   RING_BYTES        // TCP clients + AutoInterface -> Transport

// ---------------------------------------------------------------------------
// Bulletin board
// ---------------------------------------------------------------------------
#define BOARD_FILE          "/board.json"
#define BOARD_MAX_POSTS     50
#define BOARD_MAX_TEXT      280
#define BOARD_MAX_AUTHOR    32

// ---------------------------------------------------------------------------
// Shared runtime stats (single writer per field, plain volatile is enough)
// ---------------------------------------------------------------------------
struct NodeStats {
  volatile bool     radioOnline   = false;
  volatile bool     transportOnline = false;
  const char*       radioModel    = "none"; // "SX1262" / "SX1276" once probed
  volatile bool     displayPresent = false;
  volatile int16_t  radioApplyError = 0;   // last RadioLib error applying settings
  volatile uint32_t beaconsTx     = 0;
  volatile uint32_t beaconsRx     = 0;
  volatile uint32_t announcesTx   = 0;
  volatile uint32_t announcesRx   = 0;    // verified announces heard (any side)
  volatile uint32_t heapMinFree   = 0;    // lowest free internal heap seen (soak monitoring)
  volatile uint32_t psramFree     = 0;
  volatile float    lastRssi      = 0.0f;   // dBm, last LoRa RX
  volatile float    lastSnr       = 0.0f;   // dB,  last LoRa RX
  volatile uint32_t loraRxPackets = 0;      // reassembled RNS packets
  volatile uint32_t loraTxPackets = 0;
  // Channel use, maintained by the radio task (see Airtime.h)
  volatile float    airtimeShort  = 0.0f;   // 0..1 over the last two minutes
  volatile float    airtimeLong   = 0.0f;   // 0..1 over the rolling hour
  volatile float    dutyBudget    = 0.0f;   // 0..1+ of the hourly allowance
  volatile bool     dutyLocked    = false;  // transmissions held back
  volatile uint32_t dutyRetryS    = 0;      // seconds until the budget frees up
  volatile uint16_t dutyLimitBp   = 0;      // enforced allowance in basis points, 100 = 1 %
  volatile uint16_t csmaSlotMs    = 0;
  volatile uint8_t  csmaBand      = 1;      // contention window band, 1..4
  // Duty-cycled receive as it would actually behave, not as the switch reads.
  // The driver falls back to a continuous receive without saying so whenever
  // the computed sleep is too short to be worth the wake-up, so the setting
  // alone answers nothing (Airtime.h). Written by the radio task whenever the
  // channel is applied.
  volatile uint32_t rxDutyCycleSleepUs = 0;    // per cycle; 0 = the receiver never sleeps
  volatile bool     rxDutyCycleEngages = false;// setting, chip and channel all agree
  // The same question with the switch left out: would this chip on this channel
  // sleep, if it were asked to? Published beside the one above because their
  // false branches mean different things and a surface that has only the first
  // cannot tell them apart — every node ships with the setting off, so a hint
  // built on rxDutyCycleEngages alone would tell an SX1262 at SF10/125 kHz that
  // the channel was hopeless when in fact the switch is the only thing missing.
  volatile bool     rxDutyCycleWouldEngage = false;
  // ...and whether the mode is actually running, which is neither of the above.
  // Published as a fact rather than left to a sentence in docs/ because a
  // release that reports a saving it is not making is exactly the failure this
  // whole block exists to prevent, and prose is not something the API can echo.
  volatile bool     rxDutyCycleArmed   = false;
  // Where receptions go when they do not become a packet. One counter for all
  // of them told us a node was losing 94 % of its receptions but not why, and
  // the causes have nothing to do with each other: a full ring means the
  // consumer fell behind, a reassembly overflow means the fragments were
  // wrong, a CRC error means the air was noisy.
  //
  // These do NOT sum to everything heard on their own. A frame is either
  // rejected before decoding (loraRxCrcErrors, loraRxBadLength), consumed as
  // one fragment of a reassembly still in progress, or it completes a packet —
  // and a completed packet lands in loraRxPackets, in beaconsRx when it turns
  // out to be a beacon or an RNode station ID, or in loraRxDropRing when the
  // consumer could not take it. loraRxDropPartial counts reassemblies given up
  // before they completed. Note the units differ: the first two count frames,
  // the rest count packets, because a split packet arrives as two frames.
  volatile uint32_t loraRxDropRing    = 0;  // RX ring full: the RNS task fell behind
  volatile uint32_t loraRxDropReasm   = 0;  // second fragment did not fit the buffer
  volatile uint32_t loraRxDropPartial = 0;  // half-assembled packet abandoned mid-flight
  volatile uint32_t loraRxCrcErrors   = 0;  // readData() refused it: bad CRC or spurious IRQ
  volatile uint32_t loraRxBadLength   = 0;  // frame shorter than a header or longer than the max
  volatile uint32_t loraRxSpuriousIrq = 0;  // woken with no completed reception to collect
  // Not one of the six above it, whatever the neighbours suggest: nothing is
  // lost when this moves. The RNS task takes frames off the RX ring a bounded
  // batch at a time (RingDrain.h) and what a batch leaves stays in the ring for
  // the next pass, so this counts passes rather than frames. It rises when
  // frames arrived faster than one pass could take them — the pass after a
  // full-budget path-table walk is the case to expect, since two drains can be
  // 400 ms apart rather than 10.
  //
  // The walk, not the sweep: the budget covers the whole pass now, the rows
  // included, so the gap is any pass the budget ends and not only one that was
  // cleaning up. On a table too big to read in one pass that is most passes,
  // for as long as the table stays that big, so a total that climbs steadily is
  // this node getting round its own table rather than a channel fault —
  // RnsTransport.h's snapBudgetStops is what tells the two apart. Real loss on
  // this path is loraRxDropRing above, which is what the producer counts when
  // the ring has no room left.
  volatile uint32_t loraRxDrainCapped = 0;  // passes the batch cap ended with more queued
  // The other half of the radio's health, on the transmit side. A carrier-sense
  // probe that never reports is read as a busy channel — the only safe reading
  // of a medium nobody measured — so the fault is silent by construction: the
  // node stays online, keeps its rx/tx counts and its airtime, and simply waits
  // the whole CSMA deferral before every packet while transmitting without ever
  // having measured the air. These two are what that failure looks like from
  // outside. Both are zero on a healthy node whatever the traffic.
  volatile uint32_t loraCadTimeouts   = 0;  // scan armed, no verdict before its deadline
  volatile uint32_t loraCadArmErrors  = 0;  // the driver refused to start the scan at all
  volatile uint32_t tcpRxPackets  = 0;      // deframed packets from clients
  volatile uint32_t tcpClients    = 0;
  // The inbound TCP ring's "we fell behind" — and unlike the drop counters
  // above it, nothing is lost when it moves, which is why it is not called a
  // drop. The RNS task drains that ring a bounded batch at a time
  // (RingDrain.h) and what the batch leaves goes on the next pass, so this
  // counts passes rather than packets: a rising figure means a client is
  // sending faster than this node can route, not that anything was thrown
  // away. It is here because the cap is also what hides the condition — it is
  // what keeps a flood from reaching the watchdog, so without this a node
  // being outrun would only get slower and say nothing.
  volatile uint32_t tcpDrainCapped = 0;     // passes the batch cap ended with more queued
};

// Restart into the application or the bootloader: the delay before the
// quiesce step, chosen so the HTTP reply or console acknowledgement has left
// the network stack. A settings save that follows with a restart uses the
// longer figure the settings page always waited.
#define RESTART_ACK_DELAY_MS      600
#define RESTART_SETTINGS_DELAY_MS 1500

extern NodeStats g_stats;