c4002-python 0.2.0__py3-none-any.whl

c4002/__init__.py

@@ -0,0 +1,33 @@
+"""
+c4002-python — Python library for DFRobot C4002 24GHz mmWave radar sensor.
+
+DISCLAIMER:
+This is an independent, community-developed open-source library.
+It is not affiliated with, maintained by, or endorsed by DFRobot.
+"""
+
+from c4002.constants import (
+    LED_KEEP,
+    LED_OFF,
+    LED_ON,
+    LedMode,
+    MotionDirection,
+    ResolutionMode,
+    TargetState,
+)
+from c4002.sensor import C4002Sensor, CalibrationStatus, TelemetryData
+
+__version__ = "0.2.0"
+__all__ = [
+    "LED_KEEP",
+    "LED_OFF",
+    "LED_ON",
+    "C4002Sensor",
+    "CalibrationStatus",
+    "LedMode",
+    "MotionDirection",
+    "ResolutionMode",
+    "TargetState",
+    "TelemetryData",
+]
+

c4002/constants.py

@@ -0,0 +1,99 @@
+"""
+Constants for DFRobot C4002 (SEN0691) 24GHz mmWave radar sensor.
+
+DISCLAIMER:
+This is an unofficial, community-developed driver and is not affiliated
+with, maintained by, or endorsed by DFRobot.
+"""
+
+from enum import IntEnum
+
+# Frame Header sequence: 0xFA 0xF5 0xAA 0xA5
+FRAME_HEADER_BYTES = bytes([0xFA, 0xF5, 0xAA, 0xA5])
+
+# Frame Types
+FRAME_TYPE_WRITE_REQUEST = 0x00
+FRAME_TYPE_READ_REQUEST = 0x01
+FRAME_TYPE_WRITE_RESPOND = 0x02
+FRAME_TYPE_READ_RESPOND = 0x03
+FRAME_TYPE_NOTIFICATION = 0x04
+
+# Command IDs
+CMD_RESTART = 0x00
+CMD_FACTORY_RESET = 0x80
+CMD_GET_VERSION = 0x82
+CMD_SET_REPORT_PERIOD = 0x83
+CMD_SET_TARGET_DISAPPEAR_DELAY = 0x84
+CMD_SET_DETECT_RANGE = 0x86
+CMD_SET_LIGHT_THRESHOLD = 0x88
+CMD_CONFIG_OUT_MODE = 0xA0
+CMD_SET_LED_MODE = 0xA1
+CMD_ENV_CALIBRATION = 0x60
+CMD_SET_DISTANCE_DOOR = 0x62
+CMD_SET_DISTANCE_DOOR_THRESHOLD = 0x63
+CMD_GET_AND_SET_RESOLUTION_MODE = 0x66
+
+# Notification Sub-Commands
+NOTE_RESULT_CMD = 0x60
+NOTE_CALIBRATION_CMD = 0x03
+
+# Response Status Codes
+RESP_SUCCEED = 0x01
+RESP_CMD_ERR = 0x02
+RESP_AUTH_ERR = 0x03
+RESP_BUSY = 0x04
+RESP_PARAMS_ERR = 0x05
+RESP_DATA_LEN_ERR = 0x06
+RESP_INTERNAL_ERR = 0x07
+
+
+class TargetState(IntEnum):
+    """Detection state of the target."""
+    NO_TARGET = 0
+    STATIC_PRESENCE = 1
+    MOTION = 2
+
+    @property
+    def label(self) -> str:
+        labels = {
+            TargetState.NO_TARGET: "No Target",
+            TargetState.STATIC_PRESENCE: "Static Presence (Sitting/Breathing)",
+            TargetState.MOTION: "Motion Detected",
+        }
+        return labels.get(self, "Unknown")
+
+
+class MotionDirection(IntEnum):
+    """Direction of moving target relative to the sensor."""
+    AWAY = 0
+    NO_DIRECTION = 1
+    APPROACHING = 2
+
+    @property
+    def label(self) -> str:
+        labels = {
+            MotionDirection.AWAY: "Moving Away",
+            MotionDirection.NO_DIRECTION: "Stationary / No Direction",
+            MotionDirection.APPROACHING: "Approaching",
+        }
+        return labels.get(self, "Unknown")
+
+
+class ResolutionMode(IntEnum):
+    """Distance gate resolution mode."""
+    RESOLUTION_80CM = 0x00  # Up to 15 gates, max 11.6m
+    RESOLUTION_20CM = 0x01  # Up to 25 gates, max 4.9m
+
+
+class LedMode(IntEnum):
+    """LED operating mode for C4002 onboard LEDs."""
+    OFF = 0x00
+    ON = 0x01
+    KEEP = 0xFF
+
+
+# Convenience aliases
+LED_OFF = LedMode.OFF
+LED_ON = LedMode.ON
+LED_KEEP = LedMode.KEEP
+

