CubicCalibrationStore.hpp

Go to the documentation of this file.

#ifndef CUBIC_CALIBRATION_STORE_HPP
#define CUBIC_CALIBRATION_STORE_HPP
 
#include <cstdint>
#include <map>
#include <mutex>
#include <string>
#include <utility>
#include <vector>
 
namespace fsw {
namespace calibration {
 
/** One operator-captured calibration point: raw ADC code paired with a known reference PSI. */
struct CubicPoint {
    double adc = 0.0;
    double psi = 0.0;
    double t = 0.0;  // capture time (unix seconds), display/audit only
};
 
/**
 * Result of a least-squares polynomial fit over a channel's captured points.
 * Two equivalent representations are kept:
 *   - raw cubic  psi = A*adc^3 + B*adc^2 + C*adc + D   (consumed by PTCalibrationCoeffs, raw int32)
 *   - normalized psi = sum poly[i] * ((adc - norm_min)/norm_scale)^i  (well-conditioned; TS side)
 * The normalized form is what the frontend evaluates and what passes the backend's coefficient
 * validator (which rejects |A| > 1e-11 on a raw-ADC cubic).
 */
struct CubicFit {
    bool valid = false;
    double A = 0.0, B = 0.0, C = 0.0, D = 0.0;
    std::vector<double> poly;  // normalized coeffs, length = degree + 1
    double norm_min = 0.0;
    double norm_scale = 1.0;
    double rmse = 0.0;
    int degree = 0;
};
 
/**
 * Which family of sensor a channel belongs to.
 *
 * logical_ch is `(slot - 1) * 10 + connector` with `slot = board_id % 10`, and
 * check_board_slots only prevents two boards of the SAME kind sharing a slot. So PT board
 * 22 and LC board 42 are both slot 2, and PT uid 2201 and LC uid 4201 both land on logical
 * channel 11. The logical-channel maps below are written from a uid-ordered map, so the
 * higher uid silently won: on 2026-09-13 a load cell's curve overwrote a 5000 psi
 * transducer's on disk. The kind namespaces those maps so the two cannot collide.
 */
enum class SensorKind { PT, LC };
 
/** CubicChannel::raw_unit values. */
inline constexpr const char* kRawUnitAdc = "adc";
inline constexpr const char* kRawUnitMicrovolts = "uV";
 
/**
 * How trustworthy the most recent capture on this channel was.
 *
 * A capture is a mean over a short window (CaptureWindow). If the reading was still moving
 * inside that window — the operator pressed Calibrate while the load was settling — the mean
 * is between two values and belongs to neither. The point is still recorded, because
 * discarding an operator's action whose only feedback is a counter that fails to increment is
 * worse than recording it visibly; `settled` is how the GUI marks it.
 */
struct CaptureQuality {
    bool valid = false;  // false = no capture recorded since this channel was loaded
    double t = 0.0;      // unix seconds
    double adc = 0.0;
    size_t n = 0;
    uint64_t window_ms = 0;
    double spread = 0.0;
    double drift = 0.0;
    double drift_z = 0.0;
    bool settled = true;
};
 
/** Per-sensor calibration record: identity, captured points, and the current fit. */
struct CubicChannel {
    uint16_t uid = 0;       // board_id*100 + connector (UI key)
    uint8_t board_id = 0;   // uid / 100
    uint8_t connector = 0;  // uid % 100 (1..10)
    uint8_t logical_ch =
        0;             // pt_logical_calibration_channel(slot, connector) — PTCalibrationManager key
    std::string role;  // human role from config, e.g. "Fuel Upstream"
    // Which model this uid streams (from config): "cubic" (PT default) | "robust" | "linear" (a
    // load cell's default) | "physics". Decides capture routing at the service and which display
    // the frontend renders. For robust uids the cubic `fit` is left invalid (points are
    // display-only) and `fit_curve` holds the sampled model.
    std::string active_model = "cubic";
    // Which logical-channel namespace this channel's fit is serialized into. PT by default so
    // a legacy file, and any caller that does not say, keeps its historical meaning.
    SensorKind kind = SensorKind::PT;
    /**
     * True when the RUNNING config declares a board/connector that owns this uid, i.e.
     * register_channel() was called for it. False for an ORPHAN: an entry load() resumed from
     * disk whose board is disabled, removed, or whose connector is not in active_connectors.
     *
     * An orphan's points stay here — durable, and they re-attach by role when the board comes
     * back — but its `logical_ch` is NOT its own. logical_ch is (slot - 1) * 10 + connector with
     * slot = board_id % 10, and nothing stops two boards of different kinds sharing a slot, so a
     * disabled LC board 41's connectors 1/6/7 name the same logical channels as live PT board
     * 21's. Anything that pushes a fit into (or clears it from) a live logical-channel map must
     * therefore ask `live` first — see cal_target() below.
     */
    bool live = false;
    /**
     * What a point's `adc` means: kRawUnitAdc for an ESP32 board's ADC code, kRawUnitMicrovolts for
     * a LabJack T7 channel's reading in µV. Calibration is filed by role, so a role that moves from
     * an ESP32 board to a T7 (or back) would otherwise carry a curve fitted in one unit onto a
     * channel that reads in the other — a confident, wrong pressure. load() refuses that re-attach.
     */
    std::string raw_unit = "adc";
    std::vector<CubicPoint> points;
    // The fit this uid streams through: `fit_linear` when active_model is "linear", else
    // `fit_cubic` (so cubic, and physics/blend as before, are unchanged). It is what the
    // logical-channel maps carry, so the service, the tare and every reader see one curve.
    CubicFit fit;
    // Both fits over the same points, kept so the calibration page can draw linear beside cubic
    // without the browser fitting anything. fit_linear needs >= 2 points: a one-point "line" is a
    // constant, which would read the same kilograms for any load.
    CubicFit fit_cubic;
    CubicFit fit_linear;
    // Robust display overlay: (adc, psi) samples of the live robust model (predict_pressure_psi),
    // set by the service on each robust capture. Empty for cubic uids.
    std::vector<std::pair<double, double>> fit_curve;
    CaptureQuality last_capture;
    std::string status = "PENDING";  // PENDING (<2 pts) | OK | ERROR
    std::string last_error;
    double updated_at = 0.0;
};
 
/**
 * Which live calibration manager a store entry's fit belongs in — the one rule every caller that
 * applies a resumed curve to the running stream must go through.
 *
 * `None` for an orphan (see CubicChannel::live): it has no sensor streaming, and its logical
 * channel is shared with whatever live board happens to own that slot. On 2026-11-09 LC board 41
 * was disabled in config; its three saved entries (connectors 1, 6, 7) resumed as orphans, and
 * because the service's LC/PT discriminant was built from ENABLED boards they were taken for PTs.
 * Each held one point, so each fit was invalid, so the service CLEARED PT logical channels 1, 6
 * and 7 — FT-PT-R, FF-PT and DR-PT-G — right after the PT entries had set them. All three streamed
 * 0 psi, with raw ADC healthy and a good cubic sitting on disk.
 */
enum class CalTarget { None, PT, LC };
 
inline CalTarget cal_target(const CubicChannel& ch) {
    if (!ch.live)
        return CalTarget::None;
    return ch.kind == SensorKind::LC ? CalTarget::LC : CalTarget::PT;
}
 
/**
 * Owns the per-channel captured points and the fitted cubic for the calibration service.
 * Thread-safe. Persists atomically to a single JSON file that is:
 *   - re-loadable by this class on restart (resume points, re-fit), and
 *   - backward-compatible with the existing calibration_polynomials/poly_coeffs loaders
 *     (logical-channel-keyed) so the file doubles as the factory-cubic overlay the service loads.
 *     Those maps are PT-only; load cells get lc_-prefixed equivalents, because the two share a
 *     logical-channel space (see SensorKind).
 * The service is the sole writer; the Node backend only reads the file to serve the UI.
 */
class CubicCalibrationStore {
public:
    explicit CubicCalibrationStore(std::string file_path);
 
