Reference

MAKCU API

KM Host Protocol — v3.8 · Comprehensive command reference for the MAKCU ecosystem.

Protocol

Transport & Framing

All replies start with km. and end withCRLF followed by the prompt>>> .

TX samples below show the final prompt as\r\n>>> .

RX (Host → Device)

ASCII commands, e.g. move(10,-3), terminated by \r/\n/;
Optional binary frame: DE AD <lenLE:2> <ASCII or binary payload>

TX (Device → Host)

Format: km.payload\r\n>>>
Setters echo the input as ACK unless suppressed byecho(0).
Some streaming replies carry binary after the km. prefix:km.mouse<8 bytes> andkm.buttons<1-byte mask>. Lines still terminate with CRLF and the prompt.

Mouse

Buttons

Button status (GET)

Command

left() | right() | middle() | side1() | side2()

Response (GET)

km.left(0/1)
>>>

State bit view: 0=none, 1=physical, 2=software, 3=both.

Button actuation (SET)

Command

left(n) / right(n) / middle(n) / side1(n) / side2(n)

Params

First digit char parsed as int (digits map to their numeric value, e.g. 0→0, 1→1).

Response (SET)

km.left(0/1)
>>>

Echo ACK (subject to echo(0|1)).

Button lock (GET/SET)

Command

lock_ml(), lock_mr(), lock_mm(), lock_ms1(), lock_ms2()

Response (GET)

km.lock_ml(0/1/2)
>>>

Response (SET)

km.lock_ml(0/1)
>>>

Button catch (GET/SET)

Command

catch_ml(), catch_mr(), catch_mm(), catch_ms1(), catch_ms2()

Params

SET: 0=auto, 1=manual (button must be locked)

Response (GET)

km.catch_ml(0/1)
>>>

Response (SET)

No immediate ACK (async). Poll with GET to confirm state.

Mouse

Locks

Whole-axis locks (GET/SET)

Command

lock_mx(), lock_my() / lock_mx(0|1), lock_my(0|1)

Response (GET)

km.lock_mx(0/1)
>>>

Response (SET)

km.lock_mx(0/1)
>>>

Directional locks (GET/SET)

Command

lock_mx+(), lock_mx-(), lock_my+(), lock_my-()

Response (GET)

km.lock_my+(0/1)
>>>

Response (SET)

km.lock_my-(0/1)
>>>

Motion

move(x,y[,seg][,cx1,cy1[,cx2,cy2]]) — SET

Command

move(x,y[,seg][,cx1,cy1[,cx2,cy2]])

Params

x,y: int16; seg ≥ 1 (default 1, max 512); optional cubic Bézier controls. If only segments are provided (no control points), a random 2-point control curve is generated. If only (cx1,cy1) is provided it is duplicated.

Response (SET)

km.move(10,-3)
>>>

km.move(100,50,8,40,25,80,10)
>>>

Both return the input echo (ACK).

moveto(X,Y[,seg][,cx1,cy1[,cx2,cy2]]) — SET

Command

moveto(X,Y[,seg][,cx1,cy1[,cx2,cy2]])

Notes

Clamped to screen; queued as absolute (internally relative). Special: moveto(0,0) with seg=1 and no controls triggers calibration.

Response (SET)

km.moveto(640,360)
>>>

wheel(w) — SET

Command

wheel(w)

Params

w: int8

Response (SET)

km.wheel(-5)
>>>

Echo ACK.

silent(x,y) — SET

Command

silent(x,y)

Params

Two-frame silent click at (x,y)

Response (SET)

km.silent(400,300)
>>>

Echo ACK.

Streaming

Axis streaming (GET/SET)

Command

axis() / axis(mode[,period_ms])

Params (SET)

mode: 0=off, 1=abs, 2=rel, 3=act; period_ms: 1..1000 (kept if omitted). When off, the stored period is retained but not used.

Response (GET)

km.axis(rel,25)
>>>

Returns the resolved mode and current period.

Response (SET)

km.axis(act,1)
>>>

ACK returns the normalized pair (mode,period); not a verbatim echo; honors echo(0|1).

Buttons streaming (GET/SET)

Command

buttons() / buttons(mode[,period_ms])

