led-matrix-controllers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jacob Padgett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# LED Matrix Controllers
+
+Cross-firmware controllers and tooling for the [Framework Laptop 16 LED matrix module](https://frame.work/products/16-led-matrix) using WebHID and Web Serial APIs
+
+## Supported Firmwares
+
+- https://github.com/FrameworkComputer/inputmodule-rs (Out-of-box default)
+- https://github.com/vddCore/sparkle-fw16
+- https://github.com/sigroot/FW_LED_Matrix_Firmware
+
+If you maintain another firmware or a fork, please open an issue or submit a PR!
+
+## Quick Start
+
+### Installation
+
+WIP
+
+### Usage
+
+WIP
+
+## Development
+
+### Prerequisites
+
+* **Node.js** (v16.9.0 or later recommended for corepack)
+
+### Installation
+
+Setup development environment
+
+```bash
+npm install -g corepack 
+corepack enable
+yarn set version stable
+yarn install
+```
+
+Bundle (optional)
+
+```bash
+yarn build
+```

package/dist/led-matrix-controllers.browser.mjs

@@ -0,0 +1,2 @@
+const t=9,e=34,r=12972,a=[50,172],i=32,n=[0,32],s=Object.freeze([0,0,0,0,0,0,0,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,2,3,3,3,3,3,3,3,4,4,4,4,4,4,5,5,5,5,6,6,6,6,6,7,7,7,7,8,8,8,9,9,9,10,10,10,11,11,11,12,12,12,13,13,14,14,14,15,15,16,16,17,17,17,18,18,19,19,20,20,21,22,22,23,23,24,24,25,26,26,27,27,28,29,29,30,31,32,32,33,34,34,35,36,37,38,38,39,40,41,42,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,66,67,68,69,70,71,73,74,75,76,78,79,80,82,83,84,86,87,88,90,91,93,94,96,97,99,100,102,103,105,106,108,110,111,113,115,116,118,120,121,123,125,127,128,130,132,134,136,138,140,141,143,145,147,149,151,153,155,157,159,161,164,166,168,170,172,174,177,179,181,183,186,188,190,193,195,197,200,202,205,207,210,212,215,217,220,222,225,228,230,233,236,238,241,244,247,249,252,255]),o=[],c=[{vendorId:12972,productId:32}];class l extends Error{constructor(){super("User cancelled device selection."),this.name=this.constructor.name,this.date=new Date}}class d{constructor(t){this.#t=t}async send(t,e){if(e.length<t.bytes)e=function(t,e,r=0){return t.concat(new Array(e-t.length).fill(r))}(e,t.bytes);else if(e.length>t.bytes)throw new Error("Unable to send report: too many bytes");const r=new Uint8Array(e).buffer;t.feature?await this.#t.sendFeatureReport(t.id,r):await this.#t.sendReport(t.buffer)}async receive(t){let e=[];if(!t.feature)throw new Error("Invalid operation");return e=await this.#t.receiveFeatureReport(t.id),e.byteLength!=t.bytes&&console.error(`reply length=${e.byteLength} (exp ${t.bytes})`),e}#t}const h={id:1,bytes:307,feature:!0},w={id:2,bytes:16,feature:!0},u={id:4,bytes:306,feature:!0},p=0,y=1,f=2,m=3,A=5;class E{constructor(t){this.#e=t}async info(){const t=await this.#e.receive(h);return{sleep_pin:t.getUint8(1),dip1_pin:t.getUint8(2),intb_pin:t.getUint8(3),state_flags:t.getUint8(4),id_reg:t.getUint8(5),config_reg:t.getUint8(6),global_brightness:t.getUint8(7),display_width:t.getUint8(8),display_height:t.getUint8(9),timeout_ms:t.getUint32(10)}}async wake(){await this.#e.send(w,[y,!1])}async sleep(){await this.#e.send(w,[y,!0])}async disableSleep(){await this.#e.send(w,[m,255,255,255,255])}async disableDeepSleep(){await this.#e.send(w,[f,1])}async disableSleepTimer(){await this.#e.send(w,[m,0,0,0,0])}async enableDeepSleep(){await this.#e.send(w,[f,0])}async enableSleepTimer(t){const e=new DataView(new ArrayBuffer(4));e.setInt32(0,t,!1),await this.#e.send(w,[m,e.getUint8(0),e.getUint8(1),e.getUint8(2),e.getUint8(3)])}async reboot(t){await this.#e.send(w,[p,t])}async drawPixel(t,e,r){await this.#e.send(w,[A,e,t,r])}async drawLine({r1:t,c1:e},{r2:r,c2:a},i){await this.#e.send(w,[A,t,e,r,a,i])}async verifyFirmware(){try{const t=await this.info();return 34==t.display_height&&9==t.display_width}catch{return!1}}async version(){return{major:1,minor:0}}async draw(t){return await this.#e.send(u,t.flat().map(t=>s[Math.floor(255*(t??0))]))}#e}class O{static async make(t){const e=await async function(){if(o&&o.length>0)return o.pop();if(o.push(...await navigator.hid.getDevices()),o&&o.length>0)return o.pop();if(o.push(...await navigator.hid.requestDevice({filters:c})),o&&o.length>0)return o.pop();throw new l}();if(e){if("sparkle"===t)return await O.makeSparkleController(e);throw new Error(`Unsupported firmware type: ${t}`)}return null}static async makeSparkleController(t){if(t)return await t.open(),new E(new d(t))}}class b{constructor(t){this.#r=`port-mutex-${Math.random().toString()}`,this.#a=new Map,this.#i=t}async acquire(t){const e=new Error("created bad cb").stack;await this.#n(async()=>{try{await t(this.#i)}catch(t){console.error("Error occured in anonymous callback."),console.error("Original error:",t),console.error("--- This callback was created at ---\n",e)}})}async acquireIdempotent(t,e){const r=new Error("created bad cb").stack;this.#a.has(t)&&console.info(`"${t}" request coalesced.`),this.#a.set(t,async()=>{try{await e(this.#i)}catch(t){console.error("Error occured in anonymous callback."),console.error("Original error:",t),console.error("--- This callback was created at ---\n",r)}}),await this.#n(()=>this.#s(t))}async#n(t){return navigator.locks.request(this.#r,t)}async#s(t){if(this.#a.has(t)){const e=this.#a.get(t);this.#a.delete(t),await e()}}#r;#a;#i}class _{constructor(t){this.#o=t}async rx(t,e=3e3){if(null===this.#o)throw new Error("attempted RX before port initialization.");if(this.#o.readable.locked)throw new Error("attempted RX while port locked.");const r=[],a=this.#o.readable.getReader(),i=setTimeout(()=>a.cancel(),e);try{for(;r.length<t;){const{value:t,done:e}=await a.read();if(r.push(...t??[]),e||!t)break}}finally{clearTimeout(i),a.releaseLock()}return r}async tx(t){if(null===this.#o)throw new Error("attempted TX before port initialization.");if(this.#o.writable.locked)throw new Error("attempted TX while port locked.");const e=this.#o.writable.getWriter();try{await e.write(new Uint8Array(t))}finally{await e.close()}}#o}class g extends Error{constructor(){super("User cancelled port selection."),this.name=this.constructor.name,this.date=new Date}}class T extends Error{constructor(){super("Selected port already in use."),this.name=this.constructor.name,this.date=new Date}}async function I(t){try{await t.close()}catch(t){if("InvalidStateError"!=t.name&&"Failed to execute 'close' on 'SerialPort': The port is already closed."!=t.message)throw t}}const S=Object.freeze({ANIMATE:4,BRIGHTNESS:0,BOOTLOADER:2,DRAW:6,DRAW_GREY_COL_BUFFER:8,GAME_CTRL:17,GAME_STATUS:18,PANIC:5,PATTERN:1,SLEEP:3,STAGE_GREY_COL:7,START_GAME:16,VERSION:32}),M=Object.freeze({GRAY_8BIT:"8-bit",MONO_1BIT:"1-bit"});class R{constructor(t){this.#c=M.MONO_1BIT,this.#l=t}async verifyFirmware(){let t=null;await this.#l.acquire(async e=>{await e.tx([...a,S.VERSION]),t=await e.rx(32)});const e=32==t.length,r=t.slice(3).every(t=>0==t);return e&&r}async version(){let t={};return await this.#l.acquire(async e=>{await e.tx([...a,S.VERSION]);const r=await e.rx(32);t.major=r[0],t.minor=r[1]>>4,t.patch=15&r[1],t.preRelease=1==r[2]}),t}async draw(t){if(this.#c==M.GRAY_8BIT){const e=Array.from({length:9},(e,r)=>new Array({length:34},(e,a)=>GAMMA[Math.floor(255*(t[a][r]??0))]));await this.#l.acquireIdempotent("drawMatrix",async t=>{for(let r=0;r<9;r++)await t.tx([S.STAGE_GREY_COL,r,...e[r]]);await t.tx([S.DRAW_GREY_COL_BUFFER])})}else if(this.#c==M.MONO_1BIT){let e=0,r=new Uint8Array(39).fill(0);for(let a=0;a<34;a++)for(let i=0;i<9;i++)t[a][i]&&(r[e>>3]|=1<<e%8),e++;await this.#l.acquireIdempotent("drawMatrix",async t=>{await t.tx([...a,S.DRAW,...r])})}}#c;#l}const x=Object.freeze({NOOP:0,ANIMATION_DIAMOND:100,ANIMATION_FIRE:98,ANIMATION_FIREPLACE:102,ANIMATION_GEAR:103,ANIMATION_RING:114,ANIMATION_STARTUP:97,ANIMATION_STARTUP_ONCE:65,BOOTLOADER:101,DRAW_PWM:109,DRAW_PWM_BLOCKING:77,DRAW_SCALE:110,DRAW_SCALE_BLOCKING:78,FLUSH_CMD_QUEUE:99,TEST_PATTERN:116,SET_CONST_PWM:119,SET_CONST_SCALE:115,SET_PX_PWM:112,SET_PX_SCALE:113,IDENT:127}),N=/^Sig\sFW\sLED\sMatrix\sFW\sV(\d+)\.(\d+)$/;class D{constructor(t){this.#l=t}async verifyFirmware(){let t=null;return await this.#l.acquire(async e=>{await e.tx([x.IDENT]),t=await e.rx(25)}),t=String.fromCharCode(...t),t.match(N)}async version(){let t=null;await this.#l.acquire(async e=>{await e.tx([x.IDENT]),t=await e.rx(25)}),t=String.fromCharCode(...t);const e=t.match(N);return e&&3==e.length?{major:e[1],minor:e[2]}:null}async draw(t){this.#d||(await this.#l.acquire(async t=>{await t.tx([x.SET_CONST_SCALE,32])}),this.#d=!0);const e=t.flat().map(t=>s[Math.floor(255*(t??0))]);await this.#l.acquireIdempotent("drawMatrix",async t=>{await t.tx([x.DRAW_PWM,...e])})}#l;#d}class k{static async make(t){const e=await async function(){try{const t=await navigator.serial.requestPort(),{usbProductId:e,usbVendorId:r}=t;return console.log("Selected port:",t),e&&r&&console.log(`VID:PID ${r}:${e}`),t}catch(t){throw"NotFoundError"==t.name?new g:"InvalidStateError"==t.name?new T:t}}();if(e){if("framework-official"===t)return await k.makeDefaultWebController(e);if("sigroot"===t)return await k.makeSigrootWebController(e);if("auto"===t)return await k.makeAutoWebController(e);throw new Error(`Unsupported firmware type: ${t}`)}}static async makeDefaultWebController(t){if(t?.connected)return await I(t),await t.open({baudRate:115200}),new R(new b(new _(t)))}static async makeSigrootWebController(t){if(t?.connected)return await I(t),await t.open({baudRate:115200}),new D(new b(new _(t)))}static async makeAutoWebController(t){const e=await this.makeDefaultWebController(t);if(await e.verifyFirmware())return e;const r=await this.makeSigrootWebController(t);return await r.verifyFirmware()?r:void 0}}export{s as GAMMA,e as HEIGHT,O as HIDControllerFactory,i as PID,n as PID_ARR,k as SerialControllerFactory,r as VID,a as VID_ARR,t as WIDTH};
+//# sourceMappingURL=led-matrix-controllers.browser.mjs.map

package/dist/led-matrix-controllers.browser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"led-matrix-controllers.browser.mjs","sources":["../src/hardware-constants.js","../src/usb-hid/environments/web/device.js","../src/usb-hid/environments/web/HIDOperations.js","../src/usb-hid/environments/web/util.js","../src/usb-hid/firmware/sparkle/reports.js","../src/usb-hid/firmware/sparkle/SparkleController.js","../src/usb-hid/HIDControllerFactory.js","../src/usb-serial/environments/web/PortMutex.js","../src/usb-serial/environments/web/PortOperations.js","../src/usb-serial/environments/web/port.js","../src/usb-serial/firmware/framework-official/commands.js","../src/usb-serial/firmware/framework-official/DefaultController.js","../src/usb-serial/firmware/sigroot/commands.js","../src/usb-serial/firmware/sigroot/SigrootController.js","../src/usb-serial/SerialControllerFactory.js"],"sourcesContent":["export const WIDTH = 9;\r\nexport const HEIGHT = 34;\r\nexport const VID = 0x32AC;\r\nexport const VID_ARR = [0x32, 0xAC];\r\nexport const PID = 0x0020;\r\nexport const PID_ARR = [0x00, 0x20];\r\n\r\nexport const GAMMA = Object.freeze([\r\n  0, 0, 0, 0, 0, 0, 0, 1, \r\n  1, 1, 1, 1, 1, 1, 1, 1, \r\n  1, 1, 1, 1, 1, 1, 1, 1, \r\n  1, 1, 1, 1, 1, 1, 1, 1, \r\n  1, 1, 1, 2, 2, 2, 2, 2, \r\n  2, 2, 2, 2, 3, 3, 3, 3, \r\n  3, 3, 3, 4, 4, 4, 4, 4, \r\n  4, 5, 5, 5, 5, 6, 6, 6, \r\n  6, 6, 7, 7, 7, 7, 8, 8, \r\n  8, 9, 9, 9, 10, 10, 10, 11, \r\n  11, 11, 12, 12, 12, 13, 13, 14, \r\n  14, 14, 15, 15, 16, 16, 17, 17, \r\n  17, 18, 18, 19, 19, 20, 20, 21, \r\n  22, 22, 23, 23, 24, 24, 25, 26, \r\n  26, 27, 27, 28, 29, 29, 30, 31, \r\n  32, 32, 33, 34, 34, 35, 36, 37, \r\n  38, 38, 39, 40, 41, 42, 42, 43, \r\n  44, 45, 46, 47, 48, 49, 50, 51, \r\n  52, 53, 54, 55, 56, 57, 58, 59, \r\n  60, 61, 62, 63, 64, 66, 67, 68, \r\n  69, 70, 71, 73, 74, 75, 76, 78, \r\n  79, 80, 82, 83, 84, 86, 87, 88, \r\n  90, 91, 93, 94, 96, 97, 99, 100, \r\n  102, 103, 105, 106, 108, 110, 111, 113, \r\n  115, 116, 118, 120, 121, 123, 125, 127, \r\n  128, 130, 132, 134, 136, 138, 140, 141, \r\n  143, 145, 147, 149, 151, 153, 155, 157, \r\n  159, 161, 164, 166, 168, 170, 172, 174, \r\n  177, 179, 181, 183, 186, 188, 190, 193, \r\n  195, 197, 200, 202, 205, 207, 210, 212, \r\n  215, 217, 220, 222, 225, 228, 230, 233, \r\n  236, 238, 241, 244, 247, 249, 252, 255\r\n]);\r\n","import { PID, VID } from '../../../hardware-constants.js';\r\n\r\nconst extraDevices = [];\r\n\r\nconst filters = [\r\n  {\r\n    vendorId: VID,\r\n    productId: PID,\r\n  }\r\n]\r\n\r\nexport class DeviceSelectionCancelled extends Error {\r\n  constructor() {\r\n    super('User cancelled device selection.');\r\n    this.name = this.constructor.name;\r\n    this.date = new Date();\r\n  }\r\n}\r\n\r\nexport async function getDevice() {\r\n  if (extraDevices && extraDevices.length > 0) {\r\n    return extraDevices.pop();\r\n  }\r\n\r\n  extraDevices.push(...(await navigator.hid.getDevices()));\r\n  if (extraDevices && extraDevices.length > 0) {\r\n    return extraDevices.pop();\r\n  }\r\n\r\n  extraDevices.push(...(await navigator.hid.requestDevice({ filters })));\r\n  if (extraDevices && extraDevices.length > 0) {\r\n    return extraDevices.pop();\r\n  }\r\n\r\n  throw new DeviceSelectionCancelled();\r\n}\r\n","import { pad } from './util.js';\r\n\r\nexport class HIDOperations {\r\n  constructor(device) {\r\n    this.#device = device;\r\n  }\r\n\r\n  async send(report, data) {\r\n    if (data.length < report.bytes) {\r\n      data = pad(data, report.bytes);\r\n    } else if (data.length > report.bytes) {\r\n      throw new Error('Unable to send report: too many bytes');\r\n    }\r\n\r\n    const buffer = new Uint8Array(data).buffer;\r\n\r\n    if (report.feature)  {\r\n      await this.#device.sendFeatureReport(report.id, buffer);\r\n    } else {\r\n      await this.#device.sendReport(report.buffer);\r\n    }\r\n  }\r\n\r\n  async receive(report) {\r\n    let reply = [];\r\n\r\n    if (report.feature) {\r\n      reply = await this.#device.receiveFeatureReport(report.id);\r\n    } else {\r\n      /* \r\n       * HID input reports are used for unprompted data.\r\n       * An event system must be used.\r\n       * See WebHID `HIDInputReportEvent`\r\n       */\r\n      throw new Error('Invalid operation');\r\n    }\r\n\r\n    if (reply.byteLength != report.bytes) {\r\n      console.error(`reply length=${reply.byteLength} (exp ${report.bytes})`);\r\n    }\r\n\r\n    return reply;\r\n  }\r\n\r\n  #device;\r\n}\r\n","export function pad(arr, len, val=0x00) {\r\n  return arr.concat(new Array(len - arr.length).fill(val));\r\n}\r\n","export const Reports = {\r\n  GLITTER_DEVICE_INFO: {\r\n    id: 0x01,\r\n    bytes: 307,\r\n    feature: true,\r\n  },\r\n  GLITTER_BASIC_CMD: {\r\n    id: 0x02,\r\n    bytes: 16,\r\n    feature: true,\r\n  },\r\n  GLITTER_GRID_PWM_CNTL: {\r\n    id: 0x03,\r\n    bytes: 306,\r\n    feature: true,\r\n  },\r\n  GLITTER_GRID_PWM_CNTL: {\r\n    id: 0x04,\r\n    bytes: 306,\r\n    feature: true,\r\n  }\r\n}\r\n\r\nexport const Commands = {\r\n  GLITTER_CMD_REBOOT: 0x00,\r\n  GLITTER_CMD_SLEEP: 0x01,\r\n  GLITTER_CMD_WAKE_ON_COMMAND: 0x02,\r\n  GLITTER_CMD_SET_SLEEP_TIMEOUT: 0x03,\r\n  GLITTER_CMD_SET_GLOBAL_BRIGHTNESS: 0x04,\r\n  GLITTER_CMD_DRAW_PIXEL: 0x05,\r\n  GLITTER_CMD_DRAW_LINE: 0x06\r\n}\r\n\r\nexport const BootMode = {\r\n  BOOTSEL: 0x00,\r\n  NORMAL: 0x01,\r\n}\r\n","import { GAMMA, HEIGHT, WIDTH } from '../../../hardware-constants.js';\r\nimport { Commands, Reports } from './reports.js';\r\n\r\nexport class SparkleController {\r\n  constructor(hidOps) {\r\n    this.#hidOps = hidOps;\r\n  }\r\n\r\n  async info() {\r\n    const infoRaw = await this.#hidOps.receive(Reports.GLITTER_DEVICE_INFO);\r\n\r\n    return {\r\n      sleep_pin: infoRaw.getUint8(1),\r\n      dip1_pin: infoRaw.getUint8(2),\r\n      intb_pin: infoRaw.getUint8(3),\r\n      state_flags: infoRaw.getUint8(4),\r\n      id_reg: infoRaw.getUint8(5),\r\n      config_reg: infoRaw.getUint8(6),\r\n      global_brightness: infoRaw.getUint8(7),\r\n      display_width: infoRaw.getUint8(8),\r\n      display_height: infoRaw.getUint8(9),\r\n      timeout_ms: infoRaw.getUint32(10),\r\n    };\r\n  }\r\n\r\n  async wake() {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD,\r\n      [Commands.GLITTER_CMD_SLEEP, false]\r\n    );\r\n  }\r\n\r\n  async sleep() {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD,\r\n      [Commands.GLITTER_CMD_SLEEP, true]\r\n    );\r\n  }\r\n\r\n  async disableSleep() {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD, \r\n      [Commands.GLITTER_CMD_SET_SLEEP_TIMEOUT, 0xff, 0xff, 0xff, 0xff]\r\n    );\r\n  }\r\n\r\n  async disableDeepSleep() {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD, \r\n      [Commands.GLITTER_CMD_WAKE_ON_COMMAND, 0x01]\r\n    );\r\n  }\r\n\r\n  async disableSleepTimer() {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD, \r\n      [Commands.GLITTER_CMD_SET_SLEEP_TIMEOUT, 0x00, 0x00, 0x00, 0x00]\r\n    );\r\n  }\r\n  \r\n  async enableDeepSleep() {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD, \r\n      [Commands.GLITTER_CMD_WAKE_ON_COMMAND, 0x00]\r\n    );\r\n  }\r\n\r\n  async enableSleepTimer(milliseconds) {\r\n    const view = new DataView(new ArrayBuffer(4));\r\n    const littleEndian = false;\r\n    view.setInt32(0, milliseconds, littleEndian);\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD, \r\n      [\r\n        Commands.GLITTER_CMD_SET_SLEEP_TIMEOUT, \r\n        view.getUint8(0), \r\n        view.getUint8(1), \r\n        view.getUint8(2), \r\n        view.getUint8(3),\r\n      ]\r\n    );\r\n  }\r\n\r\n  async reboot(mode) {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD, \r\n      [Commands.GLITTER_CMD_REBOOT, mode]\r\n    );\r\n  }\r\n\r\n  async drawPixel(r, c, brightness) {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD,\r\n      [Commands.GLITTER_CMD_DRAW_PIXEL, c, r, brightness]\r\n    );\r\n  }\r\n\r\n  async drawLine({r1, c1}, {r2, c2}, brightness) {\r\n    await this.#hidOps.send(\r\n      Reports.GLITTER_BASIC_CMD,\r\n      [Commands.GLITTER_CMD_DRAW_PIXEL, r1, c1, r2, c2, brightness]\r\n    );\r\n  }\r\n\r\n  // --- generic methods ---\r\n\r\n  async verifyFirmware() {\r\n    try {\r\n      const info = await this.info();\r\n      return (\r\n        info.display_height == HEIGHT &&\r\n        info.display_width == WIDTH\r\n      );\r\n    } catch {\r\n      return false;\r\n    }\r\n  }\r\n\r\n  async version() {\r\n    // Not Available\r\n    return { major: 1, minor: 0 };\r\n  }\r\n\r\n  async draw(matrix) {\r\n    return await this.#hidOps.send(\r\n      Reports.GLITTER_GRID_PWM_CNTL,\r\n      matrix.flat().map(v => GAMMA[Math.floor((v ?? 0) * 255)])\r\n    );\r\n  }\r\n\r\n  #hidOps;\r\n}\r\n","import { getDevice } from './environments/web/device.js';\r\nimport { HIDOperations } from './environments/web/HIDOperations.js';\r\nimport { SparkleController } from './firmware/sparkle/SparkleController.js';\r\n\r\nexport class HIDControllerFactory {\r\n  static async make(firmware) {\r\n    const device = await getDevice();\r\n    if (device) {\r\n      if (firmware === 'sparkle') {\r\n        return await HIDControllerFactory.makeSparkleController(device);\r\n      } else {\r\n        throw new Error(`Unsupported firmware type: ${firmware}`);\r\n      }\r\n    } else {\r\n      return null;\r\n    }\r\n  }\r\n\r\n  static async makeSparkleController(device) {\r\n    if (device) {\r\n      await device.open();\r\n      return new SparkleController(\r\n        new HIDOperations(device)\r\n      );\r\n    }\r\n  }\r\n}\r\n","export class PortMutex {\r\n  constructor(portOperations) {\r\n    this.#lockName = `port-mutex-${Math.random().toString()}`;\r\n    this.#deduper = new Map();\r\n    this.#portOps = portOperations;\r\n  }\r\n\r\n  async acquire(fn) {\r\n    const trace = new Error('created bad cb').stack;\r\n\r\n    await this.#enqueue(async () => {\r\n      try {\r\n        await fn(this.#portOps);\r\n      } catch (e) {\r\n        console.error('Error occured in anonymous callback.');\r\n        console.error('Original error:', e);\r\n        console.error('--- This callback was created at ---\\n', trace);\r\n      }\r\n    });\r\n  }\r\n\r\n  async acquireIdempotent(key, fn) {\r\n    const trace = new Error('created bad cb').stack;\r\n\r\n    if  (this.#deduper.has(key)) {\r\n      console.info(`\"${key}\" request coalesced.`);\r\n    }\r\n\r\n    this.#deduper.set(key, async () => {\r\n      try {\r\n        await fn(this.#portOps);\r\n      } catch (e) {\r\n        console.error('Error occured in anonymous callback.');\r\n        console.error('Original error:', e);\r\n        console.error('--- This callback was created at ---\\n', trace);\r\n      }\r\n    });\r\n\r\n    await this.#enqueue(() => this.#execDedupedOp(key));\r\n  }\r\n\r\n  async #enqueue(fn) {\r\n    // `navigator.locks` maintains queue and provides mutual exclusion.\r\n    return navigator.locks.request(this.#lockName, fn);\r\n  }\r\n\r\n  async #execDedupedOp(key) {\r\n    if (this.#deduper.has(key)) {\r\n      const fn = this.#deduper.get(key);\r\n      this.#deduper.delete(key);\r\n      await fn();\r\n    }\r\n  }\r\n\r\n  #lockName;\r\n  #deduper;\r\n  #portOps;\r\n}\r\n","export class PortOperations {\r\n  constructor(port) {\r\n    this.#port = port;\r\n  }\r\n\r\n  async rx(length, timeout=3000) {\r\n    if (this.#port === null) {\r\n      throw new Error('attempted RX before port initialization.');\r\n    }\r\n\r\n    /*\r\n     * ReadableStream's built-in locking mechanism cannot be awaited or otherwise\r\n     * asynchronously acquired. A PortMutex must be used.\r\n     */\r\n    if (this.#port.readable.locked) {\r\n      throw new Error('attempted RX while port locked.');\r\n    }\r\n\r\n    const response = [];\r\n    const reader = this.#port.readable.getReader();\r\n    const timeoutHandle = setTimeout(() => reader.cancel(), timeout);\r\n\r\n    try {\r\n      // Response may be divided across multiple reads\r\n      while (response.length < length) {\r\n        const { value, done } = await reader.read();\r\n        response.push(...(value ?? []));\r\n        if (done || !value) break;\r\n      }\r\n    } finally {\r\n      clearTimeout(timeoutHandle);\r\n      reader.releaseLock();\r\n    }\r\n\r\n    return response;\r\n  }\r\n\r\n  async tx(buffer) {\r\n    if (this.#port === null) {\r\n      throw new Error('attempted TX before port initialization.');\r\n    }\r\n    \r\n    /*\r\n     * WritableStream's built-in locking mechanism cannot be awaited or otherwise\r\n     * asynchronously acquired. A PortMutex must be used.\r\n     */\r\n    if (this.#port.writable.locked) {\r\n      throw new Error('attempted TX while port locked.');\r\n    }\r\n\r\n    const writer = this.#port.writable.getWriter();\r\n\r\n    try {\r\n      await writer.write(new Uint8Array(buffer));\r\n    } finally {\r\n      /* \r\n       * The writer must be completely torn down between every single write.\r\n       * Many parsers can't handle delayed flushing and write coalescing.\r\n       * Command sequences will fail if `releaseLock()` is used here.\r\n       */\r\n      await writer.close();\r\n    }\r\n  }\r\n\r\n  #port;\r\n}\r\n","export class PortSelectionCancelled extends Error {\r\n  constructor() {\r\n    super('User cancelled port selection.');\r\n    this.name = this.constructor.name;\r\n    this.date = new Date();\r\n  }\r\n}\r\n\r\nexport class PortUnavailable extends Error {\r\n  constructor() {\r\n    super('Selected port already in use.');\r\n    this.name = this.constructor.name;\r\n    this.date = new Date();\r\n  }\r\n}\r\n\r\nexport async function getPort() {\r\n  try {\r\n    const port = await navigator.serial.requestPort();\r\n    const { usbProductId, usbVendorId } = port;\r\n    console.log('Selected port:', port);\r\n    if (usbProductId && usbVendorId) {\r\n      console.log(`VID:PID ${usbVendorId}:${usbProductId}`);\r\n    }\r\n    return port;\r\n  } catch (e) {\r\n    if (e.name == 'NotFoundError') {\r\n      throw new PortSelectionCancelled();\r\n    } else if (e.name == 'InvalidStateError') {\r\n      throw new PortUnavailable();\r\n    } else {\r\n      throw e;\r\n    }\r\n  }\r\n}\r\n\r\nexport async function close(port) {\r\n  try {\r\n    await port.close();\r\n  } catch(e) {\r\n    if (e.name != 'InvalidStateError') {\r\n      if (e.message != \"Failed to execute 'close' on 'SerialPort': The port is already closed.\") {\r\n        throw e;\r\n      }\r\n    }\r\n  }\r\n}\r\n","// All replies to all commands are 32 bytes\r\nexport const RX_PACKET_SZ = 32;\r\n\r\nexport const Command = Object.freeze({\r\n  ANIMATE: 0x04,\r\n  BRIGHTNESS: 0x00,\r\n  BOOTLOADER: 0x02,\r\n  DRAW: 0x06,\r\n  DRAW_GREY_COL_BUFFER: 0x08,\r\n  GAME_CTRL: 0x11,\r\n  GAME_STATUS: 0x12,\r\n  PANIC: 0x05,\r\n  PATTERN: 0x01,\r\n  SLEEP: 0x03,\r\n  STAGE_GREY_COL: 0x07,\r\n  START_GAME: 0x10,\r\n  VERSION: 0x20,\r\n});\r\n\r\n// Used with Command.PATTERN\r\nexport const Pattern = Object.freeze({\r\n  DISPLAY_LOTUS_HORIZONTAL: 0x03,\r\n  DISPLAY_LOTUS_VERTICAL: 0x07,\r\n  DISPLAY_PANIC: 0x06,\r\n  DOUBLE_GRADIENT: 0x02,\r\n  FULL_BRIGHTNESS: 0x05,\r\n  GRADIENT: 0x01,\r\n  PERCENTAGE: 0x00,\r\n  ZIG_ZAG: 0x04,\r\n});\r\n\r\n// DRAW or DRAW_GREY_COL_BUFFER\r\nexport const BitDepth = Object.freeze({\r\n  GRAY_8BIT: '8-bit',\r\n  MONO_1BIT: '1-bit',\r\n})\r\n","import { HEIGHT, VID_ARR, WIDTH } from '../../../hardware-constants.js';\r\nimport { BitDepth, Command, RX_PACKET_SZ } from './commands.js';\r\n\r\nexport class DefaultController {\r\n  constructor(portMutex) {\r\n    this.#bitDepth = BitDepth.MONO_1BIT;\r\n    this.#portMutex = portMutex;\r\n  }\r\n\r\n  async verifyFirmware() {\r\n    let packet = null;\r\n\r\n    await this.#portMutex.acquire(async p => {\r\n      await p.tx([...VID_ARR, Command.VERSION]);\r\n      packet = await p.rx(RX_PACKET_SZ);\r\n    });\r\n\r\n    const isPacket = packet.length == RX_PACKET_SZ;\r\n    const isPadded = packet.slice(3).every(e => e == 0x00);\r\n\r\n    return isPacket && isPadded;\r\n  }\r\n\r\n  async version() {\r\n    let ver = {};\r\n\r\n    await this.#portMutex.acquire(async p => {\r\n      await p.tx([...VID_ARR, Command.VERSION]);\r\n      const response = await p.rx(RX_PACKET_SZ);\r\n\r\n      // MMMMMMMM mmmmPPPP 0000000p\r\n      ver.major = response[0];\r\n      ver.minor = response[1] >> 4;\r\n      ver.patch = response[1] & 0x0F;\r\n      ver.preRelease = response[2] == 1;\r\n    });\r\n\r\n    return ver;\r\n  }\r\n\r\n  async draw(matrix) {\r\n    if (this.#bitDepth == BitDepth.GRAY_8BIT) {\r\n      // Transpose & Gamma Correction\r\n      const payloads = Array.from(\r\n        { length: WIDTH }, \r\n        (_, c) => new Array(\r\n          { length: HEIGHT }, \r\n          (_, r) => GAMMA[Math.floor((matrix[r][c] ?? 0) * 255)]\r\n        )\r\n      );\r\n\r\n      // Only execute the most recent call \r\n      await this.#portMutex.acquireIdempotent(\r\n        'drawMatrix', \r\n        async p => {\r\n          for (let i = 0; i < WIDTH; i++) {\r\n            await p.tx([Command.STAGE_GREY_COL, i, ...payloads[i]]);\r\n          }\r\n          await p.tx([Command.DRAW_GREY_COL_BUFFER]);\r\n        }\r\n      );\r\n    }\r\n\r\n    else if (this.#bitDepth == BitDepth.MONO_1BIT) {\r\n      let index = 0;\r\n      let output = new Uint8Array(39).fill(0);\r\n\r\n      // Pack cells into bits\r\n      for (let r = 0; r < HEIGHT; r++) {\r\n        for (let c = 0; c < WIDTH; c++) {\r\n          if (matrix[r][c]) {\r\n            output[index >> 3] |= 1 << index % 8;\r\n          }\r\n          index++;\r\n        }\r\n      }\r\n\r\n      await this.#portMutex.acquireIdempotent(\r\n        'drawMatrix', \r\n        async p => {\r\n          await p.tx([...VID_ARR, Command.DRAW, ...output]);\r\n        }\r\n      );\r\n    }\r\n  }\r\n\r\n  #bitDepth;\r\n  #portMutex;\r\n}\r\n","export const Command = Object.freeze({\r\n  /* 000 */ NOOP: 0x00,\r\n  /* 'd' */ ANIMATION_DIAMOND: 0x64,\r\n  /* 'b' */ ANIMATION_FIRE: 0x62,\r\n  /* 'f' */ ANIMATION_FIREPLACE: 0x66,\r\n  /* 'g' */ ANIMATION_GEAR: 0x67,\r\n  /* 'r' */ ANIMATION_RING: 0x72,\r\n  /* 'a' */ ANIMATION_STARTUP: 0x61,\r\n  /* 'A' */ ANIMATION_STARTUP_ONCE: 0x41,\r\n  /* 'e' */ BOOTLOADER: 0x65,\r\n  /* 'm' */ DRAW_PWM: 0x6D,\r\n  /* 'M' */ DRAW_PWM_BLOCKING: 0x4D,\r\n  /* 'n' */ DRAW_SCALE: 0x6E,\r\n  /* 'N' */ DRAW_SCALE_BLOCKING: 0x4E,\r\n  /* 'c' */ FLUSH_CMD_QUEUE: 0x63,\r\n  /* 't' */ TEST_PATTERN: 0x74,\r\n  /* 'w' */ SET_CONST_PWM: 0x77,\r\n  /* 's' */ SET_CONST_SCALE: 0x73,\r\n  /* 'p' */ SET_PX_PWM: 0x70,\r\n  /* 'q' */ SET_PX_SCALE: 0x71,\r\n  /* 127 */ IDENT: 0x7F,\r\n});\r\n\r\nexport const IDENT_STR_LEN = 25;\r\n\r\nexport const IDENT_STR_REGEX = /^Sig\\sFW\\sLED\\sMatrix\\sFW\\sV(\\d+)\\.(\\d+)$/;\r\n\r\nexport const IDENT_STR_PREFIX = 'Sig FW LED Matrix FW';\r\n","import { GAMMA } from '../../../hardware-constants.js';\r\nimport { Command, IDENT_STR_LEN, IDENT_STR_REGEX } from './commands.js';\r\n\r\nexport class SigrootController {\r\n  constructor(portMutex) {\r\n    this.#portMutex = portMutex;\r\n  }\r\n\r\n  async verifyFirmware() {\r\n    let ident = null;\r\n\r\n    await this.#portMutex.acquire(async p => {\r\n      await p.tx([Command.IDENT]);\r\n      ident = await p.rx(IDENT_STR_LEN);\r\n    });\r\n\r\n    ident = String.fromCharCode(...ident);\r\n\r\n    return ident.match(IDENT_STR_REGEX);\r\n  }\r\n\r\n  async version() {\r\n    let ident = null;\r\n\r\n    await this.#portMutex.acquire(async p => {\r\n      await p.tx([Command.IDENT]);\r\n      ident = await p.rx(IDENT_STR_LEN);\r\n    });\r\n\r\n    ident = String.fromCharCode(...ident);\r\n\r\n    const match = ident.match(IDENT_STR_REGEX);\r\n\r\n    if (match && match.length == 3) {\r\n      return {\r\n        major: match[1],\r\n        minor: match[2]\r\n      }\r\n    } else {\r\n      return null;\r\n    }\r\n  }\r\n\r\n  async draw(matrix) {\r\n    if (!this.#scaleInitialized) {\r\n      await this.#portMutex.acquire(\r\n        async p => {\r\n          await p.tx([Command.SET_CONST_SCALE, 0x20]);\r\n        }\r\n      );\r\n      this.#scaleInitialized = true;\r\n    }\r\n\r\n    const bytes = matrix.flat().map(v => \r\n      GAMMA[Math.floor((v ?? 0) * 255)]\r\n    );\r\n\r\n    // Only execute the most recent call \r\n    await this.#portMutex.acquireIdempotent(\r\n      'drawMatrix', \r\n      async p => {\r\n        await p.tx([Command.DRAW_PWM, ...bytes]);\r\n      }\r\n    );\r\n  }\r\n\r\n  #portMutex;\r\n  #scaleInitialized;\r\n}\r\n","import { PortMutex } from './environments/web/PortMutex.js';\r\nimport { PortOperations } from './environments/web/PortOperations.js';\r\nimport { close, getPort } from './environments/web/port.js';\r\nimport { DefaultController } from './firmware/framework-official/DefaultController.js';\r\nimport { SigrootController } from './firmware/sigroot/SigrootController.js';\r\n\r\nexport class SerialControllerFactory {\r\n  static async make(firmware) {\r\n    const port = await getPort();\r\n    if (port) {\r\n      if (firmware === 'framework-official') {\r\n        return await SerialControllerFactory.makeDefaultWebController(port);\r\n      } else if (firmware === 'sigroot') {\r\n        return await SerialControllerFactory.makeSigrootWebController(port);\r\n      } else if (firmware === 'auto') {\r\n        return await SerialControllerFactory.makeAutoWebController(port);\r\n      } else {\r\n        throw new Error(`Unsupported firmware type: ${firmware}`);\r\n      }\r\n    }\r\n  }\r\n\r\n  static async makeDefaultWebController(port) {\r\n    if (port?.connected) {\r\n      await close(port);\r\n      await port.open({ baudRate: 115200 });\r\n      return new DefaultController(\r\n        new PortMutex(\r\n          new PortOperations(port)\r\n        )\r\n      );\r\n    }\r\n  }\r\n\r\n  static async makeSigrootWebController(port) {\r\n    if (port?.connected) {\r\n      await close(port);\r\n      await port.open({ baudRate: 115200 });\r\n      return new SigrootController(\r\n        new PortMutex(\r\n          new PortOperations(port)\r\n        )\r\n      );\r\n    }\r\n  }\r\n\r\n  static async makeAutoWebController(port) {\r\n    const ctrl1 = await this.makeDefaultWebController(port);\r\n    if (await ctrl1.verifyFirmware()) {\r\n      return ctrl1;\r\n    }\r\n    const ctrl2 = await this.makeSigrootWebController(port);\r\n    if (await ctrl2.verifyFirmware()) {\r\n      return ctrl2;\r\n    }\r\n  }\r\n}\r\n"],"names":["WIDTH","HEIGHT","VID","VID_ARR","PID","PID_ARR","GAMMA","Object","freeze","extraDevices","filters","vendorId","productId","DeviceSelectionCancelled","Error","constructor","super","this","name","date","Date","HIDOperations","device","send","report","data","length","bytes","arr","len","val","concat","Array","fill","pad","buffer","Uint8Array","feature","sendFeatureReport","id","sendReport","receive","reply","receiveFeatureReport","byteLength","console","error","Reports","Commands","SparkleController","hidOps","info","infoRaw","sleep_pin","getUint8","dip1_pin","intb_pin","state_flags","id_reg","config_reg","global_brightness","display_width","display_height","timeout_ms","getUint32","wake","sleep","disableSleep","disableDeepSleep","disableSleepTimer","enableDeepSleep","enableSleepTimer","milliseconds","view","DataView","ArrayBuffer","setInt32","reboot","mode","drawPixel","r","c","brightness","drawLine","r1","c1","r2","c2","verifyFirmware","version","major","minor","draw","matrix","flat","map","v","Math","floor","HIDControllerFactory","make","firmware","async","pop","push","navigator","hid","getDevices","requestDevice","getDevice","makeSparkleController","open","PortMutex","portOperations","lockName","random","toString","deduper","Map","portOps","acquire","fn","trace","stack","enqueue","e","acquireIdempotent","key","has","set","execDedupedOp","locks","request","get","delete","PortOperations","port","rx","timeout","readable","locked","response","reader","getReader","timeoutHandle","setTimeout","cancel","value","done","read","clearTimeout","releaseLock","tx","writable","writer","getWriter","write","close","PortSelectionCancelled","PortUnavailable","message","Command","ANIMATE","BRIGHTNESS","BOOTLOADER","DRAW","DRAW_GREY_COL_BUFFER","GAME_CTRL","GAME_STATUS","PANIC","PATTERN","SLEEP","STAGE_GREY_COL","START_GAME","VERSION","BitDepth","GRAY_8BIT","MONO_1BIT","DefaultController","portMutex","bitDepth","packet","p","isPacket","isPadded","slice","every","ver","patch","preRelease","payloads","from","_","i","index","output","NOOP","ANIMATION_DIAMOND","ANIMATION_FIRE","ANIMATION_FIREPLACE","ANIMATION_GEAR","ANIMATION_RING","ANIMATION_STARTUP","ANIMATION_STARTUP_ONCE","DRAW_PWM","DRAW_PWM_BLOCKING","DRAW_SCALE","DRAW_SCALE_BLOCKING","FLUSH_CMD_QUEUE","TEST_PATTERN","SET_CONST_PWM","SET_CONST_SCALE","SET_PX_PWM","SET_PX_SCALE","IDENT","IDENT_STR_REGEX","SigrootController","ident","String","fromCharCode","match","scaleInitialized","SerialControllerFactory","serial","requestPort","usbProductId","usbVendorId","log","getPort","makeDefaultWebController","makeSigrootWebController","makeAutoWebController","connected","baudRate","ctrl1","ctrl2"],"mappings":"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"}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "led-matrix-controllers",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "packageManager": "yarn@4.12.0",
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "rollup": "^4.53.3"
+  },
+  "scripts": {
+    "build": "rollup -c"
+  }
+}

