femtofox/WARP.md

WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

Project Overview

Femtofox is an embedded Linux Meshtastic development platform originally built for the Luckfox Pico Mini (Rockchip RV1103/RV1106), now being extended to support the Luckfox Lyra Zero W (Rockchip RK3506). It combines:

• Foxbuntu: A custom Ubuntu 22.04-based distribution optimized for low power consumption
• Hardware Platform:
  • Original: Luckfox Pico Mini with 64MB DDR2, LoRa radio, and WiFi capability
  • New Target: Luckfox Lyra Zero W with RK3506 SoC and integrated WiFi/BT
• Meshtastic Integration: Native Linux client support for mesh networking via SPI and UART
• Power Management: Hardware power control for USB WiFi modules via GPIO
• SDK Integration: Includes Luckfox-Lyra-SDK for RK3506 Linux 6.1 development

This is primarily an embedded Linux distribution build system, not a traditional software project. The main artifact is a bootable SD card image for the target hardware.

Current Development Status

⚠️ Migration In Progress: The project is being updated to support the Luckfox Lyra Zero W using the new Luckfox-Lyra-SDK (RK3506_LINUX6.1_SDK_Release_V1.1.0_20241128). The goal is to produce an image nearly identical to the original Femtofox build but targeting the new hardware platform.

Essential Build Commands

Initial Environment Setup (Run Once)

# Install the Foxbuntu SDK and build environment
sudo ./environment-setup/foxbuntu-builder.sh sdk_install

This clones repositories, installs dependencies, and creates the first Foxbuntu image (~2-4 hours).

Interactive Build Menu (Recommended)

# Launch interactive build menu
sudo ./environment-setup/foxbuntu-builder.sh

Common Build Operations

# Quick update with latest changes from git
sudo ./environment-setup/foxbuntu-builder.sh update_image

# Full clean rebuild of entire system
sudo ./environment-setup/foxbuntu-builder.sh full_rebuild

# Enter chroot environment for manual changes
sudo ./environment-setup/foxbuntu-builder.sh modify_chroot

# Modify kernel configuration
sudo ./environment-setup/foxbuntu-builder.sh modify_kernel

# Build final SD card image only
sudo ./environment-setup/foxbuntu-builder.sh create_image

Development Workflow

# Original Workflow (for Pico Mini)
# Sync Foxbuntu changes to build environment
sudo ./environment-setup/foxbuntu-builder.sh sync_foxbuntu_changes

# Update filesystem overlays only
./foxbuntu/updatefs.sh

# Rebuild rootfs and firmware
sudo ./environment-setup/foxbuntu-builder.sh build_rootfs
sudo ./environment-setup/foxbuntu-builder.sh build_firmware

Migration Development Workflow

# Explore Lyra SDK structure
cd Luckfox-Lyra-SDK
find . -name "build.sh" -o -name "*.mk" -o -name "Makefile" | head -20

# Initialize Lyra SDK (if needed)
# Note: SDK appears to use repo tool for component management
repo sync  # if SDK requires repo initialization

# Examine device configurations for RK3506
find Luckfox-Lyra-SDK/device/rockchip -name "*rk3506*" -o -name "*lyra*"
find Luckfox-Lyra-SDK/device/rockchip -name "*.mk" | grep -i lyra

# Check available toolchain
ls -la Luckfox-Lyra-SDK/prebuilts/gcc/linux-x86/arm/

