Contributing - ADOS Documentation

Welcome

ADOS is built in the open and we welcome contributions. Whether you are fixing a typo, reporting a bug, adding a feature, or translating the UI into your language, there is a way to help. This page covers the practical details: where to contribute, how to set up each repo, what the PR process looks like, and the code conventions we follow.

Where to Contribute

ADOS has two main repositories. Both are on GitHub, both are GPLv3.

ADOS Mission Control

Browser-based GCS. TypeScript, Next.js 16, React 19.

ADOS Drone Agent

Companion computer software. Rust services plus Python 3.11+, native HTTP front, local setup webapp.

The Ground Agent is part of the Drone Agent repo (it is the same codebase, activated by a ground-station profile).

Types of Contributions

Bug reports. Found something broken? Open a GitHub issue with steps to reproduce, expected behavior, actual behavior, and your environment (OS, browser, FC firmware, agent version). Screenshots or logs help a lot. Bug fixes. Small fixes (typos, off-by-one errors, missing null checks) can go straight to a PR. Bigger fixes should have an issue first so we can discuss the approach. Features. Open an issue first to discuss the feature. We want to make sure it fits the project’s direction before you write code. Small features can be a single PR. Larger features should be broken into smaller PRs. Documentation. This docs site, README files, code comments, JSDoc/docstrings. Docs PRs are always welcome and reviewed quickly. Translations. Mission Control supports 16 languages. Translation files are JSON in the locales/ directory. Adding missing keys or improving existing translations is a great first contribution. Tests. Test coverage is an area where we can always improve. Vitest for Mission Control, pytest for the Drone Agent.

Setting Up Mission Control

Prerequisites

Node.js 20+ (LTS)
npm 9+
Git

Setup

# Clone the repo
git clone https://github.com/altnautica/ADOSMissionControl.git
cd ADOSMissionControl

# Install dependencies
npm install

# Start in demo mode (no hardware needed)
npm run demo

# Open http://localhost:4000

Useful Commands

# Development server (no demo data)
npm run dev

# Type checking
npx tsc --noEmit

# Linting
npm run lint

# Run tests
npx vitest

# Build for production
npm run build

Project Structure

ADOSMissionControl/
├── src/
│   ├── app/              # Next.js App Router pages and layouts
│   ├── components/       # React components, organized by feature
│   │   ├── command/      # Agent and fleet management UI
│   │   ├── dashboard/    # Per-node detail panels
│   │   ├── fc/           # Flight controller configuration panels (60+)
│   │   ├── flight/       # Flight control UI
│   │   ├── hardware/     # Ground station hardware management
│   │   ├── planner/      # Mission planning tools
│   │   ├── simulation/   # 3D mission simulation
│   │   └── ui/           # Shared UI primitives
│   ├── hooks/            # Custom React hooks
│   ├── lib/
│   │   ├── protocol/     # MAVLink and MSP protocol implementation
│   │   │   ├── firmware/ # Firmware-specific adapters
│   │   │   ├── messages/ # Binary message decoders
│   │   │   └── encoders/ # Binary message encoders
│   │   ├── video/        # WebRTC client, transport cascade
│   │   └── patterns/     # Mission pattern generators
│   ├── stores/           # Zustand state stores (60+)
│   └── i18n.ts           # Locale registry
├── locales/              # i18n translation files (16 languages)
├── convex/               # Convex backend (optional, cloud features)
└── tools/                # SITL launcher, MQTT bridge, video relay

Key Architecture Concepts

Protocol adapters. Each firmware (ArduPilot, PX4, Betaflight, iNav) has its own adapter that implements the DroneProtocol TypeScript interface. The adapters handle the differences between MAVLink and MSP, between ArduPilot parameter names and PX4 parameter names, and between different capability sets. New firmware support means writing a new adapter. Zustand stores. All state lives in Zustand stores. Components subscribe to store slices via selectors. Stores are independent. The telemetry store uses ring buffers (300 samples) for time-series data. Pattern generators. Mission patterns (survey grid, orbit, corridor, etc.) are pure functions. They take configuration in and return waypoints out. No React, no side effects. You can add new patterns by writing a generator function and registering it in the pattern registry.

Setting Up the Drone Agent

Prerequisites

Python 3.11+
pip
Git
A Linux SBC (for full testing) or macOS/Linux desktop (for development)

Setup

# Clone the repo
git clone https://github.com/altnautica/ADOSDroneAgent.git
cd ADOSDroneAgent

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[dev]"

# Run the CLI
ados --help

# Start the local API/setup server through the repository's development flow
ados --help

Project Structure

ADOSDroneAgent/
├── crates/              # Rust services (supervisor, control front,
│   │                    #   mavlink-router, cloud, video, radio,
│   │                    #   vision, logd, net, groundlink, and more)
├── src/ados/            # Python layer
│   ├── __init__.py      # Version (single source of truth)
│   ├── cli/             # ados command-line interface
│   ├── setup/           # Universal setup facade
│   ├── webapp/          # Local setup webapp assets
│   ├── api/             # Residual FastAPI (permanent-Python features)
│   │   ├── runtime.py   # API facade and runtime boundary
│   │   └── routes/      # Domain route modules
│   ├── services/        # Python service glue (AI/vision,
│   │                    #   peripherals, ground-station managers)
│   ├── plugins/         # Plugin host, signing, manifest
│   ├── sdk/             # Python plugin SDK
│   ├── hal/
│   │   ├── boards/      # Board profile YAMLs (17 profiles)
│   │   └── detect.py    # Hardware auto-detection
│   └── config/          # Configuration management
└── scripts/
    └── install.sh       # One-line installer bootstrap