package/src/hardware-constants.js

@@ -0,0 +1,41 @@
+export const WIDTH = 9;
+export const HEIGHT = 34;
+export const VID = 0x32AC;
+export const VID_ARR = [0x32, 0xAC];
+export const PID = 0x0020;
+export const PID_ARR = [0x00, 0x20];
+
+export const GAMMA = Object.freeze([
+  0, 0, 0, 0, 0, 0, 0, 1, 
+  1, 1, 1, 1, 1, 1, 1, 1, 
+  1, 1, 1, 1, 1, 1, 1, 1, 
+  1, 1, 1, 1, 1, 1, 1, 1, 
+  1, 1, 1, 2, 2, 2, 2, 2, 
+  2, 2, 2, 2, 3, 3, 3, 3, 
+  3, 3, 3, 4, 4, 4, 4, 4, 
+  4, 5, 5, 5, 5, 6, 6, 6, 
+  6, 6, 7, 7, 7, 7, 8, 8, 
+  8, 9, 9, 9, 10, 10, 10, 11, 
+  11, 11, 12, 12, 12, 13, 13, 14, 
+  14, 14, 15, 15, 16, 16, 17, 17, 
+  17, 18, 18, 19, 19, 20, 20, 21, 
+  22, 22, 23, 23, 24, 24, 25, 26, 
+  26, 27, 27, 28, 29, 29, 30, 31, 
+  32, 32, 33, 34, 34, 35, 36, 37, 
+  38, 38, 39, 40, 41, 42, 42, 43, 
+  44, 45, 46, 47, 48, 49, 50, 51, 
+  52, 53, 54, 55, 56, 57, 58, 59, 
+  60, 61, 62, 63, 64, 66, 67, 68, 
+  69, 70, 71, 73, 74, 75, 76, 78, 
+  79, 80, 82, 83, 84, 86, 87, 88, 
+  90, 91, 93, 94, 96, 97, 99, 100, 
+  102, 103, 105, 106, 108, 110, 111, 113, 
+  115, 116, 118, 120, 121, 123, 125, 127, 
+  128, 130, 132, 134, 136, 138, 140, 141, 
+  143, 145, 147, 149, 151, 153, 155, 157, 
+  159, 161, 164, 166, 168, 170, 172, 174, 
+  177, 179, 181, 183, 186, 188, 190, 193, 
+  195, 197, 200, 202, 205, 207, 210, 212, 
+  215, 217, 220, 222, 225, 228, 230, 233, 
+  236, 238, 241, 244, 247, 249, 252, 255
+]);

