一周续航实验：把传感器做成可以交接维护的电池节点

idf.py --version
idf.py -B build -D IDF_TARGET=esp32 build
idf.py -B build -p YOUR_FEATHER_PORT flash monitor

// ---- main/main.cpp ----
// SPDX-License-Identifier: MIT
#include <cstdio>
#include <cstring>
#include <inttypes.h>
#include <atomic>
#include "esp_sleep.h"
#include "esp_system.h"
#include "esp_timer.h"
#include "esp_mac.h"
#include "esp_wifi.h"
#include "esp_wifi_default.h"
#include "esp_event.h"
#include "esp_netif.h"
#include "nvs_flash.h"
#include "nvs.h"
#include "mqtt_client.h"
#include "driver/uart.h"
#include "freertos/event_groups.h"
#include "freertos/queue.h"
#include "WeekJournal.h"
#include "Hardware.h"
#include "credentials.h"
static L10Journal journal;static nvs_handle_t store;static bool healthy=false;static EventGroupHandle_t flags;static QueueHandle_t acks;static std::atomic<int> subscription{-1};static char rowTopic[80],ackTopic[80];static constexpr int IP_OK=1,FAIL=2,MQTT_READY=4;
RTC_DATA_ATTR static uint32_t heldSeen=0,heldInverse=UINT32_MAX;
struct Ack{uint64_t journal,sequence;};
static bool persist(const L10Journal& candidate){
 if(!healthy||!l10Valid(candidate)){puts("STORE_INVALID: refused commit");return false;}
 esp_err_t e=nvs_set_blob(store,"journal",&candidate,sizeof candidate);if(e==ESP_OK)e=nvs_commit(store);
 if(!l10StoreResult(healthy,e==ESP_OK)){printf("STORE_WRITE_ERROR=%s; persisted state uncertain, business blocked this boot; RAM not advanced. Preserve raw NVS before recovery.\n",esp_err_to_name(e));return false;}
 journal=candidate;return true;
}
static bool openJournal(){
 esp_err_t e=nvs_flash_init();if(e!=ESP_OK){printf("NVS_INIT_ERROR=%s; no automatic erase\n",esp_err_to_name(e));return false;}
 e=nvs_open("l10",NVS_READWRITE,&store);if(e!=ESP_OK){printf("NVS_OPEN_ERROR=%s\n",esp_err_to_name(e));return false;}
 size_t size=sizeof journal;e=nvs_get_blob(store,"journal",&journal,&size);
 if(e==ESP_ERR_NVS_NOT_FOUND){healthy=true;auto fresh=l10Fresh(l10_deployment_id());if(!persist(fresh)){healthy=false;return false;}puts("NEW_NVS_JOURNAL: record deployment ID; never reuse after erase");return true;}
 if(e!=ESP_OK||size!=sizeof journal||!l10Valid(journal)){printf("JOURNAL_INVALID error=%s bytes=%u; preserve raw NVS before recovery\n",esp_err_to_name(e),unsigned(size));return false;}healthy=true;return true;
}
static void wifiEvent(void*,esp_event_base_t base,int32_t id,void*){
 if(base==WIFI_EVENT&&id==WIFI_EVENT_STA_START){if(esp_wifi_connect()!=ESP_OK)xEventGroupSetBits(flags,FAIL);}
 if(base==WIFI_EVENT&&id==WIFI_EVENT_STA_DISCONNECTED){xEventGroupClearBits(flags,IP_OK);xEventGroupSetBits(flags,FAIL);}
 if(base==IP_EVENT&&id==IP_EVENT_STA_GOT_IP)xEventGroupSetBits(flags,IP_OK);
}
static void mqttEvent(void*,esp_event_base_t,int32_t id,void* data){
 auto* event=static_cast<esp_mqtt_event_handle_t>(data);
 if(id==MQTT_EVENT_CONNECTED){int n=esp_mqtt_client_subscribe(event->client,ackTopic,1);subscription.store(n);if(n<0)xEventGroupSetBits(flags,FAIL);}
 if(id==MQTT_EVENT_SUBSCRIBED&&event->msg_id==subscription.load())xEventGroupSetBits(flags,MQTT_READY);
 if(id==MQTT_EVENT_DISCONNECTED){xEventGroupClearBits(flags,MQTT_READY);xEventGroupSetBits(flags,FAIL);}
 if(id==MQTT_EVENT_DATA&&event->topic_len==int(strlen(ackTopic))&&!memcmp(event->topic,ackTopic,size_t(event->topic_len))&&!event->retain&&event->current_data_offset==0&&event->data_len==event->total_data_len){Ack ack{};if(l10Ack(event->data,size_t(event->data_len),ack.journal,ack.sequence))xQueueSend(acks,&ack,0);}
}
static void upload(bool operatorOverride){
 if(!healthy||!journal.count){puts("UPLOAD: no healthy queued rows");return;}
 if(!l10_ssid()[0]||!l10_broker()[0]){puts("CONFIG_DISABLED: rows retained; no network success");return;}
 if(strlen(l10_ssid())>31||strlen(l10_password())>63||strncmp(l10_broker(),"mqtt://",7)){puts("CONFIG_INVALID: trusted LAN mqtt://, SSID<=31 password<=63");return;}
 if(operatorOverride)puts("OPERATOR_UPLOAD: requires physically confirmed stable USB supply; software cannot detect USB/battery presence");
 static bool networkStack=false;if(!networkStack){ESP_ERROR_CHECK(esp_netif_init());networkStack=true;}
 xEventGroupClearBits(flags,0xff);xQueueReset(acks);subscription.store(-1);ESP_ERROR_CHECK(esp_event_loop_create_default());auto* sta=esp_netif_create_default_wifi_sta();if(!sta){puts("NETIF_ALLOC_ERROR");esp_event_loop_delete_default();return;}
 esp_event_handler_instance_t wifiHandler,ipHandler;ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT,ESP_EVENT_ANY_ID,wifiEvent,nullptr,&wifiHandler));ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT,IP_EVENT_STA_GOT_IP,wifiEvent,nullptr,&ipHandler));
 wifi_init_config_t init=WIFI_INIT_CONFIG_DEFAULT();ESP_ERROR_CHECK(esp_wifi_init(&init));ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_RAM));ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA));wifi_config_t config{};strlcpy(reinterpret_cast<char*>(config.sta.ssid),l10_ssid(),sizeof config.sta.ssid);strlcpy(reinterpret_cast<char*>(config.sta.password),l10_password(),sizeof config.sta.password);ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA,&config));ESP_ERROR_CHECK(esp_wifi_start());
 auto bits=xEventGroupWaitBits(flags,IP_OK|FAIL,pdFALSE,pdFALSE,pdMS_TO_TICKS(8000));
 if((bits&IP_OK)&&!(bits&FAIL)){
  esp_mqtt_client_config_t config{};config.broker.address.uri=l10_broker();config.network.disable_auto_reconnect=true;config.network.timeout_ms=2000;config.outbox.limit=4096;
  auto client=esp_mqtt_client_init(&config);
  if(client){ESP_ERROR_CHECK(esp_mqtt_client_register_event(client,MQTT_EVENT_ANY,mqttEvent,nullptr));esp_err_t e=esp_mqtt_client_start(client);
   if(e==ESP_OK){bits=xEventGroupWaitBits(flags,MQTT_READY|FAIL,pdFALSE,pdFALSE,pdMS_TO_TICKS(5000));
    if((bits&MQTT_READY)&&!(bits&FAIL)){for(unsigned attempt=0;attempt<20&&healthy&&journal.count;++attempt){
     const uint64_t sequence=l10Head(journal);const char* row=journal.rows[journal.head];int id=esp_mqtt_client_publish(client,rowTopic,row,0,1,0);printf("PUBLISH seq=%" PRIu64 " sdk_id=%d; PUBACK is not app commit\n",sequence,id);if(id<0){vTaskDelay(pdMS_TO_TICKS(100));continue;}
     int64_t start=esp_timer_get_time();bool acknowledged=false;
     while(esp_timer_get_time()-start<1500000){Ack ack{};if(xQueueReceive(acks,&ack,pdMS_TO_TICKS(20))==pdTRUE){auto candidate=journal;if(l10Pop(candidate,ack.journal,ack.sequence,sequence)){if(persist(candidate)){printf("APP_ACK_COMMITTED seq=%" PRIu64 " remaining=%" PRIu32 "\n",sequence,journal.count);acknowledged=true;}else puts("ACK_SEEN_BUT_NVS_COMMIT_FAILED: storage uncertain; stop business, inspect after restart");break;}}}
     if(!acknowledged)puts("APP_ACK_NOT_COMMITTED: retained current head");
    }}else puts("MQTT_TIMEOUT: data retained");
    ESP_ERROR_CHECK(esp_mqtt_client_stop(client));
   }else printf("MQTT_START_ERROR=%s\n",esp_err_to_name(e));
   ESP_ERROR_CHECK(esp_mqtt_client_destroy(client));
  }else puts("MQTT_ALLOC_ERROR");
 }else puts("WIFI_TIMEOUT_OR_FAIL: retained queue");
 ESP_ERROR_CHECK(esp_wifi_stop());ESP_ERROR_CHECK(esp_wifi_deinit());ESP_ERROR_CHECK(esp_event_handler_instance_unregister(WIFI_EVENT,ESP_EVENT_ANY_ID,wifiHandler));ESP_ERROR_CHECK(esp_event_handler_instance_unregister(IP_EVENT,IP_EVENT_STA_GOT_IP,ipHandler));esp_netif_destroy_default_wifi(sta);ESP_ERROR_CHECK(esp_event_loop_delete_default());
}
static void status(){if(!healthy){puts("STATE STORE_INVALID: read raw NVS/repair before deployment; no automatic erase");return;}printf("STATUS journal=%016" PRIx64 " generated=%" PRIu64 " queued=%" PRIu32 " drop_new=%" PRIu64 " low_latched=%" PRIu32 " head=%" PRIu64 "; voltage not SOC, no acquired UTC\n",journal.journal,journal.generated,journal.count,journal.dropped,journal.lowLatched,l10Head(journal));}
static void maintenance(){
 puts("MAINTENANCE 300s command-entry window: STATUS / DUMP / UPLOAD / EXIT; in-progress UPLOAD may extend exit time. No erase command; USB condition is operator responsibility.");
 int64_t start=esp_timer_get_time(),last=0;char line[64]{};size_t length=0;bool discarding=false,sawCR=false;
 while(esp_timer_get_time()-start<300000000){
  uint8_t ch;int n=uart_read_bytes(UART_NUM_0,&ch,1,pdMS_TO_TICKS(50));int64_t now=esp_timer_get_time();
  if((length||sawCR)&&!discarding&&now-last>2000000){length=0;sawCR=false;discarding=true;puts("INPUT_TIMEOUT: draining through next LF");}
  if(n!=1){continue;}
  last=now;
  if(ch=='\n'){
   if(discarding){puts("INPUT_DISCARDED: overflow/control/timeout drained through LF");}else{line[length]=0;if(!strcmp(line,"STATUS"))status();else if(!strcmp(line,"DUMP")){status();if(healthy){puts("BEGIN_UNACKED_CSV_V2");for(unsigned i=0;i<journal.count;++i)fputs(journal.rows[(journal.head+i)%L10_SLOTS],stdout);puts("END_UNACKED_CSV_V2");}}else if(!strcmp(line,"UPLOAD")){if(gpio_get_level(GPIO_NUM_27)==0)upload(true);else puts("PHYSICAL_MAINTENANCE_CLOSED: rejected UPLOAD");}else if(!strcmp(line,"EXIT"))break;else puts("UNKNOWN_COMMAND");}
   length=0;discarding=false;sawCR=false;continue;
  }
  if(discarding){continue;}
  if(sawCR){length=0;sawCR=false;discarding=true;continue;}
  if(ch=='\r'){sawCR=true;continue;}// Only one trailing CR immediately before LF is accepted.
  if(ch<0x20||ch>0x7e||length==sizeof line-1){discarding=true;length=0;}else if(!discarding)line[length++]=char(ch);
 }
 puts("MAINTENANCE_END; held switch will not immediately wake again");
}
static void sleepNow(uint64_t delay){
 l10PowerOff();bool released=gpio_get_level(GPIO_NUM_27)!=0;vTaskDelay(pdMS_TO_TICKS(30));released=released&&gpio_get_level(GPIO_NUM_27)!=0;
 ESP_ERROR_CHECK(esp_sleep_enable_timer_wakeup(delay));
 if(released){heldSeen=0;heldInverse=UINT32_MAX;ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_27,0));puts("WAKE timer+EXT0 GPIO27 LOW armed after release");}
 else{heldSeen=1;heldInverse=~heldSeen;puts("MAINT_HELD: timer-only sleep; EXT0 disabled to avoid repeated immediate wake");}
 fflush(stdout);ESP_ERROR_CHECK(uart_wait_tx_idle_polling(UART_NUM_0));esp_deep_sleep_start();
}
extern "C" void app_main(){
 int64_t start=esp_timer_get_time();ESP_ERROR_CHECK(rtc_gpio_hold_dis(GPIO_NUM_2));ESP_ERROR_CHECK(rtc_gpio_deinit(GPIO_NUM_2));gpio_config_t power{};power.pin_bit_mask=1ULL<<2;power.mode=GPIO_MODE_OUTPUT;ESP_ERROR_CHECK(gpio_config(&power));gpio_set_level(GPIO_NUM_2,0);l10PowerOff();
 gpio_config_t input{};input.pin_bit_mask=1ULL<<27;input.mode=GPIO_MODE_INPUT;ESP_ERROR_CHECK(gpio_config(&input));ESP_ERROR_CHECK(gpio_set_pull_mode(GPIO_NUM_27,GPIO_FLOATING));ESP_ERROR_CHECK(rtc_gpio_pullup_dis(GPIO_NUM_27));ESP_ERROR_CHECK(rtc_gpio_pulldown_dis(GPIO_NUM_27));gpio_config_t led{};led.pin_bit_mask=1ULL<<13;led.mode=GPIO_MODE_OUTPUT;ESP_ERROR_CHECK(gpio_config(&led));gpio_set_level(GPIO_NUM_13,0);
 ESP_ERROR_CHECK(uart_driver_install(UART_NUM_0,512,0,0,nullptr,0));
 if(esp_reset_reason()!=ESP_RST_DEEPSLEEP||(heldSeen^heldInverse)!=UINT32_MAX){heldSeen=0;heldInverse=UINT32_MAX;}
 vTaskDelay(pdMS_TO_TICKS(30));const bool physical=gpio_get_level(GPIO_NUM_27)==0;const bool enterMaintenance=physical&&!heldSeen;if(physical){heldSeen=1;heldInverse=~heldSeen;}
 flags=xEventGroupCreate();acks=xQueueCreate(4,sizeof(Ack));if(!flags||!acks){puts("ALLOC_ERROR: no radio result");sleepNow(600000000);}
 uint8_t mac[6];ESP_ERROR_CHECK(esp_read_mac(mac,ESP_MAC_WIFI_STA));snprintf(rowTopic,sizeof rowTopic,"hixinwu/l10/%02x%02x%02x%02x%02x%02x/row",mac[0],mac[1],mac[2],mac[3],mac[4],mac[5]);snprintf(ackTopic,sizeof ackTopic,"hixinwu/l10/%02x%02x%02x%02x%02x%02x/ack",mac[0],mac[1],mac[2],mac[3],mac[4],mac[5]);
 printf("L10 classicESP32 FeatherV2 PCB F reset=%d wake=%d maintenance=%u held=%u; no tested week/battery result\n",esp_reset_reason(),esp_sleep_get_wakeup_cause(),enterMaintenance,physical);
 if(openJournal()){
  auto battery=l10Battery();printf("BATTERY_NODE known_ADC=%u nominal_mV=%" PRIu32 " raw_mean=%d efuse=%d error=%s; presence/USB/SOC NOT detected\n",battery.known,battery.nominalmV,battery.raw,battery.efuse,esp_err_to_name(battery.error));
  esp_err_t error=ESP_FAIL;auto sample=l10Sensor(error);printf("SHT40 valid=%u result=%s; invalid values masked\n",sample.valid,esp_err_to_name(error));
  auto candidate=journal;candidate.lowLatched=l10Low(journal.lowLatched,battery.known,battery.nominalmV);l10Seal(candidate);L10Row row{};row.reset=uint32_t(esp_reset_reason());row.wake=uint32_t(esp_sleep_get_wakeup_cause());row.sensor=sample.valid;row.t=sample.valid?sample.t_mC:0;row.rh=sample.valid?sample.rh_raw_mPct:0;row.battery=battery.known;row.mV=battery.known?battery.nominalmV:0;row.flags=(candidate.lowLatched?L10_LOW:0)|(!battery.known?L10_ADC_UNKNOWN:0)|(!sample.valid?L10_SENSOR_ERROR:0)|(physical?L10_MAINT_HELD:0);
  if(l10Append(candidate,row)&&persist(candidate)){status();if(!enterMaintenance&&battery.known&&!journal.lowLatched)upload(false);else puts("RADIO_SKIPPED: maintenance/low-latch/ADC-unknown; sample retained or explicitly drop-new counted");}else puts("SAMPLE_NOT_COMMITTED: RAM not advanced; write failure blocks business, preserve raw NVS");
 }
 if(enterMaintenance)maintenance();
 const int64_t active=esp_timer_get_time()-start;printf("END active_app_us=%" PRId64 "; sleep timer adjusted toward600s app-start cycle; boot overhead/clock drift measured separately\n",active);sleepNow(active<600000000?uint64_t(600000000-active):1000000);
}

