ps-access 0.0.1

package/cli.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+// ps-access — read/write PlayStation Access Controller profiles over USB-C (no PS5).
+import { writeFileSync, readFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  parseProfile, buildProfile, describeProfile, PROFILE_SIZE, PROFILE_COUNT,
+  ACTION_BY_NAME, ACTIONS, STICK_BY_NAME, ORIENTATION_BY_NAME,
+} from "./web/access-protocol.mjs";
+import { PRESETS, presetById, fromFileText, applyPortable, decodeShare, shareURL } from "./web/profile-library.mjs";
+
+// node-hid is loaded lazily so offline commands (presets/share/show-share/help) work
+// without it installed. Device commands call loadHid() first (see the dispatcher).
+let _hid = null;
+async function loadHid() {
+  if (!_hid) {
+    try { _hid = await import("./lib/hid-node.mjs"); }
+    catch (e) { throw new Error(`this command needs the controller — run "npm install" first (${e.message || e})`); }
+  }
+  return _hid;
+}
+const listControllers = (...a) => _hid.listControllers(...a);
+const openController = (...a) => _hid.openController(...a);
+const readProfileRaw = (...a) => _hid.readProfileRaw(...a);
+const writeProfileRaw = (...a) => _hid.writeProfileRaw(...a);
+const setActiveProfile = (...a) => _hid.setActiveProfile(...a);
+
+const CAPTURES = new URL("./captures/", import.meta.url).pathname;
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--device" || a === "-d") opts.device = argv[++i];
+    else if (a === "--out" || a === "-o") opts.out = argv[++i];
+    else if (a === "--json") opts.json = true;
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+    else opts._.push(a);
+  }
+  return opts;
+}
+
+function hex(bytes) {
+  return [...bytes].map((x) => x.toString(16).padStart(2, "0")).join(" ");
+}
+function stamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function readAllProfiles(device) {
+  const profiles = [];
+  for (let n = 1; n <= PROFILE_COUNT; n++) profiles.push(readProfileRaw(device, n));
+  return profiles;
+}
+
+// Auto-backup all profiles before any write, so every change is reversible.
+function autoBackup(device, label) {
+  mkdirSync(CAPTURES, { recursive: true });
+  const raws = readAllProfiles(device);
+  const file = join(CAPTURES, `autobackup-${label}-${stamp()}.json`);
+  saveBackup(file, raws);
+  return file;
+}
+
+function saveBackup(file, raws) {
+  const payload = {
+    device: "PlayStation Access Controller",
+    vidpid: "054c:0e5f",
+    savedAt: new Date().toISOString(),
+    profiles: raws.map((raw, i) => ({
+      slot: i + 1,
+      rawHex: Buffer.from(raw).toString("hex"),
+      decoded: parseProfile(raw),
+    })),
+  };
+  writeFileSync(file, JSON.stringify(payload, (k, v) => (k === "_raw" ? undefined : v), 2));
+}
+
+function loadRawFromFile(path, slot) {
+  const txt = readFileSync(path, "utf8").trim();
+  // JSON backup with profiles[].rawHex, or a bare hex/binary file.
+  if (txt.startsWith("{")) {
+    const obj = JSON.parse(txt);
+    const entry = (obj.profiles || []).find((p) => p.slot === slot) || obj.profiles?.[0];
+    if (!entry) throw new Error("no matching profile in backup file");
+    return Uint8Array.from(Buffer.from(entry.rawHex, "hex"));
+  }
+  if (/^[0-9a-fA-F\s]+$/.test(txt)) return Uint8Array.from(Buffer.from(txt.replace(/\s+/g, ""), "hex"));
+  const bin = readFileSync(path);
+  return Uint8Array.from(bin);
+}
+
+function resolveAction(name) {
+  const n = String(name).toLowerCase();
+  if (n in ACTION_BY_NAME) return { kind: "action", code: ACTION_BY_NAME[n] };
+  if (n in STICK_BY_NAME) return { kind: "stick", code: STICK_BY_NAME[n] };
+  if (/^\d+$/.test(n)) return { kind: "action", code: Number(n) };
+  throw new Error(`unknown action "${name}". Try: ${Object.values(ACTIONS).join(", ")}, left stick, right stick`);
+}
+
+// Resolve a portable profile from a preset id, a file path (web export / backup), or a share code/URL.
+function resolvePortable(src, slotIdx) {
+  const preset = presetById(src);
+  if (preset) return preset.portable;
+  if (existsSync(src)) return fromFileText(readFileSync(src, "utf8"), slotIdx);
+  const code = src.includes("#p=") ? src.split("#p=")[1] : src; // share URL or bare code
+  return fromFileText(code, slotIdx);
+}
+
+const COMMANDS = {
+  list() {
+    const list = listControllers();
+    if (!list.length) return console.log("No Access Controller connected (VID 054C / PID 0E5F).");
+    console.log(`${list.length} Access Controller(s):`);
+    for (const d of list) {
+      console.log(`  [${d.index}] ${d.product} — ${d.manufacturer}  serial=${d.serialNumber ?? "n/a"}  path=${d.path}`);
+    }
+  },
+
+  dump(opts) {
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      console.log(`# ${info.product} [${info.index}] ${info.path}`);
+      for (let n = 1; n <= PROFILE_COUNT; n++) {
+        const raw = readProfileRaw(device, n);
+        console.log(`\n=== Profile ${n} ===`);
+        console.log(describeProfile(parseProfile(raw)));
+        console.log("raw:", hex(raw.slice(0, 32)), "...");
+      }
+    } finally {
+      device.close();
+    }
+  },
+
+  backup(opts) {
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      mkdirSync(CAPTURES, { recursive: true });
+      const raws = readAllProfiles(device);
+      const file = opts.out || join(CAPTURES, `backup-dev${info.index}-${stamp()}.json`);
+      saveBackup(file, raws);
+      console.log(`Backed up 3 profiles from controller [${info.index}] -> ${file}`);
+    } finally {
+      device.close();
+    }
+  },
+
+  "set-active"(opts) {
+    const slot = Number(opts._[0]);
+    if (!(slot >= 1 && slot <= PROFILE_COUNT)) throw new Error("usage: set-active <1..3>");
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      setActiveProfile(device, slot);
+      console.log(`Switched controller [${info.index}] to active Profile ${slot}.`);
+    } finally {
+      device.close();
+    }
+  },
+
+  "read-profile"(opts) {
+    const slot = Number(opts._[0]);
+    if (!(slot >= 1 && slot <= PROFILE_COUNT)) throw new Error("usage: read-profile <1..3>");
+    const { device } = openController(opts.device ?? 0);
+    try {
+      const raw = readProfileRaw(device, slot);
+      const p = parseProfile(raw);
+      if (opts.json) console.log(JSON.stringify(p, (k, v) => (k === "_raw" ? undefined : v), 2));
+      else console.log(describeProfile(p));
+    } finally {
+      device.close();
+    }
+  },
+
+  "write-profile"(opts) {
+    const slot = Number(opts._[0]);
+    const file = opts._[1];
+    if (!(slot >= 1 && slot <= PROFILE_COUNT) || !file) throw new Error("usage: write-profile <1..3> <file>");
+    const raw = loadRawFromFile(file, slot);
+    if (raw.length < PROFILE_SIZE) throw new Error(`file is ${raw.length} bytes, need ${PROFILE_SIZE}`);
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      const bk = autoBackup(device, `dev${info.index}-pre-write`);
+      console.log(`(auto-backup -> ${bk})`);
+      writeProfileRaw(device, slot, raw);
+      const back = readProfileRaw(device, slot);
+      const ok = Buffer.compare(Buffer.from(back.slice(0, PROFILE_SIZE)), Buffer.from(raw.slice(0, PROFILE_SIZE))) === 0;
+      console.log(`Wrote profile ${slot}. Round-trip verify: ${ok ? "OK (byte-identical)" : "DIFFERS (device may normalize fields)"}`);
+    } finally {
+      device.close();
+    }
+  },
+
+  // set <slot> button5=triangle | port1=cross | port0="left stick" | orientation=...
+  set(opts) {
+    const slot = Number(opts._[0]);
+    const assignment = opts._.slice(1).join(" ");
+    const m = assignment.match(/^(button\d+|port\d+|orientation)\s*=\s*(.+)$/i);
+    if (!(slot >= 1 && slot <= PROFILE_COUNT) || !m) {
+      throw new Error('usage: set <1..3> <button1..10|port0..4|orientation>=<action>');
+    }
+    const target = m[1].toLowerCase();
+    const value = m[2].replace(/^["']|["']$/g, "");
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      const raw = readProfileRaw(device, slot);
+      const p = parseProfile(raw);
+      if (target === "orientation") {
+        const code = value.toLowerCase() in ORIENTATION_BY_NAME ? ORIENTATION_BY_NAME[value.toLowerCase()] : Number(value);
+        for (const port of p.ports) if (port.kind === "stick") port.orientation = code;
+      } else if (target.startsWith("button")) {
+        const i = Number(target.slice(6)) - 1;
+        if (!(i >= 0 && i < 10)) throw new Error("button must be 1..10");
+        p.buttons[i].map1 = resolveAction(value).code;
+      } else {
+        const i = Number(target.slice(4));
+        if (!(i >= 0 && i < 5)) throw new Error("port must be 0..4");
+        const a = resolveAction(value);
+        if (a.kind === "stick") p.ports[i] = { kind: "stick", stick: a.code, orientation: p.ports.find((x) => x.kind === "stick")?.orientation ?? 3 };
+        else if (a.code === 0) p.ports[i] = { kind: "none" };
+        else p.ports[i] = { kind: "button", analog: false, map1: a.code, map2: 0, toggle: false };
+      }
+      const bk = autoBackup(device, `dev${info.index}-pre-set`);
+      console.log(`(auto-backup -> ${bk})`);
+      const out = buildProfile(p, { now: Date.now() });
+      writeProfileRaw(device, slot, out);
+      console.log(`set profile ${slot} ${target}=${value}`);
+      console.log(describeProfile(parseProfile(readProfileRaw(device, slot))));
+    } finally {
+      device.close();
+    }
+  },
+
+  restore(opts) {
+    const file = opts._[0];
+    if (!file) throw new Error("usage: restore <backup.json> [--device X]");
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      const bk = autoBackup(device, `dev${info.index}-pre-restore`);
+      console.log(`(auto-backup -> ${bk})`);
+      for (let slot = 1; slot <= PROFILE_COUNT; slot++) {
+        const raw = loadRawFromFile(file, slot);
+        writeProfileRaw(device, slot, raw);
+      }
+      console.log(`Restored 3 profiles from ${file} to controller [${info.index}]`);
+    } finally {
+      device.close();
+    }
+  },
+
+  // Apply a portable profile (web Library export / share code / URL / preset id) onto a slot:
+  // reads the current profile as a base (so uuid + unmodeled fields survive), applies the
+  // mapping, writes it back, and verifies.
+  apply(opts) {
+    const src = opts._[0];
+    const slot = Number(opts._[1]);
+    if (!src || !(slot >= 1 && slot <= PROFILE_COUNT)) {
+      throw new Error("usage: apply <file.json | share-code | url | preset-id> <1..3>");
+    }
+    const portable = resolvePortable(src, slot - 1);
+    const { device, info } = openController(opts.device ?? 0);
+    try {
+      const bk = autoBackup(device, `dev${info.index}-pre-apply`);
+      console.log(`(auto-backup -> ${bk})`);
+      const base = parseProfile(readProfileRaw(device, slot));
+      applyPortable(base, portable);
+      writeProfileRaw(device, slot, buildProfile(base, { now: Date.now() }));
+      const back = parseProfile(readProfileRaw(device, slot));
+      console.log(`Applied ${portable.name ? `"${portable.name}"` : "profile"} to slot ${slot} on controller [${info.index}].`);
+      console.log(describeProfile(back));
+    } finally {
+      device.close();
+    }
+  },
+
+  // List the built-in starting-point presets (shared with the web Library).
+  presets() {
+    console.log("Presets — apply as a starting point, then customize:");
+    for (const p of PRESETS) console.log(`  ${p.id.padEnd(18)} ${p.name}\n    ${p.description}`);
+    console.log(`\nUse one with:  share / show-share, or apply it in the web Library, then Save.`);
+  },
+
+  // Print a shareable link (and #p= code) for a profile in a backup file — works offline.
+  share(opts) {
+    const file = opts._[0];
+    if (!file) throw new Error("usage: share <backup.json> [slot 1..3]");
+    const slot = opts._[1] ? Number(opts._[1]) - 1 : 0;
+    const portable = fromFileText(readFileSync(file, "utf8"), slot);
+    console.log(shareURL(portable, "https://ps-access.johnhenry.me/"));
+  },
+
+  // Decode a share link/code and describe what it contains — works offline.
+  "show-share"(opts) {
+    const arg = opts._[0];
+    if (!arg) throw new Error("usage: show-share <code|url>");
+    const code = arg.includes("#p=") ? arg.split("#p=")[1] : arg;
+    const portable = decodeShare(code);
+    console.log(describeProfile({ uuid: "(shared profile)", buttons: portable.buttons, ports: portable.ports, name: portable.name }));
+  },
+
+  help() {
+    console.log(`ps-access — PlayStation Access Controller profile tool (USB-C, no PS5)
+
+Usage: node cli.mjs <command> [args] [--device <index|path>]
+
+Commands:
+  list                          List connected controllers
+  dump                          Read + decode all 3 profiles
+  read-profile <1..3> [--json]  Read + decode one profile
+  set-active <1..3>             Switch the controller's active profile (like its profile button)
+  backup [--out file]           Save all 3 profiles to captures/ (raw + decoded)
+  restore <backup.json>         Write all 3 profiles back from a backup
+  write-profile <1..3> <file>   Write one profile from a backup/hex/binary file
+  apply <src> <1..3>            Apply a web export / share code / URL / preset id to a slot
+  set <1..3> <target>=<action>  Edit one mapping, e.g.:
+                                  set 1 button5=triangle
+                                  set 1 port1=cross
+                                  set 1 "port0=left stick"
+                                  set 1 orientation="stick on the right"
+  presets                       List built-in starting-point presets
+  share <backup.json> [slot]    Print a shareable link/code for a backed-up profile (offline)
+  show-share <code|url>         Decode + describe a share link/code (offline)
+
+Every write auto-backs-up first (captures/) and round-trip verifies.
+Actions: ${Object.values(ACTIONS).join(", ")}, left stick, right stick`);
+  },
+};
+
+// Commands that never touch the controller — usable without node-hid installed.
+const OFFLINE = new Set(["presets", "share", "show-share", "help"]);
+
+const opts = parseArgs(process.argv.slice(2));
+const cmd = opts._.shift() || "help";
+const fn = COMMANDS[cmd] || COMMANDS.help;
+try {
+  if (!OFFLINE.has(cmd) && COMMANDS[cmd]) await loadHid();
+  await fn(opts);
+} catch (e) {
+  console.error("error:", e.message);
+  process.exit(1);
+}

