Reflash & Recovery

Required Tools

• SD card reader (USB 3.0 recommended for faster writes)
• Flashing utility: balenaEtcher (GUI) or dd (CLI)
• Serial console cable (USB-to-UART, 3.3V TTL) for headless recovery
• Latest Varta image bundle from your provisioning server or support channel
• For Jetson tiers: NVIDIA SDK Manager on an x86_64 Ubuntu host

Backup Procedures

Before reflashing, pull any local data you need to preserve:

# Backup sensor config and local calibration
ssh varta@<UNIT_IP> "tar czf /tmp/varta-backup.tar.gz \
  /opt/varta/config/ \
  /opt/varta/calibration/ \
  /opt/varta/certs/"

scp varta@<UNIT_IP>:/tmp/varta-backup.tar.gz ./varta-backup-$(date +%Y%m%d).tar.gz

Raspberry Pi Zero 2W + TinySA

Step 1: Download and Flash the Base Image

Use the Raspberry Pi OS Lite (Bookworm, 32-bit) image as the base. Flash it to a microSD card (16 GB minimum).

# Using Etcher (GUI): select the .img.xz, select the SD card, flash.

# Using dd (Linux/macOS):
xzcat varta-mini-v1-bookworm.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync

# Verify the write
sudo sync

Step 2: Pre-Boot Configuration

Mount the boot partition and enable SSH and Wi-Fi before first boot:

# Enable SSH
touch /media/$USER/bootfs/ssh

# Configure Wi-Fi (optional, for headless setup)
cat > /media/$USER/bootfs/wpa_supplicant.conf <<EOF
country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
network={
    ssid="FIELD_NETWORK"
    psk="NETWORK_PSK"
    key_mgmt=WPA-PSK
}
EOF

Step 3: Install Varta Services

After first boot, SSH in and deploy the Varta service stack:

ssh varta@<UNIT_IP>

