tuning_config.h

Go to the documentation of this file.

#pragma once
 
/// @file tuning_config.h
/// @brief Runtime tuning configuration for pairing and radio diagnostics.
/// @ingroup hioc_tuning
///
/// Provides a centralized, non-persistent tuning layer used by the hub and radio
/// drivers. The `TuningConfig` struct carries all tunable parameters and helpers
/// for logging and applying defaults.
 
#include "proto_frame.h"
#include "proto_timing.h"
 
#include <cstddef>
#include <cstdint>
#include <optional>
#include <string>
#include <vector>
 
namespace esphome {
namespace home_io_control {
 
/// @brief Valid SX1262 RX bandwidth options (kHz register values).
///
/// The numeric values are the register-encoded (double-sideband) bandwidth selectors used by
/// `RadioSX1262::set_rx_bandwidth()` — a regular (mantissa, exponent) grid, with the bandwidth
/// roughly doubling per group.
///
/// Semtech's sizing rule for GFSK is `BW_DSB >= bitrate + 2 * Fdev + carrier offset`, which is
/// 76.8 kHz for the IO-Homecontrol waveform (38.4 kbps, 19.2 kHz deviation) before any offset.
/// The SX1262 has no AFC in GFSK mode, so this filter alone has to absorb the peer's carrier
/// offset. These values are not comparable to `SX1276RxBandwidth`, whose values are
/// single-sideband.
///
/// Byte-for-byte identical to `LR1121RxBandwidth` below, since both chips share the same Semtech
/// GFSK bandwidth grid; the `Sx1262AndLr1121BandwidthTablesAgree` test pins that. If these two
/// tables ever need to diverge for a real chip difference, say why here.
enum class SX1262RxBandwidth : uint8_t {
  BW_39_0_KHZ = 0x1C,   ///< 39.0 kHz — narrowest; half the 76.8 kHz sizing floor, for probing only.
  BW_46_9_KHZ = 0x14,   ///< 46.9 kHz — narrow.
  BW_58_6_KHZ = 0x0C,   ///< 58.6 kHz — default; the narrowest value validated on real hardware here.
  BW_78_2_KHZ = 0x1B,   ///< 78.2 kHz — just above the 76.8 kHz sizing floor.
  BW_117_3_KHZ = 0x0B,  ///< 117.3 kHz — clears the sizing floor with ~20 kHz of offset margin.
  BW_156_2_KHZ = 0x1A,  ///< 156.2 kHz — the value a Somfy LightVar_Wh_io dimmer needs.
  BW_187_2_KHZ = 0x12,  ///< 187.2 kHz — widest selectable option.
};
 
/// @brief Valid SX1276 RX bandwidth options (RegRxBw register bytes).
///
/// The numeric values are the SX1276 RegRxBw encodings (RxBwMant in bits[4:3], RxBwExp in
/// bits[2:0]) written verbatim to both REG_RX_BW and REG_AFC_BW. Single-sideband bandwidth =
/// FXOSC / (RxBwMant * 2^(RxBwExp+2)) with FXOSC = 32 MHz; the filter's total (double-sideband)
/// width is twice that, so the 41.7 kHz default spans 83.4 kHz — just above the 76.8 kHz sizing
/// floor for this waveform. The SX1276's AFC re-centres the receiver on each packet's carrier.
/// Narrower rejects more out-of-band noise (higher sensitivity); wider tolerates more LO
/// frequency offset.
enum class SX1276RxBandwidth : uint8_t {
  BW_20_8_KHZ = 0x14,   ///< 20.8 kHz — narrowest; maximal noise rejection, least LO-offset tolerance.
  BW_41_7_KHZ = 0x13,   ///< 41.7 kHz — default (validated against real devices).
  BW_62_5_KHZ = 0x03,   ///< 62.5 kHz.
  BW_83_3_KHZ = 0x12,   ///< 83.3 kHz.
  BW_125_0_KHZ = 0x02,  ///< 125.0 kHz — widest selectable option.
};
 
/// @brief Valid LR1121 RX bandwidth options (register values).
///
/// Byte-for-byte identical to `SX1262RxBandwidth` — both chips use the same Semtech GFSK
/// bandwidth grid — and kept as a distinct enum only so each driver's options can diverge if a
/// future chip's table does. See `Sx1262AndLr1121BandwidthTablesAgree`, which pins the two tables
/// together; if they ever need to differ for a real chip difference, say why here.
enum class LR1121RxBandwidth : uint8_t {
  BW_39_0_KHZ = 0x1C,   ///< 39.0 kHz — narrowest; half the 76.8 kHz sizing floor, for probing only.
  BW_46_9_KHZ = 0x14,   ///< 46.9 kHz — narrow.
  BW_58_6_KHZ = 0x0C,   ///< 58.6 kHz.
  BW_78_2_KHZ = 0x1B,   ///< 78.2 kHz.
  BW_117_3_KHZ = 0x0B,  ///< 117.3 kHz — default.
  BW_156_2_KHZ = 0x1A,  ///< 156.2 kHz — wider tolerance for peer carrier offset.
  BW_187_2_KHZ = 0x12,  ///< 187.2 kHz — widest selectable option.
};
 
/// @brief Which power classes scan_paired_devices() calls.
///
/// The roll-call calls both classes by default; this narrows it for bisecting an installation
/// in the field (does a device answer the low-power call but not the always-alive one, or vice
/// versa?) or for restoring the shorter single-pass scan on an install with no solar/battery
/// devices. Values mirror `power_save_mode_name()` (proto_constants.h) so the report, this
/// tunable, and a responder's own self-reported power-save byte share one vocabulary.
enum class ScanPowerClasses : uint8_t {
  BOTH,          ///< Low-power pass, then always-alive pass (default).
  ALWAYS_ALIVE,  ///< Always-alive pass only: the single-shape roll-call, ~6 s.
  LOW_POWER,     ///< Low-power pass only.
};
 
/// @brief Whether and how PairingEngine sends CMD_DISCOVER_CONFIRM (0x2C) to a freshly-discovered
/// device before proceeding to the key exchange (0x31).
///
/// Every real controller in this project's corpus sends 0x2C between the device's 0x29 and its
/// own 0x31. An enum, not a bool reusing `pairing_discovery_ack_capable`: that knob's contract is
/// scoped to the discovery broadcast only (see its own doc), and `skip`/`send`/`send_with_ack`
/// avoid `on`/`off`, which YAML 1.1 would otherwise turn into booleans. The step never fails a
/// pairing attempt in any mode — see PairingEngine::run_discover_confirm_step_()'s doc.
enum class DiscoverConfirmMode : uint8_t {
  SKIP,           ///< Kill switch: sends no 0x2C and applies no post-step pause.
  SEND,           ///< Default. Sends 0x2C with CTRL1_ACK clear either way — `0x00` to an
                  ///< always-alive target, `0x20` (CTRL1_LOW_POWER only) to a low-power one. It is
                  ///< CTRL1_LOW_POWER, not CTRL1_ACK, that follows the target's power class — see
                  ///< create_discover_confirm()'s `ack` param doc and
                  ///< PairingEngine::run_discover_confirm_step_() for where that split lives.
                  ///< Hardware-validated on a Somfy Izymo dimmer (always-alive): it answers the
                  ///< `0x00` shape with 0x2D within ~25 ms.
  SEND_WITH_ACK,  ///< Like SEND, but also sets CTRL1_ACK for an always-alive target (`0x10`) — the
                  ///< shape every corpus hub (VELUX KLR200/KIG300, Somfy Connectivity Kit) uses
                  ///< there. A low-power target still gets `0x20`, identical to SEND. Not the
                  ///< default: the Somfy Izymo dimmer never answers the `0x10` shape with 0x2D
                  ///< (pairing still completes, after the full no-answer wait). Kept for an
                  ///< always-alive device from a hub ecosystem that sends this shape and does not
                  ///< answer SEND's.
};
 
/// @brief Which channels PairingEngine's discovery wait listens on.
///
/// A broadcast's answers are not pinned to the channel the request went out on: every device that
/// replies is continuing its own hopping rather than joining a pinned conversation (see
/// @ref ListenPolicy). Somfy always-alive roll-call replies land back on the request channel about
/// 1 in 149 times, so skipping it buys a third more dwell on the two channels that carry almost
/// all of them — hence the default. `all` exists because that measurement covers responders we
/// have already heard from: a device that answers discovery *only* on the request channel is
/// indistinguishable, from our side, from one that never answers at all.
enum class DiscoveryListenChannels : uint8_t {
  SKIP_REQUEST,  ///< Default. The two channels that are not the request channel.
  ALL,           ///< CH1->CH2->CH3, including the request channel. Costs a third of the dwell on
                 ///< the other two; use it to rule out a responder that only answers on CH2.
};
 
/// @brief Which direction PairingEngine moves the system key in after discovery.
///
/// `auto` (the default) picks the direction from the device's discovery answer: a device that answers
/// as a remote controller (node type 1023) is pulled, any other device is pushed. There is no switch to the
/// other direction inside one attempt: a refusal repeats, and a retry costs pairing time. `push` and
/// `pull` force the direction.
///
/// `push` is the usual pairing: we send our key to the device (0x31 key init, the device's 0x3C,
/// our 0x32, its 0x33). `pull` asks the device for its own key instead: we send a 0x38 key-transfer
/// request with six random bytes, the device answers with a 0x32 holding its key, and we challenge
/// it (0x3C) to prove it holds that key before trusting it. An Atlantic AGILIA IO radiator in its
/// display's pairing mode answers a pushed key with RESULT_COMMAND_UNKNOWN (tests/corpus/captures/
/// pairing/atlantic_agilia_pairing_key_transfer_command_unknown.yaml); `auto` pulls such a device. A
/// pulled key is carried by the devices that answer a roll-call under it, never adopted as the hub's:
/// see PairingEngine::run_key_pull_phase_() and register_pulled_key_devices_().
enum class KeyTransferMode : uint8_t {
  AUTO,  ///< Default. Pull from a device that answered discovery as a remote controller, push to any other.
  PUSH,  ///< Send our system key to the device.
  PULL,  ///< Ask the device for its key, then run a roll-call under it to find the devices that hold it.
};
 
/// @brief Discovery request command codes.
enum class DiscoveryCommand : uint8_t {
  DISCOVER = 0x28,      ///< Standard broadcast discovery request (to 0x00003B).
  DISCOVER_SPE = 0x2A,  ///< SPE roll-call request (self-authenticating; see CMD_DISCOVER_SPE_REQ).
                        ///< Deliberately **not** offered as a `pairing_discovery_commands` preset
                        ///< in tuning.py: only devices that already hold the system key answer it,
                        ///< so it can never help reach a device in learning mode. Retained here
                        ///< because the command byte is still needed to *send* a roll-call, and
                        ///< because discovery_command_from_string() stays permissive enough to
                        ///< parse it — do not remove either as dead code.
  DISCOVER_ALT = 0x2E,  ///< Alternate broadcast discovery (to 0x00003F), with optional payload byte.
};
 
// Chip-specific radio defaults live here beside the TuningConfig fields they initialize — the
// single source of truth for defaults. proto_timing.h holds only chip-neutral protocol values;
// the radio drivers consume these via apply_tuning / hop_dwell_ms.
 
/// SX1262-specific preamble for response/continuation frames within an exchange.
///
/// Applies to any tight-turnaround frame sent immediately after receiving from the device —
/// 0x3D challenge responses, 0x32 key transfers after receiving 0x3C, and any future protocol
/// frame in that position — giving the peer's receiver time to lock back on after the SX1262's
/// own TX→RX turnaround.
///
/// 8 bytes was validated on real hardware (Heltec V3.2 ↔ Device actuator) as the minimum that
/// gives reliable lock-on without perturbing exchange timing; it matches the protocol's own
/// nominal SHORT_PREAMBLE floor.
///
/// This constant is byte-denominated, like every other preamble value in this codebase
/// (LONG_PREAMBLE, SHORT_PREAMBLE) — `RadioSX1262::set_packet_params_()` is the one place that
/// converts to the chip's bit-denominated SetPacketParams field, right before the value leaves
/// for the wire.
static constexpr uint16_t SX1262_RESPONSE_PREAMBLE = 8;
 
/// SX1262-specific post-TX settling delay before re-entering RX.
///
/// The SX1262 GFSK demodulator needs time to stabilize after TX before it can
/// reliably receive the next frame. A 500 µs delay was validated as the minimum
/// that prevents challenge-byte corruption during pairing and tight-turnaround
/// authenticated exchanges.
static constexpr uint16_t SX1262_POST_TX_SETTLE_US = 500;
 
/// SX1276 preamble for response/continuation frames within an exchange.
///
/// Defaults to 12 bytes — longer than the protocol's 8-byte SHORT_PREAMBLE. On real hardware the
/// extra length improves the peer device's lock-on without measurably affecting exchange timing.
/// Runtime-tunable down to SHORT_PREAMBLE or up for a marginal-range install.
static constexpr uint16_t SX1276_RESPONSE_PREAMBLE = 12;
 
/// Per-channel dwell while SX1276 pairing discovery hops across channels.
///
/// The SX1276 supports FastHop (no standby transition), so a short slice keeps
/// discovery sweeping all three channels quickly.
static constexpr uint16_t SX1276_DISCOVERY_HOP_SLICE_MS = 5;
 
/// Per-channel dwell while SX1262 pairing discovery hops across channels.
///
/// SX1262 frequency changes require a standby→SetRfFrequency→RX cycle, unlike the SX1276's
/// FastHop, but that changes only how much a single retune costs, not how long the radio should
/// then sit still: a short dwell fits more retunes into the listen window than a long one, so the
/// receiver is more often already parked on the right channel by the time a reply starts. The
/// preamble/sync linger guard (`ListenSpec::linger_on_preamble`) is what makes a dwell this short
/// safe — it keeps a caught reply from being cut off mid-reception by extending the dwell instead
/// of hopping away. A dwell in the low single-digit milliseconds performs best; shorter than that,
/// coverage degrades gradually and only truly collapses at `0`, where `wait_for_packet(..., 0)`
/// returns before any guard can observe activity at all. `7` is the best-performing value found in
/// that range.
static constexpr uint16_t SX1262_DISCOVERY_HOP_SLICE_MS = 7;
 
/// LR1121-specific preamble for response/continuation frames within an exchange.
///
/// Seeded from the SX1262-validated default, on the principle that a validated timing value
/// encodes protocol-side reality more than a chip quirk. Not yet independently validated on
/// LR1121 hardware; a value measured by loopback tuning would fold back here.
static constexpr uint16_t LR1121_RESPONSE_PREAMBLE = SX1262_RESPONSE_PREAMBLE;
 
/// LR1121-specific post-TX settling delay before re-entering RX.
///
/// Seeded from the SX1262-validated default; same rationale as @ref LR1121_RESPONSE_PREAMBLE.
static constexpr uint16_t LR1121_POST_TX_SETTLE_US = SX1262_POST_TX_SETTLE_US;
 
/// Per-channel dwell while LR1121 pairing discovery hops across channels.
///
/// Measured independently on LR1121 hardware rather than inherited from
/// @ref SX1262_DISCOVERY_HOP_SLICE_MS — that constant's short-dwell reasoning applies equally
/// here, but the two chips are validated separately and could in principle diverge, so this stays
/// its own literal rather than an alias.
static constexpr uint16_t LR1121_DISCOVERY_HOP_SLICE_MS = 7;
 
/// Default directed start preamble for drivers built on the shared software PHY (SX1262, LR1121).
///
/// 48 bytes rather than the protocol's documented 32. Measured: on a Somfy Izymo dimmer an SX1262
/// answers 56/71 = 78.9% of first tries at 32 bytes and 60/60 at 48, 64, 128 and 256 — a step, not
/// a ramp — while an SX1276 sending the same programmed 32 bytes answers 60/60. The deficit tracks
/// the shared PHY rather than the chip, the link or the device, so the compensation belongs with
/// the PHY. The cause of the shortfall is not identified; see ADR 0042.
static constexpr uint16_t SOFT_PHY_START_PREAMBLE = 48;
 
/// @brief All runtime tunable parameters for pairing and radio diagnostics.
///
/// Values reset to their defaults on every boot. Each field initializes from a
/// canonical constant — chip-neutral defaults live in `proto_timing.h`, chip-specific
/// defaults in this header — shared with the ESPHome YAML schema. The hub stores a single
/// `TuningConfig` instance and passes it to the radio driver and pairing flow. UI
/// callbacks update the hub instance directly; the snapshot helpers emit the current
/// values in YAML-compatible form so a working combination can be copied back into the
/// configuration file.
struct TuningConfig {
  // --- Radio / physical layer ---
  /// SX1262 RX bandwidth selector.
  ///
  /// 58.6 kHz (double-sideband). This is below the 76.8 kHz sizing floor for this waveform (see
  /// `SX1262RxBandwidth`), so it trims the edges of even an on-frequency signal; it is the
  /// default because it made a real solar shutter (Somfy RS100) respond reliably where 117.3 kHz
  /// did not. Because the SX1262 has no GFSK AFC, a peer whose carrier sits off nominal needs a
  /// wider setting instead: a Somfy LightVar_Wh_io dimmer went from mostly missed to mostly
  /// confirmed replies at 156.2 kHz. The setting is global, so the right value is a per-install trade-off.
  SX1262RxBandwidth sx1262_rx_bandwidth{SX1262RxBandwidth::BW_58_6_KHZ};
  uint16_t sx1262_response_preamble{SX1262_RESPONSE_PREAMBLE};            ///< SX1262 response preamble in bytes.
  uint16_t sx1262_post_tx_settle_us{SX1262_POST_TX_SETTLE_US};            ///< Delay after SX1262 TX before RX (µs).
  SX1276RxBandwidth sx1276_rx_bandwidth{SX1276RxBandwidth::BW_41_7_KHZ};  ///< SX1276 RX bandwidth selector.
  uint16_t sx1276_response_preamble{SX1276_RESPONSE_PREAMBLE};            ///< SX1276 response preamble in bytes.
  uint16_t sx1276_discovery_hop_slice_ms{
      SX1276_DISCOVERY_HOP_SLICE_MS};  ///< Per-channel dwell while SX1276 discovery hops.
  uint16_t sx1262_discovery_hop_slice_ms{
      SX1262_DISCOVERY_HOP_SLICE_MS};  ///< Per-channel dwell while SX1262 discovery hops.
  LR1121RxBandwidth lr1121_rx_bandwidth{LR1121RxBandwidth::BW_117_3_KHZ};  ///< LR1121 RX bandwidth selector.
  uint16_t lr1121_response_preamble{LR1121_RESPONSE_PREAMBLE};             ///< LR1121 response preamble in bytes.
  uint16_t lr1121_post_tx_settle_us{LR1121_POST_TX_SETTLE_US};             ///< Delay after LR1121 TX before RX (µs).
  uint16_t lr1121_discovery_hop_slice_ms{
      LR1121_DISCOVERY_HOP_SLICE_MS};  ///< Per-channel dwell while LR1121 discovery hops.
  uint16_t cold_broadcast_reply_preamble{
      COLD_BROADCAST_REPLY_PREAMBLE};  ///< Preamble for a start-flagged key-extraction broadcast reply (0x29).
  uint16_t normal_start_preamble{
      NORMAL_START_PREAMBLE};  ///< Preamble for a directed start frame to a non-low-power target.
                               ///< Resolved at setup from RadioDriver::default_start_preamble()
                               ///< unless `normal_start_preamble_from_yaml` says the user set it.
  /// True when `normal_start_preamble:` appeared in YAML. Codegen emits this alongside the value;
  /// it exists so setup() can tell "the user chose 32" from "nobody chose anything", which decides
  /// whether the driver's default applies (ADR 0042). Only read once, at setup — a later change
  /// through the Home Assistant number simply sets the value.
  bool normal_start_preamble_from_yaml{false};
  uint8_t lbt_max_retries{LBT_MAX_RETRIES};                ///< LBT retries before forced TX.
  int16_t lbt_rssi_threshold_dbm{LBT_RSSI_THRESHOLD_DBM};  ///< LBT channel-free threshold (dBm).
  bool low_power_wake_belief{true};  ///< Order a `low_power` device's start-frame tries by its wake belief (short
                                     ///< preamble first when it is believed awake). False restores the fixed
                                     ///< wake-up preamble on every try. A diagnostic off-switch, on by default.
  uint16_t low_power_wake_preamble{LONG_PREAMBLE};  ///< Wake-up preamble (bytes) on a directed start frame to a
                                                    ///< `low_power` target believed at rest.
 
