mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

apds-9960

blakadder 2019-10-31 21:49:33 +01:00
parent c822c19674
commit b6d87b6393
3 changed files with 58 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
APDS-9960.md

@ -1,53 +1,44 @@
# Broadcom Avago APDS-9960 Ambient Light and RGB Color Sensing, Proximity Sensing and Gesture Detection Sensor # Please use this exact paragraph (formatting and links) at the beginning of an article for a feature that is not included in precompiled builds
* Ambient Light and RGB Color Sensing
* UV and IR blocking filters
* Programmable gain and integration time
* Very high sensitivity – Ideally suited for operation
behind dark glass
* Proximity Sensing
* Trimmed to provide consistent reading
* Ambient light rejection
* Offset compensation
* Programmable driver for IR LED current
* Saturation indicator bit
* Complex Gesture Sensing
* Four separate diodes sensitive to different directions
* Ambient light rejection
* Offset compensation
* Programmable driver for IR LED current
* 32 dataset storage FIFO
* Interrupt driven I<sup>2</sup>C communication
* I<sup>2</sup>C-bus Fast Mode Compatible Interface
* Data Rates up to 400 kHz
* Dedicated Interrupt Pin
* Small Package L 3.94 × W 2.36 × H 1.35 mm
**This feature is not included in precompiled binaries.** To use it you must [compile your build](compile-your-build). Add the following to `user_config_override.h`:
```
#ifndef USE_APDS9960
#define USE_APDS9960 // Enable APDS9960 Proximity Sensor (+4k7 code)
#endif
```
----
<img src="https://i.postimg.cc/qRLyPy1n/APDS-9960-1-720x533.jpg" align=right>
Broadcom APDS-9960 is a digital RGB, ambient light, proximity and gesture sensor device in a single 8-pin package. The device has an I2C compatible interface providing red, green, blue, clear (RGBC), proximity and gesture sensing with IR LED. The RGB and ambient light sensing feature detects light intensity under various lighting conditions and through various attentuation materials including darkened glass. In addition, the integrated UV-IR blocking filter enables accurate ambient light and correlated color temperature sensing.
* Break-out PCBs ## Configuration
* ~ 2€ at [AliExpress](https://www.aliexpress.com/wholesale?catId=0&initiative_id=&SearchText=apds-9960) ### Wiring
* ~ $8 at [Adafruit](https://www.adafruit.com/product/3595)
## Technical Data from the manufacturer
* [APDS-9960 Datasheet](https://docs.broadcom.com/docs/AV02-4191EN)
## Wiring breakout boards
| Breakout | ESP8266 | | Breakout | ESP8266 |
|----------|-----------| |----------|-----------|
| VCC/VIN | +3.3VDC | | VCC/VIN | +3.3VDC |
| GND | GND | | GND | GND |
| SCL | GPIO I<sup>2</sup>C SCL | | SCL | GPIO I<sup>2</sup>C SCL |
| SDA | GPIO I<sup>2</sup>C SDA | | SDA | GPIO I<sup>2</sup>C SDA |
| INT/IRQ | NC | | INT/IRQ | not used |
### Tasmota configuration After configuring the GPIO's the driver will detect the APDS-9960 automatically.
Compile Tasmota with `#define USE_APDS9960` uncommented in `user_config_override.h` On first boot sensor will start in gesture mode. It will not appear in the webUI but it can be observed via MQTT messages in console:
The driver will detect the APDS-9960 automatically. ```
The APDS-9960 chip (or breakout board) must be connected to the ESP8266 and the I<sup>2</sup>C GPIO pins must be configured: 21:34:21 MQT: tele/tasmota/RESULT = {"Gesture":"Off"}
21:34:23 MQT: tele/tasmota/RESULT = {"Gesture":"On"}
21:34:25 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:25","APDS9960":{"None":1}}
21:34:26 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:26","APDS9960":{"Right":1}}
21:34:29 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:29","APDS9960":{"Down":1}}
21:34:29 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:29","APDS9960":{"Right":1}}
21:34:31 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:31","APDS9960":{"Left":1}}
21:34:33 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:33","APDS9960":{"Up":1}}
21:34:35 MQT: tele/tasmota/SENSOR = {"Time":"2019-10-31T21:34:35","APDS9960":{"Down":1}}
```
![I<sup>2</sup>C GPIO configuration](https://raw.githubusercontent.com/arendst/arendst.github.io/master/media/wemos/wemos_sht30_config_marked.jpg) When you enable RGBC mode with `Sensor27 0` sensor will show up in web UI:
![](https://i.postimg.cc/W1Cn8Gy1/APDS-9960.png)
### MQTT commands ## Commands
| Command | Value | Description | | Command | Value | Description |
|---|---|---| |---|---|---|
| Sensor27 || Show APDS9960 gesture/RGBC mode | | Sensor27 || Show APDS9960 gesture/RGBC mode |
@ -62,14 +53,18 @@ The APDS-9960 chip (or breakout board) must be connected to the ESP8266 and the
##### Control ON/OFF, brightness and color temperature with gestures ##### Control ON/OFF, brightness and color temperature with gestures
`rule on Tele-APDS9960#Long do power toggle endon on Tele-APDS9960#Up do dimmer + endon on Tele-APDS9960#Down do dimmer - endon on Tele-APDS9960#Left do ct + endon on Tele-APDS9960#Right do ct - endon` `rule on Tele-APDS9960#Long do power toggle endon on Tele-APDS9960#Up do dimmer + endon on Tele-APDS9960#Down do dimmer - endon on Tele-APDS9960#Left do ct + endon on Tele-APDS9960#Right do ct - endon`
``` ## Known issues:
LONG: toggle ON/OFF
UP: increase brightness
DOWN: decrease brightness
Left: increase color temperature
Right: decrease color temperature
```
1. The different PCB’s on the market seem to differ quite substantially regarding to their electrical characteristics. We have at least one case report, where this led to a malfunction on an ESP8266-board within Tasmota but in another library too. The exact technical reason can only be suspected, but it is probably related to electrical noise and/or power consumption.
In the case from above the sensor measured an incorrect high proximity value, which resulted in repeated triggering of a "LONG" gesture. The solution was to decrease the gain factor for proximity and gesture. Therefore the argument 2 (`sensor27 2`) was introduced to change this at runtime.
If you experience gesture sensing problems you could try this out, but if you measure proximity values <25 with nothing in front of the sensor (e.g. web interface after `sensor27 0`), then there is very likely another problem. It can be assumed, that the gesture sensitivity will suffer with reduced gain, so first try option 1 (=default).
Beside that better wiring and maybe an additional capacitor over VCC and GROUND might be helpful.
2. The measurement of the light level is briefly described in the datasheet and the open-source-libraries use the ambient-light-value directly from the sensor or calculate a LUX-value from RGB. Both variants are usable and differentiate between low and strong light, but the absolute values are questionable and at the moment we have an uncalibrated sensor.
All known solutions use a fixed integration time, which is more or less the same as a fixed exposure time in photography. In contrast the TSL2561-library uses various integration times and maybe this is possible on the APDS9960 too.
To eventually achieve this in the future, the option to set this integration time at runtime was added. Every argument between 3 and 255 sets the ATIME-register.
The formula is: integration time = (256-ATIME)*2,78 ms, so with the default value of 219 we get (256-219)*2,78 = 102,86 ms. That means a smaller ATIME makes the integration time longer and more photons are captured, which might be usable for (very) low light conditions, because otherwise the sensor will saturate too early. The opposite is valid for a bigger ATIME value.
The change of this value only makes sense for: users who need to change the sensitivity, if the sensor resides behind dark glass or want to contribute to the development of a new LUX-calculation in the driver. If we get enough feedback, this could lead to an improvement on the software side. Feel free to open (or search for) an issue, if you have measured the APDS9960 against other devices with different ATIME-values at different light levels. This is not a trivial task though.
## Generally available types of breakout boards ## Generally available types of breakout boards
![APDS-9960](https://ae01.alicdn.com/kf/HTB19_5yc6gy_uJjSZLeq6yPlFXad/APDS-9960-APDS9960.jpg_640x640.jpg) ![APDS-9960](https://ae01.alicdn.com/kf/HTB19_5yc6gy_uJjSZLeq6yPlFXad/APDS-9960-APDS9960.jpg_640x640.jpg)
@ -78,15 +73,8 @@ Right: decrease color temperature
![](https://ae01.alicdn.com/kf/HTB10vNSlhSYBuNjSsphq6zGvVXa9/RGB-Proximity-Sensor-Detection-Direction-Gesture-APDS9960-APDS-9960-Non-Contact-Module.jpg_640x640.jpg) ![](https://ae01.alicdn.com/kf/HTB10vNSlhSYBuNjSsphq6zGvVXa9/RGB-Proximity-Sensor-Detection-Direction-Gesture-APDS9960-APDS-9960-Non-Contact-Module.jpg_640x640.jpg)
![](https://ae01.alicdn.com/kf/HTB16R.JeUl7MKJjSZFDq6yOEpXah/APDS-9960-RGB-Ambient-Light-Short-range-Gesture-Module-Color-Module-Light-Module.jpg) ![](https://ae01.alicdn.com/kf/HTB16R.JeUl7MKJjSZFDq6yOEpXah/APDS-9960-RGB-Ambient-Light-Short-range-Gesture-Module-Color-Module-Light-Module.jpg)
## Known issues: #### Where to get
* ~ 2€ at [AliExpress](https://www.aliexpress.com/wholesale?catId=0&initiative_id=&SearchText=apds-9960)
* ~ $8 at [Adafruit](https://www.adafruit.com/product/3595)
1. The different PCB’s on the market seem to differ quite substantially regarding to their electrical characteristics. We have at least one case report, where this led to a malfunction on an ESP8266-board within TASMOTA but in another library too. The exact technical reason can only be suspected, but it is probably related to electrical noise and/or power consumption. [APDS-9960 Datasheet](https://docs.broadcom.com/docs/AV02-4191EN)
In the case from above the sensor measured an incorrect high proximity value, which resulted in repeated triggering of a „LONG“ gesture. The solution was to decrease the gain factor for proximity and gesture. Therefore the argument 2 (sensor27 2) was introduced to change this at runtime.

If you experience gesture sensing problems you could try this out, but if you measure proximity values <25 with nothing in front of the sensor (e.g. web interface after sensor27 0), then there is very likely another problem. It can be assumed, that the gesture sensitivity will suffer with reduced gain, so first try option 1 (=default).

Beside that an „as-good-as-possible“ wiring and maybe an additional capacitor over VCC and GROUND might be helpful.

2. The measurement of the light level is quite shortly described in the data sheet of the APDS9960 and the open-source-libraries use wether the ambient-light-value directly from the sensor or calculate a LUX-value from RGB. Both variants are usable and differentiate between low and strong light, but the absolute values are questionable and at the moment we have an uncalibrated sensor.

All (known) solution use a fixed integration time, which is more or less the same as a fixed exposure time in photography. In contrast the TSL2561-library (from JOBA) uses various integration times and maybe this is possible on the APDS9960 too.
To eventually achieve this in the future, the option to set this integration time at runtime was added. Every argument between 3 and 255 sets the ATIME-register. 

The formula is: integration time = (256-ATIME)*2,78 ms, so with the default value of 219 we get (256-219)*2,78 = 102,86 ms. That means a smaller ATIME makes the integration time longer and more photons are captured, which might be usable for (very) low light conditions, because otherwise the sensor will saturate too early. The opposite is valid for a bigger ATIME value.
The change of this value only makes sense for users, who wether need to change the sensitivity, if the sensor resides behind dark glass or want to contribute to the development of a new LUX-calculation in the driver. If we get enough feedback, this could lead to an improvement on the software side. Feel free to open (or search for) an issue, if you have measured the APDS9960 against other devices with different ATIME-values at different light levels. This is not a trivial task though.

5
Compile-your-build.md

@ -13,6 +13,11 @@ Navigate to where you unpacked Tasmota and into /tasmota folder.
Open `my_user_config.h` and uncomment (remove `//`) line with `#define USE_CONFIG_OVERRIDE`. It should look like this: Open `my_user_config.h` and uncomment (remove `//`) line with `#define USE_CONFIG_OVERRIDE`. It should look like this:
`#define USE_CONFIG_OVERRIDE // Uncomment to use user_config_override.h file. See README.md` `#define USE_CONFIG_OVERRIDE // Uncomment to use user_config_override.h file. See README.md`
> In PlatformIO you can edit [platformio.ini](https://github.com/arendst/Tasmota/blob/20370820b85acf282fbf7ebec38ef2a484921a16/platformio.ini#L225) instead. Go to root directory of source code and uncomment (remove `;`) line:
>
>`; -DUSE_CONFIG_OVERRIDE
Create a new file in /tasmota folder called `user_config_override.h`. Create a new file in /tasmota folder called `user_config_override.h`.
Open the file in chosen development environment for editing. Open the file in chosen development environment for editing.

17
Scripting-Language.md

@ -1,10 +1,6 @@
Script Language for Tasmota - An alternative to Tasmota [Rules](Rules). # Please use this exact paragraph (formatting and links) at the beginning of an article for a feature that is not included in precompiled builds
[Script Cookbook](Script-Cookbook) **This feature is not included in precompiled binaries.** To use it you must [compile your build](compile-your-build). Add the following to `user_config_override.h`:
:warning:**Scripting is not included in release builds of Tasmota. To use it, you must compile your own firmware.**:warning:
Add the following compiler directives to `user_config_override.h`:
``` ```
#ifndef USE_SCRIPT #ifndef USE_SCRIPT
#define USE_SCRIPT # adds about 17k flash size, variable ram size #define USE_SCRIPT # adds about 17k flash size, variable ram size
@ -35,14 +31,19 @@ USE_24C256 | enables use of 24C256 I<sup>2</sup>C EEPROM to expand script buffer
USE_SCRIPT_FATFS | enables SD card support (on SPI bus). Specify the CS pin number. Also enables 4k script buffer USE_SCRIPT_FATFS | enables SD card support (on SPI bus). Specify the CS pin number. Also enables 4k script buffer
USE_SCRIPT_FATFS_EXT | enables additional FS commands USE_SCRIPT_FATFS_EXT | enables additional FS commands
SDCARD_DIR | enables support for web UI for SD card directory upload and download SDCARD_DIR | enables support for web UI for SD card directory upload and download
----
<BR><BR>To enter a script, go to `Configuration` =\> `Edit script` in the Tasmota web UI menu Scripting Language for Tasmota is an alternative to Tasmota [Rules](Rules).
[Script Cookbook](Script-Cookbook)
To enter a script, go to `Configuration` =\> `Edit script` in the Tasmota web UI menu
The maximum script size is 1535 bytes (uses rule set buffers). If the pasted script is larger than 1535 characters, comments will be stripped to attempt to make the script fit. The maximum script size is 1535 bytes (uses rule set buffers). If the pasted script is larger than 1535 characters, comments will be stripped to attempt to make the script fit.
To save code space almost no error messages are provided. However it is taken care of that at least it should not crash on syntax errors. To save code space almost no error messages are provided. However it is taken care of that at least it should not crash on syntax errors.
<BR>**Features** **Features**
- Up to 50 variables (45 numeric and 5 strings - this may be changed by setting a compilation `#define` directive) - Up to 50 variables (45 numeric and 5 strings - this may be changed by setting a compilation `#define` directive)
- Freely definable variable names (all variable names are intentionally _**case sensitive**_) - Freely definable variable names (all variable names are intentionally _**case sensitive**_)
- Nested if,then,else up to a level of 8 - Nested if,then,else up to a level of 8