Project PECAN, and Western Formula Racing's Telemetry System

A Western Formula Racing Open Source Project

Comprehensive telemetry and data acquisition system for real-time monitoring of formula racing vehicle performance. This system captures CAN bus data from the vehicle, transmits it to a base station, and visualizes it through an interactive web dashboard.

🚀 Quick Start — macOS Base Station

curl -fsSL https://raw.githubusercontent.com/Western-Formula-Racing/data-acquisition/main/universal-telemetry-software/deploy/install.sh | bash

Full setup guide →

Overview

The repository contains the end-to-end telemetry software for Western Formula Racing vehicles, enabling real-time monitoring of critical vehicle systems during testing and competition. The system consists of:

• PECAN Dashboard: Real-time web-based visualization of vehicle telemetry
• Universal Telemetry Software (/universal-telemetry-software): Car and base station software for CAN acquisition, transport, WebSocket bridging, and base-side Redis/TimescaleDB integration

System Architecture

flowchart LR
    ECU["Vehicle CAN Bus (ECU)"]
    HAT["Raspberry Pi CAN HAT"]
    EDGE["Car Raspberry Pi
    (native systemd service)"]
    BASE["Base Station
    (UTS base mode)"]
    REDIS["Redis"]
    DASH["PECAN Dashboard
    (Web UI)"]
    TIMESERIES["TimescaleDB
    (server stack)"]
    GRAFANA["Grafana
    (server stack)"]
    FLIGHTREC["Flight Recorder
    (phone store-and-forward relay)"]
    DOWNLOADER["Data Downloader
    (server stack)"]

    ECU -->|CAN| HAT
    HAT -->|SPI / CAN| EDGE
    EDGE -->|RF| BASE
    BASE --> REDIS
    REDIS -->|WebSocket| DASH
    BASE -->|direct write| TIMESERIES
    TIMESERIES --> GRAFANA
    FLIGHTREC -->|store-and-forward upload| DOWNLOADER
    DOWNLOADER --> TIMESERIES

Loading

Data Flow:

1. Vehicle CAN bus messages are read by the car-side Universal Telemetry Software running as a native car-telemetry.service systemd service on the Raspberry Pi
2. The car service packs messages in UDP/TCP for radio or Ethernet transmission
3. The base-side UTS receives telemetry and publishes it to Redis
4. Redis-to-WebSocket bridge broadcasts messages to connected clients (PECAN dashboard)
5. Base-side TimescaleDB bridge writes decoded CAN frames directly to the server stack's TimescaleDB over the network
6. Grafana visualizes historical data from TimescaleDB; Flight Recorder can relay phone-recorded runs to the data downloader API when the full base-station stack is not present

For the detailed WebSocket message contract between PECAN and UTS, see WEBSOCKET_PROTOCOL.md.

Components

PECAN Dashboard (/pecan)

Demo: https://western-formula-racing.github.io/data-acquisition/dashboard

A modern React + TypeScript web application for real-time telemetry visualization.

Features:

• Real-time CAN message visualization with WebSocket connection
• Customizable category-based filtering and color-coding
• Multiple view modes (cards, list, flow diagrams)
• Interactive charts and graphs using Plotly.js
• Built with Vite, React 19, and Tailwind CSS

Tech Stack: React 19, TypeScript, Vite, Tailwind CSS, React Bootstrap, Plotly.js

📖 Detailed Documentation

Universal Telemetry Software (/universal-telemetry-software)

Complete DAQ telemetry stack for the car Raspberry Pi and base station. UTS uses the same Python source and role-specific runtime logic on both ends; the car runs that shared code natively as car-telemetry.service, while base stations run it through Docker Compose with Redis, WebSocket, status, video relay, and optional TimescaleDB logging.

Features:

• Shared car/base telemetry logic in one Python codebase
• Native car systemd deployment with direct CAN read, UDP streaming, TCP packet resend, and direct WebSocket support
• Docker Compose base-station deployment for MacBook or Raspberry Pi
• UDP and TCP telemetry transport with packet recovery
• Base-side Redis publisher, WebSocket bridge, and status HTTP server
• Optional TimescaleDB logging (direct write to server TimescaleDB), audio/video streaming, and simulation mode

Tech Stack: Python, systemd, Redis, WebSockets, Docker, TimescaleDB

📖 Detailed Documentation

Car Simulator (/car-simulate)

Development and testing tools for simulating vehicle telemetry without physical hardware.

Features:

• CSV Data Playback: Replay recorded CAN data from CSV files
• Persistent WebSocket Server: Continuous data broadcasting for testing via car-simulate/persistent-broadcast
• WebSocket Sender / container scaffolding: Minimal Docker setup and example clients for local experiments

Includes:

• Sample CAN data files (CSV format)
• Example DBC (CAN database) file for message definitions
• Docker Compose setups for isolated testing environments, including a dev/demo server configuration in car-simulate/persistent-broadcast

CAN Adapter Bridges (/kvaser-bridge, /pecan-bridge)

GUI adapters for Kvaser and PECAN CAN hardware interfaces. Used during bench testing when physical vehicle hardware is unavailable.

Flight Recorder (/flight-recorder)

Supported phone-based store-and-forward telemetry recorder for lightweight run recording and upload. Put a phone on the car hotspot, point Flight Recorder at the car UTS WebSocket, record telemetry into browser storage during the run, then sync the captured data to the server database when WiFi or cellular access is available. This gives the team a permanent no-SD-card workflow for ECU_25 run data when the full base-station stack is not set up.

Use cases:

• Quick shakedown runs without setting up the full base station
• Phone-backed database ingest when the car is running on its hotspot
• No-SD-card upload path for ECU_25 run data
• Store-and-forward recording when server connectivity is intermittent

Notes:

• Not the primary live telemetry dashboard; use PECAN + UTS for real-time monitoring
• Stores received CAN frames locally in browser IndexedDB first, then marks them synced only after upload
• Uploads decoded signal batches via POST /api/can-frames/batch on the data-downloader API
• Has separate guarded controls for WS Relay and DB Forward; live relay and TimescaleDB upload can be used independently
• The phone must stay connected to the car hotspot and keep the page open during the run
• Supersedes the lte-relay branch for no-SD-card database ingest; optional remote live relay uses the public Wrangler Worker in flight-recorder/relay-worker to receive phone-forwarded WebSocket frames and rebroadcast them

Internal app: https://fdr.westernformularacing.org (wfr-fdr.pages.dev, protected by Cloudflare Zero Trust)

WebSocket Backend (/ws-backend)

Convenience deployment for the PECAN WebSocket broadcast server. The dashboard is hosted at pecan.westernformularacing.org (GitHub Pages); this backend provides live CAN data over ws:// or wss://.

Features:

• Runs the broadcast server with production defaults
• Standard + extended CAN IDs, accumulator simulation
• Optional CSV replay

📖 Deployment Guide

Quick Start

Prerequisites

• Node.js (v18+) and npm
• Python 3.11+
• Docker and Docker Compose (for containerized deployment)
• A cloned copy of this repository

Base Station (MacBook / Laptop)

The MacBook base station runs the UTS telemetry stack + Pecan dashboard locally. The committed deploy/.env.macbook has the LAN defaults most teammates need.

cd universal-telemetry-software/
docker compose -f deploy/docker-compose.macbook-base.yml --env-file deploy/.env.macbook up -d

Open http://localhost:3000 for Pecan, http://localhost:8080 for the status page. Add --profile timescale, --profile media, or --profile tunnel only when those optional services are needed.

See deploy/MACBOOK_DEPLOY.md for full setup details.

Car RPi Deployment

The car runs the telemetry stack natively through systemd, without Docker or Redis:

cd /home/car/data-acquisition/universal-telemetry-software
uv sync
sed -i "s/GIT_HASH=unknown/GIT_HASH=$(git rev-parse --short HEAD)/" deploy/car-telemetry.service
sudo cp deploy/car-telemetry.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable car-telemetry
sudo systemctl start car-telemetry

The service is configured for ROLE=car, REMOTE_IP=10.71.1.20, UDP 5005, TCP resend 5006, and local PECAN WebSocket 9080. See deploy/CAR_DEPLOY.md for full setup and update commands.

RPi Base Station Deployment

The Raspberry Pi base station still uses Docker Compose:

cd universal-telemetry-software/
docker compose -f deploy/docker-compose.rpi-base.yml up -d

See the UTS README for hardware setup and base-station options.

Server Stack (TimescaleDB + Grafana + APIs)

Deploy the server-side stack on a VPS:

cd server/installer/
cp .env.example .env
# Edit .env — set passwords and domain
docker compose up -d

Services: TimescaleDB (5432), Grafana (8087), data-downloader API, file-uploader, health-monitor.

Development Setup

1. Clone the repository:

   git clone https://github.com/Western-Formula-Racing/data-acquisition.git
   cd data-acquisition

   Documentation lives in component READMEs such as pecan/README.md and universal-telemetry-software/README.md.

Individual Components

PECAN Dashboard

cd pecan
npm install
npm run dev

Universal Telemetry Software (local dev)

cd universal-telemetry-software/
docker compose -f deploy/docker-compose.macbook-base.yml --env-file deploy/.env.macbook up -d

Car Simulator

cd car-simulate/persistent-broadcast
docker compose up -d

CAN Message Categories

PECAN supports configurable message categorization through a simple text-based configuration file. This allows customization of message grouping and color-coding without code changes.

Configuration: pecan/src/assets/categories.txt

Example categories:

• VCU (Vehicle Control Unit)
• BMS (Battery Management System)
• INV (Inverter)
• TEST MSG

📖 Category Configuration Guide

Docker Deployment

Simulator / Demo

cd car-simulate/persistent-broadcast
docker compose up -d

Production Deployment (WebSocket backend)

cd ws-backend
docker compose up -d --build

Development

Project Structure

data-acquisition/
├── universal-telemetry-software/  # Shared car/base telemetry code with systemd and Docker deploys
│   ├── src/           # Python telemetry source
│   ├── deploy/        # Car systemd service and base Docker Compose files
│   └── status/        # Status page HTML
├── pecan/             # React live dashboard (GitHub Pages)
│   └── src/
│       ├── components/ # React components
│       ├── pages/      # Page components
│       └── services/   # WebSocket and data services
├── flight-recorder/   # React data recording PWA
├── car-simulate/      # CAN data simulators (CSV playback, WebSocket broadcast)
├── ws-backend/        # WebSocket broadcast server for PECAN
├── server/            # VPS server stack (TimescaleDB, Grafana, data APIs)
│   └── installer/      # Docker Compose stack for server
│       ├── timescaledb/   # DB init scripts and schema
│       ├── grafana/        # Dashboards and provisioning
│       ├── grafana-bridge/ # Pecan → Grafana API bridge
│       ├── data-downloader/ # FastAPI query builder
│       ├── file-uploader/  # CSV upload web UI
│       ├── health-monitor/ # Container health monitoring
│       ├── sandbox/        # Python execution sandbox
│       └── slackbot/       # Slack bot
├── secret-dbc/        # Git submodule: private DBC files (restricted)
├── kvaser-bridge/     # Kvaser CAN adapter GUI
├── pecan-bridge/      # PECAN CAN adapter
└── grafana-worker/    # Cloudflare Workers proxy for Grafana

Technology Stack

• Frontend: React 19, TypeScript, Tailwind CSS, React Bootstrap
• Visualization: Plotly.js for interactive charts and graphs
• Build Tools: Vite
• Backend: Python, asyncio, WebSockets
• Message Broker: Redis
• Time-Series DB: TimescaleDB (PostgreSQL)
• Data Format: CAN bus (DBC files)
• Deployment: Docker, Docker Compose, Nginx

Contributing

Contributions are welcome! This project is maintained by the Western Formula Racing team.

Development Workflow

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly with the simulator
5. Submit a pull request

License

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.

Related Resources

• PECAN Project Page: Project PECAN
• Live Demo: Demo

Support

For questions or issues, please open an issue on GitHub.

---

Built with ❤️ by Western Formula Racing

London, Ontario, Canada 🇨🇦