# Explore kernel configuration
ls -la Luckfox-Lyra-SDK/kernel-6.1/arch/arm/configs/*rk3506*
ls -la Luckfox-Lyra-SDK/kernel-6.1/arch/arm/boot/dts/*rk3506*

# Check buildroot configurations
find Luckfox-Lyra-SDK/buildroot -name "*lyra*" -o -name "*rk3506*"

Project Architecture

Build System Structure

environment-setup/
├── foxbuntu-builder.sh     # Main build orchestration script
├── femtofox.chroot         # Chroot environment setup script
└── Foxbuntu SDK.pdf        # Build documentation

foxbuntu/
├── updatefs.sh             # Filesystem overlay sync utility
├── sysdrv/                 # Rootfs customizations and overlays
│   └── out/rootfs_uclibc_rv1106/
│       └── usr/local/bin/   # Femtofox system utilities
└── project/                # Hardware configuration and device trees

Luckfox-Lyra-SDK/           # NEW: RK3506 Linux 6.1 SDK
├── manifest.xml            # Repo manifest for SDK components
├── project.list            # List of SDK projects/components
├── buildroot/              # Buildroot build system
├── kernel-6.1/             # Linux 6.1 kernel sources
├── u-boot/                 # U-Boot bootloader
├── device/rockchip/        # Device-specific configurations
├── prebuilts/gcc/          # Cross-compilation toolchains
└── external/               # External libraries and tools

assets/
├── debian_install.txt      # Manual installation procedures
├── femtofox-config.txt     # Hardware configuration reference
└── images/                 # Hardware documentation and pinouts

Key System Components

1. foxbuntu-builder.sh: Main build orchestrator with interactive menu system
2. femtofox.chroot: Package installation and system configuration script
3. System Utilities: Collection of bash scripts for hardware management:
   • femto-utils.sh: System information and control utilities
   • femto-meshtasticd-config.sh: Meshtastic daemon configuration
   • femto-network-config.sh: Network interface management
   • femto-wifi-mesh-control.sh: WiFi power control integration

Hardware Control Architecture

Original Luckfox Pico Mini (RV1103/RV1106)

• GPIO 4: Controls TPS61023 boost converter for USB WiFi power
• RTL8188CU: USB WiFi adapter with custom power management
• SPI Interface: LoRa radio communication (SPI0, 2MHz)
• I2C/UART: Peripheral communication interfaces
• Button Control: Boot button for WiFi toggle and system control

Target Luckfox Lyra Zero W (RK3506)

• Integrated WiFi/BT: Built-in wireless connectivity (no external USB adapter needed)
• GPIO Control: Power management adapted for RK3506 pin assignments
• SPI Interface: LoRa radio communication (hardware-dependent configuration)
• I2C/UART: Standard peripheral communication
• Kernel: Linux 6.1 (vs 5.10.160 on original)

Build Environment Requirements

Host System

• OS: Ubuntu 24.04.3 LTS (development environment)
  • Note: Original system required Ubuntu 22.04 LTS, but development is now targeting 24.04.3 LTS
• Architecture: x86_64 with ARM cross-compilation support
• Storage: ~25GB for full build environment (increased for Lyra SDK)
• RAM: 8GB minimum, 16GB recommended
• Kernel: Linux 6.8.0-71-generic x86_64

Dependencies

Key packages installed by foxbuntu-builder.sh:

git ssh make gcc gcc-multilib g++-multilib module-assistant expect g++ 
gawk texinfo libssl-dev bison flex fakeroot cmake unzip gperf autoconf 
device-tree-compiler libncurses5-dev pkg-config bc python-is-python3 
passwd openssl openssh-server openssh-client vim file cpio rsync 
qemu-user-static binfmt-support dialog

External Dependencies

• Original Luckfox SDK: Cloned from https://github.com/Ruledo/luckfox-pico.git (for Pico Mini)
• New Luckfox Lyra SDK: Located in Luckfox-Lyra-SDK/ directory
  • Version: RK3506_LINUX6.1_SDK_Release_V1.1.0_20241128
  • Target SoC: Rockchip RK3506 (vs original RV1103/RV1106)
  • Kernel: Linux 6.1 (vs original 5.10.160)
• Cross-compilation toolchain: Provided by respective SDKs
  • Original: ARM toolchain for RV1103/RV1106
  • New: gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf for RK3506
• QEMU: ARM emulation for chroot operations

Critical Build Concepts

Chroot Environment

The build system uses chroot to customize the ARM rootfs on x86_64:

• Mount points: /proc, /sys, /dev, /dev/pts
• QEMU ARM static emulation enables running ARM binaries
• Package installation and system configuration happen in chroot
• Clean unmounting is critical to avoid corruption

Filesystem Overlays

• foxbuntu/sysdrv/: Contains all rootfs customizations
• foxbuntu/project/: Hardware-specific configurations
• Changes sync to ~/luckfox-pico/ during build
• Overlays preserve custom configurations across builds

Image Generation Process

1. Environment Setup: Configure cross-compilation toolchain
2. U-Boot Build: Bootloader compilation
3. Kernel Build: Custom kernel with device tree modifications
4. Rootfs Build: Base Ubuntu rootfs generation
5. Chroot Customization: Package installation and configuration
6. Firmware Assembly: Combine all components
7. Image Creation: Generate final SD card image

Hardware Configuration

GPIO Control (Critical for WiFi Power Management)

# GPIO 4 controls TPS61023 EN pin
echo 4 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio4/direction
echo 1 > /sys/class/gpio/gpio4/value  # WiFi powered
echo 0 > /sys/class/gpio/gpio4/value  # WiFi off

Network Stack Integration

• ifupdown: Traditional Debian networking (no NetworkManager)
• wpa_supplicant: WiFi association management
• dhclient: IPv4-only DHCP configuration
• Process cleanup: Required after power cycling WiFi hardware

Key Configuration Files (On Target)

• /etc/network/interfaces: Network interface configuration
• /etc/wpa_supplicant/wpa_supplicant.conf: WiFi credentials
• /etc/luckfox.cfg: Hardware peripheral enable/disable
• /etc/femto.conf: Femtofox-specific settings

Testing and Verification

Build Verification

# Check final image exists and size
ls -la ~/luckfox-pico/foxbuntu.img
du -h ~/luckfox-pico/foxbuntu.img

Runtime Testing (On Target Device)

# System information
sudo femto-utils.sh -i

# GPIO state verification
cat /sys/class/gpio/gpio4/value

# USB device detection
lsusb | grep -i realtek

# Network interface status
ip link show wlan0
sudo wpa_cli -i wlan0 status

# Meshtastic daemon status
sudo femto-meshtasticd-config.sh -S

Development Best Practices

Build Hygiene

• Always use sudo for build scripts (required for chroot operations)
• Clean builds recommended after major changes
• Sync git repositories before building
• Monitor disk space (~20GB required for full build)

Customization Workflow

1. System Changes: Edit femtofox.chroot script
2. File Overlays: Add files to foxbuntu/sysdrv/out/rootfs_uclibc_rv1106/
3. Hardware Config: Modify device trees in foxbuntu/project/
4. Test in Chroot: Use modify_chroot for interactive testing
5. Rebuild Image: Use full_rebuild or update_image

Power Management Considerations

• WiFi power cycling requires 8+ second delays for USB enumeration
• GPIO control must precede all network operations
• Process cleanup essential after power state changes
• IPv4-only configuration reduces complexity and power consumption

Migration-Specific Development Commands

SDK Structure Analysis

# Understand Lyra SDK build system
cd Luckfox-Lyra-SDK
cat manifest.xml | grep -E "(buildroot|device|kernel)"
ls -la buildroot/build/

# Compare with original Pico SDK structure (if available)
# ls -la ~/luckfox-pico/ # for comparison

# Find device-specific configurations
grep -r "lyra" device/rockchip/ || grep -r "rk3506" device/rockchip/
find device/rockchip -name "*.mk" -exec grep -l "rk3506\|lyra" {} \;

# Examine kernel device trees
find kernel-6.1/arch/arm/boot/dts -name "*rk3506*.dts*" -o -name "*lyra*.dts*"

# Check for WiFi/BT drivers
find kernel-6.1 -path "*/wireless/*" -name "*.c" | head -10
find external/rkwifibt* -name "*.mk" -o -name "README*"

Build Environment Setup for Migration

# Set up environment variables for RK3506
export RK_KERNEL_VERSION=6.1
export RK_TARGET_SOC=rk3506
export RK_TARGET_PRODUCT=lyra_zero_w  # tentative product name

# Source SDK environment (adapt as needed)
source envsetup.sh  # if available in Lyra SDK
# OR
cd buildroot && source build/envsetup.sh

# Test cross-compilation toolchain
export PATH="$PWD/prebuilts/gcc/linux-x86/arm/gcc-arm-10.3-2021.07-x86_64-arm-none-linux-gnueabihf/bin:$PATH"
arm-none-linux-gnueabihf-gcc --version

Common Issues and Solutions

Migration-Specific Issues

• SDK Initialization: Lyra SDK may require repo tool setup if not pre-initialized
• Toolchain Path: Ensure RK3506 toolchain is in PATH before building
• Kernel Version Mismatch: Adapt kernel modules and drivers from 5.10.160 to 6.1
• Device Tree Conflicts: RK3506 pin assignments may differ from RV1103/RV1106
• WiFi Driver Changes: Integrated WiFi requires different driver stack than USB RTL8188CU

Original Build Failures

• Disk Space: Ensure 25GB+ available (increased for dual SDK support)
• Permissions: Always run build scripts with sudo
• Network: Stable internet required for package downloads
• Dependencies: Run sdk_install if toolchain missing
• Ubuntu Version: Some scripts may need adaptation from 22.04 to 24.04.3 LTS

Runtime Issues

• WiFi Not Detected:
  • Original: Check GPIO 4 state and USB enumeration
  • Target: Check integrated WiFi module initialization
• Network Association: Verify wpa_supplicant configuration and signal strength
• Service Conflicts: Stop competing services before Meshtastic operations
• Kernel Module Loading: Ensure modules are built for correct kernel version (6.1 vs 5.10.160)

Output Artifacts

Primary Output

• ~/luckfox-pico/foxbuntu.img: Bootable SD card image for Luckfox Pico Mini

Intermediate Artifacts

• ~/luckfox-pico/sysdrv/out/rootfs_uclibc_rv1106/: Customized ARM rootfs
• ~/luckfox-pico/output/image/: Firmware components and utilities

Licensing

• Hardware (Femtofox): CC BY-NC-ND (non-commercial, attribution required)
• Software (Foxbuntu): GNU GPLv3 (open source, commercial use allowed with attribution)

SDK Migration Strategy

Current Integration Tasks

1. Toolchain Adaptation: Update build scripts to use RK3506 cross-compilation toolchain
2. Kernel Migration: Adapt customizations from Linux 5.10.160 to Linux 6.1
3. Device Tree Updates: Port hardware configurations from RV1103/RV1106 to RK3506
4. WiFi Stack Changes: Adapt from USB RTL8188CU to integrated WiFi/BT module
5. Build System Integration: Modify foxbuntu-builder.sh to work with Lyra SDK structure
6. Rootfs Compatibility: Ensure Ubuntu-based rootfs works with new kernel/hardware

Key Differences: Pico Mini vs Lyra Zero W

Component	Pico Mini (RV1103/RV1106)	Lyra Zero W (RK3506)
SoC	RV1103/RV1106	RK3506
Kernel	Linux 5.10.160	Linux 6.1
WiFi	External USB (RTL8188CU)	Integrated WiFi/BT
Toolchain	Custom for RV1103/RV1106	gcc-arm-10.3-2021.07
SDK Base	Luckfox Pico SDK	Luckfox Lyra SDK
Build System	Custom build.sh	Buildroot + device/rockchip

Integration Points

This project builds a complete embedded Linux distribution. Key integration points:

• Meshtastic Ecosystem: Native Linux client for mesh networking
• LoRa Hardware: Direct SPI communication with radio modules
• WiFi Infrastructure:
  • Original: USB adapter power management and traditional networking
  • Target: Integrated WiFi/BT module with native drivers
• IoT Applications: GPIO, I2C, and UART interfaces for sensors and peripherals
• Cross-Platform Compatibility: Maintain Femtofox utilities across hardware platforms

Lyra Zero W Migration Builder

A new migration builder script has been created specifically for transitioning from the Luckfox Pico Mini to the Luckfox Lyra Zero W:

Script Location

• environment-setup/foxbuntu-lyra-builder.sh: Lyra Zero W migration builder

Key Features

• Ubuntu Rootfs Preservation: Automatically backs up the existing Ubuntu rootfs from the Pico Mini build
• Lyra SDK Integration: Initializes and works with the Luckfox-Lyra-SDK for RK3506
• Toolchain Management: Sets up RK3506 cross-compilation environment
• Migration Validation: Tests setup status and identifies missing components

Essential Commands

# Interactive migration menu
sudo ./environment-setup/foxbuntu-lyra-builder.sh

# Individual migration steps
sudo ./environment-setup/foxbuntu-lyra-builder.sh preserve_ubuntu_rootfs
sudo ./environment-setup/foxbuntu-lyra-builder.sh analyze_lyra_sdk
sudo ./environment-setup/foxbuntu-lyra-builder.sh test_migration_setup

# Initialize Lyra SDK (requires repo tool)
sudo ./environment-setup/foxbuntu-lyra-builder.sh init_lyra_sdk

Migration Status Verification

# Check preserved Ubuntu assets
ls -la /home/hellz/femtofox-ubuntu-rootfs-backup/usr/local/bin/femto-*

# Verify femto utilities count (should be 16+ scripts)
sudo ./environment-setup/foxbuntu-lyra-builder.sh test_migration_setup

Current Migration Progress

✅ Completed:

• Ubuntu rootfs backup created (/home/hellz/femtofox-ubuntu-rootfs-backup/)
• All 16 femto utility scripts preserved
• Lyra migration builder script created and tested
• Build environment analysis framework established

⚠️ Next Steps:

• Initialize Luckfox-Lyra-SDK (requires repo tool setup)
• Set up RK3506 cross-compilation toolchain
• Adapt kernel device trees from RV1103/RV1106 to RK3506
• Modify WiFi stack for integrated WiFi/BT vs USB adapter
• Test build process with preserved Ubuntu rootfs

Migration Philosophy

The migration preserves the valuable Ubuntu-based Foxbuntu system (no longer available in newer Luckfox SDKs) while adapting the hardware platform to the more capable Luckfox Lyra Zero W with integrated WiFi/BT and the RK3506 SoC.