package/src/index.js

@@ -0,0 +1,3 @@
+export * from './hardware-constants.js'
+export * from './usb-hid/HIDControllerFactory.js';
+export * from './usb-serial/SerialControllerFactory.js';

package/src/usb-hid/HIDControllerFactory.js

@@ -0,0 +1,27 @@
+import { getDevice } from './environments/web/device.js';
+import { HIDOperations } from './environments/web/HIDOperations.js';
+import { SparkleController } from './firmware/sparkle/SparkleController.js';
+
+export class HIDControllerFactory {
+  static async make(firmware) {
+    const device = await getDevice();
+    if (device) {
+      if (firmware === 'sparkle') {
+        return await HIDControllerFactory.makeSparkleController(device);
+      } else {
+        throw new Error(`Unsupported firmware type: ${firmware}`);
+      }
+    } else {
+      return null;
+    }
+  }
+
+  static async makeSparkleController(device) {
+    if (device) {
+      await device.open();
+      return new SparkleController(
+        new HIDOperations(device)
+      );
+    }
+  }
+}

package/src/usb-hid/environments/web/HIDOperations.js

@@ -0,0 +1,46 @@
+import { pad } from './util.js';
+
+export class HIDOperations {
+  constructor(device) {
+    this.#device = device;
+  }
+
+  async send(report, data) {
+    if (data.length < report.bytes) {
+      data = pad(data, report.bytes);
+    } else if (data.length > report.bytes) {
+      throw new Error('Unable to send report: too many bytes');
+    }
+
+    const buffer = new Uint8Array(data).buffer;
+
+    if (report.feature)  {
+      await this.#device.sendFeatureReport(report.id, buffer);
+    } else {
+      await this.#device.sendReport(report.buffer);
+    }
+  }
+
+  async receive(report) {
+    let reply = [];
+
+    if (report.feature) {
+      reply = await this.#device.receiveFeatureReport(report.id);
+    } else {
+      /* 
+       * HID input reports are used for unprompted data.
+       * An event system must be used.
+       * See WebHID `HIDInputReportEvent`
+       */
+      throw new Error('Invalid operation');
+    }
+
+    if (reply.byteLength != report.bytes) {
+      console.error(`reply length=${reply.byteLength} (exp ${report.bytes})`);
+    }
+
+    return reply;
+  }
+
+  #device;
+}

