墨水屏刷新预算实验：记录残影、耗时和整板电量

arduino-cli core install esp32:esp32@3.3.12
arduino-cli lib install --no-deps 'Adafruit BusIO@1.17.4' 'Adafruit GFX Library@1.12.4' 'GxEPD2@1.6.9'
arduino-cli compile --fqbn 'esp32:esp32:esp32s3:FlashSize=8M,PSRAM=opi,FlashMode=qio,PartitionScheme=default_8MB,CDCOnBoot=default,USBMode=hwcdc' .
# 上传端口先按F06插拔确认，使用同一完整FQBN；串口115200
python3 tests/energy_test.py

// ---- RefreshPlan.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <stdint.h>
struct RefreshPlan {
 enum Decision{ALLOW,STOPPED,WAIT_INTERVAL,NEED_FULL};
 static constexpr uint64_t intervalMs=180000;
 bool baseline=false,attempted=false,stopped=false;unsigned partials=0;uint64_t last_attempt=0;
 Decision check(uint64_t now,bool partial)const{
  if(stopped)return STOPPED;
  if(partial&&(!baseline||partials>=5))return NEED_FULL;
  if(attempted&&(now<last_attempt||now-last_attempt<intervalMs))return WAIT_INTERVAL;
  return ALLOW;
 }
 void begin(uint64_t now){last_attempt=now;attempted=true;}
 void success(bool partial){if(partial)++partials;else{baseline=true;partials=0;}}
 void hibernated(){baseline=false;partials=0;}
 void fault(){stopped=true;baseline=false;}
};
struct CallBudget {
 uint64_t started=0;bool faulted=false;
 void begin(uint64_t now){started=now;faulted=false;}
 void observe(uint64_t now,bool busy){if(busy&&now>=started&&now-started>=8000000)faulted=true;}
 bool finish(uint64_t now,bool busy){observe(now,busy);if(now<started||now-started>=8000000||busy)faulted=true;return !faulted;}
};

// ---- ButtonCommand.h ----
// SPDX-License-Identifier: MIT
#pragma once
#include <stdint.h>
struct ButtonCommand {
 uint8_t candidate=0,stable=0,armed=0;uint64_t changed=0;
 char step(uint64_t now,uint8_t mask){
  mask&=3;
  if(mask!=candidate){candidate=mask;changed=now;}
  if(now<changed||now-changed<50||candidate==stable)return 0;
  uint8_t previous=stable;stable=candidate;
  if(stable==0){uint8_t action=armed;armed=0;return action==1?'f':action==2?'p':0;}
  if(previous==0&&(stable==1||stable==2))armed=stable;
  else armed=0; // Both buttons or an overlapping change cancels; never guess.
  return 0;
 }
};

// ---- esp32-epaper-refresh-budget.ino ----
// SPDX-License-Identifier: MIT
#include <Arduino.h>
#include <SPI.h>
#include <GxEPD2_BW.h>
#include <gdey/GxEPD2_213_GDEY0213B74.h>
#include "esp_timer.h"
#include "RefreshPlan.h"
#include "ButtonCommand.h"
constexpr int PIN_SCK=12,PIN_MOSI=11,PIN_CS=5,PIN_DC=4,PIN_RST=6,PIN_BUSY=10;
SPIClass epdSPI(FSPI);
GxEPD2_BW<GxEPD2_213_GDEY0213B74,GxEPD2_213_GDEY0213B74::HEIGHT>
 display(GxEPD2_213_GDEY0213B74(PIN_CS,PIN_DC,PIN_RST,PIN_BUSY));
