tuning_registry.cpp

Go to the documentation of this file.

/// @file tuning_registry.cpp
/// @brief Parameter tables and lookup helpers for the tuning registry.
/// @ingroup hioc_tuning
///
/// The getter/setter lambdas below carry all per-parameter parsing (bandwidth enum
/// decode, the comma-separated command list with whitespace trimming, the
/// destination/payload/low-power mapping). Keeping them here makes the hub's tuning
/// dispatch methods pure table lookups.
 
#include "tuning_registry.h"
 
#include "proto_codecs.h"        // ADDRESS_SUFFIX_* / encode_broadcast_address() / encode_discovery_address()
#include "proto_device_model.h"  // DeviceType
 
#include <cstddef>
#include <iterator>
 
namespace esphome {
namespace home_io_control {
 
// === Numeric parameters (23) ===================================================
// Each row narrows the incoming float to the field's storage type, matching the
// original static_cast in update_tuning_number().
static constexpr TuningNumberParam NUMBER_PARAMS[] = {
    {"sx1262_response_preamble", [](const TuningConfig &t) { return static_cast<float>(t.sx1262_response_preamble); },
     [](TuningConfig &t, float v) { t.sx1262_response_preamble = static_cast<uint16_t>(v); }, true},
    {"sx1262_post_tx_settle_us", [](const TuningConfig &t) { return static_cast<float>(t.sx1262_post_tx_settle_us); },
     [](TuningConfig &t, float v) { t.sx1262_post_tx_settle_us = static_cast<uint16_t>(v); }, true},
    {"sx1276_response_preamble", [](const TuningConfig &t) { return static_cast<float>(t.sx1276_response_preamble); },
     [](TuningConfig &t, float v) { t.sx1276_response_preamble = static_cast<uint16_t>(v); }, true},
    {"sx1276_discovery_hop_slice_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.sx1276_discovery_hop_slice_ms); },
     [](TuningConfig &t, float v) { t.sx1276_discovery_hop_slice_ms = static_cast<uint16_t>(v); }, false},
    {"sx1262_discovery_hop_slice_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.sx1262_discovery_hop_slice_ms); },
     [](TuningConfig &t, float v) { t.sx1262_discovery_hop_slice_ms = static_cast<uint16_t>(v); }, false},
    {"lr1121_response_preamble", [](const TuningConfig &t) { return static_cast<float>(t.lr1121_response_preamble); },
     [](TuningConfig &t, float v) { t.lr1121_response_preamble = static_cast<uint16_t>(v); }, true},
    {"lr1121_post_tx_settle_us", [](const TuningConfig &t) { return static_cast<float>(t.lr1121_post_tx_settle_us); },
     [](TuningConfig &t, float v) { t.lr1121_post_tx_settle_us = static_cast<uint16_t>(v); }, true},
    {"lr1121_discovery_hop_slice_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.lr1121_discovery_hop_slice_ms); },
     [](TuningConfig &t, float v) { t.lr1121_discovery_hop_slice_ms = static_cast<uint16_t>(v); }, false},
    // false: unlike sx1262/sx1276/lr1121_response_preamble, this field is not chip-specific and
    // is never cached into a radio driver via apply_tuning() — key_extraction_responder.cpp reads it
    // straight out of TuningConfig at TX time, the same way the *_discovery_hop_slice_ms fields
    // above are read live rather than applied.
    {"cold_broadcast_reply_preamble",
     [](const TuningConfig &t) { return static_cast<float>(t.cold_broadcast_reply_preamble); },
     [](TuningConfig &t, float v) { t.cold_broadcast_reply_preamble = static_cast<uint16_t>(v); }, false},
    // false: not chip-specific and never cached into a radio driver via apply_tuning() — the
    // exchange engine reads it straight out of TuningConfig at TX time, the same as
    // cold_broadcast_reply_preamble above.
    {"normal_start_preamble", [](const TuningConfig &t) { return static_cast<float>(t.normal_start_preamble); },
     [](TuningConfig &t, float v) { t.normal_start_preamble = static_cast<uint16_t>(v); }, false},
    {"low_power_wake_preamble", [](const TuningConfig &t) { return static_cast<float>(t.low_power_wake_preamble); },
     [](TuningConfig &t, float v) { t.low_power_wake_preamble = static_cast<uint16_t>(v); }, false},
    {"lbt_max_retries", [](const TuningConfig &t) { return static_cast<float>(t.lbt_max_retries); },
     [](TuningConfig &t, float v) { t.lbt_max_retries = static_cast<uint8_t>(v); }, false},
    {"lbt_rssi_threshold_dbm", [](const TuningConfig &t) { return static_cast<float>(t.lbt_rssi_threshold_dbm); },
     [](TuningConfig &t, float v) { t.lbt_rssi_threshold_dbm = static_cast<int16_t>(v); }, false},
    {"exchange_start_response_wait_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.exchange_start_response_wait_ms); },
     [](TuningConfig &t, float v) { t.exchange_start_response_wait_ms = static_cast<uint16_t>(v); }, false},
    {"exchange_early_response_wait_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.exchange_early_response_wait_ms); },
     [](TuningConfig &t, float v) { t.exchange_early_response_wait_ms = static_cast<uint16_t>(v); }, false},
    {"exchange_response_wait_ms", [](const TuningConfig &t) { return static_cast<float>(t.exchange_response_wait_ms); },
     [](TuningConfig &t, float v) { t.exchange_response_wait_ms = static_cast<uint16_t>(v); }, false},
    {"exchange_total_budget_ms", [](const TuningConfig &t) { return static_cast<float>(t.exchange_total_budget_ms); },
     [](TuningConfig &t, float v) { t.exchange_total_budget_ms = static_cast<uint16_t>(v); }, false},
    // false: read straight out of TuningConfig by the hub when a linked remote is heard and when an
    // operation ends (ADR 0080), never applied to a radio driver.
    {"remote_activity_poll_delay_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.remote_activity_poll_delay_ms); },
     [](TuningConfig &t, float v) { t.remote_activity_poll_delay_ms = static_cast<uint32_t>(v); }, false},
    {"remote_activity_catchup_poll_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.remote_activity_catchup_poll_ms); },
     [](TuningConfig &t, float v) { t.remote_activity_catchup_poll_ms = static_cast<uint32_t>(v); }, false},
    // false: read straight out of TuningConfig at TX time by PairingEngine::run_discovery_phase_(),
    // the same as normal_start_preamble/cold_broadcast_reply_preamble above. The getter reports the
    // effective value (what discovery sends), so the Home Assistant number shows the start preamble
    // it follows; the setter marks the value as set, and it stays set until the next restart (Home
    // Assistant has no way back to "follow").
    {"pairing_discovery_preamble",
     [](const TuningConfig &t) { return static_cast<float>(effective_discovery_preamble(t)); },
     [](TuningConfig &t, float v) {
       t.pairing_discovery_preamble = static_cast<uint16_t>(v);
       t.pairing_discovery_preamble_set = true;
     },
     false},
    {"pairing_discovery_wait_ms", [](const TuningConfig &t) { return static_cast<float>(t.pairing_discovery_wait_ms); },
     [](TuningConfig &t, float v) { t.pairing_discovery_wait_ms = static_cast<uint16_t>(v); }, false},
    {"pairing_discovery_initial_dwell_ms",
     [](const TuningConfig &t) { return static_cast<float>(t.pairing_discovery_initial_dwell_ms); },
     [](TuningConfig &t, float v) { t.pairing_discovery_initial_dwell_ms = static_cast<uint16_t>(v); }, false},
    {"pairing_key_exchange_retries",
     [](const TuningConfig &t) { return static_cast<float>(t.pairing_key_exchange_retries); },
     [](TuningConfig &t, float v) { t.pairing_key_exchange_retries = static_cast<uint8_t>(v); }, false},
    // false: read straight out of TuningConfig by PairingEngine::run_discover_confirm_step_() at
    // the point of the pause, the same as pairing_discovery_preamble/pairing_discovery_wait_ms above.
    {"pairing_key_init_delay_ms", [](const TuningConfig &t) { return static_cast<float>(t.pairing_key_init_delay_ms); },
     [](TuningConfig &t, float v) { t.pairing_key_init_delay_ms = static_cast<uint16_t>(v); }, false},
    // false: both are read by the key-extraction responder each time it builds a discovery answer.
    {"key_extraction_type_word", [](const TuningConfig &t) { return static_cast<float>(t.key_extraction_type_word); },
     [](TuningConfig &t, float v) { t.key_extraction_type_word = static_cast<uint16_t>(v); }, false},
    {"key_extraction_multi_info", [](const TuningConfig &t) { return static_cast<float>(t.key_extraction_multi_info); },
     [](TuningConfig &t, float v) { t.key_extraction_multi_info = static_cast<uint8_t>(v); }, false},
};
 
// Boolean select rows share one get/set shape (an On/Off toggle over a single TuningConfig
// field). Template functions, not lambdas: a TuningSelectParam's get/set are plain function
// pointers with no room for a per-row capture, and instantiating on the member pointer keeps
// each row below a one-liner without duplicating the On/Off parse.
template<bool TuningConfig::*Field> std::string bool_select_get(const TuningConfig &t) {
  return t.*Field ? "On" : "Off";
}
template<bool TuningConfig::*Field> bool bool_select_set(TuningConfig &t, const std::string &v) {
  if (v != "On" && v != "Off")
    return false;
  t.*Field = (v == "On");
  return true;
}
 
// === Select parameters (13) ====================================================
// The setters return false only when the option string is unparseable AND leaving the
// value untouched is the intended behavior (currently the bandwidth enum and the boolean
// rows). The destination/payload setters return false for unrecognized values so no radio
// re-apply is triggered; that has no observable effect since neither applies to the radio.
static constexpr TuningSelectParam SELECT_PARAMS[] = {
    {"sx1262_rx_bandwidth", [](const TuningConfig &t) { return sx1262_bandwidth_to_string(t.sx1262_rx_bandwidth); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto bw = sx1262_bandwidth_from_string(v);
       if (!bw.has_value())
         return false;
       t.sx1262_rx_bandwidth = bw.value();
       return true;
     },
     true},
    {"sx1276_rx_bandwidth", [](const TuningConfig &t) { return sx1276_bandwidth_to_string(t.sx1276_rx_bandwidth); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto bw = sx1276_bandwidth_from_string(v);
       if (!bw.has_value())
         return false;
       t.sx1276_rx_bandwidth = bw.value();
       return true;
     },
     true},
    {"lr1121_rx_bandwidth", [](const TuningConfig &t) { return lr1121_bandwidth_to_string(t.lr1121_rx_bandwidth); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto bw = lr1121_bandwidth_from_string(v);
       if (!bw.has_value())
         return false;
       t.lr1121_rx_bandwidth = bw.value();
       return true;
     },
     true},
    {"low_power_wake_belief", bool_select_get<&TuningConfig::low_power_wake_belief>,
     bool_select_set<&TuningConfig::low_power_wake_belief>, false},
    {"pairing_discovery_commands",
     [](const TuningConfig &t) { return discovery_commands_to_csv(t.pairing_discovery_commands); },
     [](TuningConfig &t, const std::string &v) -> bool {
       t.pairing_discovery_commands.clear();
       // Support both individual commands and comma-separated preset strings.
       std::size_t start = 0;
       while (start < v.size()) {
         const std::size_t comma = v.find(',', start);
         std::string token = v.substr(start, comma - start);
         // Trim whitespace.
         token.erase(0, token.find_first_not_of(" \t"));
         token.erase(token.find_last_not_of(" \t") + 1);
         auto cmd = discovery_command_from_string(token);
         if (cmd.has_value())
           t.pairing_discovery_commands.push_back(cmd.value());
         if (comma == std::string::npos)
           break;
         start = comma + 1;
       }
       return true;
     },
     false},
    {"pairing_discovery_destination",
     [](const TuningConfig &t) {
       return discovery_destination_to_string(t.pairing_discovery_destination_auto,
                                              t.pairing_discovery_destination.data());
     },
     [](TuningConfig &t, const std::string &v) -> bool {
       if (v == "auto") {
         t.pairing_discovery_destination_auto = true;
         return true;
       }
       if (v == "0x00003B") {
         t.pairing_discovery_destination_auto = false;
         t.pairing_discovery_destination = {0x00, 0x00, ADDRESS_SUFFIX_DISCOVERY};
         return true;
       }
       if (v == "0x00003F") {
         t.pairing_discovery_destination_auto = false;
         t.pairing_discovery_destination = {0x00, 0x00, ADDRESS_SUFFIX_BROADCAST};
         return true;
       }
       // Typed class addresses: the class's broadcast (all subtypes) or discovery form. The option
       // string goes last because check-tuning-sync.py reads any row in this table that opens with
       // a string literal as a parameter name.
       struct TypedDestination {
         DeviceType type;
         void (*encode)(DeviceType, uint8_t[NODE_ID_SIZE]);
         const char *option;
       };
       static constexpr TypedDestination TYPED_DESTINATIONS[] = {
           {DeviceType::LIGHT, encode_discovery_address, "0x0001BB"},
           {DeviceType::LIGHT, encode_broadcast_address, "0x0001BF"},
           // Remote controllers: the search an Atlantic Tatou heater sends to receive a key, and the
           // one a Tatou offering its key answered (#199).
           {DeviceType::REMOTE_CONTROLLER, encode_discovery_address, "0x00FFFB"},
       };
       for (const TypedDestination &entry : TYPED_DESTINATIONS) {
         if (v != entry.option)
           continue;
         uint8_t typed[NODE_ID_SIZE] = {0};
         entry.encode(entry.type, typed);
         t.pairing_discovery_destination_auto = false;
         t.pairing_discovery_destination.assign(std::begin(typed), std::end(typed));
         return true;
       }
       return false;
     },
     false},
    {"pairing_discovery_payload",
     [](const TuningConfig &t) {
       return discovery_payload_to_string(t.pairing_discovery_payload_enabled, t.pairing_discovery_payload);
     },
     [](TuningConfig &t, const std::string &v) -> bool {
       if (v == "none") {
         t.pairing_discovery_payload_enabled = false;
         return true;
       }
       if (v == "0x00") {
         t.pairing_discovery_payload_enabled = true;
         t.pairing_discovery_payload = 0x00;
         return true;
       }
       return false;
     },
     false},
    {"pairing_discovery_low_power", bool_select_get<&TuningConfig::pairing_discovery_low_power>,
     bool_select_set<&TuningConfig::pairing_discovery_low_power>, false},
    {"pairing_discovery_ack_capable", bool_select_get<&TuningConfig::pairing_discovery_ack_capable>,
     bool_select_set<&TuningConfig::pairing_discovery_ack_capable>, false},
    {"scan_power_classes", [](const TuningConfig &t) { return scan_power_classes_to_string(t.scan_power_classes); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto selection = scan_power_classes_from_string(v);
       if (!selection.has_value())
         return false;
       t.scan_power_classes = selection.value();
       return true;
     },
     false},
    {"pairing_discover_confirm",
     [](const TuningConfig &t) { return discover_confirm_mode_to_string(t.pairing_discover_confirm); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto mode = discover_confirm_mode_from_string(v);
       if (!mode.has_value())
         return false;
       t.pairing_discover_confirm = mode.value();
       return true;
     },
     false},
    {"pairing_discovery_listen_channels",
     [](const TuningConfig &t) { return discovery_listen_channels_to_string(t.pairing_discovery_listen_channels); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto channels = discovery_listen_channels_from_string(v);
       if (!channels.has_value())
         return false;
       t.pairing_discovery_listen_channels = channels.value();
       return true;
     },
     false},
    // false: read straight out of TuningConfig by PairingEngine::discover_and_pair() when the key
    // step starts, so a change applies to the next pairing attempt without a re-apply.
    {"pairing_key_transfer", [](const TuningConfig &t) { return key_transfer_mode_to_string(t.pairing_key_transfer); },
     [](TuningConfig &t, const std::string &v) -> bool {
       auto mode = key_transfer_mode_from_string(v);
       if (!mode.has_value())
         return false;
       t.pairing_key_transfer = mode.value();
       return true;
     },
     false},
};
 
const TuningNumberParam *find_tuning_number(const std::string &name) {
  for (const auto &param : NUMBER_PARAMS) {
    if (name == param.name)
      return &param;
  }
  return nullptr;
}
 
const TuningSelectParam *find_tuning_select(const std::string &name) {
  for (const auto &param : SELECT_PARAMS) {
    if (name == param.name)
      return &param;
  }
  return nullptr;
}
 
const TuningNumberParam *tuning_number_params_begin() { return std::begin(NUMBER_PARAMS); }
const TuningNumberParam *tuning_number_params_end() { return std::end(NUMBER_PARAMS); }
const TuningSelectParam *tuning_select_params_begin() { return std::begin(SELECT_PARAMS); }
const TuningSelectParam *tuning_select_params_end() { return std::end(SELECT_PARAMS); }
 
}  // namespace home_io_control
}  // namespace esphome