@em-foundation/emscope 25.2.0 → 25.4.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## VERSION-25-4.0
+
+* added `--json` option
+* port enumeration fix for PPK
+
+## 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

package/README.md

@@ -1,4 +1,15 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/em-foundation/emscope/main/docs/images/splash.png"
-       alt="EM•Scope" width="840">
-</p>
+    <img src="docs/images/logo.png" alt="EM•Scope Logo" width="400">
+</p>
+<br>
+<p align="center">
+    <img src="docs/images/tagline.png" alt="EM•Scope TagLine" width="750">
+</p>
+
+-----
+
+The **EM&bull;Scope** tool streamlines the capture, analysis, display, and delivery of real-time power-consumption measurements &ndash; used to characterize the overall energy efficiency of resource-constrained embedded systems.&thinsp; To encourage benchmarks for different HW/SW configurations performing comparable tasks, **EM&bull;Scope** introduces a novel metric for quantifying energy efficiency &ndash; the **EM&bull;erald**.
+ 
+<p align="right">
+  <a href="https://github.com/em-foundation/emscope/blob/docs-stable/docs/ReadMore.md">read more<b>&nbsp;&#x27a6;</b></a>
+</p>

package/dist/emscope

@@ -12614,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} ***`);
@@ -12627,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);
@@ -12645,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");
@@ -12817,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";
@@ -12825,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)) {
@@ -12851,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*$/, "")}
 
@@ -12862,8 +12848,25 @@ ${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) {
   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;
@@ -12877,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
 
-<br>
-<p align="right"><sub>generated at ${date}</sub></p>
-    `;
+<p align="center"><img src="event-${eid}.png" alt="Event" width="900"></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());
@@ -13112,6 +13167,7 @@ async function findDevices() {
     }
   }
   fail("no PPK2 analyzer found", res.length == 0);
+  res.sort();
   return res;
 }
 function parseMods(mods) {
@@ -13454,8 +13510,9 @@ function exec4(opts) {
   const cap = Capture.load(opts.capture);
   fail(`no prior analysis: run 'emscope scan ...'`, cap.analysis === void 0);
   const aobj = cap.analysis;
+  const json2 = !!opts.json;
   if (opts.eventInfo) {
-    printEventInfo(cap, aobj.events);
+    json2 ? printEventInfoJson(cap, aobj.events) : printEventInfo(cap, aobj.events);
     return;
   }
   if (opts.jlsFile) {
@@ -13463,16 +13520,16 @@ function exec4(opts) {
     return;
   }
   if (opts.sleepInfo) {
-    printSleepInfo(cap, aobj.sleep);
+    json2 ? printSleepInfoJson(cap, aobj.sleep) : printSleepInfo(cap, aobj.sleep);
     return;
   }
   if (opts.whatIf !== void 0) {
     const ev_rate = opts.whatIf === true ? 1 : opts.whatIf;
-    printResults(cap, aobj, ev_rate, opts.score);
+    json2 ? printResultsJson(cap, aobj, ev_rate) : printResults(cap, aobj, ev_rate, opts.score);
     return;
   }
   if (opts.score) {
-    printResults(cap, aobj, 1, true);
+    json2 ? printResultsJson(cap, aobj, 1) : printResults(cap, aobj, 1, true);
     return;
   }
   fail(`no options found: run 'emscope view -h'`);
@@ -13514,34 +13571,84 @@ 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 printEventInfoJson(cap, markers) {
+  const events = markers.map((m, i) => {
+    const energy = cap.energyWithin(m);
+    const duration = cap.current_sig.offToSecs(m.width);
+    const time = cap.current_sig.offToSecs(m.offset);
+    return {
+      id: String.fromCharCode("A".charCodeAt(0) + i),
+      time,
+      energy,
+      duration
+    };
+  });
+  const totalEnergy = events.reduce((sum, e) => sum + e.energy, 0);
+  const avgEnergy = events.length > 0 ? totalEnergy / events.length : 0;
+  console.log(JSON.stringify({
+    type: "event_info",
+    eventCount: events.length,
+    averageEnergy: avgEnergy,
+    events
+  }));
 }
 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 printResultsJson(cap, aobj, ev_rate) {
+  const sleep_pwr = aobj.sleep.avg * cap.avg_voltage;
+  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;
+  const egy_1d = egy_1c * 86400 / ev_rate;
+  const egy_1m = egy_1d * 30;
+  const ems = 2400 / egy_1m;
+  console.log(JSON.stringify({
+    type: "score",
+    emeralds: parseFloat(ems.toFixed(2)),
+    cycleRate: ev_rate,
+    sleepCurrent: aobj.sleep.avg,
+    sleepPower: sleep_pwr,
+    voltage: cap.avg_voltage,
+    eventEnergy: egy_1e,
+    energyPerCycle: egy_1c,
+    energyPerDay: egy_1d,
+    energyPerMonth: egy_1m
+  }));
+}
 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()}`);
+}
+function printSleepInfoJson(cap, si) {
+  console.log(JSON.stringify({
+    type: "sleep_info",
+    sleepCurrent: si.avg,
+    standardDeviation: si.std,
+    voltage: cap.avg_voltage,
+    sleepPower: si.avg * cap.avg_voltage
+  }));
 }
 
 // node_modules/commander/esm.mjs
@@ -13567,7 +13674,7 @@ 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("-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("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").option("--json", "output results as JSON (machine-readable)").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 {
   CMD.parse(process.argv);
@@ -13580,3 +13687,4 @@ try {
 js-yaml/dist/js-yaml.mjs:
   (*! js-yaml 4.1.0 https://github.com/nodeca/js-yaml @license MIT *)
 */
+//# sourceMappingURL=emscope.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@em-foundation/emscope",
-    "version": "25.2.0",
+    "version": "25.4.0",
     "description": "benchmark energy efficiency in resource-constrained embedded systems",
     "bin": {
         "emscope": "dist/emscope"
@@ -29,6 +29,9 @@
     "author": "The EM Foundation",
     "license": "MIT",
     "preferGlobal": true,
+    "publishConfig": {
+        "access": "public"
+    },
     "bugs": {
         "url": "https://github.com/em-foundation/emscope/issues"
     },