package/lib/bridge-sinks.mjs

@@ -0,0 +1,81 @@
+// Output sinks for the PC input bridge. A sink turns the abstract events from
+// BridgeEngine (key/button down·up, mouse motion, axes) into real OS input.
+//
+// Sinks expose:  apply(events) -> void|Promise   and   close() -> void|Promise
+//
+//   DryRunSink   — prints events; no OS input. Works everywhere (default for --dry-run).
+//   XdotoolSink  — keyboard + mouse via the `xdotool` CLI (X11). No native deps.
+//   UinputSink   — virtual gamepad/keyboard via /dev/uinput, driven by a stdlib-only
+//                  Python helper (no extra packages). Needs access to /dev/uinput
+//                  (run as root or add a udev rule). Lowest latency.
+
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------- dry run
+export class DryRunSink {
+  constructor({ log = (s) => console.log(s) } = {}) { this.log = log; this.count = 0; }
+  apply(events) {
+    for (const e of events) {
+      this.count++;
+      if (e.type === "key") this.log(`  ${e.action === "down" ? "▼" : "▲"} ${e.code}`);
+      else if (e.type === "mouseMove") this.log(`  ↔ mouse ${e.dx >= 0 ? "+" : ""}${e.dx},${e.dy >= 0 ? "+" : ""}${e.dy}`);
+      else if (e.type === "axis") this.log(`  ⊹ axis ${e.code}=${e.value.toFixed(2)}`);
+    }
+  }
+  close() { this.log(`dry-run: ${this.count} events`); }
+}
+
+// ---------------------------------------------------------------- xdotool (X11)
+const XDO_MOUSE = { mouse1: 1, mouse2: 2, mouse3: 3 };
+
+export class XdotoolSink {
+  constructor({ display = process.env.DISPLAY || ":0" } = {}) {
+    this.env = { ...process.env, DISPLAY: display };
+    const probe = spawnSync("xdotool", ["version"], { env: this.env });
+    if (probe.error) throw new Error("xdotool not found — install it (NixOS: nix-install xdotool)");
+    if (probe.status !== 0) throw new Error(`xdotool can't reach DISPLAY=${display}. Set --display.`);
+  }
+  apply(events) {
+    const args = [];
+    for (const e of events) {
+      if (e.type === "key") {
+        const mb = XDO_MOUSE[e.code];
+        if (mb) args.push(e.action === "down" ? "mousedown" : "mouseup", String(mb));
+        else args.push(e.action === "down" ? "keydown" : "keyup", e.code);
+      } else if (e.type === "mouseMove") {
+        args.push("mousemove_relative", "--", String(e.dx), String(e.dy));
+      }
+    }
+    if (args.length) spawnSync("xdotool", args, { env: this.env });
+  }
+  close() { /* nothing persistent */ }
+}
+
+// ---------------------------------------------------------------- uinput (Linux)
+// Spawns the Python helper and streams it one JSON event per line.
+export class UinputSink {
+  constructor({ kind = "gamepad", python = "python3" } = {}) {
+    const helper = join(HERE, "uinput-helper.py");
+    this.proc = spawn(python, [helper, kind], { stdio: ["pipe", "inherit", "inherit"] });
+    this.proc.on("error", (e) => { throw new Error(`couldn't start uinput helper: ${e.message}`); });
+  }
+  apply(events) {
+    if (!this.proc?.stdin.writable) return;
+    for (const e of events) this.proc.stdin.write(JSON.stringify(e) + "\n");
+  }
+  close() { try { this.proc.stdin.end(); this.proc.kill(); } catch { /* ignore */ } }
+}
+
+// Factory used by the CLI.
+export function makeSink(name, opts = {}) {
+  switch (name) {
+    case "dry-run": case "dryrun": case "dry": return new DryRunSink(opts);
+    case "xdotool": case "keyboard": return new XdotoolSink(opts);
+    case "uinput": case "gamepad": return new UinputSink({ kind: "gamepad", ...opts });
+    default: throw new Error(`unknown sink "${name}" (use: dry-run, xdotool, uinput)`);
+  }
+}

