Documentation

Onboarding

Budget Planning Common Beginner Mistakes First Boot Learning Path Legal Basics for Beginners How the Beacon Saves Lives Understanding the Modes in One Page Morse Code for Beginners Parts Overview Reading the OLED Screens Radio Basics for Complete Beginners Safety First Tools You Need Using the BOM Builder Using the Interactive Demo Welcome to the Wiki

Getting Started

Bench Power Bench Testing Basics Boot Process Build Configurations Choosing a Build Configuration Static Safety and ESD ESP32 Troubleshooting Checklist Frequently Asked Questions First Transmission First Use Project Overview Quick Start Guide Shopping List Sourcing Parts System Architecture Troubleshooting Version Selection Workspace Setup

Power & Battery

Hardware & Components

Build & Assembly

3D Printing the Enclosure Assembly Guide Assembly Sequence Audio Jack Wiring Audio Troubleshooting Bench Checklist Breadboard Prototyping Building Your Own Case Button Actions in CONFIG Mode Button System Details Button Troubleshooting Case Cutouts Guide Case Materials Circuit Description Connector Types Datasheet Reading Dummy Load and Bench Testing Electrical Specifications Enclosure Options Flux and Solder Glue and Adhesives GPIO Pin Map Reference GPIO Pin Mapping Ground Planes and Counterpoises Ohm's Law Resistors, Capacitors and Passives Schematic Reading Screw and Fastener Guide Soldering Basics Soldering Iron Guide Two-Beacon Bench Test Waterproof Build Waterproofing and Enclosure Sealing Wire and Connectors Wire Gauge Guide Wiring and Connectors Wiring Order and Routing Wiring Quick Reference

Radio & RF Design

Antenna Cable and Connectors Antenna Design Antenna Efficiency Antenna Height Matters Antenna Length Reference Antenna Mounting Antenna Quick Select Antenna Testing and Tuning Antenna Theory Primer Antenna Troubleshooting Antenna Design and Selection Coax Loss Tables dBm Explained Foliage Loss The Fresnel Zone GPS Antenna Placement Half Wave Dipole Helical Antenna Homebrew Antenna Interference Sources at 433 MHz Line of Sight and Terrain LoRa vs FSK Modulation in the Beacon Morse Timing and Audio Sync Mountain Effects on Radio Propagation and Range Propagation Modes Quarter Wave Antenna Radio Quick Start Radio Shadow Receiver Testing RF Basics for the Beacon RF Design & Link Budget RF Exposure Safety RF Interference and Noise RSSI Explained Sensitivity vs Selectivity SWR Explained SX1262 Datasheet Notes SX1262 Frequency Ranges SX1262 Registers Transmitter Testing Tropospheric Ducting Troubleshooting RF Issues Urban RF Environment VSWR Measurement

Frequencies & Regulations

Firmware & Software

Arduino CLI Guide Boot Loop Troubleshooting Boot Screens and Errors Changelog Code Style Guide Config Backup Config Dashboard Why the Dashboard Uses System Fonts CONFIG Payload Format Configuration Reference Dashboard HTTP API Dashboard Rendering ESP32 ADC Guide ESP32 Flash Security ESP32 Interrupts Guide ESP32 RTC Notes ESP32 Serial Debug Output ESP32 Timers Guide ESP32 WiFi Hardware esptool Guide Extending the Serial Protocol Factory Reset and Recovery Firmware CW Decoder Firmware System Monitoring Frequency Setting over Serial The Button System in Firmware How Firmware Loads Configuration Firmware Deep Sleep Firmware Error Codes Firmware GPS Handling The Firmware Main Loop Firmware NVS Keys Firmware Overview The Payload Builder Firmware RSSI Measurement The Scan Cycle in Detail Firmware Scan Engine The Firmware State Machine Firmware Tone Generation The TX Cycle in Detail Firmware TX Scheduler Upgrading to v5.5 Firmware Update in the Field Firmware Wake Sources The Watchdog Benchmark Demo Mode Flash Troubleshooting No Boot? Troubleshooting No Display? Troubleshooting NVS Configuration Store PlatformIO Guide RTC RAM State Battery Logging over Serial Serial Bridge Guide Serial Command Automation Serial Command Protocol Serial Debug System Serial Monitor Guide Software Build Process Unit Testing the Firmware Upload and Monitor What's New in v5.5 What's New in v6.0 WiFi and Security WiFi Configuration Portal WiFi Troubleshooting

USB & Connectivity

Android OTG Guide Bridge Automation Bridge Security Bridge Troubleshooting Bridge TUI CH340 Driver Install CP210x Driver Install Report Position Page USB-Serial Adapter Troubleshooting Serial Port Detection Termux: Serial Bridge on Android USB Cable Types USB Connection Guide USB Power vs Data Web Serial: Browser-Only Option

GPS & Navigation

Morse & Communication

Modes & Operation

Glossary of Modes and Settings BEACON Mode CONFIG Mode EMERGENCY Mode LISTEN Mode SEARCH Mode Mode Screens and Icons Operating Modes Scan Engine Details

Field Operations & Rescue

