Updated readme.md for usermods.

This commit is contained in:
Blaž Kristan 2021-11-16 08:25:01 +01:00
parent 2a949cd8f1
commit 9888510158
3 changed files with 75 additions and 14 deletions

View File

@ -9,16 +9,17 @@ The LED strip is switched [using a relay](https://github.com/Aircoookie/WLED/wik
## Webinterface
The info page in the web interface shows the remaining time of the off timer.
The info page in the web interface shows the remaining time of the off timer. Usermod can also be temporarily disbled/enabled from the info page by clicking PIR button.
## Sensor connection
My setup uses an HC-SR501 sensor, a HC-SR505 should also work.
My setup uses an HC-SR501 or HC-SR602 sensor, a HC-SR505 should also work.
The usermod uses GPIO13 (D1 mini pin D7) by default for the sensor signal but can be changed in the Usermod settings page.
[This example page](http://www.esp8266learning.com/wemos-mini-pir-sensor-example.php) describes how to connect the sensor.
Use the potentiometers on the sensor to set the time-delay to the minimum and the sensitivity to about half, or slightly above.
You can also use usermod's off timer instead of sensor's. In such case rotate the potentiometer to its shortest time possible (or use SR602 which lacks such potentiometer).
## Usermod installation
@ -59,6 +60,8 @@ void registerUsermods()
}
```
**NOTE:** Usermod has been included in master branch of WLED so it can be compiled in directly just by defining `-D USERMOD_PIRSWITCH` and optionaly `-D PIR_SENSOR_PIN=16` to override default pin.
## API to enable/disable the PIR sensor from outside. For example from another usermod.
To query or change the PIR sensor state the methods `bool PIRsensorEnabled()` and `void EnablePIRsensor(bool enable)` are available.
@ -95,8 +98,27 @@ class MyUsermod : public Usermod {
};
```
Have fun - @gegu
### Configuration options
Usermod can be configured in Usermods settings page.
* `PIRenabled` - enable/disable usermod
* `pin` - dynamically change GPIO pin where PIR sensor is attached to ESP
* `PIRoffSec` - number of seconds after PIR sensor deactivates when usermod triggers Off preset (or turns WLED off)
* `on-preset` - preset triggered when PIR activates (if this is 0 it will just turn WLED on)
* `off-preset` - preset triggered when PIR deactivates (if this is 0 it will just turn WLED off)
* `nighttime-only` - enable triggering only between sunset and sunrise (you will need to set up _NTP_, _Lat_ & _Lon_ in Time & Macro settings)
* `mqtt-only` - only send MQTT messages, do not interact with WLED
* `off-only` - only trigger presets or turn WLED on/off in WLED is not already on (displaying effect)
* `notifications` - enable or disable sending notifications to other WLED instances using Sync button
Have fun - @gegu & @blazoncek
## Change log
2021-04
* Adaptation for runtime configuration.
* Adaptation for runtime configuration.
2021-11
* Added information about dynamic configuration options
* Added option to temporary enable/disble usermod from WLED UI (Info dialog)

View File

@ -5,31 +5,35 @@ This usermod-v2 modification allows the connection of multiple relays each with
## HTTP API
All responses are returned as JSON.
Status Request: `http://[device-ip]/relays`
Switch Command: `http://[device-ip]/relays?switch=1,0,1,1`
* Status Request: `http://[device-ip]/relays`
* Switch Command: `http://[device-ip]/relays?switch=1,0,1,1`
The number of numbers behind the switch parameter must correspond to the number of relays. The number 1 switches the relay on. The number 0 switches the relay off.
Toggle Command: `http://[device-ip]/relays?toggle=1,0,1,1`
* Toggle Command: `http://[device-ip]/relays?toggle=1,0,1,1`
The number of numbers behind the parameter switch must correspond to the number of relays. The number 1 causes a toggling of the relay. The number 0 leaves the state of the device.
Examples
1. 4 relays at all, relay 2 will be toggled: `http://[device-ip]/relays?toggle=0,1,0,0`
2. 3 relays at all, relay 1&3 will be switched on: `http://[device-ip]/relays?switch=1,0,1`
1. total of 4 relays, relay 2 will be toggled: `http://[device-ip]/relays?toggle=0,1,0,0`
2. total of 3 relays, relay 1&3 will be switched on: `http://[device-ip]/relays?switch=1,0,1`
## JSON API
You can switch relay state using the following JSON object transmitted to: `http://[device-ip]/json`
Switch relay 0 on: `{"MultiRelay":{"relay":0,"on":true}}`
Switch relay4 3 & 4 off: `{"MultiRelay":[{"relay":2,"on":false},{"relay":3,"on":false}]}`
## MQTT API
wled/deviceMAC/relay/0/command on|off|toggle
wled/deviceMAC/relay/1/command on|off|toggle
* `wled`/_deviceMAC_/`relay`/`0`/`command` `on`|`off`|`toggle`
* `wled`/_deviceMAC_/`relay`/`1`/`command` `on`|`off`|`toggle`
When relay is switched it will publish a message:
wled/deviceMAC/relay/0 on|off
* `wled`/_deviceMAC_/`relay`/`0` `on`|`off`
## Usermod installation
@ -76,10 +80,21 @@ void registerUsermods()
Usermod can be configured in Usermods settings page.
* `enabled` - enable/disable usermod
* `pin` - GPIO pin where relay is attached to ESP
* `delay-s` - delay in seconds after on/off command is received
* `active-high` - toggle high/low activation of relay (can be used to reverse relay states)
* `external` - if enabled WLED does not control relay, it can only be triggered by external command (MQTT, HTTP, JSON or button)
* `button` - button (from LED Settings) that controls this relay
If there is no MultiRelay section, just save current configuration and re-open Usermods settings page.
Have fun - @blazoncek
## Change log
2021-04
* First implementation.
* First implementation.
2021-11
* Added information about dynamic configuration options
* Added button support.

View File

@ -31,9 +31,33 @@ This usermod requires the `U8g2` and `Wire` libraries. See the
`platformio_override.ini.sample` found in the Rotary Encoder
UI usermod folder for how to include these using `platformio_override.ini`.
## Configuration
* `enabled` - enable/disable usermod
* `pin` - GPIO pins used for display; I2C displays use Clk & Data; SPI displays can use SCK, MOSI, CS, DC & RST
* `type` - display type in numeric format
* 1 = I2C SSD1306 128x32
* 2 = I2C SH1106 128x32
* 3 = I2C SSD1306 128x64 (4 double-height lines)
* 4 = I2C SSD1305 128x32
* 5 = I2C SSD1305 128x64 (4 double-height lines)
* 6 = SPI SSD1306 128x32
* 7 = SPI SSD1306 128x64 (4 double-height lines)
* `contrast` - set display contrast (higher contrast may reduce display lifetime)
* `refreshRateSec` - time in seconds for display refresh
* `screenTimeOutSec` - screen saver time-out in seconds
* `flip` - flip/rotate display 180°
* `sleepMode` - enable/disable screen saver
* `clockMode` - enable/disable clock display in screen saver mode
* `i2c-freq-kHz` - I2C clock frequency in kHz (may help reduce dropped frames, range: 400-3400)
## Change Log
2021-02
* First public release
2021-04
* Adaptation for runtime configuration.
* Adaptation for runtime configuration.
2021-11
* Added configuration option description.