  // --- Exchange response windows ---
  // How long the hub listens for a device's reply. Tunable because the right value is a property
  // of the *device*, not of the radio or the protocol: observed reply latencies on one network
  // span two orders of magnitude (a mains Oximo 40 at ~23 ms, a solar RS100 at 29-3052 ms). See
  // RESPONSE_START_WAIT_MS for the measurements behind the defaults.
  uint16_t exchange_start_response_wait_ms{
      RESPONSE_START_WAIT_MS};  ///< Reply window for a start frame (wakes a sleeping device).
  uint16_t exchange_response_wait_ms{
      RESPONSE_WAIT_MS};  ///< Reply window for continuation frames and the post-auth final response.
  uint16_t exchange_total_budget_ms{EXCHANGE_TOTAL_BUDGET_MS};  ///< Ceiling on one whole exchange, retries included.
 
  // --- Pairing protocol ---
  std::vector<DiscoveryCommand> pairing_discovery_commands{
      DiscoveryCommand::DISCOVER};                                       ///< Ordered discovery commands.
  std::vector<uint8_t> pairing_discovery_destination{0x00, 0x00, 0x00};  ///< Destination when auto=false.
  bool pairing_discovery_destination_auto{true};  ///< When true, map commands to conventional addresses.
  uint8_t pairing_discovery_payload{0};           ///< Optional payload byte (used for 0x2E).
  bool pairing_discovery_payload_enabled{false};  ///< Whether the optional payload is enabled.
  bool pairing_discovery_low_power{false};        ///< Set LOW_POWER flag in discovery frames.
  bool pairing_discovery_ack_capable{false};      ///< Set ACK (CTRL1_ACK) on the discovery broadcast only.
                                                  ///< Opt-in — see the init_frame() doc in
                                                  ///< proto_frame.h; default off.
  uint16_t pairing_discovery_preamble{
      PAIRING_DISCOVERY_PREAMBLE};  ///< Preamble for the discovery broadcast (0x28/0x2E) start frame.
  uint16_t pairing_discovery_wait_ms{
      PAIRING_DISCOVERY_WAIT_MS};  ///< Total wait window after sending discovery commands.
  uint16_t pairing_discovery_initial_dwell_ms{
      PAIRING_DISCOVERY_INITIAL_DWELL_MS};  ///< Initial dwell on CH2 before discovery hopping begins.
  uint8_t pairing_key_exchange_retries{
      PAIRING_KEY_EXCHANGE_RETRIES};  ///< Retries for the authenticated key exchange phase.
  ScanPowerClasses scan_power_classes{
      ScanPowerClasses::BOTH};  ///< Power classes the scan_paired_devices roll-call calls.
  DiscoverConfirmMode pairing_discover_confirm{
      DiscoverConfirmMode::SEND};  ///< Whether/how to send CMD_DISCOVER_CONFIRM (0x2C) during pairing.
  DiscoveryListenChannels pairing_discovery_listen_channels{
      DiscoveryListenChannels::SKIP_REQUEST};                   ///< Channels the discovery response wait covers.
  KeyTransferMode pairing_key_transfer{KeyTransferMode::AUTO};  ///< Push our key, or pull the device's key.
  uint16_t pairing_key_init_delay_ms{
      PAIRING_KEY_INIT_DELAY_MS};  ///< Pause after the discover-confirm step, before CMD_KEY_INIT (0x31).
 