# Copy service files
sudo mkdir -p /opt/varta
sudo cp -r /tmp/varta-deploy/* /opt/varta/

# Install Python dependencies
cd /opt/varta
pip install -e ".[mini]"

# Enable and start services
sudo systemctl enable varta-mini.service
sudo systemctl start varta-mini.service
sudo systemctl status varta-mini.service

Raspberry Pi 5 + HAMGEEK SDR

Step 1: Flash Pi 5 Image

Use Raspberry Pi OS Lite (Bookworm, 64-bit) for Pi 5. Flash to a high-endurance microSD card (32 GB minimum recommended).

# Using dd:
xzcat varta-mini-v2-bookworm-arm64.img.xz | sudo dd of=/dev/sdX bs=4M status=progress conv=fsync
sudo sync

Step 2: SDR Driver Installation

The HAMGEEK Fish Ball SDR requires specific driver setup on Pi 5:

ssh varta@<UNIT_IP>

# Install SDR prerequisites
sudo apt update && sudo apt install -y libusb-1.0-0-dev librtlsdr-dev

# Install HAMGEEK driver package
sudo dpkg -i /tmp/hamgeek-sdr-driver_1.2.0_arm64.deb

# Blacklist default DVB-T drivers to prevent conflict
echo "blacklist dvb_usb_rtl28xxu" | sudo tee /etc/modprobe.d/blacklist-rtlsdr.conf
sudo modprobe -r dvb_usb_rtl28xxu

# Verify SDR is detected
rtl_test -t

Step 3: Varta Service Setup

# Install Varta with Mini v2 extras
cd /opt/varta
pip install -e ".[mini-v2]"

# Configure SDR URI and sample rate
cat /opt/varta/deploy/mini_v2_config.yaml
# Verify: sdr.uri, sdr.sample_rate, sdr.gain match your hardware

# Enable services
sudo systemctl enable varta-mini-v2.service
sudo systemctl start varta-mini-v2.service
sudo systemctl status varta-mini-v2.service

Jetson Orin Nano / Orin NX

Step 1: Prepare SDK Manager Host

Jetson units require NVIDIA SDK Manager on an x86_64 Ubuntu 20.04/22.04 host connected via USB-C.

# Install SDK Manager (on host machine)
sudo apt install -y ./sdkmanager_*_amd64.deb

# Launch SDK Manager
sdkmanager

Step 2: Flash JetPack

Select the appropriate JetPack version and target board:

• Varta Pro: Jetson Orin Nano, JetPack 6.0+ (L4T 36.3+)
• Varta Max: Jetson Orin NX, JetPack 6.0+ (L4T 36.3+)

# Put Jetson into recovery mode:
# 1. Power off the unit
# 2. Hold the RECOVERY button
# 3. Apply power (or press RESET while holding RECOVERY)
# 4. Release RECOVERY after 2 seconds

# Verify recovery mode on host
lsusb | grep -i nvidia
# Should show: NVIDIA Corp. APX

Step 3: Post-Flash Setup

ssh varta@<UNIT_IP>

# Verify NVIDIA drivers
nvidia-smi
# Confirm: Driver version, CUDA version, GPU detected

# Restore Docker containers
docker load -i /tmp/varta-pro-stack.tar
docker compose -f /opt/varta/docker-compose.yml up -d

# Verify all containers are running
docker ps --format "table {{.Names}}\t{{.Status}}"

When the Unit Will Not Boot

If the unit is unresponsive or stuck in a boot loop, use one of these recovery methods depending on the tier:

Serial Console Access

Connect a USB-to-UART cable (3.3V TTL) to the unit's debug header pins.

# Connect via serial (Linux/macOS)
screen /dev/ttyUSB0 115200

# Connect via serial (Windows - use PuTTY or similar)
# Port: COMx, Baud: 115200, Data: 8, Stop: 1, Parity: None

Recovery Partition (Mini v1/v2)

If the recovery partition is intact, interrupt boot at the GRUB/U-Boot prompt:

# At U-Boot prompt, boot from recovery:
setenv bootpart 2
boot

# Once in recovery shell:
mount /dev/mmcblk0p1 /mnt
cp /mnt/boot/recovery.flag /mnt/boot/
reboot

Safe Mode (Jetson)

Jetson units support a minimal boot via recovery mode:

# From serial console at U-Boot:
setenv boot_mode safe
saveenv
reset

# Safe mode disables Docker and Varta services
# Use it to diagnose driver or filesystem issues

Clear All Configuration

Factory reset removes all site-specific configuration and returns the unit to its provisioning baseline.

# Stop all Varta services
sudo systemctl stop 'varta-*'

# Remove configuration and calibration data
sudo rm -rf /opt/varta/config/*
sudo rm -rf /opt/varta/calibration/*
sudo rm -rf /opt/varta/certs/*
sudo rm -rf /opt/varta/cache/*

# Reset to default configuration
sudo cp /opt/varta/defaults/* /opt/varta/config/

Re-Pair with Max

After a factory reset, the unit must re-register with the Varta Max command tier:

# Generate a new pairing token
varta-cli pair --broker mqtt://<MAX_HOST>:8883 \
  --sensor-id <SENSOR_ID> \
  --fleet-secret <FLEET_SECRET>

# Verify MQTT connectivity
varta-cli mqtt-test --broker mqtt://<MAX_HOST>:8883 --timeout 10

Reset Calibration Data

# Clear and regenerate calibration baselines
varta-cli calibrate --reset
varta-cli calibrate --run --duration 300

# Verify calibration output
cat /opt/varta/calibration/baseline.json | python3 -m json.tool

Re-Enroll Certificates

# Request new device certificate from provisioning server
varta-cli cert-enroll \
  --ca-url https://<PROVISION_HOST>/api/v1/certs \
  --device-id <DEVICE_ID> \
  --out /opt/varta/certs/

# Verify certificate chain
openssl verify -CAfile /opt/varta/certs/ca.pem /opt/varta/certs/device.pem

Service Health Check

# Check all Varta services are active
systemctl list-units 'varta-*' --no-pager

# Check service logs for errors
journalctl -u varta-mini.service --since "5 min ago" --no-pager
journalctl -u varta-pro.service --since "5 min ago" --no-pager

MQTT Connectivity Test

# Verify broker connection and topic subscription
varta-cli mqtt-test \
  --broker mqtt://<MAX_HOST>:8883 \
  --topic "varta/sensors/+/status" \
  --timeout 15

# Expected output: "Connected. Subscribed. Messages received: N"

SDR Detection Test (Mini v2 / Pro)

# Verify SDR hardware is detected and functional
rtl_test -t
# Expected: "Found 1 device(s)" and no error output

# Run a quick capture test
rtl_sdr -f 2437000000 -s 2400000 -n 4800000 /tmp/test_capture.bin
ls -lh /tmp/test_capture.bin
# Should be ~9.2 MB for 2 seconds of capture

Signature Database Sync

# Pull latest signature database from Max
varta-cli sig-sync --broker mqtt://<MAX_HOST>:8883 --force

# Verify signature count
varta-cli sig-info
# Expected: "Signatures loaded: NNN, Last sync: <timestamp>"

When an OTA Firmware Update Fails

If an over-the-air firmware update fails mid-apply, the unit should automatically roll back to the last-known-good (LKG) image. If it does not, follow these steps:

Verify LKG Rollback

# Check which firmware slot is active
varta-cli fw-status

# Expected output (after successful rollback):
# Active slot: A (LKG)
# Slot B: FAILED (marked dirty)
# Rollback: AUTOMATIC

# If rollback did not occur:
varta-cli fw-rollback --confirm
reboot

Manual Firmware Rollback

If fw-rollback is unavailable or the unit is partially booted:

# From serial console or SSH (if accessible):
# Switch to LKG partition manually

# Mini (Pi-based):
sudo mount /dev/mmcblk0p3 /mnt/lkg
sudo cp /mnt/lkg/boot/* /boot/
sudo cp -a /mnt/lkg/opt/varta/* /opt/varta/
sudo reboot

# Jetson:
# Use nvbootctrl to switch boot slot
sudo nvbootctrl set-active-boot-slot 0
sudo reboot

Force Re-Download OTA Package

# Clear the failed OTA cache and re-request
sudo rm -rf /opt/varta/ota/staging/*

varta-cli ota-check --force
# Downloads fresh package from Max OTA server

varta-cli ota-apply --verify-checksum
# Applies update with integrity verification

# Monitor the update
journalctl -u varta-ota.service -f