package/src/usb-hid/environments/web/device.js

@@ -0,0 +1,36 @@
+import { PID, VID } from '../../../hardware-constants.js';
+
+const extraDevices = [];
+
+const filters = [
+  {
+    vendorId: VID,
+    productId: PID,
+  }
+]
+
+export class DeviceSelectionCancelled extends Error {
+  constructor() {
+    super('User cancelled device selection.');
+    this.name = this.constructor.name;
+    this.date = new Date();
+  }
+}
+
+export async function getDevice() {
+  if (extraDevices && extraDevices.length > 0) {
+    return extraDevices.pop();
+  }
+
+  extraDevices.push(...(await navigator.hid.getDevices()));
+  if (extraDevices && extraDevices.length > 0) {
+    return extraDevices.pop();
+  }
+
+  extraDevices.push(...(await navigator.hid.requestDevice({ filters })));
+  if (extraDevices && extraDevices.length > 0) {
+    return extraDevices.pop();
+  }
+
+  throw new DeviceSelectionCancelled();
+}

package/src/usb-hid/environments/web/util.js

@@ -0,0 +1,3 @@
+export function pad(arr, len, val=0x00) {
+  return arr.concat(new Array(len - arr.length).fill(val));
+}

package/src/usb-hid/firmware/sparkle/SparkleController.js

