RTOS Rover Pico Simulation

This project simulates a FreeRTOS-based robotic rover on a Raspberry Pi Pico using the Wokwi online simulator. The system integrates real-time motor control, ultrasonic obstacle detection, rotary encoders, real-time telemetry streaming, and a live Python dashboard that highlights real-time performance.

---

Features

• FreeRTOS Firmware:

  • Runs on Raspberry Pi Pico using the Pico SDK + FreeRTOS.
  • Implements separate RTOS tasks for safety monitoring, motor control, and telemetry reporting.
  • Uses critical sections and interrupt routines for precise encoder counting and atomic sensor/motor updates.

• Obstacle Detection & Safety:

  • Uses an HC-SR04 ultrasonic sensor (via simulated Wokwi part).
  • Safety task polls distance at 100Hz. If obstacle < 20cm, motors immediately stop and a warning LED lights up.

• Motor Control:

  • Drives two stepper motors using A4988 drivers (all simulated).
  • Stepper movement is gated by the safety override and updated at 50Hz.
  • Rotary encoders (KY-040) count wheel rotation via GPIO interrupts.

• Telemetry:

  • Telemetry task outputs a line to UART every second in the format:

    TEL,<speed>,<encoder1>,<encoder2>,<battery>,<latency>
    

    • speed: current speed state (0 = stopped, 1 = moving)
    • encoder1/2: wheel encoder pulse counts
    • battery: simulated battery percentage
    • latency: measured safety task execution time in ms

• Simulation in Wokwi:

  • Wokwi diagram (diagram.json) includes Pi Pico, HC-SR04, 2x A4988s, 2x stepper motors, 2x rotary encoders, and a warning LED.
  • wokwi.toml configures the sim to expose serial as an RFC2217 server for seamless integration with desktop Python scripts.

• Live Python Dashboard:

  • Monitors and plots "Safety Latency" in real-time via matplotlib.
  • Highlights any real-time deadline violation (latency > 12ms) in red for instant tracing of missed safety deadlines.

---

File Overview

• main.c, main.h – Core FreeRTOS firmware for the rover
• diagram.json – Wokwi circuit definition (Pico, sensors, motors, encoders, LED)
• wokwi.toml – Wokwi simulation and serial server setup
• telemetry_dashboard.py – Live plotting dashboard (Python 3, matplotlib, pyserial)

---

Usage

1. Build the Firmware

• Uses Pico SDK and FreeRTOS.
• Build as usual (cmake, make).
• Make sure outputs include rtospico.elf and rtospico.hex.

2. Simulate in Wokwi

• Launch Wokwi in VS Code (or online) with the provided diagram.json and wokwi.toml.
• Wokwi RFC2217 server should be enabled in wokwi.toml:

  [wokwi]
  elf = "build/rtospico.elf"
  firmware = "build/rtospico.hex"
  version = 1
  rfc2217ServerPort = 4000
  

3. Run the Python Telemetry Dashboard

• Install requirements:

  pip install matplotlib pyserial
  

• Run the dashboard from terminal:

  python telemetry_dashboard.py
  

• The dashboard connects to the running simulation on rfc2217://localhost:4000, parses telemetry, and plots the safety task latency in real time.

---

RTOS Task Structure

• Safety Task:
  • Polls sonar, checks for obstacles, triggers stop (highest priority, every 10ms, deadline 12ms).
• Motor Task:
  • Steps motors if no obstacle (every 20ms).
• Telemetry Task:
  • Prints log line to UART (every 1s).
• Encoder ISRs:
  • Increments encoder values on pulse inputs.

---

Customizing / Debugging

• Serial issues:

  • Make sure Wokwi sim tab is open and RFC2217 server is listening before starting your Python script.
  • Use /tmp/ttyWOKWI + socat if not using RFC2217 (see comments in source).

• Plotting:

  • Modify telemetry_dashboard.py for alternate serial ports, highlight criteria, or additional plots.

---