advmesh

A lightweight mesh networking utility for Raspberry Pi. Provides text and voice communication between ARM64 devices over UDP or LoRa radio, using Codec2 for low-bitrate speech encoding and direct Linux kernel ioctls for PCM audio (no ALSA userspace library).

• Windows with Visual Studio (C++ Linux Development workload)
• WSL2 (Ubuntu) with the ARM64 cross-compiler and autotools:

  sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu cmake make autoconf automake libtool

• Raspberry Pi targets running Linux (ARM64)

Clone the repository and pull submodules:

git clone <repo-url>
cd advmesh
git submodule update --init --recursive

All third-party libraries live as git submodules under extern/ and are cross-compiled for ARM64 via WSL2. A single script handles everything:

.\build_deps.ps1                  # Build all dependencies
.\build_deps.ps1 -Name codec2     # Build a specific dependency
.\build_deps.ps1 -Clean           # Clean rebuild all

This configures, builds, and installs each dependency to extern/<name>/install_arm64/, which the Visual Studio project references for headers and libraries.

To add a new dependency:

1. git submodule add <url> extern/<name>
2. Optionally add CMake overrides to $DependencyOptions in build_deps.ps1
3. Add the dependency's install paths to advmesh.vcxproj

Open advmesh.slnx in Visual Studio and build using one of the four configurations:

Output binary: bin/ARM64/<Configuration>/advmesh.out

Note: For Pi Debug/Pi Release configs (built on-device), install dependencies natively: sudo apt install libcodec2-dev

Deploy the compiled binary to one or more Raspberry Pi targets:

.\deploy.ps1                                    # Deploy local Debug to both Pis
.\deploy.ps1 -Rebuild                           # Rebuild then deploy
.\deploy.ps1 -Flavor release -Rebuild           # Rebuild Release then deploy
.\deploy.ps1 -Targets advmesh1                  # Deploy to a specific Pi
.\deploy.ps1 -Source remote -Flavor release      # Deploy Pi Release build

./advmesh.out <remote_ip> [remote_port] [local_port]
./advmesh.out --lora [options]

Example — two Pis talking to each other on port 9000:

# On Pi 1 (10.0.0.232)
./advmesh.out 10.0.0.108 9000 9000

# On Pi 2 (10.0.0.108)
./advmesh.out 10.0.0.232 9000 9000

Uses the Waveshare SX1262 LoRa HAT connected via UART and GPIO.

# Default settings (915.125 MHz, 2.4kbps air rate, 22dBm TX power)
./advmesh.out --lora

# Custom channel and UART device
./advmesh.out --lora --uart /dev/serial0 --channel 72

# Custom GPIO pins (non-standard HAT wiring)
./advmesh.out --lora --m0-pin 5 --m1-pin 6 --aux-pin 13

The HAT plugs directly onto the Raspberry Pi 40-pin header. Key connections:

Note: On Raspberry Pi, disable the serial console and enable the UART interface:

sudo raspi-config  # Interface Options → Serial Port → No console, Yes UART

Type messages and press Enter to send. Type /quit to exit.

Switch between text and voice modes at runtime:

/voice uses Codec2 at 3200 bps (full-duplex, best for UDP). /transmit and /receive auto-select codec mode based on radio type:

For voice over LoRa, use /transmit on one Pi and /receive on the other:

# Pi 1 (transmitter)
./advmesh.out --lora --baud 115200 --sub-packet 2
# Type: /transmit

# Pi 2 (receiver)
./advmesh.out --lora --baud 115200 --sub-packet 2
# Type: /receive

The stream protocol uses three packet types:

1. StreamInit — announces codec mode, batch size, sample rate
2. StreamData — 3-byte header (type + sequence number) + batched Codec2 frames
3. StreamEnd — signals transmission complete

Sequence number gaps are detected on the receiver and filled with silence (no retransmission). Recommended LoRa settings for voice:

Duty cycle: ISM 915 MHz bands have regulatory duty cycle limits. Use short push-to-talk bursts rather than continuous streaming.

advmesh/
├── main.cpp              # Application entry point (radio init, thread wiring)
├── cli.h/.cpp            # CLI argument parsing (ParseArgs, PrintUsage)
├── app.h/.cpp            # Application controller (mode management, packet routing, threads)
├── radio.h               # IRadio abstract interface
├── udp_radio.h/.cpp      # UdpRadio implementation (UDP sockets)
├── lora_radio.h/.cpp     # LoRaRadio implementation (SX1262 LoRa HAT via UART/GPIO)
├── audio.h               # IAudio abstract interface
├── pcm_audio.h/.cpp      # PcmAudio implementation (direct kernel PCM ioctls)
├── pcm_types.h           # Linux kernel ALSA UAPI type definitions (private to PcmAudio)
├── codec.h               # ICodec abstract interface
├── codec2_codec.h/.cpp   # Codec2Codec implementation (codec2 wrapper)
├── voice_stream.h        # Umbrella include for voice streaming TX/RX
├── voice_stream_tx.h/.cpp # VoiceStreamTx (batched voice capture and transmit)
├── voice_stream_rx.h/.cpp # VoiceStreamRx (batched voice receive and playback)
├── packet.h              # Packet framing (text, voice, stream protocol)
├── latency_stats.h       # Lock-free latency tracker
├── types.h               # Portable type aliases (u8, u16, i16, etc.)
├── build_deps.ps1        # Cross-compile all dependencies for ARM64
├── deploy.ps1            # Deploy binary to Raspberry Pi targets
├── test_lora.py          # On-device LoRa HAT diagnostic script
├── advmesh.slnx          # Visual Studio solution
├── advmesh.vcxproj       # Visual Studio project
└── extern/
    └── codec2/           # codec2 git submodule (low-bitrate speech codec)

A future LoRaRadio class will implement IRadio for packet transmission over LoRa. Below is the feasibility analysis for real-time voice over LoRa using the project's packet format and Codec2 codec.

Single codec frames cannot fit within one LoRa transmission — frame batching is required. Multiple 20ms codec frames are packed into a single LoRa packet to amortize preamble and header overhead.

• Codec: CODEC2_MODE_2400 (2400 bps, 6 bytes/frame) — very good voice quality
• Batch: 5 frames per packet (33 bytes payload)
• Latency: 100 ms — imperceptible to the listener
• Range: 2–8 km (urban to rural line-of-sight)
• Timing margin: 28.1% — comfortable headroom for processing

For additional range at the cost of latency, a 15-frame batch (300ms) reaches SF8 for 3–10 km, which feels like a satellite phone delay.

Most LoRa ISM bands (868 MHz EU, 915 MHz US) enforce 1–10% duty cycle limits, making continuous voice streaming infeasible. Options include:

• Amateur radio bands — no duty cycle limit (license required)
• 2.4 GHz LoRa — no duty cycle restriction (shorter range)
• Half-duplex push-to-talk — short transmission bursts within duty cycle