c4002-python

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.

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

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:

# 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)

git clone https://github.com/nobudev7/c4002-python.git
cd c4002-python
pip install -e .

To include optional Raspberry Pi GPIO support:

pip install -e ".[gpio]"

Quick Start

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:

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:

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:

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:

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):

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:

Running Unit Tests

Unit tests run without physical hardware using recorded raw telemetry packets:

# 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)
• DFRobot Official Arduino C4002 Library

License

This project is licensed under the MIT License.