femtofox/WARP.md
Neil A 037ff4e728 Add Lyra Zero W migration builder and update WARP.md
- Created foxbuntu-lyra-builder.sh for Luckfox Lyra Zero W migration
- Preserves Ubuntu rootfs and femto utilities from Pico Mini build
- Integrates with Luckfox-Lyra-SDK for RK3506 platform
- Updated WARP.md with Ubuntu 24.04.3 LTS environment info
- Added comprehensive migration strategy and workflow documentation
2025-09-12 17:13:14 -04:00

443 lines
17 KiB
Markdown

# 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)
```bash
# 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)
```bash
# Launch interactive build menu
sudo ./environment-setup/foxbuntu-builder.sh
```
### Common Build Operations
```bash
# 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
```bash
# 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
```bash
# 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`:
```bash
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)
```bash
# 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
```bash
# Check final image exists and size
ls -la ~/luckfox-pico/foxbuntu.img
du -h ~/luckfox-pico/foxbuntu.img
```
### Runtime Testing (On Target Device)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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.