    /** Attach/refresh identity + role + streaming model for a uid (idempotent; call at startup).
     *  `active_model` is the config truth ("cubic"|"robust"|"linear"|"physics"); it takes
     *  precedence over a value restored from disk by load(). A channel that already holds points
     *  is re-fitted when its model changes, so switching cubic <-> linear in config needs no
     *  recapture. */
    void register_channel(uint16_t uid, uint8_t board_id, uint8_t connector, uint8_t logical_ch,
                          const std::string& role, const std::string& active_model = "cubic",
                          SensorKind kind = SensorKind::PT, const std::string& raw_unit = "adc");
 
    /** Append a capture point (raw ADC, reference PSI), cap history, and re-fit. Returns the fit.
     *  For a robust uid the point is recorded for display only and an invalid fit is returned
     *  (the robust learner is updated by the service, not here). */
    CubicFit add_point(uint16_t uid, double adc, double psi);
 
    /** Record how the last capture on this uid went, for the UI to show. */
    void note_capture(uint16_t uid, const CaptureQuality& q);
 
    /** Replace a robust uid's display fit-curve (sampled predict_pressure_psi points). */
    void set_fit_curve(uint16_t uid, const std::vector<std::pair<double, double>>& curve);
 
    /** Drop all points, fit, and fit-curve for a uid (channel goes back to PENDING). */
    void clear_channel(uint16_t uid);
 
    const CubicFit* fit_for(uint16_t uid) const;
    const CubicChannel* channel(uint16_t uid) const;
    std::vector<uint16_t> uids() const;
 
    /** Atomically write the JSON record (temp + rename). */
    bool save() const;
 
    /** Load the JSON record, resume points, and re-fit each channel. Returns channels loaded. */
    size_t load();
 
    /** True when load() could not read an existing file, so every curve here is a fallback rather
     *  than the operator's. Callers that DERIVE from a curve (the LC tare recompute) must skip
     *  rather than persist a number computed against one. */
    bool load_failed() const {
        std::lock_guard<std::mutex> lock(mutex_);
        return load_failed_;
    }
 
    static constexpr size_t kMaxPoints = 20;
 
private:
    mutable std::mutex mutex_;
    std::string file_path_;
    /** Set when load() could not read an existing file. Blocks save(), so an unreadable
     *  store is never replaced by the empty one we fell back to. */
    bool load_failed_ = false;
    std::map<uint16_t, CubicChannel> channels_;
 
public:
    /** Least-squares polynomial of degree min(max_degree, n - 1) over `pts`. Public for tests. */
    static CubicFit compute_fit(const std::vector<CubicPoint>& pts, int max_degree = 3);
 
private:
    /** Recompute fit_cubic / fit_linear / fit / status from ch.points per ch.active_model.
     *  Caller holds mutex_. Robust channels are left to their own branch (no fit). */
    static void refit(CubicChannel& ch);
    std::string serialize() const;  // caller holds mutex_
};
 
}  // namespace calibration
}  // namespace fsw
 
#endif  // CUBIC_CALIBRATION_STORE_HPP