Tools for controlling the Embrava Blynclight Mini busylight over USB HID, derived from clean-room reverse engineering of the wire protocol used by the official Embrava Connect application.

The repository ships four pieces:

The library is a pure protocol wrapper around HidSharp; the CLI adds per-user state persistence so successive one-shot invocations compose naturally (see State below).

• .NET 10 SDK to build from source.
• A connected Blynclight Mini (USB VID 0x2C0D, PID 0x000A).

No driver install is required on macOS, Linux, or Windows — the device is a plain HID peripheral.

dotnet build

dotnet run --project src/blynclight -- <command> [args]

A handful of representative commands:

blynclight on red              # solid red
blynclight rgb 255 128 0       # explicit RGB
blynclight dim                 # halve brightness, keep colour
blynclight flash --speed fast  # flash at full brightness
blynclight off                 # blank, preserve colour for next 'on'
blynclight music 3 --repeat    # play built-in track 3 on repeat
blynclight info                # show device + persisted state
blynclight reset               # force idle and clear persisted state

blynclight --help lists every subcommand; each subcommand also has its own --help.

The device protocol is write-only — there is no way to read the current report back. The CLI therefore mirrors the last report it sent to a small file under the platform's per-user application-data directory (8 raw bytes; on macOS that is ~/Library/Application Support/blynclight/state.bin).

Each invocation loads the saved report, applies the requested mutation, sends the result, and writes it back. That makes commands like dim (which only toggles the dim bit) behave the way you'd expect even though the host process is starting from scratch every time.

If no state exists and a "lighting" command is issued without an explicit colour (e.g. a bare on, dim, or flash), the CLI auto-promotes the colour to white so the device actually lights up. Modifier-only commands (off, noflash, nodim, audio) never auto-promote.

blynclight state prints the path and a hex dump of the saved report; blynclight reset clears it.

blynclight mcp runs a Model Context Protocol server over stdio that arbitrates between multiple concurrent agents on a single shared Blynclight Mini. Each agent declares its own status via tool calls; the server picks the highest-priority status and renders it on the device.

blynclight mcp                # default: agents-dir under per-user state
blynclight mcp --agents-dir ~/blync-agents

Multiple blynclight mcp instances pointed at the same --agents-dir coordinate via per-agent JSON files in that directory, locked on every update. This means each agent can spawn its own MCP server (the usual stdio model) and still see a unified composite state.

Tools exposed:

Priority order is error > needs_input > working > success > idle; the idle resting state renders as solid green, working as solid yellow, success as a brief green flash, needs_input blinks cyan briefly then holds solid cyan, and error as a fast red flash.

The MCP server uses the same per-user state.bin as the one-shot CLI, so blynclight info / blynclight state reflect whatever the server most recently rendered.

For Copilot CLI users, the repo doubles as its own plugin marketplace. The plugin in src/Blynclight.Copilot/ bundles the MCP server config and a blynclight-status skill that teaches the agent how to use the tools:

copilot
/plugin marketplace add mjcheetham/blynclight
/plugin install blynclight@blynclight

The plugin assumes the native blynclight binary is already on PATH (see Native publish below).

The CLI is configured for NativeAOT, so a published binary is a single native executable with no managed runtime dependency:

dotnet publish src/Blynclight.Cli -c Release -r osx-arm64

Substitute the appropriate RID for other targets. The resulting binary for osx-arm64 is around 4 MB.

using Mjcheetham.Blynclight;

using var device = BlynclightMiniDevice.Open();
device.SetColor(Colors.Red);
device.SetDim(true);

BlynclightReport is a value-type model of the 8-byte HID report; advanced callers can build one explicitly and call device.SendReport(report).

PROTOCOL.md documents the report layout, the meaning of every bit and byte, and the host-side conventions for things like idle state and trailers. It is derived purely from observing traffic and from static analysis of the official Embrava Connect application — no Embrava code, headers, or documentation were used.

MIT — see LICENSE.

This project is not affiliated with or endorsed by Embrava. "Blynclight" is a trademark of Embrava and is used here only to describe the device this software interacts with.