Skip to content
This repository was archived by the owner on Jun 5, 2025. It is now read-only.

derkalle4/python3-idotmatrix-client

BranchesTags

Repository files navigation

Note

Due to a long-term health condition (post-COVID since almost three years), I am unable to continue developing this project. Although many amazing contributors have helped over the years, I am unsure when I will be able to resume work. This is my most popular project (over 300 stars!), and I hope others will continue to improve the client and library for various use cases, such as Home Assistant integration. Thank you for your understanding and support.


Logo

Pixel Display Client

control all your 16x16 or 32x32 pixel displays

Explore the docs »

Report Bug . Request Feature

Downloads Contributors Forks Stargazers Issues License

Table Of Contents

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 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 :)

Built With

Getting Started

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

Prerequisites

Please install the following for your OS:

  • Latest version of Python (Python3)

Installation

For Linux or MSYS2/Git Bash

  1. Clone the repo
git clone https://github.com/derkalle4/python3-idotmatrix-client.git
  1. cd to it
cd python3-idotmatrix-client
  1. Create virtual environment and install all dependencies
./create_venv.sh

For windows

  1. Download the repository

Either click the green "Code" button in GitHub and clicking "Download ZIP", and extracting this file to a folder, or by using Git:

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

Go to https://www.python.org/downloads/windows/ and install the latets stable release.

  1. Open it in Explorer and run "build.ps1"

The build.ps1 script automatically handles setting up the python virtual environment and a shortcut to the GUI.

Open this script by right clicking it, and clicking "Run with PowerShell", or by nagivating to them in a PowerShell terminal and writing "./" followed by its filename.

Usage

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 have manually opened the virtual environment, or are not using a virtual environment, the same can be accomplished with the following:

python3 .\app.py <YOUR_COMMAND_LINE_ARGUMENTS>

command line arguments

-h or --help

Shows you every available command line argument. This will always show the newest args, try it if something from this section doesn't work, in case an argument here is outdated.

--address (required for all commands except "scan")

Specifies the address of the pixel display device. Use "auto" to use the first available device (automatically looking for IDM-* devices in range).

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

Scans all bluetooth devices in range for iDotMatrix devices. Quits afterwards. Cannot be combined with other commands (use --address auto instead).

./run_in_venv.sh --scan
--sync-time

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

./run_in_venv.sh --address 00:11:22:33:44:ff --sync-time
--set-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
--screen

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
--flip-screen

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
--toggle-screen-freeze

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
--chronograph

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
--clock

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
--clock-with-date

Shows the date in addition to the time.

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

Shows the time in 24h format.

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

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
--countdown

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
--countdown-time

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
--fullscreen-color

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
--pixel-color

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
--scoreboard

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

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

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
--set-image

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 ./images/demo_16.png
./run_in_venv.sh --address 00:11:22:33:44:ff --image true --set-image ./images/demo_32.png
./run_in_venv.sh --address 00:11:22:33:44:ff --image true --set-image ./images/demo_64.png
--process-image

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 ./images/demo_512.png --process-image 32
--set-gif

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 ./images/demo.gif
--process-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 ./images/demo.gif --process-gif 32
--set-text

Sets a given text to the display. The Demo Font was downloaded from fontspace.com and is licensed open source (see font folder or link for details).

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World"
--text-size

Sets the size of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-size 10
--text-mode

Sets the mode of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-mode 1
--text-speed

Sets the speed of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-speed 50
--text-color-mode

Sets the color mode of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-color-mode 1
--text-color

Sets the color of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-color 255-255-255
--text-bg-mode

Sets the background mode of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-bg-mode 1
--text-bg-color

Sets the background color of the text.

./run_in_venv.sh --address 00:11:22:33:44:ff --set-text "Hello World" --text-bg-color 0-0-255

Gif Compilations

There's no internal method for creating a compilation of gifs or images, similar to what the app offers, but you can create this manually with external tools like ImageMaick or https://ezgif.com/, and upload it to the iDotMatrix device as a single gif.

GUI

Run Methods

You can run the GUI uncompiled with python, or you can build an executible with Pyinstaller.

Method 1) Run via Python

  • Open terminal at /python3-idotmatrix-client
  • Run pip install pyqt5
  • Run py gui.py

Method 2) Build and Run using PyInstaller

  • Run build.bat for Windows or build.sh for Linux
  • Click the new iDotMatrix Controller program in /python3-idotmatrix-client

Method 3) (Windows only) Build and Run using build.ps1

  • Right click build.ps1 in Windows Explorer, and click "Run with PowerShell", and answer its prompt.
  • Open the new iDotMatrix GUI program on your desktop

Features

  • Device Search: Scans for nearby devices, asks for name, adds to home screen.
  • Clock Style: Set the Clock Style and Color. Auto sync time.
  • Sync Time: Sync time to machine clock.
  • Set Time: Set time.
  • Screen On/Off: Turn the screen On or Off.
  • Stop Watch: Use a stop watch.
  • Countdown Timer: Use a Countdown Timer.
  • Set Text: Set the text value and effects.
  • Color Studio: Set background color, or paint your own designs and save them for later use.
  • Scoreboard: Show a three-digit, two player scoreboard.
  • Set Image: Pick an image from the file browser to set. Auto Image Processing.
  • Set GIF: Pick a GIF from the file browser to set. Auto GIF Processing is attempted but does not always work. Source material closer to 16x16 or 32x32 works best.

Known Issues

  • Commands somtimes fail to connect to the device. Usually rerunning the last command will work.
  • Screen Flip & Screen Freeze work inconsistantly and are not included with the GUI.

Found a GUI bug? Submitting a new GUI request? Tag @TheBigWazz


Troubleshooting

Can't upload gifs/images

Try:

  • Sending the "reset" command (--reset)
  • Use --process-image so the program tries to scale your images correctly for you
  • Pre-scale your image to 32x32 or 16x16 pixels using an image editor, and send it unprocessed ("raw" in the GUI)
  • Convert your image to a gif and upload it (You can use ImageMagick or something like http://ezgif.com)

Can't find device ID

Try:

  • Check that bluetooth is on
  • Place the iDotMatrix display nearby
  • Unplug and replug the iDotMatrix display
  • Restart your PC
    • If that's not an option for you, killing every "Python" task might work instead.

Other

If all else fails, you can open an issue on the repository's GitHub.

Roadmap

If you want to contribute please focus on the reverse-engineering part (find more information in the iDotMatrix Library). 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.

  • 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

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.

Authors

Acknowledgements

About

reverse engineered python3 client to control all your 16x16 or 32x32 pixel displays (experimental)

Resources

Readme

License

GPL-3.0 license

Code of conduct

Code of conduct
Activity

Stars

301 stars

Watchers

28 watching

Forks

52 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 11

Languages