RefreshPlan plan;CallBudget budget;ButtonCommand buttons;
constexpr int FULL_BUTTON=17,PARTIAL_BUTTON=18;
bool initialized=false,value=false;uint32_t sequence=0;
static uint64_t now_us(){return static_cast<uint64_t>(esp_timer_get_time());}
static bool is_busy(){return digitalRead(PIN_BUSY)==HIGH;}
void observe_busy(const void*){budget.observe(now_us(),is_busy());delay(1);}
bool preflight(){
 uint64_t start=now_us();while(is_busy()&&now_us()-start<2000000)delay(1);
 if(is_busy()){plan.fault();Serial.println("STOP BUSY HIGH before command; no display call started");return false;}
 return true;
}
void draw_test(){
 display.fillScreen(GxEPD_WHITE);display.setTextColor(GxEPD_BLACK);display.setTextSize(1);
 display.drawRect(0,0,display.width(),display.height(),GxEPD_BLACK);
 display.setCursor(8,16);display.print("GDEY0213B74 B/W");
 display.drawRect(8,32,112,64,GxEPD_BLACK);
 if(value)display.fillRect(16,40,40,40,GxEPD_BLACK);
 else display.drawRect(16,40,40,40,GxEPD_BLACK);
 display.setCursor(65,56);display.print(value?"VALUE 1":"VALUE 0");
 display.setCursor(132,48);display.print("STATIC");
 display.setCursor(132,65);display.print("BORDER");
 display.setCursor(8,113);display.print("Optics/current: NOT VERIFIED");
}
void refresh_test(char command){
 bool partial=command=='p';uint64_t requested=now_us();
 auto decision=plan.check(requested/1000,partial);
 if(decision!=RefreshPlan::ALLOW){Serial.printf("REJECT decision=%u: 1=stopped 2=wait180s 3=full baseline required\n",unsigned(decision));return;}
 if(!preflight())return;
 plan.begin(now_us()/1000);++sequence;value=!value;
 uint64_t started=now_us();budget.begin(started);
 /* Re-init only once after boot. Do not reset between full baseline and partials. */
 if(!initialized){display.init(115200,true,10,false);display.setRotation(1);initialized=true;}
 // This fixed driver uses compile-time fast-full waveform; never mutate it.
 if(partial)display.setPartialWindow(8,32,112,64);else display.setFullWindow();
 display.firstPage();do{draw_test();}while(display.nextPage());
 uint64_t refresh_return=now_us();
 if(!budget.finish(refresh_return,is_busy())){
  plan.fault();Serial.println("STOP call returned with BUSY/budget fault; cannot cancel inside library; power off and inspect");return;
 }
 /* powerOff retains our host baseline assumption only in this uninterrupted
    powered session. hibernate/reset/power loss always invalidates it below. */
 budget.begin(now_us());display.powerOff();uint64_t end=now_us();
 if(!budget.finish(end,is_busy())){plan.fault();Serial.println("STOP powerOff returned with BUSY/budget fault");return;}
 plan.success(partial);
 Serial.printf("D09,%lu,%c,%u,%llu,%llu,%llu,%u,%u\n",(unsigned long)sequence,command,unsigned(value),
  (unsigned long long)started,(unsigned long long)(refresh_return-started),
  (unsigned long long)(end-started),unsigned(is_busy()),plan.partials);
 Serial.println("CALL_RETURNED_BUSY_LOW only; record external photo/temperature/current. MCU remains awake.");
}
void hibernate_test(){
 if(plan.stopped||!initialized||!preflight())return;
 budget.begin(now_us());display.hibernate();
 if(!budget.finish(now_us(),is_busy())){plan.fault();Serial.println("STOP hibernate returned fault");return;}
 plan.hibernated();initialized=false;
 Serial.println("HIBERNATED: baseline invalid; next image must use f, not p. Board remains powered.");
}
void setup(){
 Serial.begin(115200);delay(300);pinMode(PIN_BUSY,INPUT);
 pinMode(FULL_BUTTON,INPUT);pinMode(PARTIAL_BUTTON,INPUT); // each external10k to3V3, SPST to GND
 digitalWrite(PIN_CS,HIGH);pinMode(PIN_CS,OUTPUT);
 if(!epdSPI.begin(PIN_SCK,-1,PIN_MOSI,PIN_CS)){plan.fault();Serial.println("STOP SPI begin failed");return;}
 display.epd2.selectSPI(epdSPI,SPISettings(4000000,MSBFIRST,SPI_MODE0));display.epd2.setBusyCallback(observe_busy);
 Serial.println("D09 confirmed GDEY0213B74 + DESPI-C02 P3=2.2ohm only; no automatic refresh");
 Serial.println("f=full-window fast waveform, p=partial(max5), h=hibernate+invalidate baseline; wait180s each refresh");
 Serial.println("Physical17=full / 18=partial, release after >=100ms; external10k pullups, both USB unplugged for metering");
 Serial.println("kind,seq,mode,value,start_us,refresh_call_us,through_poweroff_us,busy_after,partials_since_full");
}
void loop(){
 if(Serial.available()){char c=Serial.read();if(c=='f'||c=='p')refresh_test(c);else if(c=='h')hibernate_test();}
 uint8_t mask=(digitalRead(FULL_BUTTON)==LOW?1:0)|(digitalRead(PARTIAL_BUTTON)==LOW?2:0);
 char command=buttons.step(now_us()/1000,mask);if(command)refresh_test(command);
 delay(1);
}

