0.2.0

This is the first release on PyPI (pip install idotmatrix-api-client). It collects the reliability work, the protocol research and the groundwork for the Home Assistant integration ha-idotmatrix.

Breaking changes

• idotmatrix.digital_picture_frame moved to idotmatrix.apps.digital_picture_frame. The old path is gone.
• ConnectionManager.client (the raw BleakClient) is gone. The connection goes through a Transport now, see below.
• IDotMatrixClient(screen_size=...) is optional now, which is not breaking, but the screen_size property raises a RuntimeError until the size is known (see below).

Reliable uploads

• Images and GIFs wait for the acknowledgement of every 4096 byte chunk, like the official app. Before, the device dropped or garbled data, and animations stuttered or lost frames.
• All frames of a GIF get color tables of the same size, which the device needs to play them correctly.
• Photos are shown with ImageModule.show_image_file (the "static image" upload of the app), which needs no mode switching. The picture frame uses it and can mix photos and GIFs freely.
• The BLE packet size follows the negotiated MTU, which fixes uploads on macOS and other stacks with a small MTU.
• show_image_file(png=True) is an experimental opt-in that sends a PNG instead of raw pixels, which is a little faster. Tested on a 64x64 only.

Talking to the device

• Commands are acknowledged and the library waits for the acknowledgement of the commands that are known to be acknowledged. A rejected command raises CommandRejectedError.
• A heartbeat (set_heartbeat) notices a link that died without Bluetooth noticing, f.e. an unplugged display, and can reconnect.
• CommonModule.get_device_info() returns the firmware version, the screen type and the password flag, which the device sends as the reply to the set time command.
• IDotMatrixClient(screen_size=None) asks the device for its screen size when connecting (detect_screen_size()).
• MusicSync works with the microphone of the display (set_mic_type).

Internals

• idotmatrix/transport.py: a Transport protocol and BleakTransport. ConnectionManager(transport_factory=...) and IDotMatrixClient(transport_factory=...) allow another way of connecting, and tests/fake_transport.py simulates a display for tests.
• idotmatrix/protocol.py: a table of the known commands and build_command, which writes the length bytes.
• Images, GIFs and fonts are loaded in a thread, so the event loop is not blocked.
• docs/DEVICE-PROTOCOL.md collects everything known about the protocol, marked as verified, from the app, claimed or guessed.
• 339 tests, 94 % line coverage, CI for Python 3.12 to 3.14.

For Home Assistant and other Bluetooth stacks

• BleakTransport and IDotMatrixClient(ble_device=...) take a BLEDevice instead of an address, BleakTransport(connector=...) connects with bleak-retry-connector, and install_signal_handlers=False leaves SIGINT and SIGTERM alone. See the README.

Fixes

• connect() without an address no longer deadlocks, and it no longer notifies the listeners when it is already connected.
• The folder watching of the picture frame works, and removing a picture no longer skips the next one.
• Color parsing: #fff shorthand, length checks, named colors without matplotlib.
• Dropped the asyncio and matplotlib dependencies.

Thanks to everybody who contributed to the fork: compact fonts and font selection, MTU aware fragmentation, multi-pixel graffiti, light effects, reset and chunked GIF uploads.