C interfaces

These listings come directly from the firmware headers whenever the website is rebuilt. See the code guide for module ownership and the HTTP and USB references for interfaces used outside the firmware process.

Fusion core

fc_thermal_t carries native samples and validity/correction masks. Timestamps are local monotonic microseconds. fc_calibration_t holds the row-major RGB-to-thermal homography; fc_measure() computes native-sample region statistics independently of rendering.

#pragma once
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#define FC_TW 32
#define FC_TH 24
#define FC_PIXELS (FC_TW * FC_TH)
#define FC_MAX_REGIONS 8

typedef struct {
    float celsius[FC_PIXELS];
    uint8_t valid[FC_PIXELS], corrected[FC_PIXELS];
    int64_t start_us, end_us;
    uint32_t sequence;
} fc_thermal_t;

typedef struct {
    bool enabled;
    const char *version;
    unsigned width, height;
    /* RGB pixel centres -> native thermal pixel centres, row-major. */
    float rgb_to_thermal[9];
    float display_min_c, display_max_c, opacity;
} fc_calibration_t;

typedef struct {
    const char *id;
    float x0, y0, x1, y1; /* RGB pixel-centre coordinates. */
    unsigned min_samples;
} fc_region_t;

typedef struct {
    unsigned samples, boundary_samples;
    bool supported, ambiguous;
    float max_c, mean_c;
} fc_measurement_t;

bool fc_calibration_valid(const fc_calibration_t *cal);
bool fc_pair_valid(
    const fc_thermal_t *t,
    int64_t rgb_start,
    int64_t rgb_end,
    int64_t now,
    int64_t max_span,
    int64_t max_age
);
/* Out-of-coverage or invalid neighbourhood returns false; no extrapolation. */
bool fc_bicubic(const fc_thermal_t *t, float x, float y, float *celsius);
bool fc_render(
    const fc_calibration_t *cal,
    const fc_thermal_t *thermal,
    const uint8_t *rgb,
    uint8_t *fused,
    size_t buffer_size
);
bool fc_measure(
    const fc_calibration_t *cal,
    const fc_thermal_t *thermal,
    const fc_region_t *regions,
    size_t count,
    fc_measurement_t *out
);
void fc_demo(fc_thermal_t *thermal, uint8_t *rgb, unsigned width, unsigned height, int64_t now);
/* RGB888 to top-down 24-bit BMP; caller supplies full output buffer. */
size_t fc_bmp_size(unsigned width, unsigned height);
bool fc_bmp(const uint8_t *rgb, unsigned width, unsigned height, uint8_t *out, size_t size);

Protection core

pc_update() evaluates configuration, sensor freshness, thresholds and re-arm conditions. GPIO output and persistence belong to system_control.c, allowing the state machine and RMS implementation to run in host tests.

#pragma once
#include <stdbool.h>
#include <stdint.h>

typedef enum { PC_DISARMED, PC_ARMED, PC_TRIPPED } pc_state_t;

typedef enum {
    PC_NONE,
    PC_NOT_CONFIGURED,
    PC_SENSOR_FAULT,
    PC_OVERCURRENT,
    PC_OVERHEAT,
    PC_MANUAL,
    PC_STORAGE_FAULT
} pc_reason_t;

typedef struct {
    uint32_t version;
    bool commissioned;
    float current_limit_a, temperature_limit_c, current_scale_a_per_v;
} pc_config_t;

typedef struct {
    bool current_valid, thermal_valid;
    float current_a, temperature_c;
    int64_t current_time_us, thermal_time_us;
} pc_input_t;

typedef struct {
    pc_state_t state;
    pc_reason_t reason;
    int64_t healthy_since_us;
} pc_controller_t;

bool pc_config_valid(const pc_config_t *c);
void pc_init(pc_controller_t *p, bool persisted_trip);
/* All times use the same local monotonic clock. No network input can arm. */
bool pc_update(
    pc_controller_t *p,
    const pc_config_t *c,
    const pc_input_t *in,
    int64_t now,
    bool physical_rearm,
    bool open_request
);
const char *pc_state_name(pc_state_t state);
const char *pc_reason_name(pc_reason_t reason);

typedef struct {
    unsigned count;
    double mean, m2;
    bool invalid;
} pc_rms_t;

void pc_rms_add(pc_rms_t *window, int16_t adc_code);
float pc_rms_current(const pc_rms_t *window, float scale_a_per_v);

System control

The HTTP handlers and USB dispatcher share system_config_apply(). system_request_open() de-energizes the relay; it does not clear a trip or authorize closing.

#pragma once
#include "esp_err.h"
#include "esp_http_server.h"
#include "fusion_core.h"
#include "cJSON.h"
esp_err_t system_start(void);
bool system_thermal_snapshot(fc_thermal_t *out);
void system_add_status(cJSON *root);
esp_err_t system_config_get(httpd_req_t *req);
esp_err_t system_config_set(httpd_req_t *req);
esp_err_t system_open(httpd_req_t *req);
cJSON *system_config_json(void);
esp_err_t system_config_apply(const cJSON *json);
void system_request_open(void);

Connection settings

device_settings() returns immutable settings for the current boot. A successful save persists a complete replacement; callers must restart before it becomes active. device_settings_public() returns an owned cJSON object with secret values redacted.

#pragma once
#include "esp_err.h"
#include "cJSON.h"

typedef struct {
    char wifi_ssid[33], wifi_password[64], api_token[97];
    char camera_url[192], camera_id[64], installation_id[64];
    char telemetry_url[256], telemetry_token[701];
} device_settings_t;

/* Immutable active settings for this boot. Saved changes take effect after restart. */
esp_err_t device_settings_init(void);
const device_settings_t *device_settings(void);
cJSON *device_settings_public(void);
esp_err_t device_settings_save(const cJSON *json);

Telemetry publisher

The snapshot callback returns heap-allocated JSON. The publisher takes ownership and frees it after acceptance or queue eviction. See telemetry delivery.

#pragma once
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>
typedef char *(*telemetry_snapshot_fn)(void); /* Returns malloc-owned JSON. */

typedef struct {
    uint8_t *bytes;
    size_t size;
    uint32_t sequence, age_ms;
    bool synthetic;
} telemetry_frame_t;

/* Returns a free()-owned copy only when the local fusion is fresh. */
typedef telemetry_frame_t (*telemetry_frame_fn)(void);
void telemetry_start(telemetry_snapshot_fn snapshot, telemetry_frame_fn frame);