diff --git a/.github/ISSUE_TEMPLATE/hardware-report.yml b/.github/ISSUE_TEMPLATE/hardware-report.yml new file mode 100644 index 0000000..1f8b634 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/hardware-report.yml @@ -0,0 +1,57 @@ +name: Hardware report +description: Report a GAMEMAX (or other) LCD cooler that works, partly works, or does not work +title: "[hardware] " +labels: ["hardware"] +body: + - type: markdown + attributes: + value: | + Thanks for testing on your hardware! Reports from other panel revisions are how + this project grows. Please fill in what you can. + - type: input + id: cooler + attributes: + label: Cooler / panel model + placeholder: e.g. GAMEMAX IceBurg 360 Digital WH + validations: + required: true + - type: input + id: usb + attributes: + label: USB identity (lsusb) + description: "`lsusb -d 5131:2007` — paste the line, or the VID:PID if it differs" + validations: + required: true + - type: dropdown + id: result + attributes: + label: Result + options: + - Works fully (values correct on the panel) + - Partly works (which fields are wrong?) + - Panel lights up but shows wrong layout + - Not detected / no reaction + validations: + required: true + - type: textarea + id: report + attributes: + label: Output of `python3 src/gamemax_report.py --dry-run` + description: This writes nothing to the device, it only prints the report it would send. + render: text + validations: + required: false + - type: input + id: system + attributes: + label: System + placeholder: distro · kernel · desktop session · motherboard super-I/O (e.g. nct6798) + validations: + required: false + - type: textarea + id: notes + attributes: + label: Notes + description: Which fan channel / temperature source you had to pick, anything unexpected. + validations: + required: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..85414cf --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing + +Thanks for helping — the most valuable contribution is **hardware reports**: which cooler +works, which firmware revision differs, which sensor channel has to be picked. Use the +*Hardware report* issue template, or send a pull request. + +## Before opening a pull request + +The sender must stay dependency-free (standard library only) and must never write to the +device unless the user asked for it. + +```bash +# nothing is written to the panel: +python3 src/gamemax_report.py --dry-run +python3 src/gamemax_report.py --list-sensors + +# the tray app self-checks without a display, and can exercise every action: +uv run --with pyside6 python src/gamemax_gui.py --selftest +uv run --with pyside6 python src/gamemax_gui.py --selftest-actions + +# build the AppImage (needs uv + network on first run): +bash packaging/build_appimage.sh +``` + +`--selftest-actions` really does start/stop the service and toggle autostart, then leaves +the service running — expected. + +## Style + +- Python 3.10+, no new dependencies, comments only where the code cannot explain itself. +- GUI strings are Indonesian (the original author's language); code and docs are English. +- Keep the protocol knowledge in `docs/reverse-engineering.md` and the README table in sync + when you learn something new about the panel. diff --git a/README.md b/README.md index afea513..defa824 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,22 @@ Reverse engineered independently from the Windows vendor software [`docs/reverse-engineering.md`](docs/reverse-engineering.md) (Indonesian). [![Release](https://img.shields.io/github/v/release/oxpoe/Gamemax-linux-apps?color=def750&label=release)](https://github.com/oxpoe/Gamemax-linux-apps/releases) +[![Release build](https://github.com/oxpoe/Gamemax-linux-apps/actions/workflows/release.yml/badge.svg)](https://github.com/oxpoe/Gamemax-linux-apps/actions/workflows/release.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-def750)](LICENSE) +[![Platform: Linux](https://img.shields.io/badge/platform-Linux-def750)](#compatibility) +[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-def750)](src/gamemax_report.py) +[![Dependencies: none](https://img.shields.io/badge/sender_dependencies-none-def750)](src/gamemax_report.py) +[![Donate](https://img.shields.io/badge/%E2%9D%A4-donate-def750)](https://donasi.oxpoe.qzz.io/) + +```text + hwmon · /proc/stat · cpufreq · meminfo · statvfs + │ + ▼ + gamemax_report.py ──► 65-byte HID report ──► LCD panel + (stdlib only) hidraw, 5131:2007 + ▲ + gamemax_gui.py (tray) ──► systemd user unit + udev rule +``` Author: **oxpoe** · License: **MIT** · Independent project, **not affiliated with the vendor** — please read [DISCLAIMER.md](DISCLAIMER.md) before using it. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..8ab737b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,14 @@ +# Security + +This is a small local tool. The relevant surface: + +- It writes 64-byte HID reports to the panel matching `VID 0x5131 / PID 0x2007` + (plus a udev rule that grants the logged-in user access to that `hidraw` node). +- The tray app runs `systemctl --user` and, for the udev rule, `pkexec sh` on a script it + writes to `/tmp`. Nothing else is executed, and no data leaves the machine. +- No secrets are stored. The config file (`~/.config/gamemax-report/config.json`) holds + sensor channel names and display settings only. + +If you find a problem — for example a way to make the helper scripts run something else, +or a path that writes outside the documented locations — please open an issue (or a +private security advisory on GitHub). Do not test on hardware you do not own. diff --git a/assets/social-preview.png b/assets/social-preview.png new file mode 100644 index 0000000..255d589 Binary files /dev/null and b/assets/social-preview.png differ