@b-stud/lightitup-server

Light'It Up Server documentation www.b-stud.com.

1. Introduction
2. Prerequisites
3. Wiring
4. Installation
5. Usage
5.1 Launching the server
5.2 Access to the interface
6 Features
6.1 Adding light effects to your list
6.2 Priorities
6.3 Automatizing effects with the time scheduler
6.4 Controlling several devices at the same time
7. API
8. License
9. Author

1. Introduction

Light'It up server is a node server for Raspberry devices that let you easily animate your light strip. It integrates the Light'It Up engine to use existing or create customized light effects. It uses HTTP requests and expose a very simple API, which means you can now easily integrate your lightstrip inside any domotics solution. As described below, the server will offer you great features like a time scheduler, effects priorities management, multi devices control and more..

2. Prerequisites

What do I need to make it work?

• A Raspberry Device with any Debian based distribution (we recommend DietPi, a light and efficient RPi OS)

  Note 1: Once you have installed the OS of your choice, you must enabling SPI communication, to do so :

  • Enter inside the configuration menu: sudo raspi-config
  • Then select Advanced options choose SPI enable it, save and reboot your device.

  Note 2: Tests have been mostly focused on RPi 3 and Zero W devices but it should work with any RPi board.

• A compatible light strip powered by an adequate power supply

  For now, here is the light strips compatibility list, to be extended by the time.

  • APA102 (DotStar)
  • LPD8806
  • P8913
  • WS281X (WS2811, WS2811 400Khz, WS2812, WS2813, WS2818)
  • WS2801

  Power supply

  Depending on your light strip you will have to choose a 5V or 12V power supply, your choice will also depend on the length of the strip (big lengths require obviously more power, see your light strip datasheet to know what power by meter it consumes)

  • Useful note : If you have a 5V powered light strip, then you can safely use use the same power supply to power up your Raspberry device, to do so you will just have to cut an USB cable and to connect V+ and V- wires to your power supply.

  Choose any power supply compatible with your setup, for information purpose, we're using this one.

• Optional but definitely recommended

  If you want to handle audio effects, as you probably already know, your Raspberry only have an audio output, which means you can only play audio effects on what is played by the RPi itself, which is not so funny.

  For 2$ and less, you can buy an USB audio card to plug any audio source you want. Choose any device you wish, for information, we're making the tests with this one You can even choose devices cheaper than 1$.

  You will also need a ~1$ audio signal splitter to get sound on your speakers at the same time. This one, for example.

3. Wiring

After having powered your light strip you will have to connect it to your Raspberry device, for this you will have to connect the CLK and SI wires respectively to the SPI0_CLK (PIN 19), SPI0_MOSI (PIN 23) pins of the RPi device.

If you're no using the same power supply for both the RPi and the lightstrip, you will also need to connect both the RPi and the light strip grounds together (Any GND PIN of the RPi).

4. Installation

• Get the project source code either by git clone this repository or by downloading the archive and extracting it to your device.

• Move into the cloned or extracted folder cd path/to/lightitup-server

• Set your configuration by editing the default-config.yml file

  You will at least change LEDS_DRIVER, and LEDS_COUNT

  Note: You will also be able to change this file (will be moved at /opt/lightitup/) at any time after the installation process

• We are now ready to launch the installation by executing sh install-script.sh (It can take a while)

  • Note 1: We strongly advise you to make a backup of your SD card to prevent any possible issue before doing this.
  • Note 2: If for any reason you don't want the server to be installed as an autostarting service, edit the install-script.sh and change autostart_service to false. Then you will have to manually start the server at each boot.

• Once done, read the next section to learn what to do now.

5. Usage

5.1 Launching the server

• If you have left by default the install-script.sh:

  You have nothing to do, the server has started and will start by itself on each boot, a service has also been created, you can use it to (re)start & stop the server if needed).

  service lightitup start (or restart or stop)

• If you have decided to manually handling the server startup:

  Then you will have to run this command :

  node /opt/lightitup/dist/index.js

  You can append the following options to override the default configuration

  --port HTTP Port of the server
  --unsecured Will enforce not creating an HTTPS server
  --secured Will enforce to only create a HTTPS server
  --secured-port HTTPS Port of the server
  --no-audio To not handling the audio signal
  --device The audio device interface index
  --latency Audio device latency (ms) (e.g. in case of wireless speakers)
  

  Note: For a permanent configuration, you should edit the default-config.yml file instead

5.2 Access to the interface

You are now able to access to interface by browsing to :

http://<RPi Device IP>:8000 (or any HTTP port you set in the config file) https://<RPi Device IP>:8443 (or any HTTPS port you set in the config file)

You should now see the Light'It Up server interface. Some basics built-in effects are available by default, in the next section you will learn how to add other effects.

You can try to click on an effect to apply it on the lightstrip.

Note: If colors are inverted then you just have to change SPI.RGB_ORDER parameter in the default-config.yml file and then restarting the server : service lightitup restart

6 Features

6.1 Adding light effects to your list

To create effects or used existing presets, do the following process :

