Quick Start Guide

Important

Recommended Installation Methods

Use HEAR-CLI for automated installation - it handles all dependencies and configuration automatically:

• Development/Local Setup: hear-cli local_machine run_program --p petal_app_manager_prepare_sitl

• Production/Drone Deployment: hear-cli target_machine copy_run_program --p petal_app_manager_prepare_arm

• Production/Drone Testing and Development: hear-cli target_machine copy_run_program --p petal_app_manager_update_arm

Development Installation

Using HEAR-CLI (Recommended)

For local development and debugging, use the SITL (Software In The Loop) setup:

hear-cli local_machine run_program --p petal_app_manager_prepare_sitl

What this command does:

1. Installs all dependencies: Python 3.11 (Miniforge), PDM, Redis 7.2+

2. Creates development directory: ~/petal-app-manager-dev/

3. Clones all repositories:

   • petal-app-manager (main framework)

   • LeafSDK (mission planning SDK)

   • mavlink (MAVLink protocol with custom messages)

   • petal-flight-log (flight log management)

   • petal-leafsdk (LeafSDK integration for mission plan execution)

   • petal-qgc-mission-server (QGroundControl integration)

   • petal-user-journey-coordinator (user journey management)

   • petal-warehouse (data warehousing)

4. Configures development environment: Sets up PDM virtual environments for each component

5. Creates ``.env`` file: Pre-configured for development use

6. Installs development dependencies: All petals in editable mode

Note

The SITL setup creates a complete development environment with all petals linked for cross-development.

Development Directory Structure

The development setup creates the following repository structure with editable installations:

Development Repository Structure and Dependencies

Key Structure Points:

• Main Framework (petal-app-manager): Central application that loads all petals

• Editable Installations: Changes to petal code are immediately reflected without reinstallation

• pymavlink: Installed via file:// path (not editable) from the mavlink submodule. You must rebuild if changes are made using pdm install -G dev --force-rebuild pymavlink.

• Independent Petals: Each petal has its own virtual environment for isolated testing

Typical File Locations:

~/petal-app-manager-dev/
├── LeafSDK/
│   ├── src/leafsdk/          # SDK source code
│   └── tests/                # SDK tests
├── mavlink/
│   ├── pymavlink/            # Python MAVLink library
│   │   ├── generator/        # Message generator
│   │   └── dialects/         # MAVLink dialects
│   ├── message_definitions/  # Python MAVLink library
│   │   └── v1.0/             # Message definitions (.xml)
├── petal-app-manager/
│   ├── src/petal_app_manager/
│   │   ├── api/              # REST API endpoints
│   │   ├── plugins/          # Petal loader
│   │   └── proxies/          # Backend proxies
│   ├── docs/                 # This documentation
│   └── tests/                # Framework tests
├── petal-flight-log/
│   ├── src/petal_flight_log/ # Flight log handling
│   └── tests/
├── petal-warehouse/
│   ├── src/petal_warehouse/  # Data warehousing
│   └── tests/
├── petal-leafsdk/
│   ├── src/petal_leafsdk/    # Mission execution
│   └── tests/
├── petal-user-journey-coordinator/
│   ├── src/petal_user_journey_coordinator/
│   └── tests/
└── petal-qgc-mission-server/
    ├── src/petal_qgc_mission_server/
    └── tests/

Manual Development Setup

If you need to set up manually (requires dependencies from previous section):

1. Create Development Directory

mkdir -p ~/petal-app-manager-dev
cd ~/petal-app-manager-dev

2. Clone Repositories

# Core framework
git clone https://github.com/DroneLeaf/petal-app-manager.git
git clone https://github.com/DroneLeaf/LeafSDK.git
git clone --recurse-submodules https://github.com/DroneLeaf/leaf-mavlink.git mavlink

# Petals
git clone https://github.com/DroneLeaf/petal-flight-log.git
git clone https://github.com/DroneLeaf/petal-leafsdk.git
git clone https://github.com/DroneLeaf/petal-qgc-mission-server.git
git clone https://github.com/DroneLeaf/petal-user-journey-coordinator.git
git clone https://github.com/DroneLeaf/petal-warehouse.git