// ---- main/Hardware.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include "driver/gpio.h"
#include "driver/rtc_io.h"
#include "driver/i2c_master.h"
#include "esp_adc/adc_oneshot.h"
#include "esp_adc/adc_cali.h"
#include "esp_adc/adc_cali_scheme.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "ShtSample.h"
struct L10Battery{bool known=false;int raw=0;uint32_t nominalmV=0;int efuse=-1;esp_err_t error=ESP_FAIL;};
inline void l10Release(gpio_num_t pin){ESP_ERROR_CHECK(gpio_reset_pin(pin));ESP_ERROR_CHECK(gpio_set_direction(pin,GPIO_MODE_INPUT));ESP_ERROR_CHECK(gpio_set_pull_mode(pin,GPIO_FLOATING));}
inline void l10PowerOff(){
 // Sensor bus must already have been removed. Release BOTH signals before VIN.
 l10Release(GPIO_NUM_22);l10Release(GPIO_NUM_20);l10Release(GPIO_NUM_0);// NeoPixel DIN shares the switched rail.
 ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_2));ESP_ERROR_CHECK(rtc_gpio_set_direction(GPIO_NUM_2,RTC_GPIO_MODE_OUTPUT_ONLY));ESP_ERROR_CHECK(rtc_gpio_set_level(GPIO_NUM_2,0));ESP_ERROR_CHECK(rtc_gpio_hold_en(GPIO_NUM_2));
}
inline ShtSample l10Sensor(esp_err_t& error){
 ShtSample sample{};ESP_ERROR_CHECK(rtc_gpio_hold_dis(GPIO_NUM_2));ESP_ERROR_CHECK(rtc_gpio_deinit(GPIO_NUM_2));gpio_config_t power{};power.pin_bit_mask=1ULL<<2;power.mode=GPIO_MODE_OUTPUT;ESP_ERROR_CHECK(gpio_config(&power));gpio_set_level(GPIO_NUM_2,1);vTaskDelay(pdMS_TO_TICKS(20));
 i2c_master_bus_handle_t bus=nullptr;i2c_master_dev_handle_t device=nullptr;i2c_master_bus_config_t config{};config.i2c_port=I2C_NUM_0;config.sda_io_num=GPIO_NUM_22;config.scl_io_num=GPIO_NUM_20;config.clk_source=I2C_CLK_SRC_DEFAULT;config.glitch_ignore_cnt=7;config.flags.enable_internal_pullup=false;
 error=i2c_new_master_bus(&config,&bus);
 if(error==ESP_OK){i2c_device_config_t d{};d.dev_addr_length=I2C_ADDR_BIT_LEN_7;d.device_address=0x44;d.scl_speed_hz=100000;error=i2c_master_bus_add_device(bus,&d,&device);}
 if(error==ESP_OK){uint8_t cmd=0xfd,bytes[6];error=i2c_master_transmit(device,&cmd,1,100);if(error==ESP_OK){vTaskDelay(pdMS_TO_TICKS(10));error=i2c_master_receive(device,bytes,6,100);if(error==ESP_OK){sample=decodeSht(bytes);if(!sample.valid)error=ESP_ERR_INVALID_CRC;}}}
 if(device){ESP_ERROR_CHECK(i2c_master_bus_rm_device(device));}if(bus){ESP_ERROR_CHECK(i2c_del_master_bus(bus));}l10PowerOff();return sample;
}
inline L10Battery l10Battery(){
 L10Battery b;vTaskDelay(pdMS_TO_TICKS(1000));// Read before sensor/radio load; C5 and divider source condition explicitly documented.
 adc_oneshot_unit_handle_t unit=nullptr;adc_cali_handle_t calibration=nullptr;adc_oneshot_unit_init_cfg_t init{};init.unit_id=ADC_UNIT_1;init.ulp_mode=ADC_ULP_MODE_DISABLE;b.error=adc_oneshot_new_unit(&init,&unit);if(b.error!=ESP_OK)return b;
 adc_oneshot_chan_cfg_t channel{};channel.atten=ADC_ATTEN_DB_12;channel.bitwidth=ADC_BITWIDTH_12;b.error=adc_oneshot_config_channel(unit,ADC_CHANNEL_7,&channel);
 adc_cali_line_fitting_efuse_val_t efuse=ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF;if(b.error==ESP_OK)b.error=adc_cali_scheme_line_fitting_check_efuse(&efuse);b.efuse=int(efuse);
 if(b.error==ESP_OK&&efuse!=ADC_CALI_LINE_FITTING_EFUSE_VAL_DEFAULT_VREF){adc_cali_line_fitting_config_t c{};c.unit_id=ADC_UNIT_1;c.atten=ADC_ATTEN_DB_12;c.bitwidth=ADC_BITWIDTH_12;c.default_vref=0;b.error=adc_cali_create_scheme_line_fitting(&c,&calibration);}
 else if(b.error==ESP_OK){b.error=ESP_ERR_NOT_SUPPORTED;}
 int64_t sumRaw=0,sumMv=0;
 if(b.error==ESP_OK){for(unsigned i=0;i<68;++i){int raw=0,mV=0;b.error=adc_oneshot_read(unit,ADC_CHANNEL_7,&raw);if(b.error!=ESP_OK||raw<=0||raw>=4095){b.error=ESP_ERR_INVALID_RESPONSE;break;}b.error=adc_cali_raw_to_voltage(calibration,raw,&mV);if(b.error!=ESP_OK)break;if(i>=4){sumRaw+=raw;sumMv+=mV;}vTaskDelay(pdMS_TO_TICKS(10));}
  if(b.error==ESP_OK){b.raw=int(sumRaw/64);uint32_t estimated=uint32_t((sumMv*2+32)/64);if(estimated>=2000&&estimated<=5000){b.nominalmV=estimated;b.known=true;}else b.error=ESP_ERR_INVALID_RESPONSE;}
 }
 if(calibration){ESP_ERROR_CHECK(adc_cali_delete_scheme_line_fitting(calibration));}ESP_ERROR_CHECK(adc_oneshot_del_unit(unit));return b;
}

