USB Mouse Switch PCB
Worked for 3 mins 51 sec
Added independent RESET and BOOT/FLASH buttons for both ESP32-S3 processors:
- SW1: U8 reset
- SW2: U8 flash/boot
- SW3: U9 reset
- SW4: U9 flash/boot
The isolated power domains remain separate, and the schematic review reports no electrical errors or warnings.
Remove the screen
Worked for 55 sec
Removed the OLED screen (
OLED1) from the schematic and PCB.The usb a is facing the board when it should be facing the other way
Worked for 1 min 35 sec
Fixed. The USB-A connector now faces outward, while remaining centered between the two USB-C connectors.
Review and place
Run PCB review
Place new buttons
Fix stackup issue
Check USB orientation
Update docs
Refine this doc
Ask about this doc
MAKCU Compatibility Protocol
Scope and clean-room boundary
This file defines interoperable behavior from public APIs and command observations. It does not reproduce proprietary firmware. Hardware compatibility, protocol compatibility, and exact firmware quirks are tracked separately.
Transport
- PC2 USB COM through CH343-family interface.
- Required serial modes: 115200 and 4,000,000 baud, 8-N-1.
- Legacy/native commands are ASCII terminated by
\r\n. - Parser accepts complete CRLF frames only; batch/raw APIs preserve ordering.
- Replies must preserve command-associated/tracked IDs where public clients use them, followed by firmware-compatible payload and prompt. Exact whitespace/prompt tokens are compatibility-test fixtures, not guessed constants.
Required compatibility front ends
The firmware shall expose three independent adapters feeding one common mouse-injection engine:
- MAKCU ASCII adapter over CH343 USB COM at 115200 and 4,000,000 baud.
- KMBox B/B+ ASCII adapter over the same COM port, including public
km.*movement, button, wheel, lock/mask, query, baud and device-information command families. - KMBox NET UDP adapter over the ESP32-S3 Wi-Fi interface. It shall implement the publicly documented 16-byte little-endian header (
mac,rand,indexpts,cmd) and public command constants for connect, move, left/right/middle, wheel, keyboard-all, reboot, Bezier move, monitor, mask, unmask, set-config and show-picture where applicable. USB-C remains the command/power connection; NET clients require Wi-Fi provisioning and an IP/port/UUID-compatible session layer.
All adapters normalize into the same internal event structure so transport choice cannot change resulting HID behavior.
Expected USB identity
Common libraries detect CH343 at VID:PID
1A86:55D3. U10 is CH343G. Public datasheet confirms custom VID/PID is configurable for CH343P; exact CH343G default identity must be measured. Hardware is CH343-family compatible, but software-identical enumeration is an explicit bring-up gate.Public command families
- Firmware/version/device information, including raw
km.version()style command. - Mouse button query and set; click, double-click, press and release.
- Relative movement.
- Silent/smooth movement; higher-level libraries may synthesize smooth/Bezier trajectories.
- Wheel/scroll and drag.
- Axis locks and button locks.
- Asynchronous button monitoring/capture/event stream.
- Read mouse serial, spoof serial, reset serial.
- Batch commands and raw command passthrough.
Behavioral requirements
- Maintain physical button state and injected button state separately, then apply locks and merge deterministically.
- Relative movement saturates/splits reports without losing total displacement.
- Silent/smooth operations must not block 1 kHz host/device servicing.
- Locks remain active until explicitly cleared or reset according to observed public behavior.
- Asynchronous button events are ordered, edge-preserving, and distinguishable from synchronous replies.
- Serial spoofing changes the presented descriptor serial only after the documented re-enumeration/reset boundary; reset restores physical/default behavior.
- Malformed/unknown commands produce deterministic error/prompt behavior and never execute partially.
1:1 physical mouse passthrough
- Parse and retain the attached mouse HID report descriptor, report IDs, button count, relative X/Y widths, vertical/horizontal wheel fields and vendor-defined reports.
- Mirror the physical mouse VID, PID, manufacturer/product strings, serial string and HID descriptor toward PC1 when technically valid; use a standards-compliant fallback only if the source descriptor cannot be safely re-presented.
- Forward every physical input report in order with no intentional acceleration, smoothing, scaling, dead-zone, coordinate rounding or button remapping.
- Preserve button transitions and wheel deltas exactly. Large fields may be split only when the emulated endpoint report width requires it, with total delta conserved.
- Maintain separate physical and injected states. The PC1 report is the deterministic merge of physical state plus active command injection, after explicit lock/mask rules.
- Command traffic must never pause USB host polling. Target 1 ms service cadence and bounded end-to-end forwarding latency of two USB frames under normal load.
- Forward supported HID class control operations and feature/output reports needed by common gaming mice. Unsupported vendor-specific control transfers must be logged and covered by a compatibility test, not silently discarded.
- Disconnect, reset and re-enumeration must release all injected states to prevent stuck buttons.
Public KMBox NET constants
The clean-room UDP adapter shall recognize at minimum:
CONNECT 0xaf3c2828, MOUSE_MOVE 0xaede7345, MOUSE_LEFT 0x9823ae8d, MOUSE_RIGHT 0x238d8212, MOUSE_MIDDLE 0x97a3ae8d, MOUSE_WHEEL 0xffeead38, KEYBOARD_ALL 0x123c2c2f, REBOOT 0xaa8855aa, BEZIER_MOVE 0xa238455a, MONITOR 0x27388020, MASK_MOUSE 0x23234343, UNMASK_ALL 0x23344343, SETCONFIG 0x1d3d3323, and SHOWPIC 0x12334883. Sequence/index handling must reject stale duplicates without dropping valid retransmissions.Compatibility matrix
Table
| Area | 115200 | 4M | IDs | Async | Status |
|---|---|---|---|---|---|
| version/device info | ✓ | ✓ | verify | no | implement/test |
| button query/set/click | ✓ | ✓ | verify | optional stream | implement/test |
| relative move | ✓ | ✓ | verify | no | implement/test |
| smooth/silent/Bezier library behavior | ✓ | ✓ | verify | no | implement/test |
| wheel/scroll/drag | ✓ | ✓ | verify | no | implement/test |
| axis/button locks | ✓ | ✓ | verify | reflected | implement/test |
| button monitor/capture | ✓ | ✓ | correlate | yes | implement/test |
| read/spoof/reset serial | ✓ | ✓ | verify | re-enum event | implement/test |
| batch/raw commands | ✓ | ✓ | preserve order | interleaving test | implement/test |
Sources
- Espressif ESP32-S3-MINI-1/1U datasheet and ESP32-S3 Hardware Design Guidelines.
- WCH CH343 datasheet CH343DS1.
- Public MAKCU behavior and commonly exposed library capabilities enumerated in the project redesign requirements.
Unresolved quirks
Golden-device captures are still required for exact MAKCU/KMBox B+ prompt strings, whitespace, error text, command-ID syntax, undocumented B+ commands, reset timing, event interleaving, CH343G enumeration, NET UUID/session quirks and model-specific HID feature reports. These do not block clean-room implementation but block a claim of exact firmware-identical compatibility.
Scope and clean-room boundary
Transport
Required compatibility front ends
Expected USB identity
Public command families
Behavioral requirements
1:1 physical mouse passthrough
Public KMBox NET constants
Compatibility matrix
Sources
Unresolved quirks
