Skip to content

Docs: add a usage guide with use cases and step-by-step guides for running a simulation #65

Description

@amvlab

Is your feature request related to a problem? Please describe.

The current documentation is deployment-focused. The README covers installation and operations thoroughly (Docker Compose, prebuilt release, build-from-source, environment variables, BlueSky ports, offline PMTiles basemap, and the integrated edition), and script/README.md documents the navdata build pipeline. But there is no end-user guide for actually running a simulation once WebATM is up.

A new user can get the web UI running at http://localhost:8082, but from there nothing explains how to connect to BlueSky, load/run a scenario, create and control aircraft, issue commands, or use the map tools. The feature list in the README names capabilities (command palette, console map picker, aircraft creation, routes/shapes, multi-node, 3D, follow mode) without showing how to use them. The result is a steep "now what?" cliff right after install.

Describe the solution you'd like

Add user-facing usage documentation — a Usage / User Guide with concrete use cases and step-by-step guides to run a simulation. This could be a new top-level section in the README and/or a docs/ directory linked from it (and screenshots/GIFs where they help).

Proposed step-by-step guides:

  1. Your first simulation in 5 minutes — from a fresh start to a moving aircraft on the map (connect → load a demo scenario or create one aircraft → run → observe).
  2. Connecting to a BlueSky server — standalone: Settings → server IP → Connect (note ports 11000/11001 and BLUESKY_SERVER_HOST); integrated: the in-app Start button.
  3. Running a scenario (.scn) file — upload/organize files via the in-app file manager and run them (incl. the IC command flow).
  4. Creating & controlling aircraft from the UI — the Create Aircraft modal + click-to-place on the map; single-click to fly-to, double-click to follow; reading the aircraft info panel; issuing commands (e.g. HDG/ALT/SPD) from the console with tab-completion and the command palette.
  5. Using the map tools — drawing routes and shapes, and picking coordinates with the console map picker.
  6. Multi-node simulations — spawning and switching between parallel nodes.
  7. Customizing the display — labels, icons, trails, colors/styles, 2D ↔ 3D models, and Web Mercator ↔ globe projection.
  8. Integrated edition: managing the bundled server — Start / Stop / Restart / Kill and the live server-log tab.

Proposed use cases (the "why" framing each guide):

  • A quick classroom/demo of an ATM scenario for teaching or evaluation.
  • Validating a hand-authored or generated .scn scenario file end-to-end.
  • Running an offline/air-gapped demo using the local PMTiles basemap + navdata overlay.
  • Driving a single-container deployment via the integrated edition's in-app server controls.

Describe alternatives you've considered

  • Keeping everything in the README vs. splitting usage into a docs/ folder linked from the README (likely cleaner as the guides grow).
  • Text-only vs. adding short screenshots/GIFs (a few visuals would help a lot for the map-interaction guides).
  • Relying on the live demo and BlueSky's upstream command reference instead of writing our own — but neither walks a user through the WebATM UI specifically.

Additional context

  • Existing docs for reference: README.md (install/deploy/config) and script/README.md (navdata pipeline).
  • BlueSky stack commands referenced in the guides can link to the upstream BlueSky / amvlab/bluesky docs rather than being re-documented here.
  • Guides should call out the standalone vs. integrated differences where the workflow diverges (e.g. connecting to a server vs. clicking Start).

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationenhancementNew feature or request

Projects

Status
Todo

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions