|
| 1 | +# LightHouse |
| 2 | + |
| 3 | +Control lights and other devices connected to multiple Arduinos with [Redis](https://redis.io) Pub/Sub messaging. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +## Installing / Getting started |
| 8 | +__Prerequisites__ |
| 9 | +- A running Redis server |
| 10 | +- One or more Arduinos flashed with the _firmata_ sketch. |
| 11 | + |
| 12 | +__Installation__ |
| 13 | +1. Download a binary for your system from the [releases](https://github.com/xanecs/lighthouse/releases/latest) page. |
| 14 | +2. Create a `config.toml` and place it next to the binary (See [configuration](#configuration)). |
| 15 | +3. Start the binary |
| 16 | + |
| 17 | +```bash |
| 18 | +cd lighthouse |
| 19 | +wget https://.../lighthouse |
| 20 | +nano config.toml |
| 21 | +./lighthouse |
| 22 | +``` |
| 23 | + |
| 24 | + Lighthouse should now be connecting to the specified Redis server and await commands on the configured channel. |
| 25 | + |
| 26 | +## Configuration |
| 27 | +LightHouse is configured with the `config.toml` file. The service expects this file to be in the _current working directory_. |
| 28 | + |
| 29 | +A minimal `config.toml` might look like this: |
| 30 | +```toml |
| 31 | +[redis] |
| 32 | +host = "127.0.0.1:6379" |
| 33 | +topic = "lighthouse" |
| 34 | + |
| 35 | +[boards] |
| 36 | + [boards.first] |
| 37 | + serial = "/dev/ttyUSB0" |
| 38 | + [boards.first.dev] |
| 39 | + [boards.first.dev.led] |
| 40 | + mode = "direct" |
| 41 | + inverted = false |
| 42 | + pinse = ["13"] |
| 43 | +``` |
| 44 | + |
| 45 | +This tells LightHouse to connect to the redis server running on `127.0.0.1:6379` and subscribe to the channel `lighthouse`. |
| 46 | +It configures one Arduino connected to `/dev/ttyUSB0` and exposes the internal LED on pin 13. |
| 47 | + |
| 48 | +#### [redis] |
| 49 | +The `[redis]` section is pretty self-explainatory. Specify IP and Port in the `host` field and the Pub/Sub channel in the `topic` field. |
| 50 | + |
| 51 | +#### [boards] |
| 52 | +The `[boards]` section is the list of Arduinos to connect to. |
| 53 | + |
| 54 | +#### [boards.name] |
| 55 | +Each Arduino has a `serial` field, specifying the serial port and a `dev` array. |
| 56 | + |
| 57 | +#### [boards.name.dev.name] |
| 58 | +Give each device a __unique name across all boards!__ You will later address a device using this name. |
| 59 | + |
| 60 | +__mode__ |
| 61 | +what kind of device (for example `"direct"`, `"pwm"` or `"servo"`, see [modes](#modes)). |
| 62 | + |
| 63 | +__inverted__ |
| 64 | +some modes have an inverted mode. If you have an LED connected to `+5V` and Arduino pin `2`, you would need to set `inverted` to `true`. |
| 65 | + |
| 66 | +__pins__ |
| 67 | +array of pins to use for this mode. some modes require multiple pins (e.g the `rgb` mode requires a red, green and a blue pin.) |
| 68 | +Some modes will also perform actions on all pins if you specify more than one. |
| 69 | + |
| 70 | +## Commands |
| 71 | + |
| 72 | +Commands are received through Redis Pub/Sub. To send a command you publish a JSON string to the configured channel: |
| 73 | + |
| 74 | +```redis |
| 75 | +$ redis-cli |
| 76 | +redis> PUBLISH lighthouse '{"device": "internal", "action": "on", "params": {}}' |
| 77 | +redis> PUBLISH lighthouse '{"device": "internal", "action": "write", "params": {"power": false}}' |
| 78 | +``` |
| 79 | + |
| 80 | +Each command has the following format |
| 81 | +```json |
| 82 | +{ |
| 83 | + "device": "rgblight", |
| 84 | + "action": "color", |
| 85 | + "params": { |
| 86 | + "red": 255, |
| 87 | + "green": 96, |
| 88 | + "blue": 0 |
| 89 | + } |
| 90 | +} |
| 91 | +``` |
| 92 | + |
| 93 | +`device` |
| 94 | +the unique device identifier specified in the `config.toml` |
| 95 | + |
| 96 | +`action` |
| 97 | +which action to perform on the device. supported actiosn depend on the driver |
| 98 | + |
| 99 | +`params` |
| 100 | +parameters for the action |
| 101 | + |
| 102 | +## Modes |
| 103 | + |
| 104 | +Currently, LightHouse supports the following modes: |
| 105 | + |
| 106 | +| Name | Description | Inverted | Pins | |
| 107 | +| ------ | ------------------------ | ----------------- | ----------- | |
| 108 | +| direct | switch a pin high or low | `value = !value` | same on all | |
| 109 | +| pwm | apply pwm to a pin | `value = 1-value` | same on all | |
| 110 | +| rgb | control an rgb-led | like pwm | r, g, b | |
| 111 | +| servo | control a servo | does not apply | same on all | |
| 112 | + |
| 113 | +### Direct |
| 114 | + |
| 115 | +| Action | Params | |
| 116 | +| -------- | ------------------ | |
| 117 | +| `on` | `{}` | |
| 118 | +| `off` | `{}` | |
| 119 | +| `write` | `{"power": bool}` | |
| 120 | + |
| 121 | +### Pwm |
| 122 | + |
| 123 | +| Action | Params | |
| 124 | +| ------------| ----------------------------------------------- | |
| 125 | +| `on` | `{}` | |
| 126 | +| `off` | `{}` | |
| 127 | +| `power` | `{"power": bool}` | |
| 128 | +| `brightness`| `{"brightness": float}` (0 to 1) | |
| 129 | +| `write` | `{"power": bool, "brightness": float}` (0 to 1) | |
| 130 | + |
| 131 | +### Rgb |
| 132 | + |
| 133 | +| Action | Params | |
| 134 | +| -------| -------------------------------------------------------- | |
| 135 | +| `on` | `{}` | |
| 136 | +| `off` | `{}` | |
| 137 | +| `power`| `{"power": bool}` | |
| 138 | +| `color`| `{"red": int, "green": int, "blue": int}` (0 to 255) | |
| 139 | +| `write`| `{"power": bool, "red": int, "green": int, "blue": int}` | |
| 140 | + |
| 141 | +### Servo |
| 142 | + |
| 143 | +| Action | Params | |
| 144 | +| -------| -------------------------------| |
| 145 | +| `on` | `{}` | |
| 146 | +| `off` | `{}` | |
| 147 | +| `power`| `{"power": bool}` | |
| 148 | +| `angle`| `{"angle": int}` (0 to 180) | |
| 149 | +| `write`| `{"power": bool, "angle": int}`| |
| 150 | + |
| 151 | +## Licensing |
| 152 | +The code in this project is licensed under the 2-Clause BSD license (BSD-2-Clause). See `LICENSE` for further details. |
0 commit comments