@@ -0,0 +1,132 @@
+import { GAMMA, HEIGHT, WIDTH } from '../../../hardware-constants.js';
+import { Commands, Reports } from './reports.js';
+
+export class SparkleController {
+  constructor(hidOps) {
+    this.#hidOps = hidOps;
+  }
+
+  async info() {
+    const infoRaw = await this.#hidOps.receive(Reports.GLITTER_DEVICE_INFO);
+
+    return {
+      sleep_pin: infoRaw.getUint8(1),
+      dip1_pin: infoRaw.getUint8(2),
+      intb_pin: infoRaw.getUint8(3),
+      state_flags: infoRaw.getUint8(4),
+      id_reg: infoRaw.getUint8(5),
+      config_reg: infoRaw.getUint8(6),
+      global_brightness: infoRaw.getUint8(7),
+      display_width: infoRaw.getUint8(8),
+      display_height: infoRaw.getUint8(9),
+      timeout_ms: infoRaw.getUint32(10),
+    };
+  }
+
+  async wake() {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD,
+      [Commands.GLITTER_CMD_SLEEP, false]
+    );
+  }
+
+  async sleep() {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD,
+      [Commands.GLITTER_CMD_SLEEP, true]
+    );
+  }
+
+  async disableSleep() {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD, 
+      [Commands.GLITTER_CMD_SET_SLEEP_TIMEOUT, 0xff, 0xff, 0xff, 0xff]
+    );
+  }
+
+  async disableDeepSleep() {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD, 
+      [Commands.GLITTER_CMD_WAKE_ON_COMMAND, 0x01]
+    );
+  }
+
+  async disableSleepTimer() {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD, 
+      [Commands.GLITTER_CMD_SET_SLEEP_TIMEOUT, 0x00, 0x00, 0x00, 0x00]
+    );
+  }
+  
+  async enableDeepSleep() {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD, 
+      [Commands.GLITTER_CMD_WAKE_ON_COMMAND, 0x00]
+    );
+  }
+
+  async enableSleepTimer(milliseconds) {
+    const view = new DataView(new ArrayBuffer(4));
+    const littleEndian = false;
+    view.setInt32(0, milliseconds, littleEndian);
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD, 
+      [
+        Commands.GLITTER_CMD_SET_SLEEP_TIMEOUT, 
+        view.getUint8(0), 
+        view.getUint8(1), 
+        view.getUint8(2), 
+        view.getUint8(3),
+      ]
+    );
+  }
+
+  async reboot(mode) {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD, 
+      [Commands.GLITTER_CMD_REBOOT, mode]
+    );
+  }
+
+  async drawPixel(r, c, brightness) {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD,
+      [Commands.GLITTER_CMD_DRAW_PIXEL, c, r, brightness]
+    );
+  }
+
+  async drawLine({r1, c1}, {r2, c2}, brightness) {
+    await this.#hidOps.send(
+      Reports.GLITTER_BASIC_CMD,
+      [Commands.GLITTER_CMD_DRAW_PIXEL, r1, c1, r2, c2, brightness]
+    );
+  }
+
+  // --- generic methods ---
+
+  async verifyFirmware() {
+    try {
+      const info = await this.info();
+      return (
+        info.display_height == HEIGHT &&
+        info.display_width == WIDTH
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  async version() {
+    // Not Available
+    return { major: 1, minor: 0 };
+  }
+
+  async draw(matrix) {
+    return await this.#hidOps.send(
+      Reports.GLITTER_GRID_PWM_CNTL,
+      matrix.flat().map(v => GAMMA[Math.floor((v ?? 0) * 255)])
+    );
+  }
+
+  #hidOps;
+}

package/src/usb-hid/firmware/sparkle/reports.js

@@ -0,0 +1,37 @@
+export const Reports = {
+  GLITTER_DEVICE_INFO: {
+    id: 0x01,
+    bytes: 307,
+    feature: true,
+  },
+  GLITTER_BASIC_CMD: {
+    id: 0x02,
+    bytes: 16,
+    feature: true,
+  },
+  GLITTER_GRID_PWM_CNTL: {
+    id: 0x03,
+    bytes: 306,
+    feature: true,
+  },
+  GLITTER_GRID_PWM_CNTL: {
+    id: 0x04,
+    bytes: 306,
+    feature: true,
+  }
+}
+
+export const Commands = {
+  GLITTER_CMD_REBOOT: 0x00,
+  GLITTER_CMD_SLEEP: 0x01,
+  GLITTER_CMD_WAKE_ON_COMMAND: 0x02,
+  GLITTER_CMD_SET_SLEEP_TIMEOUT: 0x03,
+  GLITTER_CMD_SET_GLOBAL_BRIGHTNESS: 0x04,
+  GLITTER_CMD_DRAW_PIXEL: 0x05,
+  GLITTER_CMD_DRAW_LINE: 0x06
+}
+
+export const BootMode = {
+  BOOTSEL: 0x00,
+  NORMAL: 0x01,
+}

package/src/usb-serial/SerialControllerFactory.js

@@ -0,0 +1,57 @@
+import { PortMutex } from './environments/web/PortMutex.js';
+import { PortOperations } from './environments/web/PortOperations.js';
+import { close, getPort } from './environments/web/port.js';
+import { DefaultController } from './firmware/framework-official/DefaultController.js';
+import { SigrootController } from './firmware/sigroot/SigrootController.js';
+
+export class SerialControllerFactory {
+  static async make(firmware) {
+    const port = await getPort();
+    if (port) {
+      if (firmware === 'framework-official') {
+        return await SerialControllerFactory.makeDefaultWebController(port);
+      } else if (firmware === 'sigroot') {
+        return await SerialControllerFactory.makeSigrootWebController(port);
+      } else if (firmware === 'auto') {
+        return await SerialControllerFactory.makeAutoWebController(port);
+      } else {
+        throw new Error(`Unsupported firmware type: ${firmware}`);
+      }
+    }
+  }
+
+  static async makeDefaultWebController(port) {
+    if (port?.connected) {
+      await close(port);
+      await port.open({ baudRate: 115200 });
+      return new DefaultController(
+        new PortMutex(
+          new PortOperations(port)
+        )
+      );
+    }
+  }
+
+  static async makeSigrootWebController(port) {
+    if (port?.connected) {
+      await close(port);
+      await port.open({ baudRate: 115200 });
+      return new SigrootController(
+        new PortMutex(
+          new PortOperations(port)
+        )
+      );
+    }
+  }
+
+  static async makeAutoWebController(port) {
+    const ctrl1 = await this.makeDefaultWebController(port);
+    if (await ctrl1.verifyFirmware()) {
+      return ctrl1;
+    }
+    const ctrl2 = await this.makeSigrootWebController(port);
+    if (await ctrl2.verifyFirmware()) {
+      return ctrl2;
+    }
+  }
+}

package/src/usb-serial/environments/web/PortMutex.js

@@ -0,0 +1,58 @@
+export class PortMutex {
+  constructor(portOperations) {
+    this.#lockName = `port-mutex-${Math.random().toString()}`;
+    this.#deduper = new Map();
+    this.#portOps = portOperations;
+  }
+
+  async acquire(fn) {
+    const trace = new Error('created bad cb').stack;
+
+    await this.#enqueue(async () => {
+      try {
+        await fn(this.#portOps);
+      } catch (e) {
+        console.error('Error occured in anonymous callback.');
+        console.error('Original error:', e);
+        console.error('--- This callback was created at ---\n', trace);
+      }
+    });
+  }
+
+  async acquireIdempotent(key, fn) {
+    const trace = new Error('created bad cb').stack;
+
+    if  (this.#deduper.has(key)) {
+      console.info(`"${key}" request coalesced.`);
+    }
+
+    this.#deduper.set(key, async () => {
+      try {
+        await fn(this.#portOps);
+      } catch (e) {
+        console.error('Error occured in anonymous callback.');
+        console.error('Original error:', e);
+        console.error('--- This callback was created at ---\n', trace);
+      }
+    });
+
+    await this.#enqueue(() => this.#execDedupedOp(key));
+  }
+
+  async #enqueue(fn) {
+    // `navigator.locks` maintains queue and provides mutual exclusion.
+    return navigator.locks.request(this.#lockName, fn);
+  }
+
+  async #execDedupedOp(key) {
+    if (this.#deduper.has(key)) {
+      const fn = this.#deduper.get(key);
+      this.#deduper.delete(key);
+      await fn();
+    }
+  }
+
+  #lockName;
+  #deduper;
+  #portOps;
+}

