Lontium Open Tools

Python library and CLI for direct I²C access to Lontium LT chips, plus firmware inspection and an open protocol/reverse-engineering reference for LT Programmer 7.1.1 beta.

Designed for Linux boards and test fixtures where the LT device is already connected to a host I²C controller. No USB bridge is required. This is a clean reimplementation derived from static analysis of the supplied Windows package, not a patched or redistributed copy of the vendor program.

Files

Path	Description
src/lontium_open/programmer.py	Paged-register device API and flash-algorithm extension point
src/lontium_open/transports/i2cdev.py	Direct Linux /dev/i2c-* combined-transaction backend
src/lontium_open/firmware.py	Strict Intel HEX and raw-binary parser
src/lontium_open/crc.py	Recovered LT SUM8, CRC-8, and CRC-32 variants
src/lontium_open/data/profiles.json	Sanitized snapshot of all 28 vendor chip selections
PROTOCOL.md	Reverse-engineering report, packet formats, architecture, and confidence boundary
tests/	Hardware-free tests using mocked I²C and known protocol vectors

Status

Area	Status
Direct host I²C with repeated START	Implemented and tested without target hardware
Raw and paged register read/write/dump	Implemented
Intel HEX and binary inspection	Implemented and tested
Vendor SUM8, CRC-8, and CRC-32	Implemented and tested
28 chip-selection profiles	Imported from UpgradeFlash.xml
LT TCP/remote frame codec	Implemented and tested
Chip erase/program/read state machines	Plug-in boundary only; intentionally disabled pending exact-part validation
Optional CH341 bridge	Retained as a secondary backend; not required
Vendor “BB” WinUSB and UART offline modes	Documented, not implemented

The transport and container formats are understood. Full flashing is a different risk class: the vendor executable contains many silicon-family state machines, and an incorrect sequence can erase calibration, EDID, keys, or the bootable image. No bundled profile therefore opts into a flash algorithm.

Requirements

• Python 3.10+
• Linux with the i2c-dev module and a host controller exposed as /dev/i2c-N
• Permission to open the selected bus device

Adapter numbers can change between boots. Check /sys/class/i2c-dev/ or run i2cdetect -l to identify the correct controller.

git clone https://github.com/nasheed-x/lontium_open_tools.git
cd lontium_open_tools
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'

The direct-I²C and firmware paths have no third-party runtime dependencies.

Command Line

Firmware and profiles

# Search the 28 recovered chip selections
lt-open profiles 8711

# Validate an image and calculate all recovered checksum variants
lt-open inspect firmware.hex

# Calculate across a full 0x6000-byte flash region, filling gaps with 0xff
lt-open inspect firmware.hex --base 0 --size 0x6000

# Encode/decode the recovered remote frame format
lt-open remote-encode --command 0x03
lt-open remote-decode "aa aa 03 03 00 00 06 bb bb"

inspect validates every Intel HEX record checksum and never modifies the input. Without --base and --size, LT checksums cover the image's smallest address span. Reproducing a target's flash CRC requires the correct full region for that silicon family.

Direct I²C

# Confirm that the host bus exists and is accessible
lt-open doctor --bus /dev/i2c-1

# Scan by issuing one-byte current-address reads
lt-open scan --bus /dev/i2c-1

# Read four registers using a repeated START
lt-open read --bus /dev/i2c-1 \
  --address 0x2b --page 0x80 --register 0x00 --length 4

# Dump 64 bytes from one register page
lt-open dump --bus /dev/i2c-1 \
  --address 0x2b --page 0x80 --start 0x00 --length 0x40

# Explicit register write; mutation requires --yes
lt-open write --bus /dev/i2c-1 \
  --address 0x2b --page 0x80 --register 0x10 --data 0x01 --yes

The API uses standard 7-bit addresses. If a Lontium document or the Windows tool shows an 8-bit write address such as 0x56, make that convention explicit:

lt-open read --bus /dev/i2c-1 \
  --address 0x56 --address-mode 8bit --register 0x00

Bus speed is configured by the host controller/device tree, not this program. Scanning is not electrically or semantically passive: a current-address read can advance an internal pointer on some devices. Prefer a known address when available.

Python Library

from lontium_open.programmer import LontiumDevice
from lontium_open.transports import I2cDevTransport

with I2cDevTransport("/dev/i2c-1") as bus:
    lt = LontiumDevice(bus, address=0x2B)
    chip_bytes = lt.read_register(0x00, length=4, page=0x80)
    print(chip_bytes.hex())

Register reads use Linux I2C_RDWR, so the register write and data read form one combined transaction with a repeated START and no intervening STOP. For application development without hardware, substitute MockTransport.

To add a validated flash implementation, implement the FlashAlgorithm protocol and register it with Programmer. Keep chip identification, backup, region bounds, timeouts, power-loss behavior, and read-back verification inside that implementation.

Optional CH341 Backend

The recovered CH341 stream encoder is retained because it documents the supplied LT Debug Tool path, but direct I²C is the default. To use it explicitly:

python -m pip install -e '.[usb]'
lt-open read --transport ch341 --address 0x2b --register 0x00

Safety

• Verify target I/O voltage, power sequencing, and common ground before access.
• Back up every readable region before enabling any future flash algorithm.
• Register writes require --yes, but that flag cannot make an unknown register safe.
• The project does not inject CRCs or infer a flash size from a chip-name match.
• No vendor firmware, device keys, private path history, or proprietary binary is included in this repository.
• Tests mock all hardware; they do not prove electrical compatibility with a particular LT part or board revision.

Tests

The suite covers firmware parsing, checksum vectors, profile import, Linux combined I²C message construction, CH341 stream framing, remote frames, CLI guards, and the unvalidated-flash block.

python -m pytest
# or, with only the standard library:
PYTHONPATH=src python -m unittest discover -s tests -v

Protocol and Analysis

See PROTOCOL.md for the executable inventory and hashes, recovered architecture, register transaction shapes, CRC definitions, remote framing, profile source, known flash-sequence fragments, and what remains unverified.

Disclaimer

This is an independent, unofficial interoperability and research project. It is not affiliated with, authorized by, maintained by, or endorsed by Lontium Semiconductor. “Lontium” and product names are trademarks of their respective owners and are used only to identify compatible hardware and source material.

The software and analysis are provided as is, without warranty of any kind. Low-level I²C writes and firmware operations can make hardware inoperable or destroy data. You are solely responsible for confirming device identity, electrical compatibility, backups, authorization, and compliance with applicable licenses and law. Do not use this project to bypass access controls, licensing, encryption, or device security.

License

GPL-2.0-or-later. The optional CH341 implementation was cross-checked against WCH's GPL-licensed Linux MPHSI driver as well as the supplied USBIOX.DLL.