3. Set Up Main Application

cd petal-app-manager

# Configure PDM to use Python 3.11
pdm use -f /usr/bin/python3.11

# Install development dependencies (includes all petals in editable mode)
pdm install -G dev

Production Installation

Using HEAR-CLI (Recommended)

For deployment to drone companion computers or production systems:

hear-cli target_machine copy_run_program --p petal_app_manager_prepare_arm

What this command does:

1. Installs system dependencies: Python 3.11 (pyenv), PDM, Redis 7.2+

2. Sets up production environment: ~/.droneleaf/petal-app-manager/

3. Configures for production: Optimized for resource-constrained systems

4. Installs only production petals: Core functionality without development tools

5. Creates systemd service: Auto-start on boot

6. Configures ``.env`` file: Production-ready configuration

Warning

This command is designed for deployment to target machines (companion computers on drones). It requires HEAR-CLI to be configured with target machine credentials.

Custom Version Installation (Field Testing)

For testing specific combinations of Petal App Manager and petals on drones without creating formal releases:

hear-cli target_machine copy_run_program --p petal_app_manager_update_arm

Interactive Version Selection

This command prompts you to specify versions for each component, allowing flexible combinations for field testing:

droneleaf@ubuntu:~/HEAR_CLI$ hear-cli target_machine copy_run_program --p petal_app_manager_update_arm
Enter petal-app-manager version 😎 (v0.1.41): v0.1.42
Enter petal-flight-log version 😎 (v0.1.6): master
Enter petal-warehouse version 😎 (v0.1.7): dev
Enter petal-leafsdk version 😎 (v0.2.0):
Enter petal-user-journey-coordinator version 😎 (v0.1.2):
⭐ program will run in your target_machine, Are you sure? 😎 [y/n] (y):

Version Specification Options

• Git Tags: v0.1.42, v0.2.0 (stable releases)

• Branch Names: master, dev, feature/new-functionality (development versions)

• Commit SHA: abc123ef (specific commits)

• Empty/Default: Press Enter to use the default version shown in parentheses

Use Cases for Custom Versions

1. Feature Testing: Deploy a development branch of a specific petal while keeping others stable

2. Bug Fixes: Test a hotfix branch before creating an official release

3. Integration Testing: Combine multiple development branches for comprehensive testing

4. Rollback Testing: Test with older versions to isolate issues

What this command does:

1. Prompts for each component version: Interactive selection for precise control

2. Downloads specified versions: Clones exact git references (tags/branches/commits)

3. Updates existing installation: Replaces current versions without full reinstall

4. Preserves configuration: Keeps existing .env and proxies.yaml files

5. Restarts services: Automatically restarts Petal App Manager with new versions

Tip

Development Workflow: Use this command to test your development branches on actual hardware before merging to main or creating releases. It’s perfect for validating changes in real-world conditions.

Note

This command requires HEAR-CLI to be configured with credentials for the target drone/companion computer.

Manual Production Installation

For manual production setup:

1. Create Production Directory

sudo mkdir -p ~/.droneleaf
sudo chmod -R 777 ~/.droneleaf
cd ~/.droneleaf

2. Clone Main Repository

git clone https://github.com/DroneLeaf/petal-app-manager.git
cd petal-app-manager

3. Install Production Dependencies

# Configure PDM
pdm use -f /usr/bin/python3.11

# Install production dependencies only
pdm install -G prod

Environment Configuration

The .env file contains all configuration for Petal App Manager:

Automatic Configuration

Both HEAR-CLI methods automatically create a .env file. For manual setups, create:

Note

All environment variables use the PETAL_ prefix to avoid conflicts with other applications.

