@em-foundation/emscope 25.3.0 → 25.4.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## VERSION-25-4.1
+
+* more robust port enumeration fix for PPK
+
+## VERSION-25-4.0
+
+* added `--json` option
+* port enumeration fix for PPK
+
 ## VERSION-25-3.0
 
 * aligned with new `BlueJoule/capture` directory structure

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

@@ -13158,17 +13158,57 @@ async function powerOn(voltage) {
   progress.done();
 }
 async function findDevices() {
-  let res = new Array();
+  let candidates = new Array();
   for (const port of await import_serialport.SerialPort.list()) {
     const vid = port.vendorId;
     const pid = port.productId;
     if (vid == "1915" && pid.toLowerCase() == "c00a") {
-      res.push(port.path);
+      candidates.push(port.path);
+    }
+  }
+  fail("no PPK2 analyzer found", candidates.length == 0);
+  if (candidates.length == 1) return candidates;
+  const res = new Array();
+  for (const path of candidates) {
+    if (await probeDataPort(path)) {
+      res.push(path);
     }
   }
-  fail("no PPK2 analyzer found", res.length == 0);
+  fail("no PPK2 data port found (tried probing all candidates)", res.length == 0);
   return res;
 }
+async function probeDataPort(path, timeoutMs = 500) {
+  let port;
+  try {
+    port = new import_serialport.SerialPort({ path, baudRate: 9600, autoOpen: false });
+    await new Promise((resolve, reject) => {
+      port.open((err) => err ? reject(err) : resolve());
+    });
+    return await new Promise((resolve) => {
+      let responded = false;
+      const onData = () => {
+        if (!responded) {
+          responded = true;
+          resolve(true);
+        }
+      };
+      port.on("data", onData);
+      port.write([25 /* GET_META_DATA */]);
+      setTimeout(() => {
+        if (!responded) {
+          responded = true;
+          resolve(false);
+        }
+      }, timeoutMs);
+    });
+  } catch {
+    return false;
+  } finally {
+    if (port?.isOpen) {
+      await new Promise((resolve) => port.close(() => resolve()));
+    }
+  }
+}
 function parseMods(mods) {
   mods = mods.replace("END", "").trim().toLowerCase().replace(/-nan/g, "null").replace(/\n/g, ',\n"').replace(/: /g, '": ');
   let res;
@@ -13509,8 +13549,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) {
@@ -13518,16 +13559,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'`);
@@ -13577,6 +13618,27 @@ function printEventInfo(cap, markers) {
   infoMsg("----");
   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)}`);
@@ -13594,9 +13656,39 @@ function printResults(cap, aobj, ev_rate, score_only) {
   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 = ${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
 var import_index = __toESM(require_commander(), 1);
@@ -13621,7 +13713,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);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@em-foundation/emscope",
-    "version": "25.3.0",
+    "version": "25.4.1",
     "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"
     },