control all your 16x16 or 32x32 pixel displays

Explore the docs »

Report Bug . Request Feature

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

This repository aims to reverse engineer the iDotMatrix Android App for pixel screen displays like this one on Aliexpress. The goal is to be able to control multiple pixel screen displays via a GUI, an Rest API and the command line.

The initial reason for this project was to have a foundation to update one or multiple pixel displays during live streams on Twitch or other platforms where one can use this to further automate interactions with the audience. Please let us know if you're using this to do so :)

• Python 3
• argparse
• asyncio
• bleak
• pillow

To get a local copy up and running follow these simple example steps:

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

• latest Python3
• Python3 Virtual Env

1. Clone the repo

git clone https://github.com/derkalle4/python3-idotmatrix-client.git

2. Create virtual environment and install all dependencies

./create_venv.sh

If you used the ./create_venv.sh you should use this command to run the app:

./run_in_venv.sh <YOUR_COMMAND_LINE_ARGUMENTS>

If you do not use a virtual environment the command will look like this:

python3 .\app.py <YOUR_COMMAND_LINE_ARGUMENTS>

Specifies the address of the pixel display device.

./run_in_venv.sh --address 00:11:22:33:44:ff

Sets the time of the device to the current local time.

./run_in_venv.sh --address 00:11:22:33:44:ff --sync-time

Sets the time of the device to any time you want.

./run_in_venv.sh --address 00:11:22:33:44:ff --sync-time --set-time 18-12-2023-19:10:10

Turns the screen either on or off.

./run_in_venv.sh --address 00:11:22:33:44:ff --screen on
./run_in_venv.sh --address 00:11:22:33:44:ff --screen off

Rotates the device display by 180 degrees. True to rotate. False to disable rotation.

./run_in_venv.sh --address 00:11:22:33:44:ff --flip-screen true

Freezes or unfreezes the screen. Does not seem to work currently.

./run_in_venv.sh --address 00:11:22:33:44:ff --toggle-screen-freeze

Sets the mode of the cronograph:

• 0 = reset
• 1 = (re)start
• 2 = pause
• 3 = continue after pause

./run_in_venv.sh --address 00:11:22:33:44:ff --chronograph 0

Sets the mode of the clock:

• 0 = default
• 1 = christmas
• 2 = racing
• 3 = inverted full screen
• 4 = animated hourglass
• 5 = frame 1
• 6 = frame 2
• 7 = frame 3

./run_in_venv.sh --address 00:11:22:33:44:ff --clock 0

Shows the date in addition to the time.

./run_in_venv.sh --address 00:11:22:33:44:ff --clock 0 --clock-with-date

Shows the time in 24h format.

./run_in_venv.sh --address 00:11:22:33:44:ff --clock 0 --clock-24h

Sets the color of the clock in format --

./run_in_venv.sh --address 00:11:22:33:44:ff --clock 0 --clock-color 255-0-0

Sets the mode of the countdown:

• 0 = disable
• 1 = start
• 2 = pause
• 3 = restart

./run_in_venv.sh --address 00:11:22:33:44:ff --countdown 1

Sets the time of the countdown in format -

./run_in_venv.sh --address 00:11:22:33:44:ff --countdown 1 --countdown-time 5-0

Sets all pixels to the given color in format --

./run_in_venv.sh --address 00:11:22:33:44:ff --fullscreen-color 255-255-255

Sets one or multiple pixels to the given color in format ----

./run_in_venv.sh --address 00:11:22:33:44:ff --pixel-color 10-10-255-255-255

Sets the score of the scoreboard <0-999>-<0-999>

./run_in_venv.sh --address 00:11:22:33:44:ff --scoreboard 21-12

Wether to enable the image display mode or not. Set to true show an image or false to hide.

./run_in_venv.sh --address 00:11:22:33:44:ff --image true

Path to an image to display on the device without further processing. This must match your display pixel size (e.g. demo_16.png for the 16x16 variant). See --process-image for more information on how to process a larger (or smaller) image!

If you do not want to process the image: when using Gimp I had to export the file to a 32x32 pixel PNG (for my 32x32 Pixel Display) and disable all features except the "save resolution" feature to save time when sending the image to the device. Every kind of metadata makes the image bigger and because we only can send around 20bytes at once this can certainly increase the transfer time!

The Demo PNG was downloaded from OpenGameArt.org.

./run_in_venv.sh --address 00:11:22:33:44:ff --image true --set-image ./demo_16.png
./run_in_venv.sh --address 00:11:22:33:44:ff --image true --set-image ./demo_32.png
./run_in_venv.sh --address 00:11:22:33:44:ff --image true --set-image ./demo_64.png

If specified it will process the given image. If used, the Python3 library Pillow will be utilized to convert the given image to a PNG with the given amount of pixels (e.g. 32 for 32x32 or 16 for 16x16 pixels). Technically you could use all kind of sizes and variations of images. Keep in mind: processing could take some time depending on your computer. In my tests the given demo.png file takes around 1 second without processing and three seconds with processing.

./run_in_venv.sh --address 00:11:22:33:44:ff --image true --set-image ./demo_512.png --process-image 32

Path to an GIF to display on the device. See --process-gif for more information! The Demo GIF was downloaded from OpenGameArt.org.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-gif ./demo.gif

If specified it will process the given image. If used, the Python3 library Pillow will be utilized to convert the given image to a GIF with the given amount of pixels (e.g. 32 for 32x32 or 16 for 16x16 pixels). Technically you could use all kind of sizes for the GIF. Keep in mind: processing could take some time depending on your computer and using larger GIFs may result in a bad image quality. You should hand-craft your GIFs in the correct format for best results!

./run_in_venv.sh --address 00:11:22:33:44:ff --set-gif ./demo.gif --process-gif 32

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 pasword protection
  • understand the returned byte arrays of the device for better error logs
• outsource the reverse-engineered part to a library (suggestion from issue #17)
• build configuration file to manage (multiple) devices
• Build command line interface with all features to interact with the device
• Build RestAPI to interact with the device remotely
  • Homeassistant Integration
• Build GUI to allow non-technical people to use this software
• build search tool to find displays nearby
• make this software compatible with Windows and Linux
• provide executables for Windows

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.

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

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

• Kalle Minkner - Project Founder
• Jon-Mailes Graeffe - Co-Founder

• 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