cat > .env << 'EOF'
# .env file for Petal App Manager configuration
# General configuration
PETAL_LOG_LEVEL=INFO
PETAL_LOG_TO_FILE=true
PETAL_LOG_DIR=logs
# MAVLink configuration
PETAL_MAVLINK_ENDPOINT=udp:127.0.0.1:14551
PETAL_MAVLINK_BAUD=115200
PETAL_MAVLINK_MAXLEN=200
PETAL_MAVLINK_WORKER_SLEEP_MS=1
PETAL_MAVLINK_WORKER_THREADS=4
PETAL_MAVLINK_HEARTBEAT_SEND_FREQUENCY=5.0
PETAL_ROOT_SD_PATH=fs/microsd/log
# Cloud configuration
PETAL_ACCESS_TOKEN_URL=http://localhost:3001/session-manager/access-token
PETAL_SESSION_TOKEN_URL=http://localhost:3001/session-manager/session-token
PETAL_S3_BUCKET_NAME=devhube21f2631b51e4fa69c771b1e8107b21cb431a-dev
PETAL_CLOUD_ENDPOINT=https://api.droneleaf.io
# Local database configuration
PETAL_LOCAL_DB_HOST=localhost
PETAL_LOCAL_DB_PORT=3000
# Redis configuration
PETAL_REDIS_HOST=localhost
PETAL_REDIS_PORT=6379
PETAL_REDIS_DB=0
PETAL_REDIS_UNIX_SOCKET_PATH=/var/run/redis/redis-server.sock
PETAL_REDIS_HEALTH_MESSAGE_RATE=3.0
# Data operations URLs
PETAL_GET_DATA_URL=/drone/onBoard/config/getData
PETAL_SCAN_DATA_URL=/drone/onBoard/config/scanData
PETAL_UPDATE_DATA_URL=/drone/onBoard/config/updateData
PETAL_SET_DATA_URL=/drone/onBoard/config/setData
# MQTT client
PETAL_TS_CLIENT_HOST=localhost
PETAL_TS_CLIENT_PORT=3004
PETAL_CALLBACK_HOST=localhost
PETAL_CALLBACK_PORT=3005
PETAL_POLL_INTERVAL=1.0
PETAL_ENABLE_CALLBACKS=true
PETAL_MQTT_HEALTH_CHECK_INTERVAL=10.0
# Proxy connection retry configuration
PETAL_MQTT_RETRY_INTERVAL=10.0
PETAL_CLOUD_RETRY_INTERVAL=10.0
PETAL_MQTT_STARTUP_TIMEOUT=5.0
PETAL_CLOUD_STARTUP_TIMEOUT=5.0
PETAL_MQTT_SUBSCRIBE_TIMEOUT=5.0
# Petal User Journey Coordinator configuration
PETAL_DEBUG_SQUARE_TEST=false
EOF

Key Configuration Options

• PETAL_LOG_LEVEL: Set to DEBUG for development, INFO for production

• PETAL_LOG_DIR: Directory for log files (default: logs, production: /home/droneleaf/.droneleaf/petal-app-manager)

• PETAL_MAVLINK_ENDPOINT: UDP endpoint for MAVLink communication

• PETAL_REDIS_UNIX_SOCKET_PATH: Path to Redis UNIX socket

• PETAL_CLOUD_ENDPOINT: DroneLeaf cloud API endpoint

Running the Application

Development Mode

cd ~/petal-app-manager-dev/petal-app-manager

# Activate PDM virtual environment
source .venv/bin/activate

# Run with auto-reload for development
uvicorn petal_app_manager.main:app --reload --host 0.0.0.0 --port 9000 --log-level info --no-access-log --http h11

Development Mode with Debugging (VSCode)

A VSCode launch configuration is provided for debugging with breakpoint support:

# Location: ~/petal-app-manager-dev/petal-app-manager/.vscode/launch.json

To use the debugger:

1. Open the project in VSCode: code ~/petal-app-manager-dev/petal-app-manager

2. Press F5 or go to Run and Debug panel (Ctrl+Shift+D)

3. Select “Petal App Manager” from the launch configuration dropdown

