Note

This is a fork of the original project derkalle4/python3-idotmatrix-library which is no longer maintained due to the author's health condition. This fork aims to continue the development and maintenance of the library, ensuring it remains functional and up-to-date for users who rely on it for controlling iDotMatrix pixel displays.

Caution

Not compatible with the original project!
While the featureset should be identical (or better), the structure of the original project has been significantly altered to improve usability and maintainability. This means it is not possible to switch between the original and this fork without manually adjusting the code.

In addition to that, the support for returning the raw bytearray data for specific commands has been dropped to simplify maintenance and usability of the library.

Pixel Display Library

Control all your 16x16 or 32x32 or 64x64 iDotMatrix Pixel Displays

Report Bug or Request Feature

Table Of Contents

• About the Project
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
• License
• Authors
• Acknowledgements

About The Project

This repository aims to reverse engineer the iDotMatrix Android App for pixel screen displays like this one on Aliexpress. The goal is to provide a library which can be used to connect and control these displays without the need for the official app.

Getting Started

Prerequisites

Please install the following for your distribution (Windows may work but it is untested):

• latest Python3
• Python3 Virtual Env

Installation

use latest github source code

1. Clone the repo

git clone https://github.com/markusressel/python3-idotmatrix-library.git

2. Install the latest version locally

cd python3-idotmatrix-library/
pip -m venv venv
source venv/bin/activate  # on Windows use `venv\Scripts\activate`
pip install --upgrade pip poetry
poetry install

Usage

Device API Client

import asyncio

from idotmatrix import IDotMatrixClient, ScreenSize


async def main():
  # create a new IDotMatrixClient instance with the screen size of your device
  client = IDotMatrixClient(
    screen_size=ScreenSize.SIZE_64x64,  # or use ScreenSize.SIZE_32x32 or ScreenSize.SIZE_16x16
    # mac_address="00:11:22:33:44:55",  # (optional) specify your device's Bluetooth address
  )
  # (optional) connect to first found iDotMatrix Pixel Display
  # If the device is not connected when issuing commands, an automatic connection attempt will be made.
  await client.connect()

  # do something with the device by using one of the toplevel functions or modules e.g. chronograph, clock, countdown, etc.
  await client.set_brightness(50)  # set brightness to 50%

  await client.text.display_text("Hello World!")  # display text on the screen


if __name__ == "__main__":
  try:
    asyncio.run(main())
  except KeyboardInterrupt:
    quit()

For more examples please check the example.py.

Digital Picture Frame

Besides the IDotMatrixClient, this repository also contains a DigitalPictureFrame class which can be used to display images and GIFs in a slideshow fashion. See example_digital_picture_frame.py for more details on how to use it.

The DigitalPictureFrame can

• display a static list of images and/or GIFs
• watch one or more directories for images and GIFs
• automatically reconnect to the device in case of an error or connection loss

Roadmap

If you want to contribute please focus on the reverse-engineering part because my personal skills are not that good. Many thanks for all contributions! If you want to dive deep into other issues please check for "#TODO" comments in the source code as well.

• Reverse Engineering
  • Chronograph
  • Clock
  • Countdown
  • Graffiti Board
  • DIY-Mode
  • Animated Images
  • Display Text
  • Alarm & Buzzer (available according to issue #18)
  • Cloud-API to download images
  • Cloud-API to upload images to device
  • Cloud-Firmware Update possible?
  • Eco-Mode
  • Fullscreen Color
  • MusicSync
  • Scoreboard
  • bluetooth password protection
  • understand the returned byte arrays of the device for better error logs

Helpful Links

• Create Images or GIFs
  • pixilart
    • Create a new drawing and select a preset for the size of your display (e.g. 64x64)

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

• If you have suggestions for adding or removing projects, feel free to open an issue to discuss it, or directly create a pull request after you edit the README.md file with necessary changes.
• Please make sure you check your spelling and grammar.
• Create individual PR for each suggestion.
• Please also read through the Code Of Conduct before posting your first idea as well.

Creating A Pull Request

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the GNU GENERAL PUBLIC License. See LICENSE for more information.

Acknowledgements

Original project by derkalle4 and jmgraeffe.

• Othneil Drew - README Template
• LordRippon - Reverse Engineering for the Displays
• 8none1 - Reverse Engineering for the Displays
• schorsch3000 - smaller fixes
• tekka007 - code refactoring and reverse engineering
• inselberg - Reverse Engineering for the Displays