• Go to http://www.b-stud.com/lightitup-configurator
• Create and custom your effect using available options
• Then click on Export current effect and click on Copy
• Go back to the server interface and click on New Effect
• Give a unique name to your effect, for example: My custom Green Pulse
• On the config field, paste the effect you have copied from the configurator
• You can also set the optional Default limit time if you want the effect to stop running after a certain time
• You can change the Default priority to give more or less importance to the effect (see explanations below)
• Then click save, you are now able to use this effect.

6.2 Priorities

Let's imagine you have created a sunrise effect that lasts 30 minutes to gently wake up you. Now let's imagine that you use the HTTP API with a domotic solution (Jeedom, Domoticz..) and you have set up another effect, Red Alert that is set to the lightstrip when someone opens the entry door. The red alert is of course much more important than the sunrise, so it has to interrupt the sunrise effect.

Then, when the red alert is finished (let say after 10 seconds), the sunrise is able to resume as if it had not been interrupted at all. That is all the sense of effects priorities. For this scenario we should for example have set the sunrise priority to 0 and the red alert priority to 1 or anything higher than 0.

6.3 Automatizing effects with the time scheduler

The time scheduler gives a way to repeat launching effects over the time, for example, you could set sunset each day at 7pm, you could then schedule a Static Blue at 10pm from Monday to Friday, and so on..

To use the scheduler, you just to have to click the "Scheduler" button on the interface. Then you can very simply setup all you want to.

6.4 Controlling several devices at the same time

Sometimes devices are not close enough to control them with same RPi device, also, you may want to synchronize devices located in different places.

For this purpose, you have to complete the list of the hosts that you want to control inside the default-config.yml file :

SYNCHRONIZED_DEVICES_HOSTS: []

For example you could have something like this :

# ...
SYNCHRONIZED_DEVICES_HOSTS:
    - https://mydevice.local:8000
    - http://192.168.1.14:7400
    # - ... And so on

Note that a request coming from the master to a slave won't be forwarded anymore by the slave even if it has itself a completed list of devices hosts to control.

Please also note that the synchronized control does only concern the effects (un)stacked on the fly, toggling, and resetting options.

7. API

To control your light strip from outside, from a Domotics solution or from any other software able to send HTTP requests, a simple API is available.

Check if the server is online

• URL /ping
• Method GET
• Return 200, online

Reset the lightstrip

• URL /reset
• Method POST
• Return 200, Reset done
• Header Content-Type: application/json
• Body

{
    "apply_to_slaves": true|false  // <optional>   // Propagate the effect to slaves devices or not
}

Toggle the lightstrip (reset / last effect set)

• URL /toggle
• Method POST
• Return 200, Toggle done
• Header Content-Type: application/json
• Body

{
    "apply_to_slaves": true|false  // <optional>   // Propagate the effect to slaves devices or not
}

Setup(stack) an effect on the fly (not saved in your list)

• URL /stack
• Header Content-Type: application/json
• Method POST
• Body
• Header Content-Type: application/json
• Body

{
    "apply_to_slaves": true|false  // <optional>   // Propagate the effect to slaves devices or not
}

Unstack the effect currently being played (top of the stack)

• URL /unstack
• Header Content-Type: application/json
• Method POST
• Body

{
    "priority_min": integer|null,  // <optional>   // If set, the effect currently being played will be unstacked only if it has a priority greater than or equal the value specified
    "priority_max":  integer|null,   // <optional> , // If set, the effect currently being played will be unstacked only if it has a priority lesser than or equal the value specified
    "apply_to_slaves": true|false  // <optional>   // Propagate the effect to slaves devices or not
}

• Return 200, sent or 200, error

Getting the list of your registered effects

• URL /manager
• Method GET
• Return 200, JSON array of the effects list

Registering (saving) a new effect on your list

• URL /manager
• Method POST
• Header Content-Type: application/json
• Body

{
    "name":"My New Effect",
    "config": [], // Array of effects bricks as exported from the configurator
    "timeLimit":"", // Leave to null for a forever running effect, set a millisecond value else
    "priority":"0" // Any integer value (see above for explanations on priorities)
}

• Return 200, done OR 400, An error occurred

Updating an effect registered on the list

• URL /manager/effect-id
• Method PUT
• Header Content-Type: application/json
• Body

{
    "name":"My New Effect",
    "config": [], // Array of effects bricks as exported from the configurator
    "timeLimit":"", // Leave to null for a forever running effect, set a millisecond value else
    "priority":"0" // Any integer value (see above for explanations on priorities)
}

• Return 200, done OR 400, An error occurred

Deleting an effect registered on the list

• URL /manager/effect-id
• Method DELETE
• Return 200, done OR 400, Could not delete the effect

Applying an effect on the light strip

• URL /manager/apply/effect-name
• Optional URL parameters priority (integer value), timeLimit (millisecond time value). These parameters will override the effect settings.
• Method POST

8. License

Please find all the license information inside the LICENSE.md file

9. Author

Bilel OURAL - [e-mail]