package/src/usb-serial/environments/web/PortOperations.js

@@ -0,0 +1,66 @@
+export class PortOperations {
+  constructor(port) {
+    this.#port = port;
+  }
+
+  async rx(length, timeout=3000) {
+    if (this.#port === null) {
+      throw new Error('attempted RX before port initialization.');
+    }
+
+    /*
+     * ReadableStream's built-in locking mechanism cannot be awaited or otherwise
+     * asynchronously acquired. A PortMutex must be used.
+     */
+    if (this.#port.readable.locked) {
+      throw new Error('attempted RX while port locked.');
+    }
+
+    const response = [];
+    const reader = this.#port.readable.getReader();
+    const timeoutHandle = setTimeout(() => reader.cancel(), timeout);
+
+    try {
+      // Response may be divided across multiple reads
+      while (response.length < length) {
+        const { value, done } = await reader.read();
+        response.push(...(value ?? []));
+        if (done || !value) break;
+      }
+    } finally {
+      clearTimeout(timeoutHandle);
+      reader.releaseLock();
+    }
+
+    return response;
+  }
+
+  async tx(buffer) {
+    if (this.#port === null) {
+      throw new Error('attempted TX before port initialization.');
+    }
+    
+    /*
+     * WritableStream's built-in locking mechanism cannot be awaited or otherwise
+     * asynchronously acquired. A PortMutex must be used.
+     */
+    if (this.#port.writable.locked) {
+      throw new Error('attempted TX while port locked.');
+    }
+
+    const writer = this.#port.writable.getWriter();
+
+    try {
+      await writer.write(new Uint8Array(buffer));
+    } finally {
+      /* 
+       * The writer must be completely torn down between every single write.
+       * Many parsers can't handle delayed flushing and write coalescing.
+       * Command sequences will fail if `releaseLock()` is used here.
+       */
+      await writer.close();
+    }
+  }
+
+  #port;
+}