package/lib/hid-node.mjs

@@ -0,0 +1,67 @@
+// node-hid transport for the Access Controller. Wraps the platform-agnostic protocol
+// in lib/access-protocol.mjs with actual feature-report I/O.
+import HID from "node-hid";
+import {
+  VENDOR_ID, PRODUCT_ID, REPORT_ID_CMD, REPORT_ID_DATA, CMD_PAYLOAD_SIZE,
+  PROFILE_SIZE, PACKETS_PER_PROFILE, buildReadCommand, assembleProfile, buildWritePackets,
+  buildSetActiveCommand,
+} from "../web/access-protocol.mjs";
+
+// All connected Access Controllers, in a stable order, with index labels.
+export function listControllers() {
+  const devices = HID.devices().filter((d) => d.vendorId === VENDOR_ID && d.productId === PRODUCT_ID);
+  return devices.map((d, i) => ({
+    index: i,
+    path: d.path,
+    serialNumber: d.serialNumber || null,
+    product: d.product || "Access Controller",
+    manufacturer: d.manufacturer || "Sony",
+    release: d.release,
+    interface: d.interface,
+  }));
+}
+
+// Open a controller by index (default 0) or by HID path.
+export function openController(selector = 0) {
+  const list = listControllers();
+  if (list.length === 0) throw new Error("No Access Controller found (VID 054C / PID 0E5F). Connect it via USB-C.");
+  let entry;
+  if (typeof selector === "string" && selector.startsWith("/")) entry = list.find((d) => d.path === selector);
+  else entry = list[Number(selector)];
+  if (!entry) throw new Error(`No controller for selector ${JSON.stringify(selector)}. ${list.length} connected.`);
+  const device = new HID.HID(entry.path);
+  return { device, info: entry };
+}
+
+// Read raw 956 bytes for profile N (1..3).
+export function readProfileRaw(device, profileNumber) {
+  const cmd = buildReadCommand(profileNumber);
+  device.sendFeatureReport([REPORT_ID_CMD, ...cmd]);
+  const packets = [];
+  for (let i = 0; i < PACKETS_PER_PROFILE; i++) {
+    // node-hid returns the report data with the report id as the first byte.
+    const resp = device.getFeatureReport(REPORT_ID_DATA, CMD_PAYLOAD_SIZE + 1);
+    packets.push(resp);
+  }
+  return assembleProfile(packets);
+}
+
+// Switch the controller's active profile (1..3) — like pressing its profile button.
+export function setActiveProfile(device, profileNumber) {
+  device.sendFeatureReport([REPORT_ID_CMD, ...buildSetActiveCommand(profileNumber)]);
+}
+
+// Write raw 956 bytes to profile N (1..3). CRC handled by buildWritePackets.
+export function writeProfileRaw(device, profileNumber, profileBytes) {
+  if (profileBytes.length < PROFILE_SIZE) throw new Error(`profile must be ${PROFILE_SIZE} bytes`);
+  const packets = buildWritePackets(profileNumber, profileBytes);
+  for (const pkt of packets) device.sendFeatureReport([REPORT_ID_CMD, ...pkt]);
+  // The device streams 0x61 status after a write; drain until byte 2 (remaining) is 0,
+  // otherwise the next read command desyncs and returns empty data.
+  for (let i = 0; i < 32; i++) {
+    const resp = device.getFeatureReport(REPORT_ID_DATA, CMD_PAYLOAD_SIZE + 1);
+    if (!resp || resp[2] === 0) break;
+  }
+}
+
+export { HID };

