# Halo PixelBar MCP

A local MCP server for controlling an EDIFIER Halo PixelBar from an AI on
Windows. It exposes a small allowlist for the ambient light, pixel screen, and
the speaker's independent hardware volume.

> This is an independent community project. It is not affiliated with,
> endorsed by, or supported by EDIFIER.

See [PROTOCOL_NOTES.md](PROTOCOL_NOTES.md) for the observed packet format,
field mappings, and live hardware tests.

## Prerequisites

- Windows 10 or Windows 11.
- An **EDIFIER Halo PixelBar (花再)** exposing USB VID `0x2D99`, PID `0xA106`,
  HID interface `4`, usage page `0xFF14`, and usage `1`.
- A USB connection that carries data, not a power-only cable. A data-capable
  adapter or dock is fine when Windows can enumerate the HID interface.
- Python 3.11 or newer.
- A local MCP host that can launch a stdio server, such as Codex or Claude
  Desktop.

EDIFIER TempoHub was installed while the protocol was validated, but this MCP
does not call TempoHub, read an EDIFIER account, or require account
credentials. The device filter is intentionally strict; other EDIFIER speakers
and PixelBar revisions are not assumed to be compatible.

## Install

```powershell
git clone https://github.com/Seraph310/halo-pixelbar-mcp.git
cd halo-pixelbar-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```

### Codex configuration

Add the following to `%USERPROFILE%\.codex\config.toml`, replacing both paths:

```toml
[mcp_servers.halo_pixelbar]
command = 'C:\path\to\halo-pixelbar-mcp\.venv\Scripts\python.exe'
args = ['C:\path\to\halo-pixelbar-mcp\server.py']
startup_timeout_sec = 30
```

Restart the MCP host after changing its configuration.

## Tools

| Tool | Purpose |
| --- | --- |
| `get_halo_status` | Detect the validated HID control interface |
| `get_halo_volume` | Read the independent 0-16 speaker volume |
| `set_halo_volume` | Set the hardware volume and verify it by querying again |
| `show_halo_text` | Display a short UTF-8 message with a safe layout |
| `set_halo_scene` | Select a built-in clock, game, work, reading, pet, meme, cyber, or waveform scene |
| `set_halo_screen_color` | Set the pixel-screen theme color |
| `set_halo_ambient` | Set light effect, RGB color, brightness, and speed |
| `set_halo_ambient_power` | Switch only the ambient light on or off |

## Tested environment

- Windows 11 64-bit, build `26200`.
- EDIFIER Halo PixelBar (花再), USB VID `0x2D99`, PID `0xA106`.
- EDIFIER TempoHub installer version `1.2.6`.
- Python `3.11.5`.
- A data-capable USB adapter; a direct motherboard connection is not required
  when Windows can still enumerate the HID interface.

## Safety boundary

- Targets only the exact validated VID, PID, interface, usage page, usage, and
  a matching Halo/PixelBar product name.
- Exposes no arbitrary HID packet, firmware, factory-reset, account, file, or
  shell-command tool.
- Validates colors, scenes, effects, speed, brightness, layouts, text length,
  and hardware volume before writing.
- Does not require or read EDIFIER TempoHub credentials.
- Omits the physical device serial number from public MCP status results.

## Optional music companion

Pair this server with
[CloudMusic Desktop MCP](https://github.com/Seraph310/cloudmusic-desktop-mcp)
to let an MCP host coordinate AI-selected music with light, screen, and
hardware-volume changes. The two servers are independent and can be installed
separately.

## Protocol attribution

The packet format was established through local device observation, the
installed official controller, and live readback tests. It was also compared
with the MIT-licensed
[XFEstudio/HaloPixelToolBox](https://github.com/XFEstudio/HaloPixelToolBox)
implementation and the official Halo PixelBar user manual. No extracted
TempoHub binaries, decompiled files, credentials, firmware, or research
snapshots are included in this repository.

## Test

```powershell
.\.venv\Scripts\python.exe -m pytest -q
```

## Credits

Built together by Celia and OpenAI Codex.

Celia led the product direction and live hardware validation. Codex assisted
with reverse engineering, implementation, and testing.

## License

[MIT](LICENSE)