node-blink1-server

HTTP REST API server for blink(1) USB LED notification devices.

Version 2 — rewritten from the ground up to match the full Blink1Control2 API surface, including named color patterns, multi-device support, and a Node.js library interface.

Supports plug and unplug of blink(1) while the server is running.

Installation & running

One-off with npx (no install required)

npx node-blink1-server
npx node-blink1-server 8080
npx node-blink1-server --port 8080 --host 0.0.0.0

Global install

npm install -g node-blink1-server
blink1-server             # starts on localhost:8934
blink1-server 8080
blink1-server --port 8080 --host 0.0.0.0

From source

git clone https://github.com/todbot/node-blink1-server.git
cd node-blink1-server
npm install
npm start              # localhost:8934
npm start -- 8080      # port 8080

Persistent server with pm2

For production use or boot persistence, use pm2:

npm install -g pm2
pm2 start blink1-server -- --port 8934
pm2 startup            # configure to start on boot
pm2 save

Note on native module rebuild

node-blink1 contains a native C++ addon. If you switch Node.js versions or use this package inside an Electron app (which has its own ABI), you need to rebuild the native module:

npm run clean
npm install

When used inside an Electron app via a file: reference, rebuild against Electron's ABI instead:

./node_modules/.bin/electron-rebuild -f -w node-blink1

CLI usage

blink1-server [port]
blink1-server --port <port> --host <host>

| Option | Default | Description | |--------|---------|-------------| | port (positional or --port) | 8934 | HTTP port to listen on | | --host | localhost | Bind address (0.0.0.0 for all interfaces) |

REST API

All endpoints are HTTP GET. Query parameters use standard URL encoding.

Common query parameters

