@em-foundation/emscope 25.1.0 → 25.3.0

package/CHANGELOG.md

@@ -1,4 +1,18 @@
-## VERSION-25-0.2
+## VERSION-25-3.0
+
+* aligned with new `BlueJoule/capture` directory structure
+* streamlined generation of `ABOUT.md` with automatic HW/SW inclusion
+* one digit of precision after the decimal point in most results
+
+## VERSION-25-2.0
+
+* new `emscope grab -p, --ppk-supply` option
+* new `emscope scan --refresh` option
+* adds capture_time to generated .jls file
+* minor bug fixes
+* works with Joulescope UI 1.3.9
+
+## VERSION-25-1.0
 
 * uses `BlueJoule` repo as exemplar
 * updated `README` documentation

package/dist/emscope

@@ -12323,6 +12323,7 @@ var Capture = class _Capture {
     "duration",
     "sampling_rate",
     "sample_count",
+    "version",
     "voltage"
   ];
   static #SAVE_KEYS = [
@@ -12335,6 +12336,7 @@ var Capture = class _Capture {
     cap._rootdir = rootdir;
     cap._duration = duration;
     cap._device = device;
+    cap._version = version();
     cap._voltage = voltage;
     cap._creation_date = /* @__PURE__ */ new Date();
     cap._sampling_rate = _Capture.#SAMPLING_RATE.get(device) ?? 0;
@@ -12612,9 +12614,6 @@ var Window = class {
     return this.#off >= 0 && this.#off + this.#wid <= this.#sig.data.length;
   }
 };
