mirror of
https://github.com/femtofox/femtofox.git
synced 2026-11-21 23:46:28 -05:00
- 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
443 lines
17 KiB
Markdown
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.
|