{"id":21150853,"url":"https://github.com/cedargrovestudios/circuitpython_shadowwatcher","last_synced_at":"2026-04-25T22:32:01.949Z","repository":{"id":62076315,"uuid":"551266688","full_name":"CedarGroveStudios/CircuitPython_ShadowWatcher","owner":"CedarGroveStudios","description":"A CircuitPython helper class to detect a shadow cast over an analog light sensor such as the ALS-PT19 phototransistor.","archived":false,"fork":false,"pushed_at":"2023-02-07T05:09:20.000Z","size":609,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-09T01:01:55.952Z","etag":null,"topics":["adafruit-pyportal","als-pt19","circuitpython","circuitpython-community-bundle","gesture-detection","light-sensor","phototransistor","shadow-detection"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CedarGroveStudios.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-14T05:10:27.000Z","updated_at":"2022-11-07T19:23:52.000Z","dependencies_parsed_at":"2023-02-19T14:46:03.509Z","dependency_job_id":null,"html_url":"https://github.com/CedarGroveStudios/CircuitPython_ShadowWatcher","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/CedarGroveStudios/CircuitPython_ShadowWatcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CedarGroveStudios%2FCircuitPython_ShadowWatcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CedarGroveStudios%2FCircuitPython_ShadowWatcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CedarGroveStudios%2FCircuitPython_ShadowWatcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CedarGroveStudios%2FCircuitPython_ShadowWatcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CedarGroveStudios","download_url":"https://codeload.github.com/CedarGroveStudios/CircuitPython_ShadowWatcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CedarGroveStudios%2FCircuitPython_ShadowWatcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32279652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["adafruit-pyportal","als-pt19","circuitpython","circuitpython-community-bundle","gesture-detection","light-sensor","phototransistor","shadow-detection"],"created_at":"2024-11-20T10:09:01.200Z","updated_at":"2026-04-25T22:32:01.932Z","avatar_url":"https://github.com/CedarGroveStudios.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Introduction\n============\n\n\n\n\n.. image:: https://img.shields.io/discord/327254708534116352.svg\n    :target: https://adafru.it/discord\n    :alt: Discord\n\n\n.. image:: https://github.com/CedarGroveStudios/CircuitPython_ShadowWatcher/workflows/Build%20CI/badge.svg\n    :target: https://github.com/CedarGroveStudios/CircuitPython_ShadowWatcher/actions\n    :alt: Build Status\n\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/psf/black\n    :alt: Code Style: Black\n\nA CircuitPython helper class to detect a shadow cast over an analog light sensor\nsuch as the ALS-PT19 phototransistor.\n\nShadowWatcher is a CircuitPython helper class to detect a shadow cast over an\nanalog light sensor such as the ALS-PT19 phototransistor used in the Adafruit\nPyPortal, PyGamer, PyBadge, CircuitPlayground Express, CircuitPlayground\nBluefruit, and the ALS-PT19 breakout board. Incorporates a low-pass filter to\nreduce sensitivity to flickering light levels which may be caused by power line\nfrequency or light dimmer PWM passthrough. Useful as a simple gesture detector.\n\nDependencies\n=============\nThis driver depends on:\n\n* `Adafruit CircuitPython \u003chttps://github.com/adafruit/circuitpython\u003e`_\n\n* Analog light sensor hardware such as the ALS-PT19 phototransistor with an output value directly in proportion to the light intensity.\n\nThe ShadowWatcher was primarily built for and tested on the PyPortal, but\nshould be able to function reliably on other microcontrollers with similar\nsensors. The automatic samples mode will test the microcontroller's analog\nacquision latency and adjust the internal low-pass filter's sample size to\nmaintain the ~25 Hz cutoff frequency.\n\nPlease ensure all dependencies are available on the CircuitPython filesystem.\nThis is easily achieved by downloading\n`the Adafruit library and driver bundle \u003chttps://circuitpython.org/libraries\u003e`_\nor individual libraries can be installed using\n`circup \u003chttps://github.com/adafruit/circup\u003e`_.\n\nInstalling to a Connected CircuitPython Device with Circup\n==========================================================\n\nMake sure that you have ``circup`` installed in your Python environment.\nInstall it with the following command if necessary:\n\n.. code-block:: shell\n\n    pip3 install circup\n\nWith ``circup`` installed and your CircuitPython device connected use the\nfollowing command to install:\n\n.. code-block:: shell\n\n    circup install cedargrove_shadowwatcher\n\nOr the following command to update an existing version:\n\n.. code-block:: shell\n\n    circup update\n\nUsage Example\n=============\n\n.. code-block:: python\n\n    import board\n    import time\n    from shadowwatcher import ShadowWatcher\n    # Instantiate detector class and establish background level\n    gesture = ShadowWatcher(pin=board.LIGHT, auto=True)\n    while True:\n        if gesture.detect():\n            print(f\"SHADOW DETECTED\")\n            while gesture.detect():\n                # Wait until the shadow is gone\n                time.sleep(1)\n            # Rebaseline the background level\n            gesture.refresh_background()\n            print(f\"background: {gesture.background:6.0f}\")\n\nDocumentation\n=============\nAPI documentation for this library can be found on `Read the Docs \u003chttps://github.com/CedarGroveStudios/CircuitPython_ShadowWatcher/blob/main/media/pseudo_readthedocs_shadowwatcher.pdf\u003e`_.\n\nThe ShadowWatcher helper class was tested on the PyPortal, but should be able to\nfunction reliably on other microcontrollers with similar sensors. The automatic\nsamples mode will test the microcontroller's analog acquisition latency and\nadjust the internal low-pass filter's sample size to maintain the ~25 Hz cutoff\nfrequency.\n\nThe left oscilloscope image shows the sampled sensor light level value in a room\nwith a dimmed LED light source (yellow trace). Note that the primary frequency\nof the signal is 120Hz (purple frequency spectrum graph). The right image shows\nthe sampled sensor light level value after filtering.\n\n.. image:: https://github.com/CedarGroveStudios/CircuitPython_ShadowWatcher/blob/main/media/FIR_boxcar_filter_pyportal.png\n\nFor information on building library documentation, please check out\n`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/CedarGroveStudios/Cedargrove_CircuitPython_ShadowWatcher/blob/HEAD/CODE_OF_CONDUCT.md\u003e`_\nbefore contributing to help this project stay welcoming.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedargrovestudios%2Fcircuitpython_shadowwatcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedargrovestudios%2Fcircuitpython_shadowwatcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedargrovestudios%2Fcircuitpython_shadowwatcher/lists"}