📘 Luckfox Pico Pro Max - Firmware Project v2.1

Target Board: Luckfox Pico Pro Max (RV1106) Version: 2.1 Author: Becube Last Updated: November 23, 2025

---

📖 Table of Contents

1. Project Overview
2. Quick Start (Flash & Play)
3. Build Instructions
4. Web Interface & APIs
5. Troubleshooting
6. Development Notes

---

📄 Single Source: detailed build/flash, runtime layout, and troubleshooting notes now live in docs/PROJECT_SUMMARY.md. Reference it whenever you need deeper context than this quick README.

---

1. Project Overview

This project provides a custom firmware for the Luckfox Pico Pro Max. It includes a safe, read-only Web Status Monitor (luckfox_web_config) that allows users to:

• View system status (uptime, memory, SD-card usage).
• Confirm RTSP + recording health with LED indicators.
• Review persistent debug logs stored on the SD card.

The firmware is built using the Luckfox Buildroot SDK and includes automated scripts for compilation and packaging.

Key Features

• Web UI: Port 8080 (Modern, Dark Theme).
• RTSP Stream: Port 554 (Standard rkipc).
• Architecture: ARM 32-bit EABI5 (Optimized for RV1106).
• Auto-Start: Services start automatically on boot via /etc/init.d/S99luckfox_video.

---

2. Quick Start (Flash & Play)

Step 1: Get the Firmware

Locate the latest firmware file in the project directory. It follows the naming convention: update_v2.1_YYYYMMDD_HHMMSS_xxxxx.img (where xxxxx is the MD5 suffix of the file).

Step 2: Flash the Firmware

Use the SocToolKit or RKDevTool on Windows to flash the .img file to your board.

Step 3: Verify & Access

1. Connect Network: Ensure the board is connected via Ethernet/USB (RNDIS).
2. Check IP: Default IP is usually 172.32.0.93 (USB) or assigned via DHCP (Ethernet).
3. Access Web UI: Open http://172.32.0.93:8080 in your browser.
4. Verify Binary (Optional):

   ssh root@172.32.0.93 "md5sum /oem/usr/bin/luckfox_web_config"
   # Expected MD5: b0e6f1931a463e42347938a5404a8674

---

3. Build Instructions

We use a consolidated script to handle everything: compilation, cleaning, and packaging.

Prerequisites

• Luckfox SDK installed at /home/becube/luckfox-pico.
• sudo access (for cleaning rootfs).

One-Command Build

Run the following command from the project root:

./scripts/build_firmware.sh

What the script does:

1. Compiles src/web_config.c using the ARM cross-compiler.
2. Cleans old rootfs and Buildroot caches to ensure no stale files.
3. Builds the rootfs using the SDK's build.sh.
4. Installs the new binary and overlay files (init scripts, configs).
5. Packages the final update.img.
6. Renames the file with a timestamp and MD5 hash.

---

4. Web Interface & APIs

Web UI

• URL: http://<BOARD_IP>:8080
• Sections: Status card, LED card, Logs card.
• Auth: Basic (admin / luckfox).

REST APIs

Endpoint	Method	Description	Example
/api/status	GET	System snapshot	curl http://.../api/status
/api/logs	GET	Last log lines	curl http://.../api/logs

Recording control, FPS changes, and other risky actions were removed to keep the device stable. Apply configuration updates manually via /userdata/rkipc.ini if needed.

---

5. Troubleshooting

Web UI not loading?

1. Check if process is running:

   ssh root@<IP> "ps aux | grep luckfox_web_config"

2. Check if port 8080 is open:

   ssh root@<IP> "netstat -tuln | grep 8080"

3. Manually start it to see errors:

   ssh root@<IP>
   killall luckfox_web_config
   /oem/usr/bin/luckfox_web_config

Firmware flash failed or binary is old?

• Ensure you are using the latest .img file generated by build_firmware.sh.
• Check the MD5 of the binary inside the board (/oem/usr/bin/luckfox_web_config). It should be 33KB (not 42KB).

---

6. Development Notes

File Locations on Board

• Binary: /oem/usr/bin/luckfox_web_config
• Init Script: /etc/init.d/S99luckfox_video
• Config: /userdata/rkipc.ini
• Logs: /tmp/ (system logs)

Manual Update (Fast Dev Loop)

Instead of rebuilding the whole firmware, you can just update the binary:

# 1. Compile (Step 1 inside build script)
./scripts/build_firmware.sh   # Ctrl+C after compilation if you only need the binary

# 2. Upload
scp luckfox_web_config root@<IP>:/oem/usr/bin/

# 3. Restart just the monitor
ssh root@<IP> "killall luckfox_web_config; /oem/usr/bin/luckfox_web_config &"