4. Click the green play button or press F5

The application will start with the debugger attached, allowing you to:

• Set breakpoints in your code

• Inspect variables and call stacks

• Step through code execution

• Hot-reload on file changes (--reload flag is enabled)

Tip

Debugging Petals: Since petals are installed in editable mode, you can also set breakpoints in petal code (e.g., ~/petal-app-manager-dev/petal-flight-log/src/petal_flight_log/). To debug a petal, open the petal files in the petal-app-manager workspace in VSCode (they are linked via editable installation), then set breakpoints and run the debugger. Changes to petal code will be reflected immediately due to editable installation.

Production Mode

cd ~/.droneleaf/petal-app-manager

# Activate PDM virtual environment
source .venv/bin/activate

# Run in production mode
uvicorn petal_app_manager.main:app --host 0.0.0.0 --port 9000 --log-level info --no-access-log --http h11

Background Service (Production)

The ARM installation script sets up a systemd service for automatic startup:

# Check service status
sudo systemctl status petal-app-manager

# Start/stop service
sudo systemctl start petal-app-manager
sudo systemctl stop petal-app-manager

# Enable/disable auto-start
sudo systemctl enable petal-app-manager
sudo systemctl disable petal-app-manager

Verifying the Installation

1. Check Application Health

# Test basic connectivity
curl http://localhost:9000/health

# Expected response:
# {"status": "ok"}

2. Access API Documentation

Open your browser and navigate to:

• Swagger UI: http://localhost:9000/docs

• ReDoc: http://localhost:9000/redoc

3. Check Proxy Status

# Test detailed connectivity
curl http://localhost:9000/health/detailed

// Expected response:
{
    "status": "healthy",
    "timestamp": "..."
    "proxies": {
        "redis": {
            "status": "healthy",
        },
        "mavlink": {
            "status": "healthy",
        },

    }
}

4. Test Redis Connection

# Direct Redis test
redis-cli -s /var/run/redis/redis-server.sock ping
# Should return: PONG

5. Check Logs

# View application logs (if logging to file is enabled)
tail -f app.log

# Or check individual component logs
ls -la app-*.log

6. Verify Petals Loading

# Check available petals
curl http://localhost:9000/petals/

# Expected: List of loaded petals

Quick Development Workflow

Once installed, here’s the typical development workflow:

# 1. Navigate to development directory
cd ~/petal-app-manager-dev/petal-app-manager

# 2. Activate environment
source .venv/bin/activate

# 3. Start application with auto-reload
uvicorn petal_app_manager.main:app --reload --host 0.0.0.0 --port 9000 --log-level info --no-access-log --http h11

# 4. In another terminal, start documentation auto-build
cd docs
sphinx-autobuild . _build/html

# 5. Open browser tabs:
# - http://localhost:9000/docs (API documentation)
# - http://127.0.0.1:8000 (documentation preview)

Tip

VSCode Integration: The development setup includes a .vscode/launch.json configuration. Press F5 in VSCode to start debugging with breakpoint support.

Troubleshooting

Common Issues After Installation

1. Python 3.11 not found: Ensure symlinks were created and PATH is updated

2. PDM command not found: Check that ~/.local/bin is in your PATH

3. Redis connection failed: Verify Redis service is running and socket permissions are correct

4. Port 9000 already in use: This may occur if you’re trying to run Petal App Manager using uvicorn while the systemd service is currently running. For debugging, you may want to stop the service first with sudo systemctl stop petal-app-manager. Alternatively, kill the conflicting process. You may use the command sudo lsof -i :9000 to identify the process using the port.

5. Application errors or unexpected behavior: Check the app.log file in the petal-app-manager directory (~/petal-app-manager-dev/petal-app-manager/app.log or ~/.droneleaf/petal-app-manager/app.log) for detailed error messages and stack traces that can help troubleshoot issues.

Getting Help

• Check the Known Issues section for common problems

• View application logs for detailed error messages

• Ensure all dependencies are properly installed from the previous section