# CheerLights

> CheerLights is a global network of lights that all show the same color. Anyone sets the color on the CheerLights Discord, and the current color is published to ThingSpeak, Adafruit IO, and an MQTT broker. Reading the color is free and needs no key. Started in 2011 by Hans Scharler as a "Hello, World" for learning IoT.

The current color has two forms: a name (for example `red`) and a HEX value (for example `#ff0000`).
All feeds below carry the same color at the same time.
For real-time updates, subscribe over MQTT instead of polling.

Setting the color happens on the CheerLights Discord with the `/cheerlights` command; there is no public API for setting it.

## Read the current color

- [Color name (text)](https://api.thingspeak.com/channels/1417/field/1/last.txt): ThingSpeak channel 1417, field1. Also `.json` and `.xml`.
- [HEX value (text)](https://api.thingspeak.com/channels/1417/field/2/last.txt): ThingSpeak channel 1417, field2. Also `.json` and `.xml`.
- [Recent history](https://api.thingspeak.com/channels/1417/feed.json): every change with its time, name in `field1`, HEX in `field2`. Add `?results=N` for up to 8000 entries.
- [Adafruit IO color feed](https://io.adafruit.com/api/v2/cheerlights/feeds/color/data): user `cheerlights`, feeds `color` and `hex` (`.../feeds/hex/data` for HEX).

## MQTT

Broker `mqtt.cheerlights.com`, port 1883, no login. Each topic holds a retained message with the current value.

- `color`: the color name
- `colour`: the color name, same as `color`
- `hex`: the HEX value
- `wled/col`: the HEX value, for WLED devices
- `wled/color/set`: the HEX value, for WLED devices
- `cheerlights`: the color name (the original topic, still published)
- `cheerlightsRGB`: the HEX value (the original topic, still published)

## Colors

The color is always one of these eleven names:
red (#ff0000), green (#008000), blue (#0000ff), cyan (#00ffff), white (#ffffff), oldlace (#fdf5e6), purple (#800080), magenta (#ff00ff), yellow (#ffff00), orange (#ffa500), pink (#ffc0cb).

## Docs

- [Learn about CheerLights](https://cheerlights.com/learn/): the system, every feed, MQTT topics, and how to set the color.
- [Build a CheerLights display](https://cheerlights.com/build/): hardware projects.
- [CheerLights + WLED](https://cheerlights.com/build/wled/): WLED setup.
- [CheerLights Discord](https://cheerlights.com/discord): where the color is set.

## Code

- [CheerLights on GitHub](https://github.com/cheerlights): all official libraries and examples.
- [Python package](https://github.com/cheerlights/cheerlights-python-package): `pip install cheerlights-api`.
- [Arduino library](https://github.com/cheerlights/cheerlights-arduino-library): `CheerLights` in the Arduino Library Manager.
- [MCP server](https://github.com/cheerlights/cheerlights-mcp): lets AI assistants read the current color, the history, and color statistics.
- [JavaScript widgets](https://github.com/cheerlights/cheerlights-javascript-widgets): embeddable web widgets.

## Optional

- [ThingSpeak channel 1417](https://thingspeak.com/channels/1417): charts of the color history.
- [Live stream on Twitch](https://www.twitch.tv/cheerlights)
- [Blog](https://cheerlights.com/blog/): projects and news.