WLED/usermods/Animated_Staircase/README.md

Usermod Animated Staircase

This usermod makes your staircase look cool by switching it on with an animation. It uses PIR or ultrasonic sensors at the top and bottom of your stairs to:

• Light up the steps in your walking direction, leading the way.
• Switch off the steps after you, in the direction of the last detected movement.
• Always switch on when one of the sensors detects movement, even if an effect is still running. It can therewith handle multiple people on the stairs gracefully.

The Animated Staircase can be controlled by the WLED API. Change settings such as speed, on/off time and distance settings by sending an HTTP request, see below.

WLED integration

To include this usermod in your WLED setup, you have to be able to compile WLED from source.

Before compiling, you have to make the following modifications:

Edit usermods_list.cpp:

1. Open wled00/usermods_list.cpp
2. add #include "../usermods/Animated_Staircase/Animated_Staircase.h" to the top of the file
3. add usermods.add(new Animated_Staircase()); to the end of the void registerUsermods() function.

Edit Animated_Staircase_config.h:

1. Open usermods/Animated_Staircase/Animated_Staircase_config.h

2. To use PIR sensors, change these lines to match your setup: Using D7 and D6 pin notation as used on several boards:

     #define TOP_PIR_PIN    D7
     #define BOTTOM_PIR_PIN D6
   

   Or using GPIO numbering for pins 25 and 26:

     #define TOP_PIR_PIN    26
     #define BOTTOM_PIR_PIN 25
   

   To use Ultrasonic HC-SR04 sensors instead of (one of the) PIR sensors, uncomment one of the PIR sensor lines and adjust the pin numbers for the connected Ultrasonic sensor. In the example below we use an Ultrasonic sensor at the bottom of the stairs:

   #define TOP_PIR_PIN 32
   //#define BOTTOM_PIR_PIN D6 /* This PIR sensor is disabled   */
   
   #ifndef TOP_PIR_PIN
   #define TOP_SIGNAL_PIN D2
   #define TOP_ECHO_PIN   D3
   #endif
   
   #ifndef BOTTOM_PIR_PIN      /* If the bottom PIR is disabled, */
   #define BOTTOM_SIGNAL_PIN 25 /* This Ultrasonic sensor is used */
   #define BOTTOM_ECHO_PIN   26
   #endif
   

After these modifications, compile and upload your WLED binary to your board and check the WLED info page to see if this usermod is enabled.

Hardware installation

1. Stick the LED strip under each step of the stairs.
2. Connect the ESP8266 pin D4 or ESP32 pin D2 to the first LED data pin at the bottom step of your stairs.
3. Connect the data-out pin at the end of each strip per step to the data-in pin on the other end of the next step, creating one large virtual LED strip.
4. Mount sensors of choice at the bottom and top of the stairs and connect them to the ESP.
5. To make sure all LEDs get enough power and have your staircase lighted evenly, power each step from one side, using at least AWG14 or 2.5mm^2 cable. Don't connect them serial as you do for the datacable!

You may need to use 10k pull-down resistors on the selected PIR pins, depending on the sensor.

WLED configuration

1. In the WLED UI, confgure a segment for each step. The lowest step of the stairs is the lowest segment id.
2. Save your segments into a preset.
3. Ideally, add the preset in the config > LED setup menu to the "apply preset n at boot" setting.

Changing behavior through API

The Staircase settings can be changed through the WLED JSON api.

NOTE: We are using curl to send HTTP POSTs to the WLED API. If you're using Windows and want to use the curl commands, replace the \ with a ^ or remove them and put everything on one line.

Setting	Description	Default
enabled	Enable or disable the usermod	true
segment-delay-ms	Delay (milliseconds) between switching on/off each step	150
on-time-s	Time (seconds) the stairs stay lit after last detection	5
bottom-echo-us	Detection range of ultrasonic sensor	1749
bottom-sensor	Manually trigger a down to up animation via API	false
top-sensor	Manually trigger an up to down animation via API	false

To read the current settings, open a browser to http://xxx.xxx.xxx.xxx/json/state (use your WLED device IP address). The device will respond with a json object containing all WLED settings. The staircase settings and sensor states are inside the WLED status element:

{
    "state": {
        "staircase": {
            "enabled": true,
            "segment-delay-ms": 150,
            "on-time-s": 5,
            "bottom-sensor": false,
            "tops-ensor": false
        },
}

Enable/disable the usermod

By disabling the usermod you will be able to keep the LED's on, independent from the sensor activity. This enables to play with the lights without the usermod switching them on or off.

To disable the usermod:

curl -X POST -H "Content-Type: application/json" \
     -d {"staircase":{"enabled":false}} \
     xxx.xxx.xxx.xxx/json/state

To enable the usermod again, use "enabled":true.

Changing animation parameters

To change the delay between the steps to (for example) 100 milliseconds and the on-time to 10 seconds:

curl -X POST -H "Content-Type: application/json" \
     -d '{"staircase":{"segment-delay-ms":100,"on-time-s":10}}' \
     xxx.xxx.xxx.xxx/json/state

Changing detection range of the ultrasonic HC-SR04 sensor

When an ultrasonic sensor is enabled in Animated_Staircase_config.h, you'll see a bottom-echo-us setting appear in the json api:

{
    "state": {
        "staircase": {
            "enabled": true,
            "segment-delay-ms": 150,
            "on-time-s": 5,
            "bottom-echo-us": 1749
        },
}

If the HC-SR04 sensor detects an echo within 1749 microseconds (corresponding to ~30 cm detection range from the sensor), it will trigger switching on the staircase. This setting can be changed through the API with an HTTP POST:

curl -X POST -H "Content-Type: application/json" \
     -d '{"staircase":{"bottom-echo-us":1166}}' \
     xxx.xxx.xxx.xxx/json/state

Calculating the detection range can be performed as follows: The speed of sound is 343m/s at 20 degrees Centigrade. Since the sound has to travel back and forth, the detection range for the sensor in cm is (0.0343 * maxTimeUs) / 2. To get you started, please find delays and distances below:

Distance	Detection time
5 cm	292 uS
10 cm	583 uS
20 cm	1166 uS
30 cm	1749 uS
50 cm	2915 uS
100 cm	5831 uS

Please note: that using an HC-SR04 sensor, particularly when detecting echos at longer distances creates delays in the WLED software, and might introduce timing hickups in your animations or a less responsive web interface. It is therefore advised to keep the detection time as short as possible.

Animation triggering through the API

Instead of stairs activation by one of the sensors, you can also trigger the animation through the API. To simulate triggering the bottom sensor, use:

curl -X POST -H "Content-Type: application/json" \
     -d '{"staircase":{"bottom-sensor":true}}' \
     xxx.xxx.xxx.xxx/json/state

Likewise, to trigger the top sensor, use:

curl -X POST -H "Content-Type: application/json" \
     -d '{"staircase":{"top-sensor":true}}' \
     xxx.xxx.xxx.xxx/json/state

Have fun with this usermod.
www.rolfje.com