# Legacy TMS2812 / BALZAM protocol

`src/tms2812.c` is the shared wire implementation for the host terminal,
memory access, firmware framing and CRC validation. The wire format is the
legacy controller protocol, **not SETProtocol v2**. The shared library name
does not select or change the wire format.

- `tms2812_build_memory_request`: PEEK (56), POKE (57), host operation 0
  for PING (PEEK of service word address `0x00000100`).
- `tms2812_build_test_request`: TEST_ALL (66), two uint16 timings and
  twelve control bytes.
- `tms2812_build_fixed_request`: address, command, payload, CRC16/MODBUS.
- `tms2812_validate_response`: checks controller, command, length and CRC;
  may accept omission of the two reserved bytes after CRC. The transport
  must wait for a receive gap before sending the next command.
- UPLOAD (52) retains its separate validator: four reserved trailing bytes.

Bindings:

- Python: `python/protocan/tms_terminal.py` calls the exported `pcan_abi.h`
  functions through ctypes. `set_devices.tms_terminal` keeps telemetry
  layouts/parsing; it uses the C framing for CMD_STD.
- Kotlin: `ports/android/kotlin/ru/setcorp/setflash/core/Tms2812Protocol.kt`
  calls the same C functions through `setprotocol_jni.c` and
  `NativeSetProtocol`. Consumers include the templates Kotlin source tree;
  they must not keep a second Tms2812Protocol class in their app source tree.

Consumers own UART I/O, timeout/settle timers, sequential write/readback
transactions, GUI field names and JSON display profiles. They do not own
copies of request builders or response CRC checks.

Rebuild the native library after updating templates. There is no fallback
to a separate local encoder if the terminal ABI is missing.

Tests: `tests/test_tms2812.c`, `python/tests/test_tms_terminal_shared.py`,
and the Android `TmsTerminalSharedTest`. All use the same Android/captured
PING and PEEK vectors and TEST_ALL field layout.