@yee94/qk80mk2 0.0.0-stage → 0.1.0

package/scripts/verify-assets.js

@@ -0,0 +1,11 @@
+import {readFile} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+
+const reference = new URL('../reference/',import.meta.url);
+const manifest = JSON.parse(await readFile(new URL('manifest.json',reference),'utf8'));
+for (const entry of manifest.files) {
+  const data = await readFile(new URL(entry.path,reference));
+  const sha = createHash('sha256').update(data).digest('hex');
+  if (data.length !== entry.bytes || sha !== entry.sha256) throw new Error(`Integrity mismatch: ${entry.path}`);
+  console.log(`PASS: ${entry.path} (${data.length} bytes)`);
+}

package/scripts/verify-official.js

@@ -0,0 +1,42 @@
+// Offline golden-file verification, never accesses USB.
+import fs from 'node:fs';
+import vm from 'node:vm';
+import path from 'node:path';
+import {createRequire} from 'node:module';
+import sharp from 'sharp';
+import {encodeImage} from '../src/image.js';
+
+const [assets,wasm,input,out] = process.argv.slice(2);
+if (!assets || !wasm || !input) throw new Error('Usage: node scripts/verify-official.js ASSETS WASM INPUT [GOLDEN_OUTPUT]');
+// Feed exactly the same normalized PNG to both encoders, including non-native-size inputs.
+const png = await sharp(input).autoOrient().resize(320,172,{fit:'cover',position:'centre'})
+  .flatten({background:'#000'}).toColourspace('srgb').removeAlpha().png().toBuffer();
+const bundle = fs.readFileSync(path.join(assets,'index.js'),'utf8');
+const start = bundle.indexOf('var createModule='), end = bundle.indexOf(';let module,loading=',start);
+if (start < 0 || end < 0) throw new Error('Upstream JS module boundary changed');
+const context = vm.createContext({
+  console,process,Buffer,URL,WebAssembly,TextDecoder,TextEncoder,performance,
+  setTimeout,clearTimeout,setInterval,clearInterval,
+  require:createRequire(import.meta.url),__dirname:path.resolve(assets),
+  __vitePreload:async () => ({createRequire}),self:{location:import.meta.url},
+});
+vm.runInContext(bundle.slice(start,end+1).replaceAll('import.meta.url',JSON.stringify(import.meta.url)),context);
+const module = await context.createModule({wasmBinary:fs.readFileSync(wasm)});
+const config = JSON.parse(fs.readFileSync(path.join(assets,'configs.json')))
+  .find(c => Number(c.vendorId) === 0x514b && Number(c.productId) === 0x4d02);
+const vector = list => { const result = new module.IntVec(); list.forEach(n => result.push_back(n)); return result; };
+module.FS.writeFile('/input.png',png);
+const size = vector([320,172]), origin = vector([0,0]), extra = new module.U8Vec();
+for (const target of ['theme','custom']) {
+  const format = target === 'theme' ? 'ABKT' : 'ABKG';
+  const area = config.screen.fileTypes.find(c => c.type === 'image' && c.format === format);
+  const status = module.convert_image_ext('/input.png','/out.bin',area.orientations,size,size,origin,
+    format,config.screen.swapBit ? 1 : 0,extra);
+  if (status !== 0) throw new Error(`Official encoder returned ${status}`);
+  const official = Buffer.from(module.FS.readFile('/out.bin'));
+  const ours = await encodeImage(png,{target});
+  if (!ours.equals(official)) throw new Error(`FAIL: ${format} differs from official output`);
+  if (out && target === 'theme') fs.writeFileSync(out,official);
+  console.log(`PASS: ${format}, ${official.length} bytes identical to official WASM`);
+}
+size.delete(); origin.delete(); extra.delete();

