Installation - ADOS Documentation

Mission Control is a Next.js 16 application. You can run it in your browser during development, or build a standalone Electron desktop app.

System Requirements

Requirement	Minimum	Recommended
Node.js	20.x	22.x (LTS)
Browser	Chrome 89+ / Edge 89+	Latest Chrome
RAM	4 GB	8 GB
OS	macOS, Windows 10+, Linux	Any

WebSerial (USB connections) only works in Chromium-based browsers. Safari and Firefox do not support it.

Quick Start

Clone the repository

git clone https://github.com/altnautica/ADOSMissionControl.git
cd ADOSMissionControl

Install dependencies

npm install

Start the dev server

npm run dev

This starts the development server on port 4000 with Turbopack.

Open in your browser

Navigate to http://localhost:4000. You will see the dashboard.

Available Scripts

Command	Description
`npm run dev`	Development server on port 4000 (Turbopack). No demo data.
`npm run demo`	Development server with the simulated demo fleet. Great for exploring the UI.
`npm run build`	Production build.
`npm run start`	Start the production server on port 4000.
`npm run lint`	Run ESLint.
`npm run test`	Run Vitest unit tests.
`npm run test:e2e`	Run Playwright end-to-end tests (demo mode).
`npm run test:e2e:sitl`	Run Playwright tests against a real SITL instance.

Demo Mode

Demo mode is the fastest way to explore Mission Control without hardware.

npm run demo

This sets NEXT_PUBLIC_DEMO_MODE=true and starts the dev server. Seven simulated drones (ArduPilot, PX4, and iNav) appear on the dashboard with realistic telemetry, GPS tracks, and flight modes. All configuration panels work with mock parameters. You can also activate demo mode by adding ?demo=true to any URL:

http://localhost:4000?demo=true

Environment Variables

Create a .env file in the project root for optional features. A .env.example file is included in the repo.

# Required only for cloud features (auth, fleet sync, community)
NEXT_PUBLIC_CONVEX_URL=https://your-convex-deployment.convex.cloud
CONVEX_DEPLOY_KEY=your_deploy_key

# Optional: Cesium token for 3D simulation globe
NEXT_PUBLIC_CESIUM_TOKEN=your_cesium_ion_token

# Demo mode (alternative to npm run demo)
NEXT_PUBLIC_DEMO_MODE=true

Cloud features are entirely optional. Mission Control works fully offline for direct USB and WebSocket connections. The Convex backend adds fleet sync, authentication, and community features.

Electron Desktop App

Build a standalone desktop application for macOS, Windows, or Linux.

Build the Next.js app and compile Electron

# macOS
npm run desktop:build:mac

# Windows
npm run desktop:build:win

# Linux
npm run desktop:build:linux

Find the output

The built application is in the dist/ directory. On macOS, look for the .dmg file. On Windows, the .exe installer. On Linux, the .AppImage or .deb.

For development, you can run the Electron app without building a distributable:

# Standard dev mode
npm run desktop:dev

# Demo mode in Electron
npm run desktop:demo

Electron Architecture

The Electron app wraps the same Next.js standalone server. No proxy layer is needed. The main process starts the Node.js server and opens a BrowserWindow pointed at http://127.0.0.1:4000.

The Electron app always uses 127.0.0.1 instead of localhost. On macOS, localhost can resolve to ::1 (IPv6), causing connection failures when the server only listens on IPv4.

Convex Backend (Optional)

If you want cloud features (authentication, fleet sync, community changelog, cloud relay), deploy a Convex backend.

# Start the Convex dev server
npx convex dev

The convex/ directory in the repo contains the standalone backend with around 30 custom tables plus the auth tables. Community users can deploy their own instance without depending on any external service.

Updating

Pull the latest changes and reinstall dependencies:

git pull origin main
npm install
npm run dev

Troubleshooting

Port 4000 is already in use

Another process is using port 4000. Kill it or change the port:

# Find the process
lsof -i :4000

# Or use a different port
PORT=4001 npm run dev

WebSerial not available

WebSerial requires a Chromium-based browser (Chrome 89+, Edge 89+). It is not available in Firefox or Safari. Make sure you are not running in an incognito window with restricted permissions.

Convex connection fails

Check that your NEXT_PUBLIC_CONVEX_URL is correct and the Convex backend is running. Cloud features are optional. The GCS works fine without Convex for local connections.

Electron build fails on macOS

Make sure Xcode command line tools are installed: xcode-select --install. Electron Builder needs native compilation tools for the packaging step.

​System Requirements

​Quick Start

​Available Scripts

​Demo Mode

​Environment Variables

​Electron Desktop App

​Electron Architecture

​Convex Backend (Optional)

​Updating

​Troubleshooting

System Requirements

Quick Start

Available Scripts

Demo Mode

Environment Variables

Electron Desktop App

Electron Architecture

Convex Backend (Optional)

Updating

Troubleshooting