hello-lights

Commands to control a traffic light

Works with a Cleware USB traffic light.

Install

As a CLI (global)

$ npm install -g hello-lights

As a library

$ npm install hello-lights --save

Usage

CLI

Install globally and run hello-lights from the command line:

$ hello-lights exec bounce 300          # execute a command
$ hello-lights exec-file ./cmds.clj     # execute commands from a file
$ hello-lights repl                     # start an interactive REPL
$ hello-lights serve                    # start the HTTP server on port 9000
$ hello-lights serve --port 3000        # start the HTTP server on a custom port
$ hello-lights --selector http exec bounce 300   # execute via a remote server
$ hello-lights --selector http --host http://myserver:3000 repl  # REPL via a remote server

Use --help for the full list of options, including --serial-num to target a specific device, --selector multi to control multiple traffic lights at once, and --selector http to send commands to a remote hello-lights server.

Library

Use hello-lights as a library in your Node.js project:

const {Commander} = require('hello-lights');

let commander = new Commander();

// keeps flashing the red light in 400ms intervals
commander.run('twinkle red 400');

For the Commander class documentation look here.

Commands

Check out the available commands here. For multiple traffic lights (Commander.multi) look here.

Documentation

For the documentation look here.

HTTP Server REST API

The serve command starts an HTTP server that exposes the Commander interface as a REST API. By default it listens on port 9000.

Examples:

$ curl -X POST http://localhost:9000/run -d 'blink 3 green 300'
$ curl -X POST http://localhost:9000/run?reset=true -d 'twinkle red 400'
$ curl -X POST http://localhost:9000/cancel
$ curl http://localhost:9000/commands
$ curl http://localhost:9000/commands/turn
$ curl http://localhost:9000/info

The server also serves a browser demo at the root URL (/).

Running as a Linux Service

You can set up hello-lights serve to run automatically as a systemd user service on Linux.

Create the service file at ~/.config/systemd/user/hello-lights.service:

[Unit]
Description=Hello Lights Server
After=network.target

[Service]
Type=simple
Environment=PATH=/path/to/node/bin:/usr/bin:/bin
ExecStart=/path/to/node/bin/hello-lights serve
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Replace /path/to/node/bin with the directory containing your node and hello-lights binaries (e.g. ~/.nvm/versions/node/v24.13.1/bin). The Environment=PATH=... line is needed because systemd doesn't load your shell profile, so tools installed via nvm won't be found otherwise.

Then enable and start the service:

$ systemctl --user daemon-reload
$ systemctl --user enable hello-lights   # start automatically on login
$ systemctl --user start hello-lights    # start now

To start the service on boot (without needing to log in), enable lingering for your user:

$ sudo loginctl enable-linger $USER

Check status and logs:

$ systemctl --user status hello-lights
$ journalctl --user -u hello-lights -f   # follow logs

Development

Install dependencies:

$ npm install

npm scripts

CI

The CI workflow runs on every push and pull request to master. It has three jobs:

• Build -- lints, runs tests with coverage, and builds all web assets.
• Deploy -- on push to master, deploys the web/ directory to GitHub Pages.
• Publish -- on push to master, bumps the package version, publishes to npm with provenance via trusted publishing, and creates a GitHub Release. The version bump type is determined from the commit message: [major] or BREAKING CHANGE for major, [minor] for minor, and patch by default.

License

Licensed under the MIT license.