package/src/usb-serial/environments/web/port.js

@@ -0,0 +1,47 @@
+export class PortSelectionCancelled extends Error {
+  constructor() {
+    super('User cancelled port selection.');
+    this.name = this.constructor.name;
+    this.date = new Date();
+  }
+}
+
+export class PortUnavailable extends Error {
+  constructor() {
+    super('Selected port already in use.');
+    this.name = this.constructor.name;
+    this.date = new Date();
+  }
+}
+
+export async function getPort() {
+  try {
+    const port = await navigator.serial.requestPort();
+    const { usbProductId, usbVendorId } = port;
+    console.log('Selected port:', port);
+    if (usbProductId && usbVendorId) {
+      console.log(`VID:PID ${usbVendorId}:${usbProductId}`);
+    }
+    return port;
+  } catch (e) {
+    if (e.name == 'NotFoundError') {
+      throw new PortSelectionCancelled();
+    } else if (e.name == 'InvalidStateError') {
+      throw new PortUnavailable();
+    } else {
+      throw e;
+    }
+  }
+}
+
+export async function close(port) {
+  try {
+    await port.close();
+  } catch(e) {
+    if (e.name != 'InvalidStateError') {
+      if (e.message != "Failed to execute 'close' on 'SerialPort': The port is already closed.") {
+        throw e;
+      }
+    }
+  }
+}