-function amps(val) {
-  return toEng(val, "A");
-}
 function fail(msg, cond = true) {
   if (cond) {
     console.log(`*** ${msg} ***`);
@@ -12625,7 +12624,7 @@ function infoMsg(msg) {
   console.log(`${TAB}${msg}`);
 }
 function joules(j) {
-  return toEng(j, "J");
+  return toEng(j, "J", 0);
 }
 function parseHms(s) {
   if (/^\d+$/.test(s)) return Number(s);
@@ -12643,12 +12642,18 @@ function secsToHms(total) {
   const pad = (n) => n.toString().padStart(2, "0");
   return `${pad(h)}:${pad(m)}:${pad(s)}`;
 }
-function toEng(x, u) {
+function toEng(x, u, e) {
   if (x == 0) return `0 ${u}`;
-  const exp = Math.floor(Math.log10(Math.abs(x)) / 3) * 3;
+  const exp = e ?? Math.floor(Math.log10(Math.abs(x)) / 3) * 3;
   const mantissa = x / 10 ** exp;
   const unit = { [-9]: ` n${u}`, [-6]: ` \xB5${u}`, [-3]: ` m${u}`, [0]: ` ${u}`, [3]: ` k${u}` }[exp] || `e${exp} ${u}`;
-  return `${mantissa.toFixed(3).padStart(7, " ")}${unit}`;
+  return `${mantissa.toFixed(1).padStart(4, " ")}${unit}`;
+}
+function uAmps(val) {
+  return toEng(val, "A", -6);
+}
+function uJoules(j) {
+  return toEng(j, "J", -6);
 }
 function version() {
   const path = import_path.default.resolve(__dirname, "..", "package.json");
@@ -12686,10 +12691,28 @@ ${dpath}:`);
 // src/Detecter.ts
 function exec(opts) {
   const cap = Capture.load(opts.capture);
-  const aobj = analyze(cap, opts.trim, opts.gap, opts.minDuration, opts.minEnergy);
+  let params = {};
+  if (opts.refresh) {
+    if (cap.analysis) {
+      for (const opt of cap.analysis?.options) {
+        const a = opt.split(" ");
+        const [pname, pval] = [a[0].slice(2), Number(a[1])];
+        params[pname] = Number(pval);
+      }
+      if (Number.isNaN(params.trim)) {
+        params.trim = cap.analysis.events.length;
+      }
+    }
+  } else {
+    params.gap = opts.gap;
+    params.min_dur = opts.minDuration;
+    params.min_egy = opts.minEnergy;
+    params.trim = opts.trim;
+  }
+  const aobj = analyze(cap, params);
   cap.bind(aobj);
 }
-function analyze(cap, trim, gap, min_dur, min_egy) {
+function analyze(cap, params = {}) {
   infoMsg("analyzing captured data...");
   const rsig = cap.current_sig;
   const width = rsig.secsToOff(25e-5);
@@ -12717,26 +12740,26 @@ function analyze(cap, trim, gap, min_dur, min_egy) {
     }
   }
   let options = new Array();
-  if (gap !== void 0) {
-    markers = combineMarkers(rsig, markers, rsig.secsToOff(gap / 1e3));
-    options.push(`--gap ${gap}`);
+  if (params.gap !== void 0) {
+    markers = combineMarkers(rsig, markers, rsig.secsToOff(params.gap / 1e3));
+    options.push(`--gap ${params.gap}`);
   }
-  if (min_dur != void 0) {
-    const min_wid = rsig.secsToOff(min_dur / 1e3);
+  if (params.min_dur != void 0) {
+    const min_wid = rsig.secsToOff(params.min_dur / 1e3);
     markers = markers.filter((m) => m.width >= min_wid);
-    options.push(`--min-duration ${min_dur}`);
+    options.push(`--min-duration ${params.min_dur}`);
   }
-  if (min_egy != void 0) {
-    markers = markers.filter((m) => cap.energyWithin(m) >= min_egy / 1e6);
-    options.push(`--min-energy ${min_egy}`);
+  if (params.min_egy != void 0) {
+    markers = markers.filter((m) => cap.energyWithin(m) >= params.min_egy / 1e6);
+    options.push(`--min-energy ${params.min_egy}`);
   }
   let span = rsig.window(rsig.data.length).toMarker();
-  if (trim) {
-    [span, markers] = trimEvents(cap, markers, trim);
-    options.push(`--trim ${trim}`);
+  if (params.trim) {
+    [span, markers] = trimEvents(cap, markers, params.trim);
+    options.push(`--trim ${params.trim}`);
   }
   infoMsg(`found ${markers.length} event(s)`);
-  return { span, events: markers, sleep: si, options };
+  return { span, events: markers, sleep: si, options, version: version() };
 }
 function combineMarkers(sig, markers, gap) {
   let res = new Array();
@@ -12797,6 +12820,7 @@ function trimEvents(cap, markers, count) {
 }
 
 // src/AboutFile.ts
+var ChildProc = __toESM(require("child_process"));
 var Fs3 = __toESM(require("fs"));
 var Path3 = __toESM(require("path"));
 var TAG = "@emscope-pack";
@@ -12805,25 +12829,10 @@ var END = `<!-- ${TAG}:end -->`;
 var RE = /<!--\s*@emscope-pack:start\s*-->[\s\S]*?<!--\s*@emscope-pack:end\s*-->/m;
 function update(capdir) {
   const cap = Capture.load(capdir);
-  const TXT = `
-<h1 align="center">Hardware Platform \xB7 Software Environment</h1>
-
-## HW/SW configuration
-
-## EM&bull;Scope results
+  const TXT = `<h1 align="center">Hardware Platform \xB7 Software Environment \xB7 xVx</h1>
 
 ${START}
-
 ${END}
-
-## Typical event
-
-<p align="center">
-    <img src="event-ID.png" alt="Event" width="900">
-</p>
-
-## Observations
-
 `;
   const file = Path3.join(cap.rootdir, "ABOUT.md");
   if (!Fs3.existsSync(file)) {
@@ -12831,10 +12840,7 @@ ${END}
   }
   const src = Fs3.readFileSync(file, "utf-8");
   const gen = mkGen(cap);
-  const block = `${START}
-
-${gen}
-
+  const block = `${START}${gen}
 ${END}`;
   const out = RE.test(src) ? src.replace(RE, block) : `${src.replace(/\s*$/, "")}
 
@@ -12842,8 +12848,26 @@ ${block}
 `;
   Fs3.writeFileSync(file, out);
 }
+function getBuildDir(cap) {
+  const bn = Path3.basename(cap.rootdir).split("-")[0];
+  return Path3.join(Path3.dirname(cap.rootdir), bn);
+}
+function getEvtId(cap) {
+  for (const fn of Fs3.readdirSync(cap.rootdir)) {
+    const m = fn.match(/^event\-([A-Z])\.png$/);
+    if (m) return m[1];
+  }
+  fail(`no 'event-ID.png' file found`);
+  return "";
+}
 function mkGen(cap) {
-  const aobj = cap.analysis ?? analyze(cap);
+  fail(`no prior analysis: run 'emscope scan ...'`, cap.analysis === void 0);
+  const brd = Path3.basename(Path3.dirname(cap.rootdir));
+  const brd_txt = readBrdTxt(brd);
+  const bld_dir = getBuildDir(cap);
+  const bld_txt = readBldTxt(bld_dir);
+  const eid = getEvtId(cap);
+  const aobj = cap.analysis;
   const si = aobj.sleep;
   const sl_v = cap.avg_voltage;
   const sl_avg = aobj.sleep.avg;
@@ -12856,31 +12880,83 @@ function mkGen(cap) {
   const egy10_s = sl_pwr * 10 + egy1_e;
   const egy10_d = egy10_s * 86400 / 10;
   const ems10 = 80 / egy10_d;
-  const date = (/* @__PURE__ */ new Date()).toISOString();
+  const cap_date = mkTimestamp(cap.creation_date);
+  const gen_date = mkTimestamp(/* @__PURE__ */ new Date());
   const GEN = `
+
+<!-- *** AUTOMATICALLY GENERATED CONTENT \u2013 DO NOT EDIT *** -->  
+
+<p align="right"><sub>captured on ${cap_date}<br>generated on ${gen_date}</sub></p>
+
+## HW/SW Configuration
+
+${brd_txt}
+${bld_txt}
+
+
+## EM&bull;Scope results \xB7 ${cap.device}
+
 ### \u{1F7E0}&ensp;sleep
 
 | supply voltage | &emsp;current (avg)&emsp; | &emsp;current (std)&emsp; | &emsp;average power&emsp;
 |:---:|:---:|:---:|:---:|
-| ${sl_v.toFixed(2)} V | ${amps(sl_avg)} | ${amps(sl_std)} | ${toEng(sl_pwr, "W")} |
+| ${sl_v.toFixed(1)} V | ${uAmps(sl_avg)} | ${uAmps(sl_std)} | ${toEng(sl_pwr, "W")} |
 
 ### \u{1F7E0}&ensp;1&thinsp;s event period
 
 | &emsp;&emsp;event energy (avg)&emsp;&emsp; | &emsp;&emsp;energy per period&emsp;&emsp; | &emsp;&emsp;energy per day&emsp;&emsp; | &emsp;&emsp;&emsp;**EM&bull;eralds**&emsp;&emsp;&emsp;
 |:---:|:---:|:---:|:---:|
-| ${joules(egy1_e)} | ${joules(egy1_s)} | ${joules(egy1_d)} | ${ems1.toFixed(2)} |
+| ${uJoules(egy1_e)} | ${uJoules(egy1_s)} | ${joules(egy1_d)} | ${ems1.toFixed(2)} |
 
 ### \u{1F7E0}&ensp;10&thinsp;s event period
 
 | &emsp;&emsp;event energy (avg)&emsp;&emsp; | &emsp;&emsp;energy per period&emsp;&emsp; | &emsp;&emsp;energy per day&emsp;&emsp; | &emsp;&emsp;&emsp;**EM&bull;eralds**&emsp;&emsp;&emsp;
 |:---:|:---:|:---:|:---:|
-| ${joules(egy1_e)} | ${joules(egy10_s)} | ${joules(egy10_d)} | ${ems10.toFixed(2)} |
+| ${uJoules(egy1_e)} | ${uJoules(egy10_s)} | ${joules(egy10_d)} | ${ems10.toFixed(2)} |
+
+## Typical Event
+
+<p align="center"><img src="event-${eid}.png" alt="Event" width="900"></p>
 
-<br>
-<p align="right"><sub>generated at ${date}</sub></p>
-    `;
+## Notes
+`;
   return GEN;
 }
+function mkTimestamp(d) {
+  const ds = d.toISOString().split("T")[0];
+  const pad = (n) => String(n).padStart(2, "0");
+  const HH = pad(d.getUTCHours());
+  const MM = pad(d.getUTCMinutes());
+  const SS = pad(d.getUTCSeconds());
+  const ts = `${HH}:${MM}:${SS}`;
+  return `${ds} @ ${ts}`;
+}
+function readBldTxt(bld_dir) {
+  try {
+    const txt = Fs3.readFileSync(Path3.join(bld_dir, "BUILD.md"), { encoding: "utf-8" });
+    return `${txt}
+* [BUILD ARTIFACTS](../${Path3.basename(bld_dir)}) &thinsp;\u2699\uFE0F
+`;
+  } catch (e) {
+    console.log(`... skipping 'BUILD.md' inclusion`);
+  }
+  return "";
+}
+function readBrdTxt(brd) {
+  const url = `https://raw.githubusercontent.com/em-foundation/emscope/docs-stable/docs/boards/${brd}.md`;
+  const is_win = process.platform === "win32";
+  const cmd = is_win ? "curl.exe" : "curl";
+  const args = is_win ? ["-fsSL", "--tlsv1.2", "--ssl-no-revoke", url] : ["-fsSL", url];
+  try {
+    const txt = ChildProc.execFileSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return `${txt}
+* [BOARD PINOUT](https://github.com/em-foundation/emscope/blob/docs-stable/docs/boards/${brd}.png) &thinsp;\u2699\uFE0F
+`;
+  } catch (e) {
+    console.log(`... skipping 'BOARD.md' inclusion`);
+  }
+  return "";
+}
 
 // src/Exporter.ts
 var import_adm_zip = __toESM(require_adm_zip());
@@ -12911,6 +12987,16 @@ function deflateLfs(repo, gpath) {
   import_child_process.default.execFileSync("git", ["lfs", "pull", "--include", gpath], { cwd: repo, stdio: "inherit" });
   import_child_process.default.execFileSync("git", ["lfs", "checkout", gpath], { cwd: repo, stdio: "inherit" });
 }
+function fetchOid(repo, gpath) {
+  let res = "";
+  try {
+    const out = import_child_process.default.execFileSync("git", ["show", gpath], { cwd: repo, stdio: ["ignore", "pipe", "ignore"] }).toString();
+    const m = out.match(/^\s*oid sha256:([0-9a-f]{64})/m);
+    if (m) res = m[1];
+  } catch {
+  }
+  return res;
+}
 function findRepoDir(capdir) {
   let repo = "";
   let dir = capdir;
@@ -12951,6 +13037,12 @@ function toggleLfs(capdir, opts) {
     import_fs2.default.rmSync(Capture.workdir(capdir), { recursive: true });
     return;
   }
+  const oid = fetchOid(repo, `:${gpath}`);
+  fail(`'emscope-capture.zip' not yet committed`, !oid);
+  const oid_head = fetchOid(repo, `HEAD:${gpath}`);
+  if (oid_head && oid_head != oid) {
+    restoreLfs(repo, gpath);
+  }
   if (desc_flag) {
     deflateLfs(repo, gpath);
   }
@@ -13027,10 +13119,6 @@ var DATALOSS_THRESHOLD = 500;
 var getMaskedValue = (value, { mask, pos }) => (value & mask) >> pos;
 async function execCapture2(opts) {
   const path_list = await findDevices();
-  if (path_list.length == 0) {
-    console.error("*** no PPK2 analyzer");
-    process.exit(1);
-  }
   const progress = new Progress("capturing: ");
   const port = new import_serialport.SerialPort({ path: path_list[0], baudRate: 9600, autoOpen: false });
   await new Promise((resolve, reject) => {
@@ -13040,7 +13128,7 @@ async function execCapture2(opts) {
   port.on("data", () => {
   });
   const cap = Capture.create(opts.capture, opts.duration, "PPK2", opts.voltage);
-  const ppk = new PPK2(port, cap);
+  const ppk = new PPK2(port);
   await ppk.getModifiers();
   if (opts.ampereMode) {
     ppk.setMode("ampere");
@@ -13049,11 +13137,26 @@ async function execCapture2(opts) {
     ppk.setSourceVoltage(cap.voltage * 1e3);
   }
   ppk.togglePower("on");
-  await ppk.capture(progress);
+  await ppk.record(cap, progress);
   ppk.togglePower("off");
   ppk.close();
   return cap;
 }
+async function powerOn(voltage) {
+  const path_list = await findDevices();
+  const progress = new Progress("powering: ");
+  const port = new import_serialport.SerialPort({ path: path_list[0], baudRate: 9600, autoOpen: false });
+  await new Promise((resolve, reject) => {
+    port.open((err) => err ? reject(err) : resolve());
+  });
+  await progress.spin(2500);
+  const ppk = new PPK2(port);
+  await ppk.getModifiers();
+  ppk.setMode("source");
+  ppk.setSourceVoltage(voltage * 1e3);
+  ppk.togglePower("on");
+  progress.done();
+}
 async function findDevices() {
   let res = new Array();
   for (const port of await import_serialport.SerialPort.list()) {
@@ -13063,6 +13166,7 @@ async function findDevices() {
       res.push(port.path);
     }
   }
+  fail("no PPK2 analyzer found", res.length == 0);
   return res;
 }
 function parseMods(mods) {
@@ -13077,7 +13181,6 @@ function parseMods(mods) {
   return res;
 }
 var PPK2 = class {
-  #cap;
   #port;
   #modifiers = {
     r: [1031.64, 101.65, 10.15, 0.94, 0.043],
@@ -13103,15 +13206,14 @@ var PPK2 = class {
   #afterSpike;
   #consecutiveRangeSample;
   #currentVdd = 0;
-  constructor(port, cap) {
-    this.#cap = cap;
+  constructor(port) {
     this.#port = port;
   }
-  async capture(progress) {
+  async record(cap, progress) {
     await progress.spin(2e3);
     this.startMeasurement();
     return await new Promise((resolve) => {
-      const raw = Buffer.allocUnsafe(this.#cap.duration * 1e5 * 4);
+      const raw = Buffer.allocUnsafe(cap.duration * 1e5 * 4);
       let offset = 0;
       this.#port.on("data", (buf) => {
         progress.update(`${(offset / 1e5 / 4).toFixed(3)} s`);
@@ -13124,7 +13226,7 @@ var PPK2 = class {
           });
           this.stopMeasurement();
           for (const adcVal of new Uint32Array(raw.buffer, raw.byteOffset, raw.length / 4)) {
-            this.#cap.current_ds.add(this.#handleRawDataSet(adcVal) / 1e6);
+            cap.current_ds.add(this.#handleRawDataSet(adcVal) / 1e6);
           }
           resolve();
         }
@@ -13269,6 +13371,10 @@ var PPK2 = class {
 async function exec3(opts) {
   let c;
   if (opts.js220) {
+    if (opts.ppk2Supply) {
+      const voltage = opts.ppk2Supply === true ? 3.3 : Number(opts.ppk2Supply);
+      await powerOn(voltage);
+    }
     c = await execCapture(opts);
   } else if (opts.ppk2) {
     c = await execCapture2(opts);
@@ -13290,7 +13396,7 @@ function saveSignal(cap, cname, span, markers = []) {
   const msig_I = cap.current_sig.window(span.width, span.offset).toSignal();
   const msig_V = cap.voltage_sig.window(span.width, span.offset).toSignal();
   const data_V = msig_V.data.length > 0 ? msig_V.data : new Float32Array(msig_I.data.length).fill(cap.avg_voltage);
-  writer.store(msig_I.data, data_V, msig_I.sample_rate);
+  writer.store(msig_I.data, data_V, msig_I.sample_rate, Math.trunc(cap.creation_date.getTime() / 1e3));
   let cobj = {
     id: "joulescope.ui.waveform_widget",
     version: "1.0",
@@ -13346,7 +13452,8 @@ var WriterAux = class _WriterAux {
     this.#jfile.close();
     infoMsg(`wrote '${this.cname}.jls'`);
   }
-  store(f32_I, f32_V, sample_rate) {
+  store(f32_I, f32_V, sample_rate, utc) {
+    utc = Date.now() / 1e3;
     const sdef = {
       source_id: 1,
       name: "mysource",
@@ -13374,11 +13481,13 @@ var WriterAux = class _WriterAux {
     };
     this.#jfile.signalDef(sigdef);
     this.#jfile.writeF32(1, f32_I);
+    this.#jfile.setTime(1, utc);
     sigdef.signal_id = 2;
     sigdef.name = "voltage";
     sigdef.units = "V";
     this.#jfile.signalDef(sigdef);
     this.#jfile.writeF32(2, f32_V);
+    this.#jfile.setTime(2, utc);
     const f32_W = new Float32Array(f32_I.length);
     for (let i = 0; i < f32_W.length; i++) {
       f32_W[i] = f32_I[i] * f32_V[i];
@@ -13388,6 +13497,7 @@ var WriterAux = class _WriterAux {
     sigdef.units = "W";
     this.#jfile.signalDef(sigdef);
     this.#jfile.writeF32(3, f32_W);
+    this.#jfile.setTime(3, utc);
   }
 };
 
@@ -13397,7 +13507,8 @@ var import_os = __toESM(require("os"));
 var import_path3 = __toESM(require("path"));
 function exec4(opts) {
   const cap = Capture.load(opts.capture);
-  const aobj = cap.analysis ?? analyze(cap);
+  fail(`no prior analysis: run 'emscope scan ...'`, cap.analysis === void 0);
+  const aobj = cap.analysis;
   if (opts.eventInfo) {
     printEventInfo(cap, aobj.events);
     return;
@@ -13458,34 +13569,33 @@ function printEventInfo(cap, markers) {
   for (const m of markers) {
     const egy = cap.energyWithin(m);
     avg += egy * scale;
-    const dur = (cap.current_sig.offToSecs(m.width) * 1e3).toFixed(3).padStart(7, " ");
-    const dur_s = cap.current_sig.offToSecs(m.width);
+    const dur = (cap.current_sig.offToSecs(m.width) * 1e3).toFixed(2).padStart(5, " ");
     const off_s = cap.current_sig.offToSecs(m.offset).toFixed(2).padStart(5, " ");
-    infoMsg(`${lab} :: time = ${off_s} s, energy = ${joules(egy)}, duration = ${toEng(dur_s, "s")}`);
+    infoMsg(`${lab} :: time = ${off_s} s, energy = ${uJoules(egy)}, duration = ${dur} s`);
     lab = String.fromCharCode(lab.charCodeAt(0) + 1);
   }
   infoMsg("----");
-  infoMsg(`average energy over ${markers.length} event(s): ${joules(avg)}`);
+  infoMsg(`average energy over ${markers.length} event(s): ${uJoules(avg)}`);
 }
 function printResults(cap, aobj, ev_rate, score_only) {
   const sleep_pwr = aobj.sleep.avg * cap.avg_voltage;
-  score_only || infoMsg(`event period: ${secsToHms(ev_rate)}`);
-  score_only || infoMsg(`average sleep power: ${toEng(sleep_pwr, "W")}`);
+  score_only || infoMsg(`event period:        ${secsToHms(ev_rate)}`);
+  score_only || infoMsg(`average sleep power:  ${toEng(sleep_pwr, "W")}`);
   score_only || infoMsg("----");
   const egy_1s = cap.energyWithin(aobj.span) / cap.current_sig.offToSecs(aobj.span.width);
   const egy_1e = egy_1s - sleep_pwr * 1;
   const egy_1c = sleep_pwr * ev_rate + egy_1e;
-  score_only || infoMsg(`representative event: ${joules(egy_1e)}`);
-  score_only || infoMsg(`energy per period: ${joules(egy_1c)}`);
+  score_only || infoMsg(`representative event: ${uJoules(egy_1e)}`);
+  score_only || infoMsg(`energy per period:    ${uJoules(egy_1c)}`);
   const egy_1d = egy_1c * 86400 / ev_rate;
-  score_only || infoMsg(`energy per day: ${joules(egy_1d)}`);
+  score_only || infoMsg(`energy per day:       ${joules(egy_1d)}`);
   const egy_1m = egy_1d * 30;
   const ems = 2400 / egy_1m;
   score_only || infoMsg("----");
   infoMsg(`${ems.toFixed(2)} EM\u2022eralds`);
 }
 function printSleepInfo(cap, si) {
-  infoMsg(`sleep current = ${amps(si.avg)} @ ${cap.avg_voltage.toFixed(2)} V, standard deviation = ${amps(si.std)}`);
+  infoMsg(`sleep current = ${uAmps(si.avg).trim()} @ ${cap.avg_voltage.toFixed(1)} V, standard deviation = ${uAmps(si.std).trim()}`);
 }
 
 // node_modules/commander/esm.mjs
@@ -13509,8 +13619,8 @@ var {
 var CAP = ["-c --capture <directory path>", "working capture directory", "."];
 var VERS = version();
 var CMD = new Command("emscope").option("-C, --capture-glob [name pattern]", `apply this command to each matching child capture directory (default "**")`).version(VERS);
-CMD.command("grab").description("record power signals with an attached capture device").option(CAP[0], CAP[1], CAP[2]).option("-d --duration <value>", "capture duration in seconds", parseFloat, 3).option("-J --js220", "use a Joulescope JS220 device").option("-P --ppk2", "use a Nordic PPK2 device").addOption(new Option("-A --ampere-mode", "enable PPK ampere mode").conflicts(["sourceMode", "js220"])).addOption(new Option("-S --source-mode", "enable PPK source mode").default(true).conflicts(["ampereMode", "js220"])).addOption(new Option("-v, --voltage [value]", "source voltage").argParser(parseFloat).default(3.3).conflicts("js220")).action((opts, cmd) => execCmd(exec3, opts, cmd.parent.opts()));
-CMD.command("scan").description("analyze captured data and locate active events").option(CAP[0], CAP[1], CAP[2]).option("-d, --min-duration <milliseconds>", "remove events whose duration is under a threshold", parseFloat).option("-e, --min-energy <microJoules>", "remove events whose energy is under a threshold", parseFloat).option("-g, --gap <milliseconds>", "combine adjacent events whose gap is under a threshold", parseFloat).option("-t --trim <event count>", "remove extra events", parseFloat).action((opts, cmd) => execCmd(exec, opts, cmd.parent.opts()));
+CMD.command("grab").description("record power signals with an attached capture device").option(CAP[0], CAP[1], CAP[2]).option("-d --duration <value>", "capture duration in seconds", parseFloat, 3).option("-J --js220", "use a Joulescope JS220 device").option("-P --ppk2", "use a Nordic PPK2 device").addOption(new Option("-A --ampere-mode", "enable PPK ampere mode").conflicts(["sourceMode", "js220"])).addOption(new Option("-S --source-mode", "enable PPK source mode").default(true).conflicts(["ampereMode", "js220"])).addOption(new Option("-p, --ppk2-supply [voltage]", "supply JS220 voltage from a PPK").argParser(parseFloat).conflicts("ppk2")).addOption(new Option("-v, --voltage [value]", "source voltage").argParser(parseFloat).default(3.3).conflicts("js220")).action((opts, cmd) => execCmd(exec3, opts, cmd.parent.opts()));
+CMD.command("scan").description("analyze captured data and locate active events").option(CAP[0], CAP[1], CAP[2]).option("-d, --min-duration <milliseconds>", "remove events whose duration is under a threshold", parseFloat).option("-e, --min-energy <microJoules>", "remove events whose energy is under a threshold", parseFloat).option("-g, --gap <milliseconds>", "combine adjacent events whose gap is under a threshold", parseFloat).option("-t --trim <event count>", "remove extra events", parseFloat).option("--refresh", "(re-)scan using the last set of options").action((opts, cmd) => execCmd(exec, opts, cmd.parent.opts()));
 CMD.command("view").description("present captured data in different formats").option(CAP[0], CAP[1], CAP[2]).option("-e --event-info", "characterize power consumption when active").option("-j --jls-file [event ID]", "generate a Joulescope .jls file containing events").option("-s --sleep-info", "characterize power consumption when inactive").option("-w --what-if [event period]", `extrapolate results for a given event period (default: '00:00:01')`, parseHms).option("--score", "only print the EM\u2022eralds benchmark score").action((opts, cmd) => execCmd(exec4, opts, cmd.parent.opts()));
 CMD.command("pack").description(`bundle captured data into an 'emscope.zip' file`).option(CAP[0], CAP[1], CAP[2]).option("-a --about-file", `update the 'ABOUT.md' file only`).option("-s,--status", `status of the 'emscope.zip' file`).option("-u --unpack", `deflate the 'emscope.zip' file for local use`).option("-z --zip-file", `generate the 'emscope.zip' file`).option("--restore", `restores the 'emscope.zip' LFS descriptor (debug only)`).action((opts, cmd) => execCmd(exec2, opts, cmd.parent.opts()));
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@em-foundation/emscope",
-    "version": "25.1.0",
+    "version": "25.3.0",
     "description": "benchmark energy efficiency in resource-constrained embedded systems",
     "bin": {
         "emscope": "dist/emscope"
@@ -32,14 +32,14 @@
     "bugs": {
         "url": "https://github.com/em-foundation/emscope/issues"
     },
-    "homepage": "https://github.com/em-foundation/emscope/blob/main/docs/ReadMore.md",
+    "homepage": "https://github.com/em-foundation/emscope/blob/docs-stable/docs/ReadMore.md",
     "dependencies": {
         "@serialport/bindings-cpp": "^13.0.1",
         "@types/adm-zip": "^0.5.7",
         "@types/js-yaml": "^4.0.9",
         "adm-zip": "^0.5.16",
         "commander": "^14.0.0",
-        "jls-writer": "https://github.com/em-foundation/npm-packages/releases/download/resources/jls-writer-0.0.2.tgz",
+        "jls-writer": "https://github.com/em-foundation/npm-packages/releases/download/resources/jls-writer-0.0.3.tgz",
         "joulescope_driver": "^1.10.0",
         "js-yaml": "^4.1.0",
         "picomatch": "^4.0.3",
@@ -50,4 +50,4 @@
         "@types/picomatch": "^4.0.2",
         "esbuild": "^0.25.8"
     }
-}
+}