{"id":15023507,"url":"https://github.com/adafruit/adafruit_circuitpython_apds9960","last_synced_at":"2025-10-03T04:31:26.250Z","repository":{"id":28055331,"uuid":"116050026","full_name":"adafruit/Adafruit_CircuitPython_APDS9960","owner":"adafruit","description":"Adafruit Bundle driver for APSD9960 Gesture breakout board","archived":false,"fork":true,"pushed_at":"2025-06-17T16:08:30.000Z","size":203,"stargazers_count":12,"open_issues_count":0,"forks_count":18,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-09-30T06:53:11.491Z","etag":null,"topics":["circuitpython","hacktoberfest"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"mrmcwethy/Adafruit_CircuitPython_APDS9960","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adafruit.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-01-02T19:35:34.000Z","updated_at":"2025-06-17T15:25:31.000Z","dependencies_parsed_at":"2023-02-12T00:01:20.948Z","dependency_job_id":"889ab975-3298-4d79-8d38-57d5b20bfe34","html_url":"https://github.com/adafruit/Adafruit_CircuitPython_APDS9960","commit_stats":{"total_commits":130,"total_committers":24,"mean_commits":5.416666666666667,"dds":0.8384615384615385,"last_synced_commit":"cd01e25e0008eefb31a50539f32b1021f109f5e7"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/adafruit/Adafruit_CircuitPython_APDS9960","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2FAdafruit_CircuitPython_APDS9960","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2FAdafruit_CircuitPython_APDS9960/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2FAdafruit_CircuitPython_APDS9960/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2FAdafruit_CircuitPython_APDS9960/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adafruit","download_url":"https://codeload.github.com/adafruit/Adafruit_CircuitPython_APDS9960/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2FAdafruit_CircuitPython_APDS9960/sbom","scorecard":{"id":164238,"data":{"date":"2025-08-11","repo":{"name":"github.com/adafruit/Adafruit_CircuitPython_APDS9960","commit":"00127a75d22f035096ea9317ad57c74c6a9b4232"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.1,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"1 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":0,"reason":"Found 2/24 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/build.yml:1","Warn: no topLevel permission defined: .github/workflows/failure-help-text.yml:1","Warn: no topLevel permission defined: .github/workflows/release_gh.yml:1","Warn: no topLevel permission defined: .github/workflows/release_pypi.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/build.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/adafruit/Adafruit_CircuitPython_APDS9960/build.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/failure-help-text.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/adafruit/Adafruit_CircuitPython_APDS9960/failure-help-text.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release_gh.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/adafruit/Adafruit_CircuitPython_APDS9960/release_gh.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release_pypi.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/adafruit/Adafruit_CircuitPython_APDS9960/release_pypi.yml/main?enable=pin","Info:   0 out of   4 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact 3.1.16 not signed: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/225917778","Warn: release artifact 3.1.15 not signed: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/218368751","Warn: release artifact 3.1.14 not signed: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/196962850","Warn: release artifact 3.1.13 not signed: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/195193317","Warn: release artifact 3.1.12 not signed: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/178779391","Warn: release artifact 3.1.16 does not have provenance: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/225917778","Warn: release artifact 3.1.15 does not have provenance: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/218368751","Warn: release artifact 3.1.14 does not have provenance: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/196962850","Warn: release artifact 3.1.13 does not have provenance: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/195193317","Warn: release artifact 3.1.12 does not have provenance: https://api.github.com/repos/adafruit/Adafruit_CircuitPython_APDS9960/releases/178779391"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 10 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-16T14:23:17.511Z","repository_id":28055331,"created_at":"2025-08-16T14:23:17.511Z","updated_at":"2025-08-16T14:23:17.511Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278113373,"owners_count":25932120,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-03T02:00:06.070Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circuitpython","hacktoberfest"],"created_at":"2024-09-24T19:59:08.363Z","updated_at":"2025-10-03T04:31:26.244Z","avatar_url":"https://github.com/adafruit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nIntroduction\n============\n\n.. image:: https://readthedocs.org/projects/adafruit-circuitpython-apds9960/badge/?version=latest\n    :target: https://docs.circuitpython.org/projects/apds9960/en/latest/\n    :alt: Documentation Status\n\n.. image:: https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg\n    :target: https://adafru.it/discord\n    :alt: Discord\n\n.. image:: https://github.com/adafruit/Adafruit_CircuitPython_APDS9960/workflows/Build%20CI/badge.svg\n    :target: https://github.com/adafruit/Adafruit_CircuitPython_APDS9960/actions/\n    :alt: Build Status\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n    :target: https://github.com/astral-sh/ruff\n    :alt: Code Style: Ruff\n\nThe APDS-9960 is a specialized chip that detects hand gestures, proximity\nand ambient light color over I2C. Its available from\n`Adafruit as a breakout \u003chttps://www.adafruit.com/product/3595\u003e`_ and as a built-in sensor on\nseveral Adafruit development boards.\n\n* `Adafruit CLUE \u003chttps://www.adafruit.com/product/4500\u003e`_\n* `Adafruit Feather nRF52840 Sense \u003chttps://www.adafruit.com/product/4516\u003e`_\n* `Adafruit Proximity Trinkey \u003chttps://www.adafruit.com/product/5022\u003e`_\n\nThis driver provides easy access to proximity, gesture and color data from the APDS-9960 sensor\nwith a minimal footprint to allow it to work on all CircuitPython platforms.\n\nInstallation and Dependencies\n=============================\nThis driver depends on:\n\n* `Adafruit CircuitPython \u003chttps://github.com/adafruit/circuitpython\u003e`_\n\nPlease ensure all dependencies are available on the CircuitPython filesystem.\n\nThis is easily achieved by downloading\n`the Adafruit library and driver bundle \u003chttps://github.com/adafruit/Adafruit_CircuitPython_Bundle\u003e`_.\n\nInstalling from PyPI\n--------------------\n\nOn supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from PyPI \u003chttps://pypi.org/project/adafruit-circuitpython-apds9960/\u003e`_.\n\nTo install for current user:\n\n.. code-block:: shell\n\n    pip3 install adafruit-circuitpython-apds9960\n\nTo install system-wide (this may be required in some cases):\n\n.. code-block:: shell\n\n    sudo pip3 install adafruit-circuitpython-apds9960\n\nTo install in a virtual environment in your current project:\n\n.. code-block:: shell\n\n    mkdir project-name \u0026\u0026 cd project-name\n    python3 -m venv .venv\n    source .venv/bin/activate\n    pip3 install adafruit-circuitpython-apds9960\n\nUsage Example\n=============\n\n.. code-block:: python3\n\n    import board\n    import digitalio\n    from adafruit_apds9960.apds9960 import APDS9960\n\n    i2c = board.I2C()\n    int_pin = digitalio.DigitalInOut(board.D5)\n    int_pin.switch_to_input(pull=digitalio.Pull.UP)\n    apds = APDS9960(i2c)\n\n    apds.enable_proximity_interrupt = True\n    apds.proximity_interrupt_threshold = (0, 175)\n    apds.enable_proximity = True\n\n    while True:\n        if not int_pin.value:\n            print(apds.proximity)\n            apds.clear_interrupt()\n\nHardware Set-up\n---------------\n\nIf you're using a board with a built-in APDS-9960, no hardware setup will be required.\n\nIf you're using a breakout board via the pin header, connect ``Vin`` to a 3.3 V or 5 V power source,\nconnect ``GND`` to ground, then connect ``SCL`` and ``SDA`` to the appropriate pins.\n\nOptionally, if you'd like to use the sensor's interrupt pin connect ``INT`` to any available\ndigital I/O pin.\n\nBasics\n------\n\nTo get started, import ``board`` and, and this library:\n\n.. code:: python3\n\n\n    import board\n    from adafruit_apds9960.apds9960 import APDS9960\n\nTo set up the sensor to gather data, initialize the I2C bus via ``board.I2C()``\nthen initialize the APDS-9960 library.\n\n.. code:: python3\n\n    i2c = board.I2C()\n    apds = APDS9960(i2c)\n\nProximity\n---------\n\nTo get a proximity result, enable the proximity engine then read the `proximity` value.\n\nThis will return a value between 0 and 255, with higher values indicating that something is close\nto the sensor.\n\n.. code:: python3\n\n    apds.enable_proximity = True\n\n    while True:\n      print(apds.proximity)\n\nGestures\n--------\n\nFirst, enable both the proximity and gesture engines. The gesture engine relies on the proximity\nengine to determine when to start itself up and, as a result, proximity readings won't be reliable\nwhile the gesture engine is enabled.\n\nTo get a gesture, use the `gesture()` function to see if a gesture has been detected. If a value\ngreater than 0 is returned, a gesture has been detected.\n\n.. code:: python3\n\n    # Uncomment and set the rotation if depending on how your sensor is mounted.\n    # apds.rotation = 270 # 270 for CLUE\n\n    apds.enable_proximity = True\n    apds.enable_gesture = True\n\n    while True:\n      gesture = apds.gesture()\n      if gesture == 1:\n        print(\"up\")\n      if gesture == 2:\n        print(\"down\")\n      if gesture == 3:\n        print(\"left\")\n      if gesture == 4:\n        print(\"right\")\n\nColor/Light Measurement\n-----------------------\n\nTo get a color measurement, first enable the color/light engine, wait for color data to arrive,\nthen read the `color_data` values.\n\n.. code:: python3\n\n    apds.enable_color = True\n\n    while True:\n        while not apds.color_data_ready:\n            time.sleep(0.005)\n\n        r, g, b, c = apds.color_data\n        print(\"r: {}, g: {}, b: {}, c: {}\".format(r, g, b, c))\n\nInterrupt Pin\n-------------\n\nThis sensor has an interrupt pin can be asserted (pulled low) if proximity is detected outside of a\nspecified window of values.\n\nFor boards with a built-in APDS-9960 this interupt pin will already be defined. For example, on the\nClue and Feather nRF52840 Sense boards this pin is mapped to ``board.PROXIMITY_LIGHT_INTERRUPT``\nand on the Proximity Trinkey it is mapped to ``board.INTERRUPT``.\n\n.. code:: python3\n\n    int_pin = digitalio.DigitalInOut(board.D5)\n    int_pin.switch_to_input(pull=digitalio.Pull.UP)\n\nProximity Detection\n-------------------\n\nWith the interrupt pin set up we can define a threshold and enable the assertion of the sensor's\ninterrupt pin by the proximity engine before enabling the proximity engine itself.\n\nIn this configuration, the sensor's interrupt pin will be asserted when an object is close to the\nsensor. After checking on the interrupt it can be cleared using `clear_interrupt()`\n\n.. code:: python3\n\n    apds.enable_proximity = True\n\n    # set the interrupt threshold to fire when proximity reading goes above 175\n    apds.proximity_interrupt_threshold = (0, 175)\n\n    # assert interrupt pin on internal proximity interrupt\n    apds.enable_proximity_interrupt = True\n\n    # enable the sensor's proximity engine\n    apds.enable_proximity = True\n\n    while True:\n      if not interrupt_pin.value:\n        print(apds.proximity)\n\n        # clear the interrupt\n        apds.clear_interrupt()\n\nInitiaization Options\n----------------------\n\nBy default, when the driver is initialized, the APDS-9960 sensor's internal settings are reset and\nsensible defaults are applied to several low-level settings that should work well for most use cases.\n\nIf either the \"reset\" or \"set defaults\" behaviors (or both) aren't desired, they can be individually\ndisabled via init kwargs.\n\n.. code:: python3\n\n    apds = APDS9960(i2c, reset=False, set_defaults=False)\n\nDocumentation\n=============\n\nAPI documentation for this library can be found on `Read the Docs \u003chttps://docs.circuitpython.org/projects/apds9960/en/latest/\u003e`_.\n\nFor information on building library documentation, please check out `this guide \u003chttps://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1\u003e`_.\n\nContributing\n============\n\nContributions are welcome! Please read our `Code of Conduct\n\u003chttps://github.com/adafruit/Adafruit_CircuitPython_APDS9960/blob/main/CODE_OF_CONDUCT.md\u003e`_\nbefore contributing to help this project stay welcoming.\n\nBuilding locally\n================\n\nTo build this library locally you'll need to install the\n`circuitpython-travis-build-tools \u003chttps://github.com/adafruit/circuitpython-build-tools\u003e`_ package.\n\n.. code-block::shell\n\n    python3 -m venv .venv\n    source .venv/bin/activate\n    pip install -r requirements.txt\n\nOnce installed, make sure you are in the virtual environment:\n\n.. code-block::shell\n\n    source .venv/bin/activate\n\nThen run the build:\n\n.. code-block::shell\n\n    circuitpython-build-bundles --filename_prefix adafruit-circuitpython-apds --library_location .\n\nSphinx documentation\n-----------------------\n\nSphinx is used to build the documentation based on rST files and comments in the code. First,\ninstall dependencies (feel free to reuse the virtual environment from above):\n\n.. code-block:: shell\n\n    python3 -m venv .venv\n    source .venv/bin/activate\n    pip install Sphinx sphinx-rtd-theme\n\nNow, once you have the virtual environment activated:\n\n.. code-block:: shell\n\n    cd docs\n    sphinx-build -E -W -b html . _build/html\n\nThis will output the documentation to ``docs/_build/html``. Open the index.html in your browser to\nview them. It will also (due to -W) error out on any warning like Travis will. This is a good way to\nlocally verify it will pass.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadafruit%2Fadafruit_circuitpython_apds9960","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadafruit%2Fadafruit_circuitpython_apds9960","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadafruit%2Fadafruit_circuitpython_apds9960/lists"}