package/src/usb-serial/firmware/framework-official/DefaultController.js

@@ -0,0 +1,89 @@
+import { HEIGHT, VID_ARR, WIDTH } from '../../../hardware-constants.js';
+import { BitDepth, Command, RX_PACKET_SZ } from './commands.js';
+
+export class DefaultController {
+  constructor(portMutex) {
+    this.#bitDepth = BitDepth.MONO_1BIT;
+    this.#portMutex = portMutex;
+  }
+
+  async verifyFirmware() {
+    let packet = null;
+
+    await this.#portMutex.acquire(async p => {
+      await p.tx([...VID_ARR, Command.VERSION]);
+      packet = await p.rx(RX_PACKET_SZ);
+    });
+
+    const isPacket = packet.length == RX_PACKET_SZ;
+    const isPadded = packet.slice(3).every(e => e == 0x00);
+
+    return isPacket && isPadded;
+  }
+
+  async version() {
+    let ver = {};
+
+    await this.#portMutex.acquire(async p => {
+      await p.tx([...VID_ARR, Command.VERSION]);
+      const response = await p.rx(RX_PACKET_SZ);
+
+      // MMMMMMMM mmmmPPPP 0000000p
+      ver.major = response[0];
+      ver.minor = response[1] >> 4;
+      ver.patch = response[1] & 0x0F;
+      ver.preRelease = response[2] == 1;
+    });
+
+    return ver;
+  }
+
+  async draw(matrix) {
+    if (this.#bitDepth == BitDepth.GRAY_8BIT) {
+      // Transpose & Gamma Correction
+      const payloads = Array.from(
+        { length: WIDTH }, 
+        (_, c) => new Array(
+          { length: HEIGHT }, 
+          (_, r) => GAMMA[Math.floor((matrix[r][c] ?? 0) * 255)]
+        )
+      );
+
+      // Only execute the most recent call 
+      await this.#portMutex.acquireIdempotent(
+        'drawMatrix', 
+        async p => {
+          for (let i = 0; i < WIDTH; i++) {
+            await p.tx([Command.STAGE_GREY_COL, i, ...payloads[i]]);
+          }
+          await p.tx([Command.DRAW_GREY_COL_BUFFER]);
+        }
+      );
+    }
+
+    else if (this.#bitDepth == BitDepth.MONO_1BIT) {
+      let index = 0;
+      let output = new Uint8Array(39).fill(0);
+
+      // Pack cells into bits
+      for (let r = 0; r < HEIGHT; r++) {
+        for (let c = 0; c < WIDTH; c++) {
+          if (matrix[r][c]) {
+            output[index >> 3] |= 1 << index % 8;
+          }
+          index++;
+        }
+      }
+
+      await this.#portMutex.acquireIdempotent(
+        'drawMatrix', 
+        async p => {
+          await p.tx([...VID_ARR, Command.DRAW, ...output]);
+        }
+      );
+    }
+  }
+
+  #bitDepth;
+  #portMutex;
+}

package/src/usb-serial/firmware/framework-official/commands.js

@@ -0,0 +1,36 @@
+// All replies to all commands are 32 bytes
+export const RX_PACKET_SZ = 32;
+
+export const Command = Object.freeze({
+  ANIMATE: 0x04,
+  BRIGHTNESS: 0x00,
+  BOOTLOADER: 0x02,
+  DRAW: 0x06,
+  DRAW_GREY_COL_BUFFER: 0x08,
+  GAME_CTRL: 0x11,
+  GAME_STATUS: 0x12,
+  PANIC: 0x05,
+  PATTERN: 0x01,
+  SLEEP: 0x03,
+  STAGE_GREY_COL: 0x07,
+  START_GAME: 0x10,
+  VERSION: 0x20,
+});
+
+// Used with Command.PATTERN
+export const Pattern = Object.freeze({
+  DISPLAY_LOTUS_HORIZONTAL: 0x03,
+  DISPLAY_LOTUS_VERTICAL: 0x07,
+  DISPLAY_PANIC: 0x06,
+  DOUBLE_GRADIENT: 0x02,
+  FULL_BRIGHTNESS: 0x05,
+  GRADIENT: 0x01,
+  PERCENTAGE: 0x00,
+  ZIG_ZAG: 0x04,
+});
+
+// DRAW or DRAW_GREY_COL_BUFFER
+export const BitDepth = Object.freeze({
+  GRAY_8BIT: '8-bit',
+  MONO_1BIT: '1-bit',
+})

package/src/usb-serial/firmware/sigroot/SigrootController.js

@@ -0,0 +1,69 @@
+import { GAMMA } from '../../../hardware-constants.js';
+import { Command, IDENT_STR_LEN, IDENT_STR_REGEX } from './commands.js';
+
+export class SigrootController {
+  constructor(portMutex) {
+    this.#portMutex = portMutex;
+  }
+
+  async verifyFirmware() {
+    let ident = null;
+
+    await this.#portMutex.acquire(async p => {
+      await p.tx([Command.IDENT]);
+      ident = await p.rx(IDENT_STR_LEN);
+    });
+
+    ident = String.fromCharCode(...ident);
+
+    return ident.match(IDENT_STR_REGEX);
+  }
+
+  async version() {
+    let ident = null;
+
+    await this.#portMutex.acquire(async p => {
+      await p.tx([Command.IDENT]);
+      ident = await p.rx(IDENT_STR_LEN);
+    });
+
+    ident = String.fromCharCode(...ident);
+
+    const match = ident.match(IDENT_STR_REGEX);
+
+    if (match && match.length == 3) {
+      return {
+        major: match[1],
+        minor: match[2]
+      }
+    } else {
+      return null;
+    }
+  }
+
+  async draw(matrix) {
+    if (!this.#scaleInitialized) {
+      await this.#portMutex.acquire(
+        async p => {
+          await p.tx([Command.SET_CONST_SCALE, 0x20]);
+        }
+      );
+      this.#scaleInitialized = true;
+    }
+
+    const bytes = matrix.flat().map(v => 
+      GAMMA[Math.floor((v ?? 0) * 255)]
+    );
+
+    // Only execute the most recent call 
+    await this.#portMutex.acquireIdempotent(
+      'drawMatrix', 
+      async p => {
+        await p.tx([Command.DRAW_PWM, ...bytes]);
+      }
+    );
+  }
+
+  #portMutex;
+  #scaleInitialized;
+}

package/src/usb-serial/firmware/sigroot/commands.js

@@ -0,0 +1,28 @@
+export const Command = Object.freeze({
+  /* 000 */ NOOP: 0x00,
+  /* 'd' */ ANIMATION_DIAMOND: 0x64,
+  /* 'b' */ ANIMATION_FIRE: 0x62,
+  /* 'f' */ ANIMATION_FIREPLACE: 0x66,
+  /* 'g' */ ANIMATION_GEAR: 0x67,
+  /* 'r' */ ANIMATION_RING: 0x72,
+  /* 'a' */ ANIMATION_STARTUP: 0x61,
+  /* 'A' */ ANIMATION_STARTUP_ONCE: 0x41,
+  /* 'e' */ BOOTLOADER: 0x65,
+  /* 'm' */ DRAW_PWM: 0x6D,
+  /* 'M' */ DRAW_PWM_BLOCKING: 0x4D,
+  /* 'n' */ DRAW_SCALE: 0x6E,
+  /* 'N' */ DRAW_SCALE_BLOCKING: 0x4E,
+  /* 'c' */ FLUSH_CMD_QUEUE: 0x63,
+  /* 't' */ TEST_PATTERN: 0x74,
+  /* 'w' */ SET_CONST_PWM: 0x77,
+  /* 's' */ SET_CONST_SCALE: 0x73,
+  /* 'p' */ SET_PX_PWM: 0x70,
+  /* 'q' */ SET_PX_SCALE: 0x71,
+  /* 127 */ IDENT: 0x7F,
+});
+
+export const IDENT_STR_LEN = 25;
+
+export const IDENT_STR_REGEX = /^Sig\sFW\sLED\sMatrix\sFW\sV(\d+)\.(\d+)$/;
+
+export const IDENT_STR_PREFIX = 'Sig FW LED Matrix FW';