// ---- main/WeekJournal.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <cstdint>
#include <cstddef>
#include <cstring>
#include <cstdio>
#include <inttypes.h>
constexpr unsigned L10_SLOTS=16,L10_ROW=192;
constexpr uint32_t L10_LOW=1,L10_ADC_UNKNOWN=2,L10_SENSOR_ERROR=4,L10_MAINT_HELD=8;
inline uint32_t l10Crc(const void* ptr,size_t n){auto* b=static_cast<const uint8_t*>(ptr);uint32_t crc=UINT32_MAX;for(size_t i=0;i<n;++i){crc^=b[i];for(unsigned bit=0;bit<8;++bit)crc=(crc>>1)^((crc&1)?0xedb88320U:0);}return ~crc;}
struct L10Row {uint64_t journal=0,seq=0,cycle=0;uint32_t reset=0,wake=0;bool sensor=false;int32_t t=0,rh=0;bool battery=false;uint32_t mV=0,flags=0;uint64_t dropped=0;};
inline bool l10Encode(const L10Row& q,char* out,size_t capacity){
 if(!q.journal||!q.seq||!q.cycle||q.dropped>=q.seq||q.reset>32||q.wake>32||q.flags>15||(!q.sensor&&(q.t||q.rh))||(q.sensor&&(q.t< -45000||q.t>130000||q.rh< -6000||q.rh>119000))||(!q.battery&&q.mV)||(q.battery&&(q.mV<2000||q.mV>5000))||bool(q.flags&L10_ADC_UNKNOWN)==q.battery||bool(q.flags&L10_SENSOR_ERROR)==q.sensor){return false;}
 int n=snprintf(out,capacity,"2,%016" PRIx64 ",%" PRIu64 ",%" PRIu64 ",%" PRIu32 ",%" PRIu32 ",%u,%" PRId32 ",%" PRId32 ",%u,%" PRIu32 ",%" PRIu32 ",%" PRIu64,q.journal,q.seq,q.cycle,q.reset,q.wake,q.sensor,q.t,q.rh,q.battery,q.mV,q.flags,q.dropped);
 if(n<=0||size_t(n)+11>capacity){return false;}uint32_t crc=l10Crc(out,size_t(n));int end=snprintf(out+n,capacity-size_t(n),",%08" PRIx32 "\n",crc);return end==10;
}
inline bool l10Decode(const char* bytes,size_t n,L10Row& q){
 if(!bytes||n<35||n>=L10_ROW||bytes[n-1]!='\n'||std::memchr(bytes,0,n)){return false;}char input[L10_ROW]{};memcpy(input,bytes,n);unsigned valid=0,battery=0;uint32_t crc=0;int end=0;L10Row parsed;
 int count=sscanf(input,"2,%16" SCNx64 ",%" SCNu64 ",%" SCNu64 ",%" SCNu32 ",%" SCNu32 ",%u,%" SCNd32 ",%" SCNd32 ",%u,%" SCNu32 ",%" SCNu32 ",%" SCNu64 ",%8" SCNx32 "\n%n",&parsed.journal,&parsed.seq,&parsed.cycle,&parsed.reset,&parsed.wake,&valid,&parsed.t,&parsed.rh,&battery,&parsed.mV,&parsed.flags,&parsed.dropped,&crc,&end);
 if(count!=13||end!=int(n)||valid>1||battery>1){return false;}parsed.sensor=valid;parsed.battery=battery;char canonical[L10_ROW]{};if(!l10Encode(parsed,canonical,sizeof canonical)||strlen(canonical)!=n||memcmp(canonical,bytes,n)){return false;}q=parsed;return true;
}
struct L10Journal {
 uint32_t magic=0,version=0;uint64_t journal=0,generated=0,dropped=0,cycle=0;uint32_t head=0,count=0,lowLatched=0,reserved=0;char rows[L10_SLOTS][L10_ROW]{};uint32_t crc=0,reserved2=0;
};
static_assert(offsetof(L10Journal,crc)==3128&&sizeof(L10Journal)==3136,"fixed NVS blob layout; migration must be explicit");
inline void l10Seal(L10Journal& j){j.crc=l10Crc(&j,offsetof(L10Journal,crc));}
inline L10Journal l10Fresh(uint64_t id){L10Journal j{};j.magic=0x4c31304a;j.version=1;j.journal=id;l10Seal(j);return j;}
inline bool l10Valid(const L10Journal& j){
 if(j.magic!=0x4c31304a||j.version!=1||!j.journal||j.count>L10_SLOTS||j.head>=L10_SLOTS||j.lowLatched>1||j.reserved||j.reserved2||j.crc!=l10Crc(&j,offsetof(L10Journal,crc))||j.dropped>j.generated||j.generated!=j.cycle){return false;}
 uint64_t previous=0;for(unsigned i=0;i<j.count;++i){const char* line=j.rows[(j.head+i)%L10_SLOTS];size_t n=strnlen(line,L10_ROW);L10Row row;if(!l10Decode(line,n,row)||row.journal!=j.journal||row.seq<=previous||row.seq>j.generated||row.cycle!=row.seq||row.dropped>j.dropped){return false;}previous=row.seq;}return true;
}
inline bool l10Append(L10Journal& j,L10Row row){
 if(!l10Valid(j)||j.generated==UINT64_MAX||j.dropped==UINT64_MAX){return false;}
 row.journal=j.journal;row.seq=j.generated+1;row.cycle=j.cycle+1;row.dropped=j.dropped;
 char encoded[L10_ROW]{};if(!l10Encode(row,encoded,sizeof encoded)){return false;}
 ++j.generated;++j.cycle;
 if(j.count==L10_SLOTS){++j.dropped;l10Seal(j);return true;}// Keep old unacknowledged rows, drop new sample explicitly.
 unsigned slot=(j.head+j.count)%L10_SLOTS;memset(j.rows[slot],0,L10_ROW);memcpy(j.rows[slot],encoded,strlen(encoded)+1);++j.count;l10Seal(j);return true;
}
inline uint64_t l10Head(const L10Journal& j){if(!j.count)return 0;L10Row row;const char* text=j.rows[j.head];return l10Decode(text,strnlen(text,L10_ROW),row)?row.seq:0;}
inline bool l10Pop(L10Journal& j,uint64_t jid,uint64_t seq,uint64_t inflight){if(!l10Valid(j)||!j.count||jid!=j.journal||seq!=inflight||seq!=l10Head(j)){return false;}memset(j.rows[j.head],0,L10_ROW);j.head=(j.head+1)%L10_SLOTS;--j.count;l10Seal(j);return true;}
inline bool l10Low(bool before,bool adcKnown,uint32_t nominalmV){if(!adcKnown)return before;if(nominalmV<=3550)return true;if(nominalmV>=3700)return false;return before;}
inline bool l10Ack(const char* bytes,size_t n,uint64_t& journal,uint64_t& seq){
 if(!bytes||n<18||n>37||std::memchr(bytes,0,n)){return false;}char copy[40]{};memcpy(copy,bytes,n);int end=0;uint64_t j=0,s=0;if(sscanf(copy,"%16" SCNx64 ",%" SCNu64 "%n",&j,&s,&end)!=2||end!=int(n)||!j||!s){return false;}char encoded[40];int size=snprintf(encoded,sizeof encoded,"%016" PRIx64 ",%" PRIu64,j,s);if(size!=int(n)||memcmp(encoded,bytes,n)){return false;}journal=j;seq=s;return true;
}

// A failed write/commit makes persisted state uncertain. Only a fresh restart/inspection
// can establish health again; a later success must not silently rearm this boot.
inline bool l10StoreResult(bool& healthy,bool success){if(!healthy)return false;if(!success)healthy=false;return healthy;}

// ---- main/ShtSample.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <stdint.h>
struct ShtSample { bool valid=false;int t_mC=0;int rh_raw_mPct=0;int rh_mPct=0; };
inline uint8_t shtCrc(const uint8_t* b){uint8_t c=0xff;for(int k=0;k<2;++k){c^=b[k];for(int j=0;j<8;++j)c=(c&0x80)?uint8_t((c<<1)^0x31):uint8_t(c<<1);}return c;}
inline ShtSample decodeSht(const uint8_t b[6]){ShtSample s;if(shtCrc(b)!=b[2]||shtCrc(b+3)!=b[5])return s;uint16_t t=(uint16_t(b[0])<<8)|b[1],h=(uint16_t(b[3])<<8)|b[4];s.valid=true;s.t_mC=-45000+int(175000LL*t/65535);s.rh_raw_mPct=-6000+int(125000LL*h/65535);s.rh_mPct=s.rh_raw_mPct<0?0:(s.rh_raw_mPct>100000?100000:s.rh_raw_mPct);return s;}

// ---- main/credentials.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
const char* l10_ssid(void);
const char* l10_password(void);
const char* l10_broker(void);
uint64_t l10_deployment_id(void);
#ifdef __cplusplus
}
#endif

// ---- main/credentials.c ----
// SPDX-License-Identifier: MIT
#include "credentials.h"
// Empty networking configuration is safe offline operation, not successful upload.
const char* l10_ssid(void){return "";}
const char* l10_password(void){return "";}
const char* l10_broker(void){return "";}// trusted LAN mqtt:// only; do not expose to Internet.
// Public deployment namespace, not a secret. Change for EVERY erased/new journal
// and record it in the handoff. Existing valid NVS journal keeps its original ID.
uint64_t l10_deployment_id(void){return UINT64_C(0x4c31304649454c44);}

python3 host/receiver.py receive --host YOUR_BROKER --port 1883 --db week.db --client-dir /path/to/mosquitto/client
python3 host/receiver.py export --db week.db --output week-export.csv

python3 tools/budget.py ACTUAL-CYCLE.csv --period-s 600 --days 7 --nominal-voltage 3.7 --rated-capacity-mAh 1200 --max-gap-s 0.001
python3 tools/week_audit.py week-export.csv deployment-ledger.csv