uplotr

Open-source field testing for moving hardware. Capture GPS and arbitrary sensor telemetry, diagnose data quality, and compare hardware or firmware test runs on a fast MapLibre map.

Website · Live synthetic demo · Documentation · Discussions

Public Beta — v0.3.1-beta.1. uplotr is suitable for evaluation, maker field tests, and self-hosted deployments. Back up location data before upgrades. The official instance does not offer public registration or accept visitor location uploads.

What works today

• Generic REST ingestion with bearer API keys
• LoRaWAN webhooks for The Things Network, Helium, and ChirpStack payloads
• Live device state, online/offline status, battery, RSSI, and SNR
• Historical paths, point view, time filtering, and trajectory replay
• Structured field-test runs with hardware, firmware, goals, and notes
• Arbitrary flat telemetry metrics stored beside every position
• Explainable reporting-gap, GPS-jump, and timestamp diagnostics
• Baseline-to-candidate run comparison reports
• DIY drone flight-log import from GPX and generic, PX4, ArduPilot, or Betaflight CSV exports
• Run-scoped route replay, telemetry-colored paths, and flight-specific altitude, speed, GPS, and home-distance summaries
• MapLibre + OpenFreeMap by default; Mapbox is optional
• Single-owner private console with administrator-managed users and keys
• PostgreSQL persistence, retention cleanup, Docker Compose, and Vercel deployment
• Public, deterministic, read-only demo that never touches the production database

Not included in this Beta: open registration, multi-tenant SaaS, alerts, native MQTT/Kafka adapters, public report sharing, or a commercial SLA. These are roadmap items, not advertised features.

Five-minute Docker start

git clone https://github.com/iblh/uplotr.git
cd uplotr
cp .env.prod.example .env
# Set strong AUTH_SECRET, DB_PASSWORD, and CRON_SECRET values in .env
docker compose -f docker-compose.prod.yml up -d

Open http://localhost:3000/login, create the owner account, then create an API key in Settings → Access and security. The full key is displayed once.

curl -X POST http://localhost:3000/api/v1/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"tracker-01","lat":37.7749,"lon":-122.4194,"battery":98,"metrics":{"altitude":32,"voltage":4.08}}'

See the Quick Start, Deployment Guide, and API Reference for complete instructions.

Architecture

flowchart LR
  D[Devices and gateways] -->|REST or LoRaWAN webhook| A[Next.js API]
  A --> V[Validation, auth, rate limits]
  V --> P[(PostgreSQL)]
  P --> C[Private console /app]
  S[Deterministic synthetic data] --> M[Public read-only demo /demo]
  C --> L[MapLibre + OpenFreeMap]
  M --> L

The public website and demo are isolated from private tracking data. API routes enforce their own authorization; the request proxy is used only for page navigation.

Development

Requires Node.js 22, pnpm 10, and PostgreSQL.

pnpm install
cp .env.example .env
pnpm exec prisma migrate dev
pnpm dev

Before opening a pull request:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

CI also runs real-Postgres integration tests, browser smoke tests, a production dependency audit, and a Docker build.

Security and data responsibility

Internet-facing deployments should use AUTH_MODE=REQUIRED, strong unique secrets, HTTPS, a connection-pooled PostgreSQL database near the application, and regular encrypted backups. Location data is sensitive; do not attach real payloads, coordinates, credentials, or logs to public issues.

Please report suspected vulnerabilities privately as described in SECURITY.md.

Roadmap

1. Raw PX4 ULog, ArduPilot DataFlash, Betaflight Blackbox, and licensed DJI flight-record adapters
2. Read-only MCP tools for devices, runs, reports, and comparisons
3. Native MQTT/Meshtastic worker plus webhook retry and idempotency
4. Geofences, offline/low-battery rules, and outgoing automation webhooks
5. Private report sharing plus GPX, GeoJSON, and CSV export

Community and license

Questions and ideas belong in GitHub Discussions; actionable defects belong in Issues. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SUPPORT.md.

Licensed under Apache-2.0.