KATASYMBOL E12 Lab

Open-source Python tools for reverse engineering and printing to KATASYMBOL/SUPVAN E12-style Bluetooth label makers.

The goal of this project is simple: make the printer usable without the vendor mobile app. It provides a small protocol library, a command-line tool, a Tkinter GUI, and a raw BLE experiment harness so developers can inspect the printer, render labels, and send print jobs directly over Bluetooth Low Energy.

This is not an official KATASYMBOL or SUPVAN SDK. It is a community reverse-engineering project built from public protocol notes plus hands-on testing against real hardware.

What Works

• Scan for nearby BLE devices and identify likely printer candidates.
• Probe printer characteristics, status, and label material metadata.
• Print text labels.
• Print image labels.
• Print QR labels.
• Use a GUI preview before sending a job.
• Batch-print one incrementing QR label per click, for IDs like COB-1, COB-2, COB-3.
• Adjust experimental protocol settings when a printer behaves differently.

The most reliable tested path so far is:

• E12-class BLE printer
• BLE service 0000fee7-0000-1000-8000-00805f9b34fb
• characteristic 0000fec1-0000-1000-8000-00805f9b34fb
• 96-dot printhead
• 12 mm strip width
• raster data sent in compressed 512-byte frames

Why This Exists

These small label printers are useful, but the official workflow usually depends on a closed mobile app. This project documents enough of the Bluetooth protocol to let you print from your own scripts and tools.

It is also meant to be a practical reverse-engineering workspace. The GUI keeps debug controls visible because different printer firmware revisions may need slightly different command timing, status handling, or stop behavior.

Project Layout

• katasymbol_e12.py - protocol code, raster rendering, compression, CLI.
• katasymbol_e12_gui.py - Tkinter desktop UI for manual and batch printing.
• e12_reverse_lab.py - raw BLE experiment runner for protocol testing.
• requirements.txt - runtime dependencies for direct script use.
• pyproject.toml - package metadata and console entry points.

Install

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

This installs three commands:

katasymbol-e12
katasymbol-e12-gui
e12-reverse-lab

For script-only development, this also works:

pip install -r requirements.txt

GUI Usage

Start the GUI:

katasymbol-e12-gui

or:

python katasymbol_e12_gui.py

Recommended first run:

1. Open the Devices tab.
2. Click Scan and select the printer.
3. Click Probe and confirm check=True.
4. Open Manual Print.
5. Use Dry Run to verify the rendered payload size.
6. Print Test before printing custom labels.
7. Use Batch QR when you want one incrementing QR label per click.

The GUI stores remembered devices, settings, batch counter, and log outside the repository:

~/.katasymbol-e12/gui_state.json

Override that path with:

KATASYMBOL_E12_STATE=/path/to/gui_state.json katasymbol-e12-gui

CLI Usage

Scan:

katasymbol-e12 scan

Probe:

katasymbol-e12 probe <BLE_ADDRESS_OR_UUID>

Print text:

katasymbol-e12 print-text <BLE_ADDRESS_OR_UUID> "HELLO E12" \
  --label-width-mm 12 \
  --length-mm 40 \
  --printhead-width-dots 96

Print an image:

katasymbol-e12 print-image <BLE_ADDRESS_OR_UUID> label.png \
  --label-width-mm 12 \
  --length-mm 40 \
  --printhead-width-dots 96

Render without printing:

katasymbol-e12 dry-run "HELLO E12" \
  --label-width-mm 12 \
  --length-mm 40 \
  --printhead-width-dots 96

Raw BLE Lab

e12-reverse-lab sends low-level command/data sequences. It is useful for protocol research, but it can leave the printer stuck in a busy or printing state. Keep the printer nearby and be ready to power-cycle it.

Run with an explicit address:

e12-reverse-lab --address <BLE_ADDRESS_OR_UUID> \
  --pattern full_band \
  --length-mm 40

Or set the address once:

export KATASYMBOL_E12_ADDRESS=<BLE_ADDRESS_OR_UUID>
e12-reverse-lab --pattern columns

Protocol Background

This project builds on public SUPVAN protocol work, especially:

• https://github.com/heeen/supvan-cups
• https://github.com/heeen/supvan-cups/blob/master/docs/PROTOCOL.md

The printer uses 0x7E 0x5A command frames and compressed raster data frames. Related KATASYMBOL/SUPVAN BLE printers have been seen using these GATT patterns:

• service 0000fee7-0000-1000-8000-00805f9b34fb, characteristic 0000fec1-0000-1000-8000-00805f9b34fb
• service 0000e0ff-3c17-d293-8e48-14fe2e4da212, notify 0000ffe1-0000-1000-8000-00805f9b34fb, write 0000ffe9-0000-1000-8000-00805f9b34fb
• service 0000ff00-0000-1000-8000-00805f9b34fb, notify 0000ff01-0000-1000-8000-00805f9b34fb, write 0000ff02-0000-1000-8000-00805f9b34fb

Known Quirks

• Some printers report ribbon_end=True even when printable label stock is installed. The GUI includes Ignore ribbon_end status for this case.
• Some firmware revisions need different STOP_PRINT timing to reduce trailing blank feed.
• macOS exposes BLE devices as UUID-like identifiers instead of public MAC addresses.
• If a print job freezes, use Stop Print first. If that does not clear the state, power-cycle the printer.

Safety

Start with short labels and low density. The protocol is still experimental, and bad command sequences can waste label stock or leave the printer busy until it is restarted.

License

MIT. See LICENSE.