c4002-python 0.2.0__tar.gz

c4002_python-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build
+
+      - name: Build distribution packages
+        run: python -m build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Required for OIDC Trusted Publisher
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

c4002_python-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Test & Lint
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyserial pytest ruff
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/ examples/
+
+      - name: Run unit tests
+        run: |
+          PYTHONPATH=src pytest -v tests/

c4002_python-0.2.0/.gitignore

@@ -0,0 +1,221 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Mac
+.DS_Store

c4002_python-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nobu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

c4002_python-0.2.0/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.5
+Name: c4002-python
+Version: 0.2.0
+Summary: Unofficial Python driver and tools for DFRobot C4002 (SEN0691) 24GHz mmWave radar sensor
+Project-URL: Homepage, https://github.com/nobudev7/c4002-python
+Project-URL: Documentation, https://github.com/nobudev7/c4002-python#readme
+Project-URL: Issues, https://github.com/nobudev7/c4002-python/issues
+Project-URL: Repository, https://github.com/nobudev7/c4002-python.git
+Author: nobudev7
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware :: Hardware Drivers
+Requires-Python: >=3.8
+Requires-Dist: pyserial>=3.5
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: gpio
+Requires-Dist: rpi-gpio>=0.7.1; extra == 'gpio'
+Description-Content-Type: text/markdown
+
+# c4002-python
+
+[![Test & Lint](https://github.com/nobudev7/c4002-python/actions/workflows/test.yml/badge.svg)](https://github.com/nobudev7/c4002-python/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+Python driver and CLI tools for the **DFRobot C4002 (SEN0691) 24GHz mmWave Human Presence Detection Module**.
+
+Provides robust UART packet framing, real-time telemetry decoding (static presence, motion distance, speed, direction, ambient light), automated room background noise calibration, and optional digital OUT pin monitoring on Raspberry Pi and other Linux systems.
+
+---
+
+> [!IMPORTANT]
+> **Disclaimer**: This is an independent open-source library. It is not affiliated with, maintained by, or endorsed by DFRobot. All product names, logos, and brands are property of their respective owners.
+
+---
+
+![DFRobot C4002 mmWave Sensor](docs/images/c4002_sensor.jpeg)
+
+## Features
+
+* **Complete Telemetry Decoding**: Parses 32-byte binary notification frames from the C4002 sensor.
+  * **Static Presence**: Detects stationary humans (breathing, sitting) with distance (m) and signal energy (0–100).
+  * **Motion Tracking**: Measures distance (m), speed (m/s), signal energy (0–100), and direction (Approaching / Away).
+  * **Ambient Light**: Decodes onboard light sensor intensity (Lux).
+  * **Gate Bitmasks & Hold Timers**: Reports active distance gates and presence disappearance countdown.
+* **Auto Environmental Calibration**: Built-in routine to sample room reflections and store the background noise floor, preventing false triggers.
+* **Reliable Checksum Verification**: Validates 16-bit packet checksums to reject corrupted data.
+* **Hardware Agnostic**: Tested on Raspberry Pi Zero W, but works with any Raspberry Pi and standard USB-to-UART TTL serial converter on Linux, macOS, or Windows.
+* **Optional GPIO Monitoring**: Support for the module's digital OUT pin via `RPi.GPIO` (falls back gracefully if GPIO is unavailable).
+
+---
+
+## Hardware Wiring
+
+The C4002 operates at **3.6V – 5.5V** with **3.3V TTL UART logic**. It can be powered directly from the Raspberry Pi 5V power rail.
+
+<!-- ![Raspberry Pi Wiring Diagram](docs/images/wiring_diagram.png) -->
+```
+  Raspberry Pi GPIO Header                  DFRobot C4002
+ ┌─────────────────────────┐               ┌─────────────┐
+ │ Pin 2  [5V]             ├───────────────┤ VIN         │
+ │ Pin 6  [GND]            ├───────────────┤ GND         │
+ │ Pin 8  [GPIO 14 / TXD]  ├───────────────┤ RX          │
+ │ Pin 10 [GPIO 15 / RXD]  ├───────────────┤ TX          │
+ │ Pin 11 [GPIO 17]        ├───────────────┤ OUT (opt)   │
+ └─────────────────────────┘               └─────────────┘
+```
+
+### Pinout Table (Raspberry Pi 40-Pin Header)
+
+| C4002 Pin | Raspberry Pi Pin | Header Pin # | Description |
+| :--- | :--- | :--- | :--- |
+| **VIN** | 5V Power | Pin 2 or 4 | Power supply (3.6V – 5.5V) |
+| **GND** | Ground | Pin 6, 9, or 14 | Common ground |
+| **TX** | GPIO 15 (RXD0) | Pin 10 | Sensor TX $\rightarrow$ Pi RXD |
+| **RX** | GPIO 14 (TXD0) | Pin 8 | Sensor RX $\leftarrow$ Pi TXD |
+| **OUT** *(Optional)* | GPIO 17 | Pin 11 | Digital presence indicator (HIGH = presence) |
+
+
+### Raspberry Pi Serial Port Setup
+
+Ensure the hardware UART is enabled and the serial login console is disabled:
+
+1. Run `sudo raspi-config`
+2. Navigate to **Interface Options** $\rightarrow$ **Serial Port**
+3. "Would you like a login shell to be accessible over serial?" $\rightarrow$ Select **No**
+4. "Would you like the serial port hardware to be enabled?" $\rightarrow$ Select **Yes**
+5. Reboot the Raspberry Pi: `sudo reboot`
+
+The primary serial port will be accessible at `/dev/serial0`.
+
+---
+
+## Installation
+
+### Direct Install via pip (No git clone required)
+
+Install directly into your Python environment from GitHub:
+
+```bash
+# Standard installation
+pip install git+https://github.com/nobudev7/c4002-python.git
+
+# With optional Raspberry Pi GPIO support
+pip install "c4002-python[gpio] @ git+https://github.com/nobudev7/c4002-python.git"
+```
+
+### From Source (For Local Development)
+
+```bash
+git clone https://github.com/nobudev7/c4002-python.git
+cd c4002-python
+pip install -e .
+```
+
+To include optional Raspberry Pi GPIO support:
+
+```bash
+pip install -e ".[gpio]"
+```
+
+---
+
+## Quick Start
+
+```python
+import time
+from c4002 import C4002Sensor, TargetState
+
+# Initialize sensor on default serial port and optional GPIO 17
+sensor = C4002Sensor(port="/dev/serial0", baudrate=115200, out_pin=17)
+sensor.connect()
+
+try:
+    while True:
+        data = sensor.read_packet()
+        if data and not getattr(data, "is_calibrating", False):
+            print(f"State: {data.target_state_name} | Light: {data.ambient_light_lux} Lux")
+            if data.presence_detected:
+                print(f"  Presence: {data.presence_distance_m} m (Energy: {data.presence_energy}/100)")
+                if data.target_state == TargetState.MOTION:
+                    print(f"  Motion: {data.motion_distance_m} m at {data.motion_speed_m_s} m/s ({data.motion_direction_name})")
+        time.sleep(0.5)
+except KeyboardInterrupt:
+    sensor.close()
+```
+
+Using as a context manager:
+
+```python
+with C4002Sensor(port="/dev/serial0") as sensor:
+    data = sensor.read_packet()
+    if data:
+        print("Presence:", data.presence_detected)
+```
+
+---
+
+## Onboard LED Control (Dark / Stealth Mode)
+
+The C4002 module includes two onboard LEDs:
+* **Blue RUN LED**: Operation / power indicator (blinks or stays solid blue).
+* **OUT LED**: Detection indicator (lights up when presence/motion is detected).
+
+You can control or completely disable both LEDs via software over UART:
+
+```python
+from c4002 import C4002Sensor, LedMode
+
+with C4002Sensor(port="/dev/serial0") as sensor:
+    # Turn off both LEDs (stealth/bedroom mode)
+    sensor.turn_off_leds()
+
+    # Or control each LED individually:
+    sensor.set_run_led(False)       # Turn off blue RUN LED
+    sensor.set_out_led(False)       # Turn off detection OUT LED
+    sensor.set_run_led(True)        # Turn blue RUN LED back on
+    sensor.set_led(run_led=LedMode.OFF, out_led=LedMode.OFF)
+```
+
+In the example scripts, pass the `--led-off` flag:
+
+```bash
+python3 examples/basic_monitor.py --led-off
+python3 examples/minute_aggregator.py --led-off
+```
+
+> [!NOTE]
+> Like sensor detection thresholds, the LED state is stored in volatile memory on the radar module. When the sensor is power-cycled (power disconnected or Raspberry Pi rebooted), the module reverts to its hardware default (RUN LED ON). Call `turn_off_leds()` on startup in your script or daemon to ensure it stays dark.
+
+---
+
+## Environmental Background Noise Calibration
+
+
+Because 24GHz radar waves detect micro-movements, reflective objects (metal furniture, fans, moving curtains) can cause false presence triggers in an empty room. 
+
+The sensor features built-in automatic background noise calibration:
+
+```bash
+python3 examples/auto_calibrate.py
+```
+
+1. Run the script.
+2. Step out of the room within 10 seconds.
+3. Keep the room empty for 30 seconds while the sensor samples static background reflections and stores dynamic noise thresholds.
+
+---
+
+## 1-Minute Time-Series Logging (Aggregation)
+
+To log presence data into a CSV file for charting without missing transient movements (e.g., someone walking through the room for 10 seconds):
+
+```bash
+python3 examples/minute_aggregator.py --output presence_1min_timeseries.csv
+```
+
+* Samples sensor telemetry continuously at 1 Hz and aggregates into 1-minute rows.
+* Generates metrics ideal for charting:
+  * `occupancy_pct`: Occupancy percentage (`0.0% – 100.0%`) during the minute.
+  * `avg_distance_m`: Mean presence distance (calculated only when presence is active).
+  * `max_motion_energy`: Peak movement energy (`0 – 100`) recorded in that window.
+  * `avg_light_lux`: Mean ambient light level.
+
+---
+
+## Telemetry Data Reference
+
+`sensor.read_packet()` returns a `TelemetryData` object with the following attributes:
+
+| Attribute | Type | Unit / Range | Description |
+| :--- | :--- | :--- | :--- |
+| `target_state` | `TargetState` | Enum (`0`, `1`, `2`) | `NO_TARGET`, `STATIC_PRESENCE`, or `MOTION` |
+| `target_state_name` | `str` | String | Human-readable state name |
+| `presence_detected` | `bool` | `True` / `False` | `True` if state is presence or motion |
+| `ambient_light_lux` | `float` | Lux (0.0 – 6553.5) | Onboard ambient light intensity |
+| `presence_distance_m` | `float` | Meters | Distance to static presence target |
+| `presence_energy` | `int` | `0` – `100` | Reflected signal energy of static target |
+| `presence_countdown_s` | `int` | Seconds | Delay countdown before presence clears |
+| `motion_distance_m` | `float` | Meters | Distance to moving target |
+| `motion_speed_m_s` | `float` | m/s | Radial speed of moving target |
+| `motion_energy` | `int` | `0` – `100` | Reflected signal energy of motion target |
+| `motion_direction` | `MotionDirection` | Enum (`0`, `1`, `2`) | `AWAY`, `NO_DIRECTION`, or `APPROACHING` |
+| `gate_bitmask` | `int` | Bitmask | Bit flags representing active distance gates |
+
+---
+
+## Running Unit Tests
+
+Unit tests run without physical hardware using recorded raw telemetry packets:
+
+```bash
+# Using standard Python unittest
+PYTHONPATH=src python3 -m unittest discover -s tests -p "test_*.py"
+
+# Or using pytest (if installed)
+PYTHONPATH=src pytest -v tests/
+```
+
+---
+
+## References & Documentation
+
+* [DFRobot C4002 Product Wiki (SEN0691)](https://wiki.dfrobot.com/sen0691)
+* [DFRobot Official Arduino C4002 Library](https://github.com/DFRobot/DFRobot_C4002)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).