package/lib/uinput-helper.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""Virtual input device for the ps-access PC bridge — Linux /dev/uinput, stdlib only.
+
+Reads one JSON event per line on stdin (from lib/bridge-sinks.mjs UinputSink):
+    {"type":"key","code":"space","action":"down"}
+    {"type":"axis","code":"x","value":-1.0}
+and injects them as a virtual keyboard or gamepad via /dev/uinput.
+
+No third-party packages: just ctypes/struct/fcntl/os. Needs write access to
+/dev/uinput (run as root, or add a udev rule granting your user the `input` group).
+
+Usage:
+    uinput-helper.py keyboard      # virtual keyboard (xdotool-style keysyms)
+    uinput-helper.py gamepad       # virtual gamepad (BTN_* + ABS_X/Y)
+    uinput-helper.py keyboard --selftest   # print planned device setup, don't open uinput
+"""
+import sys, os, json, struct, fcntl, time
+
+# ---- linux/uinput.h + input-event-codes.h constants ----
+EV_SYN, EV_KEY, EV_ABS = 0x00, 0x01, 0x03
+SYN_REPORT = 0
+ABS_X, ABS_Y = 0x00, 0x01
+BUS_USB = 0x03
+
+def _IOC(d, t, nr, size): return (d << 30) | (size << 16) | (t << 8) | nr
+_IOW = lambda t, nr, size: _IOC(1, t, nr, size)
+_IO = lambda t, nr: _IOC(0, t, nr, 0)
+UI_SET_EVBIT = _IOW(ord('U'), 100, 4)
+UI_SET_KEYBIT = _IOW(ord('U'), 101, 4)
+UI_SET_ABSBIT = _IOW(ord('U'), 103, 4)
+UI_DEV_CREATE = _IO(ord('U'), 1)
+UI_DEV_DESTROY = _IO(ord('U'), 2)
+
+# A practical subset of KEY_* codes, keyed by the xdotool-style keysyms the bridge emits.
+KEY = {
+    "space": 57, "Return": 28, "Escape": 1, "BackSpace": 14, "Tab": 15,
+    "shift": 42, "ctrl": 29, "alt": 56,
+    "Up": 103, "Down": 108, "Left": 105, "Right": 106,
+    "a": 30, "b": 48, "c": 46, "d": 32, "e": 18, "f": 33, "g": 34, "h": 35,
+    "i": 23, "j": 36, "k": 37, "l": 38, "m": 50, "n": 49, "o": 24, "p": 25,
+    "q": 16, "r": 19, "s": 31, "t": 20, "u": 22, "v": 47, "w": 17, "x": 45,
+    "y": 21, "z": 44,
+    "1": 2, "2": 3, "3": 4, "4": 5, "5": 6, "6": 7, "7": 8, "8": 9, "9": 10, "0": 11,
+}
+# Gamepad buttons (BTN_*), keyed by friendly names a gamepad mapping would use.
+BTN = {
+    "BTN_SOUTH": 0x130, "BTN_EAST": 0x131, "BTN_NORTH": 0x133, "BTN_WEST": 0x134,
+    "BTN_TL": 0x136, "BTN_TR": 0x137, "BTN_SELECT": 0x13a, "BTN_START": 0x13b,
+    "BTN_THUMBL": 0x13d, "BTN_THUMBR": 0x13e,
+    # friendly aliases
+    "cross": 0x130, "circle": 0x131, "triangle": 0x133, "square": 0x134,
+    "l1": 0x136, "r1": 0x137, "select": 0x13a, "start": 0x13b,
+}
+ABS_RANGE = (-32767, 32767)
+
+
+def codes_for(kind):
+    return KEY if kind == "keyboard" else {**BTN, **KEY}
+
+
+def build(kind, selftest=False):
+    table = codes_for(kind)
+    keycodes = sorted(set(table.values()))
+    name = f"ps-access {kind}".encode()[:79]
+    if selftest:
+        print(f"[selftest] device='{name.decode()}' kind={kind} "
+              f"keys={len(keycodes)} abs={'X,Y' if kind=='gamepad' else 'none'}")
+        return None
+    try:
+        fd = os.open("/dev/uinput", os.O_WRONLY | os.O_NONBLOCK)
+    except (PermissionError, FileNotFoundError) as ex:
+        print(f"uinput: cannot open /dev/uinput ({ex}). Run as root, or grant access with a "
+              f"udev rule (add your user to a group that owns /dev/uinput).", file=sys.stderr)
+        sys.exit(13)
+    fcntl.ioctl(fd, UI_SET_EVBIT, EV_KEY)
+    fcntl.ioctl(fd, UI_SET_EVBIT, EV_SYN)
+    for code in keycodes:
+        fcntl.ioctl(fd, UI_SET_KEYBIT, code)
+    absmin = [0] * 64
+    absmax = [0] * 64
+    if kind == "gamepad":
+        fcntl.ioctl(fd, UI_SET_EVBIT, EV_ABS)
+        for ax in (ABS_X, ABS_Y):
+            fcntl.ioctl(fd, UI_SET_ABSBIT, ax)
+            absmin[ax], absmax[ax] = ABS_RANGE
+    # struct uinput_user_dev: char name[80]; input_id(4*u16); u32 ff; s32 absmax/min/fuzz/flat[64]
+    dev = struct.pack("80sHHHHi", name, BUS_USB, 0x054c, 0x0e5f, 1, 0)
+    dev += struct.pack("64i", *absmax) + struct.pack("64i", *absmin)
+    dev += struct.pack("64i", *([0] * 64)) + struct.pack("64i", *([0] * 64))
+    os.write(fd, dev)
+    fcntl.ioctl(fd, UI_DEV_CREATE)
+    time.sleep(0.2)  # give udev a moment to create the node
+    return fd
+
+
+def emit(fd, etype, code, value):
+    # struct input_event: timeval(2*long) + u16 type + u16 code + s32 value
+    os.write(fd, struct.pack("llHHi", 0, 0, etype, code, value))
+
+
+def syn(fd):
+    emit(fd, EV_SYN, SYN_REPORT, 0)
+
+
+def main():
+    args = [a for a in sys.argv[1:] if not a.startswith("--")]
+    kind = args[0] if args else "keyboard"
+    selftest = "--selftest" in sys.argv
+    if kind not in ("keyboard", "gamepad"):
+        print(f"unknown kind '{kind}' (keyboard|gamepad)", file=sys.stderr); sys.exit(2)
+    fd = build(kind, selftest)
+    if selftest:
+        return
+    table = codes_for(kind)
+    try:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                e = json.loads(line)
+            except ValueError:
+                continue
+            if e.get("type") == "key":
+                code = table.get(e.get("code"))
+                if code is not None:
+                    emit(fd, EV_KEY, code, 1 if e.get("action") == "down" else 0)
+                    syn(fd)
+            elif e.get("type") == "axis" and kind == "gamepad":
+                ax = ABS_X if e.get("code") == "x" else ABS_Y
+                val = int(max(-1.0, min(1.0, float(e.get("value", 0)))) * ABS_RANGE[1])
+                emit(fd, EV_ABS, ax, val)
+                syn(fd)
+    finally:
+        try:
+            fcntl.ioctl(fd, UI_DEV_DESTROY)
+            os.close(fd)
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "ps-access",
+  "version": "0.0.1",
+  "description": "Read/write PlayStation Access Controller profiles from a PC (no PS5). CLI + WebHID tool + PC input bridge.",
+  "type": "module",
+  "bin": {
+    "ps-access": "./cli.mjs",
+    "ps-access-bridge": "./bridge.mjs"
+  },
+  "scripts": {
+    "start": "npx --yes serve -l 3000 .",
+    "list": "node cli.mjs list",
+    "backup": "node cli.mjs backup",
+    "bridge": "node bridge.mjs",
+    "test": "node --test"
+  },
+  "files": [
+    "cli.mjs",
+    "bridge.mjs",
+    "lib/",
+    "web/",
+    "PROTOCOL.md",
+    "README.md"
+  ],
+  "keywords": [
+    "playstation",
+    "access-controller",
+    "ps5",
+    "accessibility",
+    "adaptive-controller",
+    "webhid",
+    "hid",
+    "node-hid",
+    "remapping",
+    "assistive-technology"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/ps-access.git"
+  },
+  "homepage": "https://ps-access.johnhenry.me",
+  "bugs": {
+    "url": "https://github.com/johnhenry/ps-access/issues"
+  },
+  "author": "johnhenry",
+  "dependencies": {
+    "node-hid": "^3.1.2"
+  },
+  "license": "MIT"
+}