package/src/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import {parseArgs} from 'node:util';
+import {readFile,writeFile,mkdir} from 'node:fs/promises';
+import path from 'node:path';
+import {devices,encodeImage,upload,validateImage} from './index.js';
+
+const help = `qk80-screen — Node.js USB CDC static-image tool
+
+node src/cli.js devices
+node src/cli.js encode photo.png --out output/theme.abkt
+node src/cli.js upload photo.png [--target theme|custom] [--port /dev/cu.usbmodem...]
+node src/cli.js upload output/theme.abkt
+
+Upload tuning: --packet-delay-ms 6 --settle-ms 2000 --timeout-ms 5000
+JSON results on stdout; progress on stderr. --json suppresses progress.
+Default destination: theme (ABKT). No HTTP server or browser required.
+`;
+
+const controller = new AbortController();
+const abort = () => controller.abort(new Error('Upload interrupted'));
+process.once('SIGINT',abort); process.once('SIGTERM',abort);
+try {
+  const {values:v,positionals:p} = parseArgs({allowPositionals:true,options:{
+    help:{type:'boolean',short:'h'},version:{type:'boolean',short:'v'},json:{type:'boolean'},
+    out:{type:'string'},target:{type:'string'},port:{type:'string'},
+    'packet-delay-ms':{type:'string'},'settle-ms':{type:'string'},'timeout-ms':{type:'string'},
+  }});
+  const [command,input] = p;
+  if (v.version) console.log(JSON.parse(await readFile(new URL('../package.json',import.meta.url),'utf8')).version);
+  else if (v.help || !command) console.log(help);
+  else if (command === 'devices') console.log(JSON.stringify(await devices(),null,2));
+  else {
+    if (!['encode','upload'].includes(command)) throw new Error('Unknown command');
+    if (p.length > 2) throw new Error('Unexpected positional arguments');
+    const image = input;
+    if (!image) throw new Error('An input image is required');
+    const encoded = /\.(abkt|abkg)$/i.test(image);
+    const file = encoded ? await readFile(image) : await encodeImage(image,{target:v.target ?? 'theme'});
+    validateImage(file);
+    if (encoded && v.target && (v.target === 'theme' ? 'ABKT' : v.target === 'custom' ? 'ABKG' : '') !== file.toString('ascii',0,4))
+      throw new Error('--target does not match encoded file');
+    if (command === 'upload') {
+      let last = -10;
+      const numeric = (key,fallback) => v[key] === undefined ? fallback : Number(v[key]);
+      const result = await upload(file,{port:v.port,signal:controller.signal,
+        packetDelayMs:numeric('packet-delay-ms',6),settleMs:numeric('settle-ms',2000),
+        timeoutMs:numeric('timeout-ms',5000),onProgress:event => {
+          const pct = Math.floor(event.sent/event.total*100);
+          if (!v.json && (pct >= last+10 || event.stage === 'settling')) {
+            console.error(`${event.stage}: ${pct}% (flowControl=${event.flowControl})`); last = pct;
+          }
+        }});
+      console.log(JSON.stringify(result,null,2));
+    } else {
+      const extension = file.toString('ascii',0,4).toLowerCase();
+      const out = path.resolve(v.out ?? `output/theme.${extension}`);
+      await mkdir(path.dirname(out),{recursive:true}); await writeFile(out,file);
+      console.log(JSON.stringify({encoded:out,bytes:file.length},null,2));
+    }
+  }
+} catch (error) {
+  console.error(JSON.stringify({status:'error',message:error.message}));
+  process.exitCode = controller.signal.aborted ? 130 : 1;
+} finally {
+  process.removeListener('SIGINT',abort); process.removeListener('SIGTERM',abort);
+}

package/src/image.js