| Parameter | Alias | Description | |-----------|-------|-------------| | rgb | | Hex color, e.g. %23ff00ff (URL-encoded #ff00ff) | | time | | Fade time in seconds (e.g. 0.5) | | millis | | Fade time in milliseconds (e.g. 500) — takes priority over time | | ledn | | LED number: 0 = all, 1 = top, 2 = bottom (default: 0) | | blink1_id | id | Device serial number to target (omit for default device) |

Device info

| Endpoint | Description | |----------|-------------| | GET /blink1 | List connected device serial numbers and IFTTT key | | GET /blink1/id | Same as above | | GET /blink1/enumerate | Re-scan for devices, then list |

Color control

| Endpoint | Description | |----------|-------------| | GET /blink1/fadeToRGB?rgb=<hex>&time=<secs> | Fade to a specific color | | GET /blink1/lastColor | Return current color state | | GET /blink1/on | Fade to white | | GET /blink1/off | Fade to black (stops any playing pattern) | | GET /blink1/red | Named color shortcuts | | GET /blink1/green | | | GET /blink1/blue | | | GET /blink1/cyan | | | GET /blink1/yellow | | | GET /blink1/magenta | | | GET /blink1/random | Random color | | GET /blink1/blink?rgb=<hex>&count=<n>&time=<secs> | Blink N times |

Pattern control

A pattern is a named sequence of {color, time, ledn} steps. System patterns are built in; user patterns are added via the API and persist in the config file (when a config file is provided).

| Endpoint | Query params | Description | |----------|-------------|-------------| | GET /blink1/patterns | | List all patterns | | GET /blink1/pattern/queue | | List currently-playing pattern queue | | GET /blink1/pattern/play | pname or name | Play a pattern by name | | GET /blink1/pattern/stop | pname or name (optional) | Stop a pattern, or all if omitted | | GET /blink1/pattern/add | name, pattern | Add a pattern from a pattern string | | GET /blink1/pattern/del | name or id | Delete a user pattern |

Pattern strings

Pattern strings encode a repeating color sequence:

repeats,#color1,secs1,ledn1,#color2,secs2,ledn2,...

Examples:

3,#ff0000,0.3,0,#000000,0.3,0          # red blink 3x
0,#ff0000,0.5,1,#0000ff,0.5,2          # alternating red/blue forever (repeats=0)

Special (meta) patterns

These pattern names are interpreted directly without needing a pre-defined pattern:

| Name | Example | Description | |------|---------|-------------| | #rrggbb | #ff00ff | Fade to that hex color | | ~off | | Stop all patterns and fade to black | | ~blink:<color>-<count> | ~blink:#ff0000-5 | Blink color N times | | ~blink:<color>-<count>-<secs> | ~blink:#ff0000-5-0.3 | Blink with custom timing | | ~pattern:<name>:<patternstr> | ~pattern:mypatt:3,#ff0000,0.3,0 | Play an inline pattern |

Examples

$ blink1-server &

# Device info
$ curl 'http://localhost:8934/blink1'
{
  "blink1_serialnums": [ "AB0026C1" ],
  "blink1_id": "DEADBEEFAB0026C1",
  "status": "blink1 id"
}

# Fade to blue over 2.5 seconds on LED 2
$ curl 'http://localhost:8934/blink1/fadeToRGB?rgb=%230000ff&time=2.5&ledn=2'
{
  "blink1_serialnums": [ "AB0026C1" ],
  "lastColor": "#0000ff",
  "lastTime": 2.5,
  "lastMillis": 2500,
  "lastLedn": 2,
  "cmd": "fadeToRGB",
  "status": "success"
}

# Blink red 5 times
$ curl 'http://localhost:8934/blink1/blink?rgb=%23ff0000&count=5&time=0.3'

# Play a built-in pattern
$ curl 'http://localhost:8934/blink1/pattern/play?pname=red+flash'

# Add and play a custom pattern
$ curl 'http://localhost:8934/blink1/pattern/add?name=police&pattern=6,%23ff0000,0.3,1,%230000ff,0.3,2,%23000000,0.1,0'
$ curl 'http://localhost:8934/blink1/pattern/play?pname=police'

# Stop all patterns
$ curl 'http://localhost:8934/blink1/pattern/stop'

# Play a meta-pattern inline (no pre-defined pattern needed)
$ curl 'http://localhost:8934/blink1/pattern/play?pname=~blink:%23ff00ff-3-0.5'

Testing

Three test suites, all using the built-in node:test runner (no extra dependencies).

npm test                       # unit + HTTP integration — no device needed
npm run test:hardware          # hardware-in-the-loop — skips if no device found
node --test test/blink1Service.test.js   # single file

| Suite | File | Requires device | |-------|------|----------------| | blink1Service unit | test/blink1Service.test.js | No | | patternsService unit | test/patternsService.test.js | No | | apiServer HTTP integration | test/apiServer.test.js | No | | Hardware-in-the-loop | test/blink1Hardware.test.js | Yes (skipped if absent) |

The hardware suite actually lights up the device — run it in an environment where that's acceptable. It covers device detection, fadeToColor, pattern playback, writePatternToBlink1, and all color/blink/pattern HTTP endpoints end-to-end.

Node.js library usage

var createBlink1Server = require('node-blink1-server');

var server = createBlink1Server({
    apiConfig:      { port: 8934, host: 'localhost' },
    blink1Config:   { deviceRescan: true, enableGamma: false },
    patternsConfig: { playingSerialize: false },
    patterns:       [],   // array of saved user pattern objects
});

// The server object is an EventEmitter
server.on('status',          function(s)       { console.log(s.type, s.text); });
server.on('deviceUpdated',   function()         { /* blink1 list changed */ });
server.on('patternsChanged', function(patterns) { /* persist patterns array */ });
server.on('configChanged',   function(key, val) { /* persist config value */ });

server.start();

// Access underlying service singletons directly if needed
server.blink1Service.fadeToColor(500, '#ff0000', 0);
server.patternsService.playPatternFrom('myapp', 'red flash');
server.apiServer.stop(function() { console.log('stopped'); });

Factory options

| Option | Type | Description | |--------|------|-------------| | apiConfig | object | { port, host } — HTTP server config | | blink1Config | object | { deviceRescan, enableGamma, blink1ToUse, hostId } | | patternsConfig | object | { playingSerialize } — serialize pattern playback | | patterns | Array | Saved user pattern objects to pre-load | | logger | object | Optional logger with .msg() and .error() methods |

Events emitted

| Event | Arguments | Description | |-------|-----------|-------------| | status | {type, source, id, text} | Service status / error updates | | deviceUpdated | | blink(1) device list changed | | patternsChanged | patternsArray | User patterns were saved or deleted | | configChanged | key, value | A config value changed (e.g. hostId) |

Differences from v1

| Feature | v1 | v2 | |---------|----|----| | Named patterns | No | Yes — play, stop, add, delete | | Multi-device | No | Yes — blink1_id on all endpoints | | Pattern persistence | No | Via patternsChanged event | | Library API | No | Yes — createBlink1Server() factory | | Config system | None | Plain objects / CLI args | | Events | None | EventEmitter on server object |