Avalanche Rescue Operation Avalanche Safety Basics Beacon Care Seasonal Beacon Log Template Cleaning and Inspection Crevasse Rescue Distance Estimation from RSSI Emergency Cheat Sheet Emergency Communications Plan Emergency Kit Emergency Response Minute by Minute Emergency Response Scenarios Field Checklist Field Deployment Guide Field Maintenance and Storage Field Repair Kit Field Signals Cheat Sheet First Aid Kit Ground to Air Signals Group Communication Plan Hiking Safety Homing Technique Homing with the Serial Bridge Hypothermia Recognition Incident Command Long Term Storage Mirror Signaling Mission Debrief One Bridge, Several Beacons Night Operations Off-Grid Position Sharing Outdoor Testing Guide Pack Check Routine Position Logging Workflow Pre-Trip Checklist Repeater Position Reporting Ridge Crossing Technique Safety Guidelines Safety Quick Rules Search Patterns and Procedure Signal Strength Mapping Signal Triangulation Signaling Techniques Snow and Signal Behavior Snow Shelter Signaling Snow Signal Math Storm Operations Terrain Reading for Radio Trip Planning Water Damage Recovery Weather Planning Whistle Signals Winter Operations Winter Pack

Building Effectively

Effective Build Strategy Build Quality Gates Bench Jigs and Fixtures Rework and Desoldering Build Time Planning Build Log and Tracking

Build Variants

Displayless Build Minimal Build Multi-Beacon Network Multi-Beacon Operations Multi-Beacon Frequency Planning Repeater Beacon Standard Build Configuration

Project & Reference

Software Build Process

Edit on GitHub

Compile and flash with Arduino IDE or PlatformIO, plus CI, testing and debug workflow

Software Build Process

Overview

The Aegis-Beacon firmware can be built using either Arduino IDE or PlatformIO. Both methods produce identical output.

Prerequisites

Software Requirements

Software	Version	Purpose
Git	Latest	Clone repository
Arduino IDE	2.x	IDE (optional)
PlatformIO	Latest	Build system (recommended)

Hardware Requirements

ESP32 DevKit V1 (30-pin)
USB-C cable for programming

Option 1: PlatformIO (Recommended)

Installation

Install VS Code
Install PlatformIO extension
Clone repository:

CODE

git clone https://github.com/Leo-Galli/Aegis-Beacon.git
cd Aegis-Beacon

Build Configuration

File: platformio.ini

CODE

[env:esp32devkitv1]
platform  = espressif32
board     = esp32dev
framework = arduino

lib_deps =
    jgromes/RadioLib @ ^6.6.0
    bblanchon/ArduinoJson @ ^7.0.0
    olikraus/U8g2 @ ^2.34.0
    mikalhart/TinyGPSPlus @ ^1.0.3

monitor_speed = 115200
upload_speed  = 921600

build_flags =
    -DBOARD_HAS_PSRAM=0

board_build.flash_size = 4MB

Build Commands

CODE

# Build firmware
pio run

# Upload to device
pio run --target upload

# Monitor serial output
pio device monitor --baud 115200

# Clean build
pio run --target clean

Tip

PlatformIO automatically downloads and installs all dependencies. No manual library installation required.

Option 2: Arduino IDE

Installation

Download Arduino IDE 2.x
Add ESP32 board support:

CODE

File → Preferences → Additional boards URL:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

Install ESP32 board:

CODE

Tools → Board Manager → search "esp32" → install "esp32 by Espressif"

Library Installation

CODE

Sketch → Include Library → Manage Libraries

Install:

RadioLib by Jan Gromes (>= 6.0.0)
ArduinoJson by Benoit Blanchon (>= 7.0.0)
U8g2 by oliver (>= 2.34.0)
TinyGPS++ by Mikal Hart (>= 1.0.3)

Build Process

Open AegisBeacon.ino
Select board: Tools → Board → ESP32 Dev Module
Select port: Tools → Port → COMx
Upload: Click Upload button (→)

Build Output

Successful Build

CODE

RAM:   [========= ]  89.2% (used 463876 bytes from 520192 bytes)
Flash: [=======   ]  71.4% (used 2985000 bytes from 4194304 bytes)

File Locations

File	Location
Firmware binary	`.pio/build/esp32dev/firmware.bin`
Bootloader	`.pio/build/esp32dev/bootloader.bin`
Partition table	`.pio/build/esp32dev/partitions.bin`

OTA Updates (Future)

Note

OTA (Over-The-Air) updates are planned for v6.0. Currently requires USB connection.

Debug Builds

Enable Verbose Debug

In config.h:

CODE

#define DEBUG_VERBOSE   1   // Per-symbol Morse + RadioLib codes

Serial Monitor Settings

Setting	Value
Baud rate	115200
Data bits	8
Parity	None
Stop bits	1

CI/CD Pipeline

GitHub Actions

File: .github/workflows/firmware-ci.yml

CODE

name: Firmware CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/cache@v3
        with:
          path: |
            ~/.platformio
          key: ${{ runner.os }}-pio-${{ hashFiles('platformio.ini') }}
      - uses: actions/setup-python@v4
        with:
          python-version: '3.x'
      - name: Install PlatformIO
        run: pip install platformio
      - name: Build
        run: pio run

Checks Performed

Check	Description
Syntax	C++ compilation
Dependencies	Library resolution
Binary size	Flash/RAM usage
PlatformIO config	Valid configuration

Tip

All CI checks must pass before merging pull requests. Run pio run locally before committing.