[](https://pypi.org/project/IS-Matrix-Forge)
# IS Matrix Forge
**IS Matrix Forge** is a Python framework for creating applications that drive
9×34 LED matrix displays. It provides high level helpers for talking to the
hardware, tools for building animations, and utilities such as progress bars and
a battery monitor.
## Project Overview
Matrix Forge grew out of the LED Matrix Battery Monitor project. The goal is to
make it easy to create rich LED matrix experiences from Python. In addition to
monitoring the battery, you can design custom frames, display scrolling text,
run animations, and integrate the LED matrix with your own applications.
Highlighted features include:
- Device discovery and control via `pyserial`
- Drawing grids and patterns with the `Grid` class
- Built-in and custom animations
- Progress bars that render on the matrix
- A battery monitor example using these building blocks
## Hardware Requirements
- LED Matrix display with dimensions 9x34 (compatible with the project's specifications)
- Serial connection to the computer (USB)
- The LED matrix should have the following hardware identifiers:
- VID: 0x32AC
- PID: 0x20
- Serial Number Prefix: FRAK
## Software Dependencies
This project requires Python 3.12 or newer and the following dependencies:
- chime (>=0.7.0,<0.8.0) - For audio notifications
- pyserial (>=3.5,<4.0) - For serial communication with the LED matrix
- inspy-logger (>=3.2.3,<4.0.0) - For logging
- inspyre-toolbox (>=1.6.0) - Utility functions
- pillow (>=11.2.1,<12.0.0) - Image processing
- opencv-python (>=4.11.0.86,<5.0.0.0) - Image processing
- pysimplegui-4-foss (>=4.60.4.1,<5.0.0.0) - GUI components
- tk (>=0.1.0,<0.2.0) - GUI toolkit
- easy-exit-calls (>=1.0.0.dev1,<2.0.0) - Exit handling
- psutil - For battery status monitoring
## Installation Instructions
### Using Poetry (Recommended)
1. Clone the repository:
```
git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
cd IS-Matrix-Forge
```
2. Install dependencies using Poetry:
```
poetry install
```
3. Activate the virtual environment:
```
poetry shell
```
### Using pip
1. Clone the repository:
```
git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git
cd IS-Matrix-Forge
```
2. Install the package:
```
pip install .
```
## Usage Examples
### Identify Connected Devices
```python
from is_matrix_forge.led_matrix.helpers.device import DEVICES
for dev in DEVICES:
print(dev)
```
### Display Text on the Matrix
```python
from is_matrix_forge.led_matrix.controller.controller import LEDMatrixController
from is_matrix_forge.led_matrix.helpers.device import DEVICES
ctrl = LEDMatrixController(DEVICES[0])
ctrl.scroll_text("Hello World!", loop=False)
```
### Progress Bars
```python
import time
from is_matrix_forge.progress import tqdm
for _ in tqdm(range(100)):
time.sleep(0.05)
```
### Battery Monitor Example
```python
from is_matrix_forge.monitor import run_power_monitor
from is_matrix_forge.led_matrix.helpers.device import DEVICES
device = DEVICES[0]
run_power_monitor(device)
```
## Troubleshooting
### LED Matrix Not Detected
1. Check that the LED matrix is properly connected to your computer.
2. Verify that the LED matrix has the correct hardware identifiers (VID, PID, SN_PREFIX).
3. Make sure you have the necessary permissions to access the serial port.
4. Try running the application with administrator/root privileges.
### Audio Notifications Not Working
1. Ensure your system's audio is working correctly.
2. Check that the WAV files for notifications exist in the expected locations.
3. Verify that the chime library is properly installed.
### Battery Status Not Updating
1. Make sure psutil is properly installed.
2. Check that your system supports battery status monitoring through psutil.
3. Try increasing the battery_check_interval to reduce CPU usage.
### Animation Issues
1. Verify that the LED matrix is functioning correctly.
2. Check that the matrix dimensions match the expected 9x34 size.
3. Try clearing the matrix and restarting the application.
## Contributing
Contributions are welcome! If you have ideas or improvements for Matrix Forge,
feel free to open an issue or submit a pull request.
## License
This project is licensed under the MIT License - see the LICENSE.md file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/Inspyre-Softworks/IS-Matrix-Forge",
"name": "IS-Matrix-Forge",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "led, matrix, framework, hardware",
"author": "Taylor B.",
"author_email": "t.blackstone@inspyre.tech",
"download_url": "https://files.pythonhosted.org/packages/03/2a/4e9d62cc35912860a90f8ee8aa1915230be31ce2557461fa21bc75211681/is_matrix_forge-1.0.0.dev7.tar.gz",
"platform": null,
"description": "[](https://pypi.org/project/IS-Matrix-Forge)\n\n\n\n# IS Matrix Forge\n\n**IS Matrix Forge** is a Python framework for creating applications that drive\n9\u00d734 LED matrix displays. It provides high level helpers for talking to the\nhardware, tools for building animations, and utilities such as progress bars and\na battery monitor.\n\n## Project Overview\n\nMatrix Forge grew out of the LED Matrix Battery Monitor project. The goal is to\nmake it easy to create rich LED matrix experiences from Python. In addition to\nmonitoring the battery, you can design custom frames, display scrolling text,\nrun animations, and integrate the LED matrix with your own applications.\n\nHighlighted features include:\n- Device discovery and control via `pyserial`\n- Drawing grids and patterns with the `Grid` class\n- Built-in and custom animations\n- Progress bars that render on the matrix\n- A battery monitor example using these building blocks\n\n## Hardware Requirements\n\n- LED Matrix display with dimensions 9x34 (compatible with the project's specifications)\n- Serial connection to the computer (USB)\n- The LED matrix should have the following hardware identifiers:\n - VID: 0x32AC\n - PID: 0x20\n - Serial Number Prefix: FRAK\n\n## Software Dependencies\n\nThis project requires Python 3.12 or newer and the following dependencies:\n\n- chime (>=0.7.0,<0.8.0) - For audio notifications\n- pyserial (>=3.5,<4.0) - For serial communication with the LED matrix\n- inspy-logger (>=3.2.3,<4.0.0) - For logging\n- inspyre-toolbox (>=1.6.0) - Utility functions\n- pillow (>=11.2.1,<12.0.0) - Image processing\n- opencv-python (>=4.11.0.86,<5.0.0.0) - Image processing\n- pysimplegui-4-foss (>=4.60.4.1,<5.0.0.0) - GUI components\n- tk (>=0.1.0,<0.2.0) - GUI toolkit\n- easy-exit-calls (>=1.0.0.dev1,<2.0.0) - Exit handling\n- psutil - For battery status monitoring\n\n## Installation Instructions\n\n### Using Poetry (Recommended)\n\n1. Clone the repository:\n ```\n git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git\n cd IS-Matrix-Forge\n ```\n\n2. Install dependencies using Poetry:\n ```\n poetry install\n ```\n\n3. Activate the virtual environment:\n ```\n poetry shell\n ```\n\n### Using pip\n\n1. Clone the repository:\n ```\n git clone https://github.com/Inspyre-Softworks/IS-Matrix-Forge.git\n cd IS-Matrix-Forge\n ```\n\n2. Install the package:\n ```\n pip install .\n ```\n\n## Usage Examples\n\n### Identify Connected Devices\n\n```python\nfrom is_matrix_forge.led_matrix.helpers.device import DEVICES\n\nfor dev in DEVICES:\n print(dev)\n```\n\n### Display Text on the Matrix\n\n```python\nfrom is_matrix_forge.led_matrix.controller.controller import LEDMatrixController\nfrom is_matrix_forge.led_matrix.helpers.device import DEVICES\n\nctrl = LEDMatrixController(DEVICES[0])\nctrl.scroll_text(\"Hello World!\", loop=False)\n```\n\n### Progress Bars\n\n```python\nimport time\nfrom is_matrix_forge.progress import tqdm\n\nfor _ in tqdm(range(100)):\n time.sleep(0.05)\n```\n\n### Battery Monitor Example\n\n```python\nfrom is_matrix_forge.monitor import run_power_monitor\nfrom is_matrix_forge.led_matrix.helpers.device import DEVICES\n\ndevice = DEVICES[0]\nrun_power_monitor(device)\n```\n\n## Troubleshooting\n\n### LED Matrix Not Detected\n\n1. Check that the LED matrix is properly connected to your computer.\n2. Verify that the LED matrix has the correct hardware identifiers (VID, PID, SN_PREFIX).\n3. Make sure you have the necessary permissions to access the serial port.\n4. Try running the application with administrator/root privileges.\n\n### Audio Notifications Not Working\n\n1. Ensure your system's audio is working correctly.\n2. Check that the WAV files for notifications exist in the expected locations.\n3. Verify that the chime library is properly installed.\n\n### Battery Status Not Updating\n\n1. Make sure psutil is properly installed.\n2. Check that your system supports battery status monitoring through psutil.\n3. Try increasing the battery_check_interval to reduce CPU usage.\n\n### Animation Issues\n\n1. Verify that the LED matrix is functioning correctly.\n2. Check that the matrix dimensions match the expected 9x34 size.\n3. Try clearing the matrix and restarting the application.\n\n## Contributing\n\nContributions are welcome! If you have ideas or improvements for Matrix Forge,\nfeel free to open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE.md file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": null,
"version": "1.0.0.dev7",
"project_urls": {
"Homepage": "https://github.com/Inspyre-Softworks/IS-Matrix-Forge",
"Repository": "https://github.com/Inspyre-Softworks/IS-Matrix-Forge"
},
"split_keywords": [
"led",
" matrix",
" framework",
" hardware"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15ef8f896ed81a300971fa514a3afc386d25ef07ee0e057ee8ccec34cf969364",
"md5": "eeb92524775f85b5b828c1c6cd156083",
"sha256": "3ed734ce97dd543c6fec1642fbf2a7388a5e99d215ad31488dbb7767ab0edcd3"
},
"downloads": -1,
"filename": "is_matrix_forge-1.0.0.dev7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eeb92524775f85b5b828c1c6cd156083",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 767779,
"upload_time": "2025-07-12T22:39:29",
"upload_time_iso_8601": "2025-07-12T22:39:29.993052Z",
"url": "https://files.pythonhosted.org/packages/15/ef/8f896ed81a300971fa514a3afc386d25ef07ee0e057ee8ccec34cf969364/is_matrix_forge-1.0.0.dev7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "032a4e9d62cc35912860a90f8ee8aa1915230be31ce2557461fa21bc75211681",
"md5": "9effd3b933a7c5b756545af70fc684d2",
"sha256": "7fdf9be45f38d327a0e6a4f60e3fb834e981da9fed74bbbaa258458cd8477dc9"
},
"downloads": -1,
"filename": "is_matrix_forge-1.0.0.dev7.tar.gz",
"has_sig": false,
"md5_digest": "9effd3b933a7c5b756545af70fc684d2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 723320,
"upload_time": "2025-07-12T22:39:31",
"upload_time_iso_8601": "2025-07-12T22:39:31.846998Z",
"url": "https://files.pythonhosted.org/packages/03/2a/4e9d62cc35912860a90f8ee8aa1915230be31ce2557461fa21bc75211681/is_matrix_forge-1.0.0.dev7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 22:39:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Inspyre-Softworks",
"github_project": "IS-Matrix-Forge",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "is-matrix-forge"
}
JSON
