Skip to content

Software Checkout Procedure

The software checkout procedure prepares the Highdra drone system with the required software configurations and scripts for installation.

Important

Checkout is now fully Web UI-based. Run highdra software to start the local runner service and open the software checkout page.

Equipment

To perform this checkout, you will need the following:

  • A computer with the highdra CLI installed
  • GitHub CLI (gh) installed and authenticated (for private repository access)
  • Internet connection for downloading files from GitHub
  • Access to https://highdra-cli.starcopter.de/commands/software-checkout/

How It Works Now

highdra software is now the normal entrypoint for software checkout. It already includes the required local runner functionality, so you do not need to start highdra runner separately for a standard checkout session.

When you run highdra software, the CLI:

  1. Starts the local websocket runner service
  2. Opens the software checkout web page:
  3. https://highdra-cli.starcopter.de/commands/software-checkout/

The web UI then selects the manifest and dispatches checkout steps to your runner via websocket.

You would only run highdra runner directly when you want the runner without automatically opening the software checkout page.

Setup

Before starting, ensure you have:

  1. Authenticated with GitHub CLI if accessing private repositories:
gh auth login

Procedure

Run highdra software.

highdra software

The procedure will:

  1. Start local runner service - Registers runner state and starts the websocket command endpoint
  2. Open software checkout page - Browser opens the Web UI flow
  3. Select checkout target - In the Web UI, choose runner and software manifest
  4. Run step subflows - download, automated, and manual substeps execute remotely on the selected runner via websocket
  5. Complete checkout - Files are saved under the runner checkout working directory

Flow Overview

flowchart LR
    A[Run highdra software] --> B[Runner Starts]
    B --> C[Web UI Opens]
    C --> D[Select Manifest and Runner]
    D --> E[Run download/automated/manual Steps]
    E --> F[Complete Checkout]
Sample Output 
    $ highdra software
    Opening software checkout UI: https://highdra-cli.starcopter.de/commands/software-checkout/
    Runner 'my-runner', host (192.168.1.10) online on wss://0.0.0.0:8765

    # Continue the checkout in the browser.
    # Step execution output and prompts are streamed between runner and Web UI.

Checkout Process Details

Manifest and Step Validation

Validation occurs in the web-driven runner step handlers:

  • Required step fields are validated before execution
  • Substep type must be set (download, automated, or manual)
  • User confirmation gates each substep

File Download

For each software step, the runner can download:

  • Automated scripts: Python scripts that run automatically with minimal user interaction
  • Manual scripts: Python scripts that require user input and manual steps
  • Reference files: Configuration files (YAML, XML, etc.) needed for the installation

Files are downloaded using:

  • GitHub CLI for private repositories (requires gh auth login)
  • urllib as fallback for public URLs

All downloaded files are organized in a timestamped working directory under ~/.cache/highdra-cli/software_checkout/.

Script Execution

When automated scripts are downloaded, the web flow asks for confirmation before execution:

  • Scripts run using uv run for dependency management
  • The working directory is set to the step directory containing all downloaded files
  • Script output is captured and streamed line-by-line to the Web UI
  • Non-zero exit codes stop the current checkout flow and are shown as failed substeps in the Web UI

Tip

You can skip any substep (download, automated, manual) from the web UI confirmation controls.

Working Directory Structure

Files are organized as follows:

~/.cache/highdra-cli/software_checkout/runner_run_YYYYMMDD_HHMMSS/
├── step_1/
│   ├── automated.py
│   ├── manual.py
│   └── reference_0.yaml
├── step_2/
│   ├── automated.py
│   └── reference_0.yaml
└── step_3/
    └── manual.py

Each step gets its own directory with all associated files, making it easy to reference materials during manual installation steps.

Troubleshooting

Authentication Errors

If you encounter authentication errors when downloading from private repositories:

gh auth login

Follow the prompts to authenticate with GitHub.

Download Failures

If file downloads fail:

  • Check your internet connection
  • Verify the URLs in manifest steps are correct
  • Ensure you have access to private repositories (if applicable)
  • Check that the branch and file paths exist in the repository

Websocket Connection Failures

If step execution cannot start from the web UI:

  • Ensure highdra software is still running locally
  • Do not start a separate highdra runner for the normal software checkout flow unless you explicitly want runner-only mode
  • Confirm runner appears online in the web UI
  • Verify TLS trust / wss:// settings on the CA certificate page