# 下面列名、单位、电压/窗口都换成自己真实原始记录
python3 tools/normalize_trace.py raw.csv trace.csv --time-column REPLACE_TIME_COLUMN --time-unit us --current-column REPLACE_CURRENT_COLUMN --current-unit uA --voltage-column REPLACE_MEASURED_VOLTAGE_COLUMN
python3 tools/integrate_energy.py trace.csv --start REPLACE_START_S --end REPLACE_END_S --max-gap REPLACE_MAX_GAP_S
python3 tests/energy_test.py

# ---- tools/integrate_energy.py ----
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Integrate nonnegative sampled current and power over one covered time window.
Input CSV: t_s,voltage_V,current_mA. Linear interpolation of sampled P and I.
Synthetic tests prove arithmetic only, never an ESP32 measurement.
"""
import argparse,csv,json,math

def integrate(path,start,end,max_gap):
 if not all(math.isfinite(x) for x in (start,end,max_gap)) or start>=end or max_gap<=0:
  raise ValueError('finite start<end and positive max_gap required')
 previous=None;charge=energy=covered=0.0;rows=0
 with open(path,newline='') as stream:
  reader=csv.DictReader(stream)
  if not reader.fieldnames or not {'t_s','voltage_V','current_mA'}<=set(reader.fieldnames):raise ValueError('missing explicit units/columns')
  for row in reader:
   t,v,i=(float(row[k]) for k in ('t_s','voltage_V','current_mA'))
   if not all(math.isfinite(x) for x in (t,v,i)) or v<=0 or i<0:raise ValueError('nonfinite/negative current or nonpositive voltage; inspect zero offset')
   rows+=1
   if previous is not None:
    a,av,ai=previous;dt=t-a
    if dt<=0:raise ValueError('timestamps must strictly increase')
    left=max(a,start);right=min(t,end)
    if right>left:
     if dt>max_gap+1e-12:raise ValueError('sample gap exceeds declared limit in window')
     f0=(left-a)/dt;f1=(right-a)/dt
     i0=ai+(i-ai)*f0;i1=ai+(i-ai)*f1
     p0=av*ai+(v*i-av*ai)*f0;p1=av*ai+(v*i-av*ai)*f1
     charge+=(i0+i1)*0.5*(right-left);energy+=(p0+p1)*0.5*(right-left);covered+=right-left
   previous=(t,v,i)
 if rows<2 or not math.isclose(covered,end-start,rel_tol=1e-8,abs_tol=1e-9):raise ValueError('window not fully bracketed by samples; no extrapolation')
 return {'start_s':start,'end_s':end,'duration_s':end-start,'input_rows':rows,'max_gap_s':max_gap,'charge_mC':charge,'energy_mJ':energy,'energy_mWh':energy/3600,'mean_current_mA':charge/(end-start),'method':'trapezoid of sampled nonnegative I and V*I; interpolate cut endpoints; includes whole measured input'}

if __name__=='__main__':
 parser=argparse.ArgumentParser();parser.add_argument('csv');parser.add_argument('--start',required=True,type=float);parser.add_argument('--end',required=True,type=float);parser.add_argument('--max-gap',required=True,type=float);args=parser.parse_args()
 print(json.dumps(integrate(args.csv,args.start,args.end,args.max_gap),indent=2,allow_nan=False))