adafruit / adafruit_circuitpython_apds9960 Goto Github PK

The proximity value is currently accessed via a function call:

apds.proximity()

It would be more inline with other libraries to make that a property.

apds.proximity

Also - not seeing any entry in the Design Guide for proximity sensor:
https://circuitpython.readthedocs.io/en/latest/docs/design_guide.html#sensor-properties-and-units
Closest is distance, which may be possible in an approximate way by curve fitting one or more of these (from datasheet):

I know that the policy for this lib is to not expose all registers to keep the footprint small. But I think it really needs methods for setting the proximity-gain (PGAIN) and gesture-gain (GGAIN). The default is 1x and 4x respectively. With this setting, proximity detection kicks in at a distance below an inch (at least for my sensor), which makes the driver almost useless.

The lib already has a setter/getter for the color-gain (AGAIN), and I would provide a patch with similar methods for the PGAIN/GGAIN settings if you also think this is a useful addition.

The CLUE module sets the sensor object's enable_color and enable_proximity to true before asking for the related data. It never sets them to false. More interestingly I don't see where in the sensor code those values get propagated to the sensor enable register, although they do get initialized from the register value.

There are missing type annotations for some functions in this library.

The typing module does not exist on CircuitPython devices so the import needs to be wrapped in try/except to catch the error for missing import. There is an example of how that is done here:

try:
    from typing import List, Tuple
except ImportError:
    pass

Once imported the typing annotations for the argument type(s), and return type(s) can be added to the function signature. Here is an example of a function that has had this done already:

def wrap_text_to_pixels(
    string: str, max_width: int, font=None, indent0: str = "", indent1: str = ""
) -> List[str]:

If you are new to Git or Github we have a guide about contributing to our projects here: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

There is also a guide that covers our CI utilities and how to run them locally to ensure they will pass in Github Actions here: https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/check-your-code In particular the pages: Sharing docs on ReadTheDocs and Check your code with pre-commit contain the tools to install and commands to run locally to run the checks.

If you are attempting to resolve this issue and need help, you can post a comment on this issue and tag both @FoamyGuy and @kattni or reach out to us on Discord: https://adafru.it/discord in the #circuitpython-dev channel.

The following locations are reported by mypy to be missing type annotations:

• adafruit_apds9960/colorutility.py:18
• adafruit_apds9960/colorutility.py:43
• adafruit_apds9960/apds9960.py:138
• adafruit_apds9960/apds9960.py:215
• adafruit_apds9960/apds9960.py:229
• adafruit_apds9960/apds9960.py:234
• adafruit_apds9960/apds9960.py:332
• adafruit_apds9960/apds9960.py:365
• adafruit_apds9960/apds9960.py:381
• adafruit_apds9960/apds9960.py:399
• adafruit_apds9960/apds9960.py:403
• adafruit_apds9960/apds9960.py:411
• adafruit_apds9960/apds9960.py:418
• adafruit_apds9960/apds9960.py:426

Debra (@geekmomprojects on Twitter) has been trying to use the Light + Gesture + Proximity: APDS9960 on CLUE and it has been either returning no value (distance) or irregular values (gesture). This library is quite old (9/2017) and may not be entirely functional under CircuitPython 5. I also posted in the CLUE library.

The C/Arduino library has a method called setADCIntegrationTime which takes a uint16_t iTimeMS and converts it into values that the APDS9660 uses, full code can be seen here https://github.com/adafruit/Adafruit_APDS9960/blob/master/Adafruit_APDS9960.cpp#L130-L149 (NB that code does not do a particularly explicit conversion from FP to (8 bit) integer).

The CircuitPython library currently just sends the raw value but the property is a bit misleading and called integration_time. The library defaults this to 0x01 which translates to (256 - 1) * 2.78ms = 708.9ms.

I'm not sure if this should be corrected to match the Arduino library with its more intuitive and user-friendly values? Changing this value now would disrupt existing users as there's no (clean!) way to code this with the existing property name. Is there a way to code this to happen in CP 5+ libraries only? Is that a good approach?

The class doc states that it expects a Pin but, when given a Pin object, the library throws this error:

>>> light = APDS9960(i2c, interrupt_pin=board.PROXIMITY_LIGHT_INTERRUPT)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "adafruit_apds9960/apds9960.py", line 155, in __init__
AttributeError: 'Pin' object has no attribute 'switch_to_input'

Since this internal variable is never used it may be best to just remove it.

From @kevinjwalters in #16:
FYI, If the RGBC values are of interest, the current defauls set the ADC Integration Time Register (0x81) register to 0x01 which equates to 708.9ms integration time giving updates only ~ 1.4Hz. Page 20 of the datasheet has a slight error on how this value is treated, it says 256 - TIME / 2.78 ms. I'm pretty sure it means (256 - TIME) * 2.78. There's an integration_time property which can be used to adjust this.

I've also noticed clue.color() values getting "stuck" on REPL on the CLUE but I've only seen this once. foamyguy on discord has also seen this.

Add a Basic DisplayIO Based Example

We would like to have a basic displayio example for this library. The example should be written for microcontrollers with a built-in display. At a minimum it should show a Label on the display and update it with live readings from the sensor.

The example should not be overly complex, it's intended to be a good starting point for displayio based projects that utilize this sensor library. Try to keep all visual content as near to the top left corner as possible in order to best fascilitate devices with small built-in display resolutions.

The new example should follow the naming convention examples/libraryname_displayio_simpletest.py with "libraryname" being replaced by the actual name of this library.

You can find an example of a Pull Request that adds this kind of example here: adafruit/Adafruit_CircuitPython_BME680#72

We have a guide that covers the process of contributing with git and github: https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github

If you're interested in contributing but need additional help, or just want to say hi, feel free to join the Discord server to ask questions: https://adafru.it/discord

From @dastels in #16:
Related: gestures being triggered (prox > gesture_proximity_threshold) freeze the returned proximity value. E.g. if the threshold is at the default 50, the returned proximity value to 'lock in' when it reaches 51. Setting the threshold to 255 allows proximity to work property throughout it's full 0-255 range.

From the Adafruit documentation:

read the color_data property to retrieve the red, green, blue, and clear color values as a 4-tuple of 16-bit values …

I can't, for the life of me, figure out what a "clear" color value or "clear light" refers to! Deep googling yields information about Tibetan Bhuddism and a psychedelic rock band from the 1960s.

Thanks in advance.

Hi all!
i have this board:
https://www.berrybase.at/apds-9960-rgb-infrarot-gestensensor

but cant get it to work with my xiao nrf:

Traceback (most recent call last):
  File "main.py", line 8, in <module>
  File "adafruit_apds9960/apds9960.py", line 187, in __init__
RuntimeError: 

i2c address is the same as in library

thanks ahead

The APDS9960 is rotated 90 degrees on the CLUE, therefore the gestures are off by 90 degrees.

Add the ability to compensate for sensor rotation by including gesture rotation.

The other capabilities of the sensor are not affected by rotation.