c4002/sensor.py

@@ -0,0 +1,380 @@
+"""
+Driver for DFRobot C4002 (SEN0691) 24GHz mmWave radar sensor.
+
+DISCLAIMER:
+This is an independent, unofficial community-developed Python library.
+It is not affiliated with, maintained by, or endorsed by DFRobot.
+"""
+
+from __future__ import annotations
+
+import logging
+import struct
+import time
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    import serial
+except ImportError:
+    serial = None  # type: ignore
+
+try:
+    from RPi import GPIO
+    HAS_GPIO = True
+except (ImportError, RuntimeError):
+    HAS_GPIO = False
+
+from c4002.constants import (
+    CMD_ENV_CALIBRATION,
+    CMD_SET_DETECT_RANGE,
+    CMD_SET_LED_MODE,
+    CMD_SET_REPORT_PERIOD,
+    CMD_SET_TARGET_DISAPPEAR_DELAY,
+    FRAME_HEADER_BYTES,
+    FRAME_TYPE_NOTIFICATION,
+    FRAME_TYPE_WRITE_REQUEST,
+    NOTE_CALIBRATION_CMD,
+    NOTE_RESULT_CMD,
+    LedMode,
+    MotionDirection,
+    TargetState,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TelemetryData:
+    """Parsed sensor telemetry frame."""
+    target_state: TargetState
+    target_state_name: str
+    presence_detected: bool
+    ambient_light_lux: float
+    gate_bitmask: int
+    presence_countdown_s: int
+    presence_distance_m: float
+    presence_energy: int
+    motion_distance_m: float
+    motion_speed_m_s: float
+    motion_energy: int
+    motion_direction: MotionDirection
+    motion_direction_name: str
+
+
+@dataclass
+class CalibrationStatus:
+    """Status during environmental background noise calibration."""
+    is_calibrating: bool
+    countdown_s: int
+
+
+class C4002Sensor:
+    """
+    Python interface for DFRobot C4002 mmWave Human Presence Module (SEN0691).
+
+    Communicates via 115200 baud UART and optional digital GPIO OUT pin.
+    """
+
+    def __init__(
+        self,
+        port: str = "/dev/serial0",
+        baudrate: int = 115200,
+        out_pin: int | None = None,
+        timeout: float = 1.0,
+    ) -> None:
+        """
+        Initialize the sensor instance.
+
+        :param port: UART serial port path (default '/dev/serial0' for Raspberry Pi)
+        :param baudrate: Serial baud rate (default 115200)
+        :param out_pin: BCM GPIO pin number connected to C4002 OUT pin (None to disable)
+        :param timeout: Serial read timeout in seconds
+        """
+        self.port = port
+        self.baudrate = baudrate
+        self.out_pin = out_pin
+        self.timeout = timeout
+        self.ser: Any = None
+
+        if self.out_pin is not None:
+            if not HAS_GPIO:
+                logger.warning(
+                    "RPi.GPIO is not available in this environment. OUT pin monitoring disabled."
+                )
+                self.out_pin = None
+            else:
+                GPIO.setwarnings(False)
+                GPIO.setmode(GPIO.BCM)
+                GPIO.setup(self.out_pin, GPIO.IN, pull_up_down=GPIO.PUD_DOWN)
+
+    def connect(self) -> None:
+        """Open the serial port connection."""
+        if serial is None:
+            raise ImportError(
+                "pyserial is required to connect to hardware. Install it via: pip install pyserial"
+            )
+        self.ser = serial.Serial(self.port, self.baudrate, timeout=self.timeout)
+        self.ser.flushInput()
+        logger.info("Connected to C4002 on %s at %d baud", self.port, self.baudrate)
+
+    def close(self) -> None:
+        """Close serial port and clean up GPIO resources."""
+        if self.ser and hasattr(self.ser, "is_open") and self.ser.is_open:
+            self.ser.close()
+            logger.info("Closed serial port %s", self.port)
+        if self.out_pin is not None and HAS_GPIO:
+            GPIO.cleanup(self.out_pin)
+
+    def __enter__(self) -> C4002Sensor:
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def read_out_pin(self) -> bool | None:
+        """
+        Read the digital OUT pin if configured.
+        :return: True if HIGH (presence detected), False if LOW (clear), or None if unconfigured.
+        """
+        if self.out_pin is not None and HAS_GPIO:
+            return GPIO.input(self.out_pin) == GPIO.HIGH
+        return None
+
+    @staticmethod
+    def verify_checksum(packet: bytes) -> bool:
+        """
+        Validate packet checksum: sum of bytes [0..N-3] & 0xFFFF == uint16 LE at [N-2..N-1].
+        """
+        if len(packet) < 8:
+            return False
+        calc = sum(packet[:-2]) & 0xFFFF
+        recv = packet[-2] | (packet[-1] << 8)
+        return calc == recv
+
+    @classmethod
+    def parse_packet(cls, packet: bytes) -> TelemetryData | CalibrationStatus | None:
+        """
+        Parse a raw binary frame without requiring an open serial port.
+
+        Frame Layout (32 bytes standard notification):
+          [0..3]   Header (FA F5 AA A5)
+          [4..5]   Total length (uint16 LE)
+          [6]      Reserved (0x00)
+          [7]      Pack type (0x04 = Notification)
+          [8]      Command ID (0x60 = Result, 0x03 = Calibration)
+          [9]      Response code (0x01 = Success)
+          [10..11] Inner data length (uint16 LE)
+          [12..N]  Payload
+          [N+1..]  Checksum (uint16 LE)
+        """
+        if len(packet) < 14:
+            return None
+        if not packet.startswith(FRAME_HEADER_BYTES):
+            return None
+        if not cls.verify_checksum(packet):
+            logger.debug("Packet checksum mismatch")
+            return None
+
+        pack_type = packet[7]
+        cmd = packet[8]
+
+        # Normal detection notification (type 0x04, cmd 0x60)
+        if pack_type == FRAME_TYPE_NOTIFICATION and cmd == NOTE_RESULT_CMD:
+            payload = packet[12:-2]
+            if len(payload) < 18:
+                return None
+
+            status_val = payload[0]
+            light_raw = payload[1] | (payload[2] << 8)
+            gate_bitmask = payload[3] | (payload[4] << 8) | (payload[5] << 16) | (payload[6] << 24)
+            countdown = payload[7] | (payload[8] << 8)
+            pres_dist_cm = payload[9] | (payload[10] << 8)
+            pres_energy = payload[11]
+            motion_dist_cm = payload[12] | (payload[13] << 8)
+            motion_speed_raw = struct.unpack('<h', bytes([payload[14], payload[15]]))[0]
+            motion_energy = payload[16]
+            motion_dir_val = payload[17]
+
+            target_state = TargetState(status_val) if status_val in TargetState._value2member_map_ else TargetState.NO_TARGET
+            direction = MotionDirection(motion_dir_val) if motion_dir_val in MotionDirection._value2member_map_ else MotionDirection.NO_DIRECTION
+
+            return TelemetryData(
+                target_state=target_state,
+                target_state_name=target_state.label,
+                presence_detected=target_state != TargetState.NO_TARGET,
+                ambient_light_lux=round(light_raw * 0.1, 1),
+                gate_bitmask=gate_bitmask,
+                presence_countdown_s=countdown,
+                presence_distance_m=round(pres_dist_cm * 0.01, 2),
+                presence_energy=pres_energy,
+                motion_distance_m=round(motion_dist_cm * 0.01, 2),
+                motion_speed_m_s=round(motion_speed_raw * 0.01, 2),
+                motion_energy=motion_energy,
+                motion_direction=direction,
+                motion_direction_name=direction.label,
+            )
+
+        # Environmental calibration progress notification (cmd 0x03)
+        if pack_type == FRAME_TYPE_NOTIFICATION and cmd == NOTE_CALIBRATION_CMD:
+            countdown = packet[12] | (packet[13] << 8)
+            return CalibrationStatus(is_calibrating=True, countdown_s=countdown)
+
+        return None
+
+    def read_packet(self) -> TelemetryData | CalibrationStatus | None:
+        """
+        Synchronously synchronize to the next frame header and read the full packet.
+        :return: TelemetryData, CalibrationStatus, or None on timeout.
+        """
+        if not self.ser or not hasattr(self.ser, "is_open") or not self.ser.is_open:
+            raise RuntimeError("Serial port is not connected. Call connect() first.")
+
+        header_buf = bytearray()
+        start = time.time()
+
+        # Synchronize to 4-byte header
+        while len(header_buf) < 4:
+            if time.time() - start > self.timeout:
+                return None
+            b = self.ser.read(1)
+            if not b:
+                continue
+            header_buf.append(b[0])
+            if len(header_buf) == 4 and bytes(header_buf) != FRAME_HEADER_BYTES:
+                header_buf.pop(0)
+
+        # Read 2-byte total length
+        len_bytes = self.ser.read(2)
+        if len(len_bytes) < 2:
+            return None
+        total_len = len_bytes[0] | (len_bytes[1] << 8)
+
+        if total_len < 14 or total_len > 128:
+            return None
+
+        # Read remaining packet body
+        remaining_len = total_len - 6
+        remaining = self.ser.read(remaining_len)
+        if len(remaining) < remaining_len:
+            return None
+
+        full_packet = bytes(header_buf + len_bytes + remaining)
+        return self.parse_packet(full_packet)
+
+    def start_env_calibration(self, delay_time: int = 10, cont_time: int = 30) -> None:
+        """
+        Trigger automatic environmental background noise calibration.
+        :param delay_time: Seconds before calibration starts (0-65535s)
+        :param cont_time: Duration of background measurement (15-65535s)
+        """
+        data = [
+            CMD_ENV_CALIBRATION,
+            0x00,               # Read/Write request
+            0x09, 0x00,         # Data length
+            delay_time & 0xFF, (delay_time >> 8) & 0xFF,
+            cont_time & 0xFF, (cont_time >> 8) & 0xFF,
+            0x01
+        ]
+        self._send_frame(data, 9, FRAME_TYPE_WRITE_REQUEST)
+
+    def set_report_period(self, period_100ms: int = 10) -> None:
+        """
+        Set sensor telemetry report period in units of 100ms (10 = 1.0s).
+        """
+        data = [
+            CMD_SET_REPORT_PERIOD,
+            0x00,
+            0x05, 0x00,
+            period_100ms & 0xFF
+        ]
+        self._send_frame(data, 5, FRAME_TYPE_WRITE_REQUEST)
+
+    def set_detect_range(self, closest_cm: int = 0, farthest_cm: int = 1100) -> None:
+        """
+        Set minimum and maximum detection range in centimeters (0 - 1100 cm).
+        """
+        farthest = min(max(farthest_cm, 0), 1100)
+        closest = max(closest_cm, 0)
+        data = [
+            CMD_SET_DETECT_RANGE,
+            0x00,
+            0x08, 0x00,
+            closest & 0xFF, (closest >> 8) & 0xFF,
+            farthest & 0xFF, (farthest >> 8) & 0xFF
+        ]
+        self._send_frame(data, 8, FRAME_TYPE_WRITE_REQUEST)
+
+    def set_target_disappear_delay(self, delay_s: int = 1) -> None:
+        """
+        Set delay time in seconds before reporting target disappearance (0 - 65535s).
+        """
+        data = [
+            CMD_SET_TARGET_DISAPPEAR_DELAY,
+            0x00,
+            0x06, 0x00,
+            delay_s & 0xFF, (delay_s >> 8) & 0xFF
+        ]
+        self._send_frame(data, 6, FRAME_TYPE_WRITE_REQUEST)
+
+    def set_led(
+        self,
+        run_led: int | bool = LedMode.OFF,
+        out_led: int | bool = LedMode.OFF,
+    ) -> None:
+        """
+        Configure the onboard RUN (operation) and OUT (detection) LEDs.
+
+        :param run_led: LedMode.OFF (or False), LedMode.ON (or True), or LedMode.KEEP
+        :param out_led: LedMode.OFF (or False), LedMode.ON (or True), or LedMode.KEEP
+        """
+        run_val = int(run_led)
+        out_val = int(out_led)
+        data = [
+            CMD_SET_LED_MODE,
+            0x00,  # Read/Write request
+            0x06, 0x00,  # Data length = 6
+            run_val & 0xFF,
+            out_val & 0xFF,
+        ]
+        self._send_frame(data, 6, FRAME_TYPE_WRITE_REQUEST)
+
+    def set_run_led(self, state: int | bool) -> None:
+        """
+        Configure the onboard blue RUN (operation/power) LED.
+
+        :param state: LedMode.OFF (False) or LedMode.ON (True)
+        """
+        self.set_led(run_led=state, out_led=LedMode.KEEP)
+
+    def set_out_led(self, state: int | bool) -> None:
+        """
+        Configure the onboard OUT (detection indicator) LED.
+
+        :param state: LedMode.OFF (False) or LedMode.ON (True)
+        """
+        self.set_led(run_led=LedMode.KEEP, out_led=state)
+
+    def turn_off_leds(self) -> None:
+        """Convenience method to turn off both onboard LEDs (stealth/dark mode)."""
+        self.set_led(run_led=LedMode.OFF, out_led=LedMode.OFF)
+
+
+    def _send_frame(self, data: list[int], data_len: int, msg_type: int) -> None:
+        """Internal helper to construct and transmit a validated command frame."""
+        total_len = data_len + 10
+        frame = bytearray([
+            FRAME_HEADER_BYTES[0], FRAME_HEADER_BYTES[1],
+            FRAME_HEADER_BYTES[2], FRAME_HEADER_BYTES[3],
+            total_len & 0xFF, (total_len >> 8) & 0xFF,
+            0x00, msg_type
+        ])
+        frame.extend(data)
+        checksum = sum(frame) & 0xFFFF
+        frame.append(checksum & 0xFF)
+        frame.append((checksum >> 8) & 0xFF)
+
+        if self.ser and hasattr(self.ser, "is_open") and self.ser.is_open:
+            self.ser.flushInput()
+            self.ser.write(frame)

c4002_python-0.2.0.dist-info/METADATA

@@ -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).

c4002_python-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+c4002/__init__.py,sha256=8cbtf-VUDyDl-Io9SdwA-cob649GYeHjGOCSlZFrj1k,670
+c4002/constants.py,sha256=awlRfUg6hRstLWV_SUHr-_vqqUQY50FwWUQQcyr3Ecs,2411
+c4002/sensor.py,sha256=-Q2GXvXkyV_MKJM6Ccxs06FZH7c3hVsc6W2Fa32FnnI,13165
+c4002_python-0.2.0.dist-info/METADATA,sha256=VnDVvKUp4WIZAN6rZEQT57w4isONGYx2Rcqj1Q8ZK0o,11511
+c4002_python-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+c4002_python-0.2.0.dist-info/licenses/LICENSE,sha256=zcx4XwMH4zmzm-lobER5pmZ5RvHuEjj3BHiUpIpzY7s,1061
+c4002_python-0.2.0.dist-info/RECORD,,

c4002_python-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

c4002_python-0.2.0.dist-info/licenses/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.