Metadata-Version: 2.4
Name: cm-pixel
Version: 0.1.0
Summary: Open-source driver for the Cooler Master MasterLiquid Atmos II Pixel LED hexagonal screen
Author-email: Feiko Wielsma <feiko.w@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/FeikoWielsma/cm-pixel
Project-URL: Source, https://github.com/FeikoWielsma/cm-pixel
Project-URL: Issues, https://github.com/FeikoWielsma/cm-pixel/issues
Keywords: cooler-master,atmos,pixel,led,hid,aio
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: hidapi>=0.14
Requires-Dist: numpy>=1.21
Requires-Dist: Pillow>=9
Dynamic: license-file

# cm-pixel

Open-source driver + toolkit for the **Cooler Master MasterLiquid Atmos II Pixel LED**
hexagonal pixel screen — a clean, lightweight alternative to the official MasterCTRL app
for controlling the LEDs over USB. **Screen only** (pump/fans are PWM and untouched).

The USB protocol was reverse-engineered from scratch; see [`PROTOCOL.md`](PROTOCOL.md).

## Hardware
- Cooler Master "Atmos V2 - Pixel", USB `2516:021C`, plain HID (no special driver).
- 32×32 addressing grid, **556 real LEDs** arranged in a hexagon, RGB888.

## Install

This project uses [uv](https://docs.astral.sh/uv/). From a clone:
```bash
uv sync                 # creates .venv and installs everything (incl. uv.lock)
uv run cm-pixel list    # run the CLI
```
Or add it to your own uv project:
```bash
uv add cm-pixel
```
(Plain pip also works: `pip install cm-pixel`.)

> Close the official MasterCTRL software first — only one program can drive the screen.
> On Linux you may need a udev rule for HID write access.

## CLI
```bash
cm-pixel color 255 0 0           # solid red
cm-pixel image photo.png         # show an image (auto-fit to the hexagon)
cm-pixel gif spinner.gif         # play a GIF
cm-pixel text "HI"               # static centered text
cm-pixel scroll "HELLO WORLD"    # scrolling marquee
cm-pixel anim plasma             # procedural animation
cm-pixel anim fire --speed 1.5
cm-pixel list                    # list animations
```
Common flags: `--fps`, `--duration`, `--mask` (blank pixels outside the hexagon), `--keep`,
`--brightness 0-100`, `--rotate 0|90|180|270`. Brightness and rotation are applied in software
(the device has no command for them); 180° is exact, 90/270 clip slightly at the hexagon vertices.

Animations: `plasma rainbow swirl ripple breathe sparkle fire starfield`.

## Library
```python
from cmpixel import PixelDisplay, Canvas
from cmpixel.font import draw_text

with PixelDisplay() as d:
    c = Canvas().fill((0, 0, 20))
    c.set_pixel(16, 16, (255, 255, 255))
    draw_text(c, "GO", color=(0, 255, 0))
    d.send_canvas(c)
```

```python
# play a built-in animation
from cmpixel import PixelDisplay
from cmpixel.animations import plasma
from cmpixel.media import play

with PixelDisplay() as d:
    play(d, plasma(speed=1.0), fps=30, duration=10)
```

## How it works (short version)
A frame is 28 HID output reports of 64 bytes: `80 DD <pkt:u16> + 60 data`, concatenated to
556×RGB in serpentine LED order. Streaming a frame displays it immediately — no handshake.
Full details and the LED layout map are in [`PROTOCOL.md`](PROTOCOL.md) and `cmpixel/layout.json`.

## Status
v0.1 — drawing, text, GIF, procedural animations, software brightness & rotation.

## Disclaimer
Unofficial, not affiliated with Cooler Master. Use at your own risk; touches only the
screen framebuffer (no firmware/DFU).
