Overview

RPi + Rosmaster line-following and obstacle-avoidance car. The main loop is in src/main.py: the main thread handles camera capture and black-line detection, while a worker thread runs PID motion control, ultrasonic avoidance, health checks, and periodic MQTT telemetry publishing.

Highlights

• Black-line detection (picamera2 + OpenCV) to compute offset/angle and command lateral/yaw speeds.
• Rosmaster motion control: PID setup and ramped speed startup.
• Sensors: DHT temperature/humidity, INA219 power, battery voltage, IMU, encoders.
• Ultrasonic avoidance state machine (side-step → forward bypass → return).
• Health guard for low battery / CPU over-temp / suspected motor stall.
• CSV event/state logging (data/raw/events.csv) and rotating file logs (logs/app.log).
• MQTT telemetry publisher thread with configurable broker/topic/credentials.

Hardware & Python Dependencies

Hardware: Raspberry Pi (Pi 4/5 recommended), Hiwonder Rosmaster chassis, PiCam, DHT11/22, HC-SR04 (or similar ultrasonic), INA219, power module.

Python deps (pip install -r requirements.txt):

• Core: pyyaml, numpy, opencv-python
• Camera: picamera2 (installable on Raspberry Pi OS via sudo apt install python3-picamera2)
• Hardware: adafruit-blinka, adafruit-circuitpython-dht, adafruit-circuitpython-ina219, gpiozero
• Comms: paho-mqtt
• Other: Rosmaster_Lib (official chassis control lib), tests via pytest

Suggested setup on Raspberry Pi:

sudo apt update
sudo apt install -y python3-picamera2 libatlas-base-dev libopenblas-dev libhdf5-serial-dev \
    libilmbase-dev libopenexr-dev libgstreamer1.0-dev
python3 -m venv .venv && source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Configuration

Primary config: configs/default.yaml

• serial: serial port (auto to auto-detect), car type, comm delay, debug toggle.
• motion: initial speeds, limits, ramp time, line-follow speed.
• pid: motion PID gains and whether to persist to the controller.
• vision.line_follow: ROI height, thresholds, kernels, offset/angle gains, saturation/deadband.
• sensors: DHT type/GPIO, ultrasonic pins/trigger distance/cooldown, avoidance motion parameters.
• health: battery voltage floor, CPU temp ceiling, stall window, auto-shutdown.
• logging & post: log dir/level, power-on self-test thresholds.

Create additional YAML configs as needed and pass via --config.

Run

Activate your venv, then:

python -m src.main --config configs/default.yaml

• Starts MQTT publisher to zoo/veh (default) with get_status() payloads.
• Logs to logs/app.log; state snapshots to data/raw/events.csv.
• Ctrl+C triggers graceful shutdown and resource cleanup.

Debug & Utilities

• MQTT only (no hardware): python src/mqtt_test.py
• Line-follow vision tuning with OpenCV GUI: run python src/vision.py directly and use trackbars.
• Ultrasonic quick test: in src/main.py, run App(cfg).ultra_test().

Project Layout

• src/main.py: entrypoint and threading
• src/vision.py: camera wrapper, line detection, tuning GUI
• src/control.py: PID, speed ramp, basic motion commands
• src/sensors.py: DHT, INA219, ultrasonic readings
• src/health.py: health guard and protection actions
• src/motor_post.py: power-on self-test and serial detection
• src/mqtt_publisher.py / src/mqtt_test.py: MQTT telemetry
• src/event_logger.py / src/logger_setup.py: CSV and file logging
• configs/: default and example configs
• data/, logs/: runtime data and log outputs

Tests

Example tests exist; run with:

pytest

(src/utils.py and src/module1.py are currently missing; add or prune those tests before enabling.)