  // --- Internal state ---
  bool active{false};  ///< True when the YAML `tuning:` block is present.
};
 
/// @brief One selectable RX bandwidth: the chip's register byte and its nominal kHz value.
///
/// The per-chip bandwidth conversion functions below (SX1262/SX1276/LR1121) are all the same
/// logic over a different table of these; they are thin typed wrappers around the three generic
/// helpers that follow, which own the register-byte lookup, the "%.1f" formatting, and the
/// input normalization once instead of three times.
struct BandwidthOption {
  uint8_t reg;
  float khz;
};
 
/// @brief Look up the kHz value for a register byte in a bandwidth table.
/// @param table Bandwidth option table.
/// @param n Number of entries in @p table.
/// @param reg Register byte to look up.
/// @param fallback kHz value returned when @p reg is not in the table.
float bandwidth_to_khz(const BandwidthOption *table, size_t n, uint8_t reg, float fallback);
 
/// @brief Format a kHz value as its YAML/UI option string (bare number, one decimal, e.g. "117.3").
std::string bandwidth_to_string(float khz);
 
/// @brief Parse a YAML/UI bandwidth string against a table, returning the matching register byte.
///
/// Accepts surrounding whitespace and a trailing "kHz" suffix in any case, and accepts both the
/// one-decimal spelling ("39.0") and the integer-truncated spelling ("39") of every table entry.
/// @return The register byte, or std::nullopt when the string matches no entry.
std::optional<uint8_t> bandwidth_from_string(const BandwidthOption *table, size_t n, const std::string &value);
 
/// @brief A pointer/size view over one chip's RX-bandwidth option table.
struct BandwidthTableView {
  const BandwidthOption *data;
  size_t size;
};
 
/// @brief The SX1262 RX-bandwidth option table. Exposed so tests derive their legal-option
/// lists from the same source production uses rather than re-listing them by hand.
BandwidthTableView sx1262_bandwidth_table();
/// @brief The SX1276 RX-bandwidth option table (see sx1262_bandwidth_table()).
BandwidthTableView sx1276_bandwidth_table();
/// @brief The LR1121 RX-bandwidth option table (see sx1262_bandwidth_table()).
BandwidthTableView lr1121_bandwidth_table();
 
/// @brief Convert a bandwidth enum to the numeric kHz value used in YAML/logs.
/// @param bw SX1262 bandwidth enum.
/// @return Floating-point kHz value (39.0, 46.9, 58.6, 78.2, 117.3, 156.2, or 187.2).
float sx1262_bandwidth_to_khz(SX1262RxBandwidth bw);
 
/// @brief Format a bandwidth enum as its YAML/UI option string (bare kHz number, e.g. "117.3").
/// @param bw SX1262 bandwidth enum.
/// @return Bandwidth rendered with one decimal place and a "kHz" suffix.
std::string sx1262_bandwidth_to_string(SX1262RxBandwidth bw);
 
/// @brief Convert a YAML bandwidth string to the enum value.
/// @param value YAML string such as "117.3kHz" or "156.2kHz".
/// @return Bandwidth enum, or std::nullopt on invalid input.
std::optional<SX1262RxBandwidth> sx1262_bandwidth_from_string(const std::string &value);
 
/// @brief Convert an SX1276 bandwidth enum to the numeric kHz value used in YAML/logs.
/// @param bw SX1276 bandwidth enum.
/// @return Floating-point kHz value (20.8, 41.7, 62.5, 83.3, or 125.0).
float sx1276_bandwidth_to_khz(SX1276RxBandwidth bw);
 
/// @brief Format an SX1276 bandwidth enum as its YAML/UI option string (bare kHz number).
/// @param bw SX1276 bandwidth enum.
/// @return Bandwidth rendered with one decimal place (e.g. "41.7").
std::string sx1276_bandwidth_to_string(SX1276RxBandwidth bw);
 
/// @brief Convert a YAML SX1276 bandwidth string to the enum value.
/// @param value YAML string such as "41.7" or "83.3kHz".
/// @return Bandwidth enum, or std::nullopt on invalid input.
std::optional<SX1276RxBandwidth> sx1276_bandwidth_from_string(const std::string &value);
 
/// @brief Convert an LR1121 bandwidth enum to the numeric kHz value used in YAML/logs.
/// @param bw LR1121 bandwidth enum.
/// @return Floating-point kHz value (39.0, 46.9, 58.6, 78.2, 117.3, 156.2, or 187.2).
float lr1121_bandwidth_to_khz(LR1121RxBandwidth bw);
 
/// @brief Format an LR1121 bandwidth enum as its YAML/UI option string (bare kHz number).
/// @param bw LR1121 bandwidth enum.
/// @return Bandwidth rendered with one decimal place (e.g. "117.3").
std::string lr1121_bandwidth_to_string(LR1121RxBandwidth bw);
 
/// @brief Convert a YAML LR1121 bandwidth string to the enum value.
/// @param value YAML string such as "117.3" or "39.0kHz".
/// @return Bandwidth enum, or std::nullopt on invalid input.
std::optional<LR1121RxBandwidth> lr1121_bandwidth_from_string(const std::string &value);
 
/// @brief Format the current tuning configuration as a one-line YAML-compatible snapshot.
///
/// Only values that differ from the default are emitted, so the line can be copied
/// back into YAML with minimal editing. When all values are default, an empty string
/// is returned.
///
/// @param cfg Current tuning configuration.
/// @return One-line snapshot string, or empty when no overrides are active.
std::string tuning_config_snapshot(const TuningConfig &cfg);
 
/// @brief Format the current tuning configuration as a full one-line snapshot.
///
/// Emits every non-default value, regardless of whether it was changed from YAML or
/// from the HA UI. This is logged at the start of every pairing attempt.
///
/// @param cfg Current tuning configuration.
/// @return One-line snapshot string, or a "defaults" marker when nothing is overridden.
std::string tuning_config_full_snapshot(const TuningConfig &cfg);
 
/// @brief Format a single tuning update for the log.
///
/// @param name YAML key name of the updated parameter.
/// @param value YAML-compatible string representation of the new value.
/// @return One-line log string suitable for ESP_LOGI.
std::string tuning_update_log_line(const std::string &name, const std::string &value);
 
/// @brief Resolve the destination address for a discovery command.
///
/// When `destination_auto` is true, returns the conventional address for the
/// given command code. Otherwise returns the configured `destination` value.
///
/// @param command Discovery command code.
/// @param destination_auto Whether to use the automatic mapping.
/// @param destination Explicit 3-byte destination when auto is false.
/// @return Pointer to the resolved 3-byte node ID.
const uint8_t *resolve_discovery_destination(uint8_t command, bool destination_auto,
                                             const uint8_t destination[NODE_ID_SIZE]);
 
/// @brief Parse a discovery command string (e.g., "0x28") into the enum.
/// @param value String to parse.
/// @return Discovery command enum, or std::nullopt on invalid input.
std::optional<DiscoveryCommand> discovery_command_from_string(const std::string &value);
 
/// @brief Format a discovery command enum for YAML/logs.
/// @param cmd Discovery command enum.
/// @return Lowercase hex string such as "0x28".
std::string discovery_command_to_string(DiscoveryCommand cmd);
 
/// @brief Format a destination option for YAML/logs.
///
/// @param destination_auto Whether automatic destination mapping is used.
/// @param destination Explicit 3-byte destination when auto is false.
/// @return "auto" or a hex address such as "0x00003B".
std::string discovery_destination_to_string(bool destination_auto, const uint8_t destination[NODE_ID_SIZE]);
 
/// @brief Format a payload option for YAML/logs.
///
/// @param payload_enabled Whether the optional payload is enabled.
/// @param payload The payload byte when enabled.
/// @return "none" or a hex byte such as "0x00".
std::string discovery_payload_to_string(bool payload_enabled, uint8_t payload);
 
/// @brief Format the ordered discovery command list for logs.
///
/// @param commands Ordered list of discovery commands.
/// @return Bracketed comma-separated list such as "[0x28,0x2E]".
std::string discovery_commands_to_string(const std::vector<DiscoveryCommand> &commands);
 
/// @brief Format the ordered discovery command list as a UI/preset option string.
///
/// Matches the comma-separated `select` option labels (no brackets) so a boot-time
/// snapshot round-trips to a selectable dropdown value.
///
/// @param commands Ordered list of discovery commands.
/// @return Comma-separated list such as "0x28,0x2E" (empty string when the list is empty).
std::string discovery_commands_to_csv(const std::vector<DiscoveryCommand> &commands);
 
/// @brief Format a ScanPowerClasses value for YAML/logs.
///
/// `BOTH` is its own literal; the two single-class values return
/// `power_save_mode_name(POWER_SAVE_ALWAYS_ALIVE)` / `power_save_mode_name(POWER_SAVE_LOW_POWER)`
/// so the roll-call report and this tunable share one vocabulary rather than a second spelling.
/// @param value Selection to format.
/// @return "both", "always_alive", or "low_power".
std::string scan_power_classes_to_string(ScanPowerClasses value);
 
/// @brief Parse a scan_power_classes string into the enum.
///
/// Exact, case-sensitive match against the same three strings scan_power_classes_to_string()
/// produces.
/// @param value String to parse.
/// @return The matching selection, or std::nullopt on invalid input.
std::optional<ScanPowerClasses> scan_power_classes_from_string(const std::string &value);
 
/// @brief Whether `selection` calls the roll-call pass for `power_save_mode`.
///
/// Pure predicate, used both by the sweep loop (which pass to skip) and by the report (which
/// class to name in the selection NOTE) — one source of truth for "does this selection include
/// that class" instead of two.
/// @param selection Current `scan_power_classes` tuning value.
/// @param power_save_mode POWER_SAVE_ALWAYS_ALIVE or POWER_SAVE_LOW_POWER.
/// @return true if `selection` calls that class; false for an unrecognized power_save_mode.
bool scan_power_classes_include(ScanPowerClasses selection, uint8_t power_save_mode);
 
/// @brief Format a DiscoverConfirmMode value for YAML/logs.
/// @param value Selection to format.
/// @return "skip", "send", or "send_with_ack".
std::string discover_confirm_mode_to_string(DiscoverConfirmMode value);
 
/// @brief Parse a `pairing_discover_confirm` string into the enum.
///
/// Exact, case-sensitive match against the same three strings discover_confirm_mode_to_string()
/// produces.
/// @param value String to parse.
/// @return The matching mode, or std::nullopt on invalid input.
std::optional<DiscoverConfirmMode> discover_confirm_mode_from_string(const std::string &value);
 
/// @brief Render a DiscoveryListenChannels as its YAML/select option string.
/// @param value Selection to render.
/// @return `"skip_request"` or `"all"`.
std::string discovery_listen_channels_to_string(DiscoveryListenChannels value);
 
/// @brief Parse a DiscoveryListenChannels from its YAML/select option string.
///
/// Exact, case-sensitive match against the same strings discovery_listen_channels_to_string()
/// emits, so the two stay each other's inverse.
/// @param value Option string to parse.
/// @return The selection, or `std::nullopt` if `value` is not one of the options.
std::optional<DiscoveryListenChannels> discovery_listen_channels_from_string(const std::string &value);
 
/// @brief Render a KeyTransferMode as its YAML/select option string.
/// @param value Selection to render.
/// @return `"push"` or `"pull"`.
std::string key_transfer_mode_to_string(KeyTransferMode value);
 
/// @brief Parse a KeyTransferMode from its YAML/select option string.
///
/// Exact, case-sensitive match against the strings key_transfer_mode_to_string() emits.
/// @param value Option string to parse.
/// @return The selection, or `std::nullopt` if `value` is not one of the options.
std::optional<KeyTransferMode> key_transfer_mode_from_string(const std::string &value);
 
}  // namespace home_io_control
}  // namespace esphome