@@ -0,0 +1,32 @@
+import sharp from 'sharp';
+
+export const WIDTH = 320, HEIGHT = 172, FILE_SIZE = 20 + WIDTH * HEIGHT * 2;
+
+export async function encodeImage(input, { target = 'theme' } = {}) {
+  if (!['theme', 'custom'].includes(target)) throw new Error('target must be theme or custom');
+  const {data, info} = await sharp(input, {limitInputPixels: 40_000_000})
+    .autoOrient().resize(WIDTH, HEIGHT, {fit:'cover', position:'centre'})
+    .flatten({background:'#000000'}).toColourspace('srgb').removeAlpha()
+    .raw().toBuffer({resolveWithObject:true});
+  if (info.channels !== 3) throw new Error('Expected RGB pixels');
+  const file = Buffer.alloc(FILE_SIZE);
+  file.write(target === 'theme' ? 'ABKT' : 'ABKG');
+  file.writeUInt16LE(20,4); file.writeUInt16LE(20,6);
+  file.writeUInt32LE(FILE_SIZE,8);
+  file.writeUInt16LE(WIDTH,12); file.writeUInt16LE(HEIGHT,14);
+  file.writeUInt16LE(1,18);
+  for (let p = 0; p < WIDTH * HEIGHT; p++) {
+    const i = p * 3;
+    file.writeUInt16LE(((data[i] >> 3) << 11) | ((data[i+1] >> 2) << 5) | (data[i+2] >> 3), 20 + p * 2);
+  }
+  return file;
+}
+
+export function validateImage(file) {
+  if (!Buffer.isBuffer(file) || file.length !== FILE_SIZE ||
+      !['ABKT','ABKG'].includes(file.toString('ascii',0,4)) ||
+      file.readUInt16LE(4) !== 20 || file.readUInt16LE(6) !== 20 ||
+      file.readUInt32LE(8) !== FILE_SIZE || file.readUInt16LE(12) !== WIDTH ||
+      file.readUInt16LE(14) !== HEIGHT || file.readUInt16LE(16) !== 0 || file.readUInt16LE(18) !== 1)
+    throw new Error('Invalid 320x172 static ABKT/ABKG file');
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export {encodeImage,validateImage} from './image.js';
+export {devices,upload} from './serial.js';

package/src/protocol.js

@@ -0,0 +1,55 @@
+import {setTimeout as sleep} from 'node:timers/promises';
+import {validateImage} from './image.js';
+
+export function packet(command, args = Buffer.alloc(0)) {
+  if (args.length > 63) throw new Error('Packet payload exceeds 63 bytes');
+  const result = Buffer.alloc(64); result[0] = command; args.copy(result,1); return result;
+}
+
+function echo(response, command, args) {
+  if (response.length !== 64 || response[0] !== command || !response.subarray(1,1+args.length).equals(args))
+    throw new Error(`Invalid CDC response for 0x${command.toString(16)}`);
+}
+
+// IO exposes write/read/drain; read must buffer split and coalesced serial events.
+// Wire protocol has no render-complete command: never report visual success here.
+export async function transfer(io, file, {
+  signal, packetDelayMs = 6, settleMs = 2000, timeoutMs = 5000, onProgress = () => {},
+} = {}) {
+  validateImage(file);
+  for (const [key,value] of Object.entries({packetDelayMs,settleMs,timeoutMs})) {
+    if (!Number.isFinite(value) || value < 0 || (key === 'timeoutMs' && value === 0))
+      throw new Error(`Invalid ${key}`);
+  }
+  const check = () => signal?.throwIfAborted();
+  const delay = ms => sleep(ms, undefined, {signal});
+  let started = false;
+  try {
+    check(); started = true;
+    await io.write(packet(0xe0,file.subarray(0,20)), timeoutMs, signal);
+    const response = await io.read(64,timeoutMs,signal);
+    echo(response,0xe0,file.subarray(0,20));
+    if (response[21] === 0xee) throw new Error('Keyboard rejected image header (0xEE)');
+    const flowControl = !!response[22];
+    onProgress({stage:'sending',sent:0,total:file.length,flowControl});
+    for (let offset = 0; offset < file.length; offset += 56) {
+      check();
+      const chunk = file.subarray(offset,offset+56), args = Buffer.alloc(5+chunk.length);
+      args.writeUInt32BE(offset,0); args[4] = chunk.length; chunk.copy(args,5);
+      await io.write(packet(0xe1,args),timeoutMs,signal);
+      if (flowControl) echo(await io.read(64,timeoutMs,signal),0xe1,args);
+      else if (packetDelayMs) await delay(packetDelayMs);
+      onProgress({stage:'sending',sent:offset+chunk.length,total:file.length,flowControl});
+    }
+    await io.drain(timeoutMs,signal);
+    onProgress({stage:'settling',sent:file.length,total:file.length,flowControl});
+    if (settleMs) await delay(settleMs);
+    return {status:'sent',bytes:file.length,target:file.toString('ascii',0,4),flowControl,
+      packetDelayMs,settleMs,displayVerified:false};
+  } catch (error) {
+    if (started) {
+      try { await io.write(packet(0xe2),1000); await io.drain(1000); } catch {}
+    }
+    throw error;
+  }
+}

package/src/serial.js

@@ -0,0 +1,85 @@
+import {SerialPort} from 'serialport';
+import {transfer} from './protocol.js';
+
+export async function devices() {
+  return (await SerialPort.list()).filter(p => parseInt(p.vendorId,16) === 0x514b && parseInt(p.productId,16) === 0x4d02);
+}
+
+function callback(operation, timeoutMs, signal) {
+  return new Promise((resolve,reject) => {
+    let timer;
+    const finish = error => {
+      clearTimeout(timer); signal?.removeEventListener('abort',abort);
+      error ? reject(error) : resolve();
+    };
+    const abort = () => finish(signal.reason ?? new Error('Aborted'));
+    if (signal?.aborted) return abort();
+    signal?.addEventListener('abort',abort,{once:true});
+    timer = setTimeout(() => finish(new Error('Serial operation timed out')),timeoutMs);
+    try { operation(finish); } catch (error) { finish(error); }
+  });
+}
+
+export class SerialIO {
+  constructor(port) {
+    this.port = port; this.buffer = Buffer.alloc(0); this.failure = null; this.waiter = null;
+    this.onData = data => {
+      this.buffer = Buffer.concat([this.buffer,data]);
+      if (this.buffer.length > 65536) this.failure = new Error('Unexpected serial response overflow');
+      this.pump();
+    };
+    this.onError = error => { this.failure = error; this.pump(); };
+    this.onClose = () => this.onError(new Error('Keyboard disconnected'));
+    port.on('data',this.onData); port.on('error',this.onError); port.on('close',this.onClose);
+  }
+  pump() {
+    if (!this.waiter) return;
+    if (this.failure) return this.waiter.finish(this.failure);
+    if (this.buffer.length >= this.waiter.size) {
+      const result = this.buffer.subarray(0,this.waiter.size);
+      this.buffer = this.buffer.subarray(this.waiter.size);
+      this.waiter.finish(null,result);
+    }
+  }
+  read(size,timeoutMs,signal) {
+    if (this.waiter) return Promise.reject(new Error('Concurrent serial reads are not supported'));
+    return new Promise((resolve,reject) => {
+      let timer;
+      const finish = (error,result) => {
+        clearTimeout(timer); signal?.removeEventListener('abort',abort); this.waiter = null;
+        error ? reject(error) : resolve(result);
+      };
+      const abort = () => finish(signal.reason ?? new Error('Aborted'));
+      if (signal?.aborted) return abort();
+      signal?.addEventListener('abort',abort,{once:true});
+      timer = setTimeout(() => finish(new Error(`Timed out waiting for ${size} CDC bytes`)),timeoutMs);
+      this.waiter = {size,finish}; this.pump();
+    });
+  }
+  write(bytes,timeoutMs,signal) {
+    if (this.failure) return Promise.reject(this.failure);
+    return callback(done => this.port.write(bytes,done),timeoutMs,signal);
+  }
+  drain(timeoutMs,signal) { return callback(done => this.port.drain(done),timeoutMs,signal); }
+  dispose() {
+    this.waiter?.finish(new Error('Serial connection disposed'));
+    this.port.off('data',this.onData); this.port.off('error',this.onError); this.port.off('close',this.onClose);
+  }
+}
+
+export async function upload(file, options = {}) {
+  const found = await devices();
+  const match = options.port ? found.find(p => p.path === options.port) : found.length === 1 ? found[0] : null;
+  if (!match) throw new Error(found.length > 1 ? 'Multiple keyboards found; specify --port' : 'QK80 MK2 USB serial port not found');
+  options.signal?.throwIfAborted();
+  const port = new SerialPort({path:match.path,baudRate:115200,autoOpen:false,lock:true});
+  const io = new SerialIO(port);
+  try {
+    // Wait for open to finish before cleanup, even if SIGINT arrives meanwhile.
+    await callback(done => port.open(done),options.timeoutMs ?? 5000);
+    return {...await transfer(io,file,options),port:match.path};
+  } finally {
+    try { if (port.isOpen) await callback(done => port.close(done),3000); }
+    finally { io.dispose(); }
+  }
+}