{"id":50965611,"url":"https://github.com/tricked-dev/monsgeek-js-driver","last_synced_at":"2026-06-18T20:01:39.829Z","repository":{"id":362401091,"uuid":"1209873685","full_name":"Tricked-dev/monsgeek-js-driver","owner":"Tricked-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-13T21:42:37.000Z","size":39,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-04T04:30:18.863Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tricked-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Tricked-dev"}},"created_at":"2026-04-13T21:42:06.000Z","updated_at":"2026-04-13T21:42:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Tricked-dev/monsgeek-js-driver","commit_stats":null,"previous_names":["tricked-dev/monsgeek-js-driver"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Tricked-dev/monsgeek-js-driver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tricked-dev%2Fmonsgeek-js-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tricked-dev%2Fmonsgeek-js-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tricked-dev%2Fmonsgeek-js-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tricked-dev%2Fmonsgeek-js-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tricked-dev","download_url":"https://codeload.github.com/Tricked-dev/monsgeek-js-driver/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tricked-dev%2Fmonsgeek-js-driver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34505423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-18T20:01:36.288Z","updated_at":"2026-06-18T20:01:39.824Z","avatar_url":"https://github.com/Tricked-dev.png","language":"JavaScript","funding_links":["https://github.com/sponsors/Tricked-dev"],"categories":[],"sub_categories":[],"readme":"# MonsGeek TypeScript Driver Reimplementation\n\nTypeScript/Bun reimplementation of the MonsGeek local IoT driver, intended to replace the proprietary binary while keeping existing Electron app and web client behavior compatible.\n\n## Why This Exists\n\n- Remove hard dependency on a closed-source local binary.\n- Keep the existing app and web frontend working with minimal changes.\n- Make protocol behavior inspectable, testable, and maintainable in source control.\n- Enable deterministic debugging with trace logs and side-by-side conformance checks.\n\n## Project Goals\n\n- Match gRPC-web RPC behavior of the official `iot_driver` for real client traffic.\n- Match USB/HID request/response packet behavior for supported MonsGeek devices.\n- Preserve compatibility with:\n  - Electron desktop app flow\n  - Browser web driver flow\n- Provide tooling for protocol capture, replay, and compare.\n\n## Implementation Overview\n\n### Runtime Components\n\n- `src/server-node.ts`\n  - Node entrypoint.\n  - Boots gRPC-web server and USB bridge.\n\n- `src/grpc-web-server.ts`\n  - Implements `driver.DriverGrpc` endpoints from `driver.proto`.\n  - Handles both `grpc-web+proto` and `grpc-web-text` wire modes.\n  - Provides unary + stream endpoints and response framing/trailers.\n\n- `src/bridges/node-usb-bridge.ts`\n  - USB/HID transport for keyboard device communication.\n  - Sends feature reports and reads feature responses.\n  - Maintains last-read fallback behavior for read error paths.\n\n- `src/protocol.ts`\n  - gRPC-web framing utilities.\n  - Checksum behavior (`Bit7`/`Bit8`) and 64-byte report shaping.\n\n- `src/db.ts`\n  - Local JSON-backed key/value storage used by DB RPCs.\n\n### Protocol + Compatibility Tooling\n\n- `scripts/grpc-capture-proxy.mjs`\n  - Proxy that captures app RPC traffic to structured logs.\n  - Optional mirror mode to forward same requests to TS server for side-by-side diffs.\n\n- `scripts/driver-conformance.mjs`\n  - RPC probe and compare utility (`iot` vs `ts`).\n  - Useful for regression checks during protocol parity work.\n\n## USB Packet Confidence (How It Is Validated)\n\nThe packet path is not blind guesswork.\n\n- We run official driver and TS driver in parallel.\n- We mirror identical RPC requests to both.\n- We compare:\n  - Decoded RPC payloads\n  - HID command/reply heads and lengths\n  - Initialization opcode sequence behavior\n- Trace files in `.db/` are used to validate parity against live device traffic.\n\n## Current Compatibility Status\n\n- Core startup/init flow: implemented and validated with side-by-side traces.\n- Core HID message path (`sendMsg` / `readMsg`): implemented and actively validated.\n- gRPC-web response framing/header/trailer behavior: aligned to observed client expectations.\n- DB RPC behavior: implemented with compatibility handling for observed path/error cases.\n- Some less-used endpoints still require full parity testing under all edge cases.\n\n## Quick Start\n\n### Requirements\n\n- Bun\n- Node.js (for some scripts/tools)\n- Supported MonsGeek USB device connected\n- macOS/Linux environment with HID access\n\n### Windows Support\n\n- The codebase is cross-platform at the Node layer (`node-hid`, `usb`, gRPC-web server).\n- On Windows, USB/HID behavior depends on driver stack/device permissions and may require device-specific setup.\n- CI runs build/typecheck on Windows, and release workflow includes a Windows `.exe` packaging step.\n\n### Install\n\n```bash\nbun install\ncp .env.example .env\n```\n\n### Build\n\n```bash\nbun run build\n```\n\n### Run TS Driver\n\n```bash\nbun run start\n```\n\nDefault bind: `127.0.0.1:3814`\n\n### Useful Environment Variables\n\n- `MONSGEEK_PORT` (default `3814`)\n- `MONSGEEK_HOST` (default `127.0.0.1`)\n- `MONSGEEK_JS_VERSION` (default `223`)\n- `MONSGEEK_DEVICE_ID` (default `2648`)\n- `MONSGEEK_REPORT_ID` (default `1`)\n- `MONSGEEK_DB_DIR` (default `./.db`)\n- `MONSGEEK_IOT_BIN` (used by conformance tooling)\n\n## Conformance + Debug Workflows\n\n### Run Basic Conformance Probe\n\n```bash\nbun run conformance\n```\n\n### Compare Official Driver and TS Driver\n\n```bash\nbun run conformance:compare -- --mode text\n```\n\n### Run Proxy Capture\n\n```bash\nnode scripts/grpc-capture-proxy.mjs \\\n  --host 127.0.0.1 --port 3814 \\\n  --upstream-host 127.0.0.1 --upstream-port 3815\n```\n\nMirror mode (for side-by-side TS validation):\n\n```bash\nnode scripts/grpc-capture-proxy.mjs \\\n  --host 127.0.0.1 --port 3814 \\\n  --upstream-host 127.0.0.1 --upstream-port 3815 \\\n  --mirror-host 127.0.0.1 --mirror-port 3816\n```\n\n## Repository Notes\n\n- `src/server.js` is a legacy reference implementation kept for behavior comparison.\n- `dist/`, `.db/`, `node_modules/`, and local binary artifacts are generated and should not be committed.\n- This project is for interoperability and local driver replacement; avoid misuse.\n\n## CI / Release\n\n- GitHub Actions workflow: `.github/workflows/ci-release.yml`\n- CI matrix: Linux + macOS + Windows (`build` + `typecheck`)\n- Tag release (`v*`) produces:\n  - packaged archives per OS\n  - Windows `.exe` artifact via `pkg`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftricked-dev%2Fmonsgeek-js-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftricked-dev%2Fmonsgeek-js-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftricked-dev%2Fmonsgeek-js-driver/lists"}