#ifndef RF_CATALOGER_H
#define RF_CATALOGER_H

// ============================================================================
// rf_cataloger.h — Situational sub-GHz ISM RF cataloging (ADDITIVE, off by
// default until enabled).
//
// PURPOSE: a commander needs more than "is there a drone" -- an honest
// picture of what's actually transmitting in the local RF environment is
// itself operationally useful (a garage-door remote firing every time a
// vehicle passes a checkpoint, a weather station or agricultural sensor
// network established nearby, an unexplained LoRa/ISM network with no
// known owner). This module reuses subghz_scanner.cpp's proven dwell-and-
// count architecture (same SX1262, same brief/infrequent/mesh-restoring
// discipline) but scans a DIFFERENT, complementary set of real US/EU ISM
// frequencies and classifies the burst PATTERN into general activity
// classes instead of a single yes/no "is this a drone control link" check.
//
// Real frequency sourcing (not guessed):
//   - 315.0 MHz / 390.0 MHz -- FCC Part 15 US garage-door-opener / keyfob /
//     TPMS band (the de-facto standard US short-range-device frequencies
//     for these device classes for decades; 433.92 MHz is the EU
//     equivalent under EN 300 220).
//   - 433.92 MHz -- EU/global ISM center frequency: garage remotes,
//     weather stations (Oregon Scientific / Acurite / La Crosse all
//     transmit here), TPMS (EU), generic 433 ISM telemetry.
//   - 868.3 MHz -- EU868 LoRaWAN's actual fixed uplink channel center
//     (TTN/Helium EU868 channel plan), distinct from subghz_scanner's
//     864/867 MHz FHSS-hop sampling points.
//   - 902.3 / 904.6 / 906.9 MHz -- US915 LoRaWAN fixed-channel plan
//     sampling points (TTN/Helium US915 sub-band 2), distinct from
//     subghz_scanner's own FCC915 ELRS-FHSS sampling points.
//
// CLASSIFICATION, STATED HONESTLY: this is a burst-timing heuristic, not a
// protocol decoder -- same caveat as subghz_scanner. It buckets the
// observed above-threshold crossing rate during a brief dwell into a
// coarse activity class (continuous carrier / low-rate keyfob-like /
// periodic sensor-telemetry-like / control-link-rate). A "control-link-
// rate" catalog entry here is a coarse duplicate of what SUBGHZ_FINDINGS
// already covers more specifically (see subghz_scanner.h) -- cross-check
// both before acting. This has NOT been validated against real garage
// remotes, TPMS transmitters, or weather stations; report catalog entries
// as "there is periodic sub-GHz activity here, of roughly this character,"
// not as a confirmed device identification.
// ============================================================================

#include <cstdint>
#include <cstddef>

// Coarse activity classification for a dwell's observed burst rate.
// Exposed (not static) so it can be unit-tested directly in the native
// env without needing a real radio.
enum RfActivityClass : uint8_t {
    RF_ACTIVITY_NONE = 0,          // below threshold the whole dwell
    RF_ACTIVITY_CONTINUOUS,        // above threshold ~the whole dwell, near-0 crossings
    RF_ACTIVITY_LOW_RATE,          // sparse bursts -- keyfob/garage-remote/TPMS-like
    RF_ACTIVITY_PERIODIC,          // steady moderate rate -- sensor/telemetry-like
    RF_ACTIVITY_CONTROL_LINK_RATE, // matches RC-control-link packet-rate range
    RF_ACTIVITY_ERRATIC,           // too fast/inconsistent to be a real periodic device
};

// Pure classification function: given a dwell's crossing rate and whether
// the signal stayed continuously above threshold, returns the coarse
// activity class. No radio access -- safe to unit test directly.
RfActivityClass rf_cataloger_classify(float crossing_rate_hz, bool continuously_above);

void rf_cataloger_init();

// Call periodically from the main loop -- internally no-ops unless the
// scan interval has elapsed. Shares the sensor's one SX1262 with
// subghz_scanner.cpp / mesh_publish.cpp; always restores mesh RX after a
// scan cycle completes.
void rf_cataloger_tick();

struct RfCatalogEntry {
    float          freq_mhz;
    RfActivityClass activity_class;
    float          crossing_rate_hz;
    int16_t        peak_rssi_dbm;
};

struct RfCatalogerStats {
    uint32_t scan_cycles_completed;
    uint16_t entries_last_cycle;   // frequencies with any classified activity
};

void rf_cataloger_get_stats(RfCatalogerStats* out);

// Snapshot the catalog from the most recent completed scan cycle. Returns
// the number of entries written (<= max). Includes RF_ACTIVITY_NONE
// frequencies too, so a caller can see "scanned but quiet" vs. "not
// scanned yet."
size_t rf_cataloger_list(RfCatalogEntry* out, size_t max);

#endif // RF_CATALOGER_H
