adafruit / adafruit_circuitpython_vcnl4010

CircuitPython module for VCNL4010 proximity and ambient light sensor.

Introduction

CircuitPython module for the VCNL4010 proximity and light sensor.

Dependencies

This driver depends on:

• Adafruit CircuitPython
• Bus Device

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install adafruit-circuitpython-vcnl4010

To install system-wide (this may be required in some cases):

sudo pip3 install adafruit-circuitpython-vcnl4010

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .venv/bin/activate
pip3 install adafruit-circuitpython-vcnl4010

Usage Example

See examples/vcnl4010_simpletest.py for an example of the usage.

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.

adafruit_circuitpython_vcnl4010's Issues

Incorrect implementation of proximity measurement frequency

After a comparison of the CP version of this module with the data sheet, and the Arduino version of the Adafruit VCNL4010 library, I think that this module is not correctly setting the proximity measurement read rate on the chip.

The documentation for this module says that setting the frequency property is supposed to set the proximity read frequency:

The frequency of proximity measurements. Must be a value of:

FREQUENCY_3M125: 3.125 Mhz

FREQUENCY_1M5625: 1.5625 Mhz

FREQUENCY_781K25: 781.25 Khz

FREQUENCY_390K625: 390.625 Khz (default)

See the datasheet for how frequency changes the proximity detection accuracy.

However, the data sheet states that there are 8 modes for the proximity rate register:

000 - 1.95 measurements/s (DEFAULT)
001 - 3.90625 measurements/s
010 - 7.8125 measurements/s
011 - 16.625 measurements/s
100 - 31.25 measurements/s
101 - 62.5 measurements/s
110 - 125 measurements/s
111 - 250 measurements/s

In addition, this module is setting the PROXIMITY MODULATOR TIMING ADJUSTMENT (register 15) register at address 0x8f, not the PROXIMITY RATE REGISTER (register 2) at 0x82 (as described in the data sheet and implemented in the Arduino library). Based on this information, I’m pretty sure this is not what was intended, as the register being used changes the frequency of the square wave of the IR signal, not the number of measurements made by the sensor.

DisplayIO Example Wanted

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

Missing Type Annotations

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_vcnl4010.py:109
• adafruit_vcnl4010.py:119
• adafruit_vcnl4010.py:126
• adafruit_vcnl4010.py:133
• adafruit_vcnl4010.py:150
• adafruit_vcnl4010.py:167
• adafruit_vcnl4010.py:186