freeRTOS-visualizer

Real-time visualization of FreeRTOS task states over serial. Open-source and cross-platform.

Features · How It Works · Quick Start · CLI Options · Serial Protocol · Development · Project Layout · Roadmap

---

Features

• Real-Time Visualization — monitor task states (Running, Ready, Blocked, Suspended) as they change
• Dynamic Bar Charts — each task's current state rendered as a live-updating bar chart
• CSV Data Export — export the full task-state history to a CSV file on exit via --export-csv
• Automatic Reconnect — if the serial link drops, the tool retries with exponential backoff
• CLI Configuration — serial URL, baud rate, timeout, and refresh interval are all configurable
• Cross-Platform — compatible with macOS, Linux, and Windows

---

How It Works

┌──────────────┐   serial/TCP   ┌───────────────────┐   matplotlib   ┌────────────┐
│  FreeRTOS    │ ─────────────▶ │  SerialConnection │ ────────────▶ │  PyQt5 GUI │
│  (QEMU/HW)  │   Task:X,      │  + TaskStateStore │               │  Bar Chart │
└──────────────┘   State:N      └───────────────────┘               └────────────┘

1. FreeRTOS prints Task:<name>,State:<code> lines over a serial port
2. SerialConnection reads and decodes lines, reconnecting automatically on failure
3. TaskStateStore parses and accumulates task-state history
4. The PyQt5 GUI renders a live bar chart, refreshing on a configurable interval

---

Quick Start

Install

From PyPI:

pip install freertos-visualizer

From source:

git clone https://github.com/hariharanragothaman/freeRTOS-visualizer.git
cd freeRTOS-visualizer
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Run

1. Start QEMU with serial redirection:

qemu-system-arm -M mps2-an385 -kernel RTOSDemo.axf -nographic \
  -serial tcp::12345,server,nowait

2. Launch the visualizer:

# If installed from PyPI
rtos-visualize

# Or run the module directly
python -m freertos_visualizer.visualize

3. (Optional) Export history on exit:

rtos-visualize --export-csv task_history.csv

---

CLI Options

Flag	Default	Description
--serial-url	socket://localhost:12345	Serial endpoint URL
--baudrate	115200	Serial baud rate
--timeout	1.0	Serial read timeout (seconds)
--refresh-ms	1000	GUI refresh interval (milliseconds)
--export-csv	(none)	Path to write task-history CSV on exit

Example — custom endpoint and fast refresh:

rtos-visualize --serial-url socket://192.168.1.10:5555 --refresh-ms 500 \
  --export-csv task_history.csv

---

Serial Protocol

The tool expects lines in the format:

Task:<name>,State:<code>

Code	State
0	Running
1	Ready
2	Blocked
3	Suspended

Any unrecognized code is displayed as Unknown. Lines that don't match the pattern are silently ignored.

---

Development

git clone https://github.com/hariharanragothaman/freeRTOS-visualizer.git
cd freeRTOS-visualizer
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

Running Tests

python -m pytest -v

Tests cover: serial-line parsing, state-store history tracking, CSV export, SerialConnection reconnect/backoff logic, malformed binary input, and end-to-end pipeline integration.

---

Project Layout

freertos_visualizer/
  visualize.py          # Core logic: parsing, state store, serial, GUI
tests/
  test_serial.py        # 22 unit tests (parser, store, serial mock, CSV)
docs/
  paper.md              # JOSS-style paper
  paper.bib
.github/workflows/
  ci.yml                # CI: tests on push to main (Python 3.9–3.13)
  build-publish.yml     # Publish to PyPI on version tags

---

Roadmap

• Timestamps in task-state history (not just sample index)
• In-app export button / periodic autosave
• Timeline / Gantt chart view alongside bar chart
• Configurable color schemes and chart types
• Support for additional FreeRTOS trace data (stack usage, CPU %)

---

Contributing

Contributions are welcome! Please read the CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License — see the LICENSE file for details.