Key Architecture Concepts

systemd services. In production, each agent service runs as a separate systemd unit. Many units run native Rust binaries (the supervisor, MAVLink router, control front, cloud relay, video, radio). Others run Python (the residual API, health, and the ground-station hardware managers). A Rust supervisor orchestrates the unit catalog through systemd. For development, you can run individual services directly. HAL board profiles. Each supported SBC has a YAML profile (src/ados/hal/boards/*.yaml) that describes its hardware: serial ports, camera paths, GPIO pins, capabilities. The agent reads the profile at boot and configures itself accordingly. IPC via Unix sockets. Agent services communicate through Unix domain sockets at /run/ados/. The MAVLink service writes parsed telemetry to /run/ados/mavlink.sock. Other services read from it. API runtime facade. Residual Python API route modules should use the accessors in ados.api.runtime for telemetry, FC, video, WFB-ng, and parameter state. If a new route needs more runtime data, add a facade method instead of reading private process fields from a route handler.

Pull Request Guidelines

Before Submitting

Check existing issues. Someone may already be working on this.
For features, open an issue first. Discuss the approach before writing code.
Keep PRs focused. One feature or fix per PR. If your PR touches 50 files across 5 features, split it.
Test your changes. Run the linter, type checker, and tests. If you add a feature, add tests.

Branch Naming

fix/short-description      # Bug fixes
feat/short-description     # New features
docs/short-description     # Documentation
i18n/short-description     # Translations
refactor/short-description # Code cleanup

Commit Messages

Write clear, short commit messages. Describe what changed and why.

feat: add corridor scan pattern generator

fix: prevent null reference in telemetry store when FC disconnects

docs: add gamepad setup instructions to flight control page

i18n: add missing Hindi translations for configure panels

Keep commit messages focused on what the change does. Do not reference issue trackers from other projects.

The Review Process

Push your branch and open a PR against main
Fill in the PR template (summary, test plan, screenshots if UI changes)
A maintainer will review within a few days
Address review feedback
Once approved, the PR is merged

Code Style

Mission Control (TypeScript):

TypeScript strict mode (noEmit type check must pass)
Functional React components with hooks
Zustand for state (not Redux, not Context for data)
Tailwind CSS for styling
No any types without a comment explaining why

Drone Agent (Python):

Python 3.11+ features are fine (match statements, | union types, etc.)
Type hints on all public functions
structlog for logging
Pydantic for config and API models
Black for formatting (if configured)

Translation Guide

Mission Control supports 16 languages. Translation files live at locales/<lang>.json.

Current Languages

Code	Language	Status
`en`	English	Complete (reference)
`de`	German	Partial
`es`	Spanish	Partial
`fr`	French	Partial
`gu`	Gujarati	Partial
`hi`	Hindi	Partial
`id`	Indonesian	Partial
`ja`	Japanese	Partial
`kn`	Kannada	Partial
`ko`	Korean	Partial
`mr`	Marathi	Partial
`pa`	Punjabi	Partial
`pt`	Portuguese	Partial
`ta`	Tamil	Partial
`te`	Telugu	Partial
`zh`	Chinese (Simplified)	Partial

How to Contribute Translations

Open locales/en.json (the reference file)
Open the target language file (e.g., locales/hi.json)
Find keys that are missing or have English placeholder values
Translate them
Submit a PR

Keep these in mind:

Drone terminology often does not have direct translations. Use the term pilots in your language actually use. For example, “throttle” in Hindi might stay as “throttle” rather than a literal Hindi translation.
Keep strings short. UI labels have limited space.
Do not translate parameter names (like MOT_SPIN_ARM). Those are ArduPilot identifiers.

Adding a New Language

Copy locales/en.json to locales/<code>.json
Translate all keys
Add the language to the locale registry in src/i18n.ts
Submit a PR

Reporting Security Issues

If you find a security vulnerability, do not open a public issue. Email team@altnautica.com with details. We will work with you on a fix and coordinated disclosure.

Code of Conduct

Be respectful. Be constructive. Help each other learn. We do not tolerate harassment, discrimination, or personal attacks. If you see bad behavior, report it to team@altnautica.com.

Need Help?

If you want to contribute but are not sure where to start:

Look for issues labeled good first issue on GitHub
Ask in the #contributing channel on Discord
Read the Architecture section to understand the codebase

Next Steps

Architecture Overview

Understand the system architecture before making changes.

Community

Join the Discord and connect with other contributors.

​Welcome

​Where to Contribute

ADOS Mission Control

ADOS Drone Agent

​Types of Contributions

​Setting Up Mission Control

​Prerequisites

​Setup

​Useful Commands

​Project Structure

​Key Architecture Concepts

​Setting Up the Drone Agent

​Prerequisites

​Setup

​Project Structure

​Key Architecture Concepts

​Pull Request Guidelines

​Before Submitting

​Branch Naming

​Commit Messages

​The Review Process

​Code Style

​Translation Guide

​Current Languages

​How to Contribute Translations

​Adding a New Language

​Reporting Security Issues

​Code of Conduct

​Need Help?

​Next Steps

Architecture Overview

Community

Welcome

Where to Contribute

Types of Contributions

Setting Up Mission Control

Prerequisites

Setup

Useful Commands

Project Structure

Key Architecture Concepts

Setting Up the Drone Agent

Prerequisites

Setup

Project Structure

Key Architecture Concepts

Pull Request Guidelines

Before Submitting

Branch Naming

Commit Messages

The Review Process

Code Style

Translation Guide

Current Languages

How to Contribute Translations

Adding a New Language

Reporting Security Issues

Code of Conduct

Need Help?

Next Steps