Params

mode: 0=off, 1=raw (physical), 2=mut (post-edit); period_ms: 1..1000 (kept if omitted; retained when off but not used).

Response (GET)

km.buttons(mut,25)
>>>

Human-readable mode with current period (ms).

Response (SET)

km.buttons(raw,10)
>>>

ACK reports the normalized (mode,period); honors echo(0|1).

When enabled and the period elapses, the device emits a de-duplicated 1-byte mask:

km.buttons<mask_u8>
>>>

raw: physical (pre-edit) mask; mut: processed (post-edit) mask.
Strictly self-gated: only checks/sends when period_ms has elapsed; per-view de-duplication.

Mouse composite streaming (GET/SET)

Command

mouse() / mouse(mode[,period_ms])

Modes

0=off, 1=raw, 2=mut

Params

period_ms: 1..1000 (kept if omitted; retained when off but unused). Rate-limited; zero-suppressed with de-dup.

GET reply

km.mouse(mut,25)
>>>

SET reply

km.mouse(raw,10)
>>>

ACK returns normalized (mode,period); honors echo.

Streaming format

While enabled, device emits one fixed-length binary frame per event:

km.mouse<bytes>
>>>

Bytes follow the ASCII prefix directly; line still ends with CRLF and the prompt.

Binary layout (LE)

mask: u8 — button bitmask
x: int16 — X delta/position*
y: int16 — Y delta/position*
wheel: int8 — vertical wheel
pan: int8 — horizontal wheel (tilt-wheel)
tilt: int8 — additional tilt/aux axis

*Raw: x/y are raw deltas. Mut: post-edit effective. If km.axis(abs) is active, x/y are absolute, clamped to screen.

Non-applicable fields are encoded as 00 to preserve spacing.

Example (hex, spaced):

km.mouse  07 00  05 00  FB FF  01  FF  00
>>>

mask=0x07, x=+5 (05 00), y=-5 (FB FF), wheel=+1 (01), pan=-1 (FF), tilt=0 (00)

All multi-byte fields are little-endian; each frame is 8 bytes: 1+2+2+1+1+1.

Screen

Position & Screen

getpos() — GET

Command

getpos()

Response (GET)

km.(123,456)
>>>

Absolute position (clamped to screen(W,H)).

screen() / screen(W,H) — GET/SET

Command

screen() / screen(W,H)

Response (GET)

km.screen(1920,1080)
>>>

Response (SET)

km.screen(2560,1440)
>>>

SETTINGS

Baud rate

Baud rate (GET/SET)

Command

baud() / baud(<rate>)

Params

rate: 115200 – 4000000; use 0 to reset to 115200.

Response (GET)

km.baud(115200)
>>>

Returns current baud rate.

Response (SET)

km.baud(921600)
>>>

Applies immediately; host must re-open serial at new speed.

Reset (SET)

km.baud(0)
>>>

Resets to default 115200 baud.

NEW API

Baud rate change (Binary)

Purpose

Set UART baud rate using a binary frame (no ASCII command).

Frame

DE AD <lenLE:2> <cmd:0xA5> <baud_rate:LE32>

Header

DE AD

Length

u16 little-endian (payload bytes only). For this command: 5 (1 cmd + 4 baud)

Command

0xA5 (baud rate set)

Payload

uint32_t baud_rate (little-endian). Example: 115200 → 00 C2 01 00

Example (115200)

DE AD 05 00 A5 00 C2 01 00

Breakdown: DE AD | 05 00(len=5) | A5 (cmd) |00 C2 01 00 (115200 LE)

Effect

Applies immediately; host must re-sync serial port at the new speed.

Spec

Limits & Parsing

Bézier segments: default 1, max 512
Movement integers: int16 with saturation
Wheel: int8
Legacy ASCII terminators: \r, \n, ;
Binary RX supported: DE AD <lenLE> <payload>
echo(0) suppresses most setter echoes; GETs still reply
Baud range (baud()): 115200–4000000; baud(0) resets to 115200.

Notes

Tips

The km.axis function can fully decouple mouse movement. Combined with X/Y axis locks, this isolates user inputs from the host for seamless programmatic control.

API version 3.8makcu 2025