Tinix I -- Porting ESP-Hosted for the Luckfox Pico
#linux #buildroot #embedded #esp #luckfox
Introduction
I've been interested in embedded Linux for a while. After working on many microcontroller-based projects, I wanted to gain some hands-on experience with embedded Linux. Over the holidays, I finally had the opportunity to dive into it.
After some research into hardware options, I eventually settled on the Luckfox Pico series boards. These boards stood out because they have a Buildroot-compatible SDK available on GitHub, accompanied by reasonably good documentation. Having previously experimented with Buildroot through the Bootlin Buildroot tutorial, I saw this as a chance to use Buildroot in a more practical setting.
With my board selected (Luckfox Pico Max), I needed a practical project to work on. One idea I had been considering for a while was building my own IP camera for home use. Off-the-shelf IP cameras tend to be expensive and often lack flexibility in configuration. So why not build my own as an exercise in embedded Linux?
Proof of Concept
Before fully committing to this project, I wanted to evaluate the feasibility of the Luckfox Pico Max as a platform. To guide my investigation, I outlined a few high-level design requirements:
- Small footprint
- Wi-Fi capable
- Battery-powered (at least 1-day runtime)
- Good camera quality (at least 2MP)
Camera Compatibility
The Luckfox Pico series boards support Luckfox's SC3306 camera module. However, these boards use a non-standard CSI pinout, meaning only this specific camera is natively supported.
In theory, I could use other camera modules by designing a custom FPC interconnect, but since the SC3306 meets my resolution requirements, it makes sense to start with the default module. This ensures compatibility and reduces initial hardware complexity.
Initial Testing with the SC3306
I did some initial testing with the provided RTSP camera example and the SC3306, following the Luckfox wiki steps. I should note that since I bought the Pico Max board, I did testing via ethernet and SSH, rather than USB.
After plugging in the board to power and ethernet, I checked for it's IP using router's web interface. I then SSH'ed into the device using the default password luckfox.
ssh root@ip-addr
Once logged in, I confirmed that the camera had been correctly detected by listing /userdata.
# ls /userdata/ ethaddr.txt lost+found image.bmp video0 video2 rkipc . ini video1
The presence of the rkipc.ini file indicates that the camera was successfully recognised.
RTSP Stream Testing
Next I tried opening the RTSP stream in VLC, but this kept failing for unknown reasons. I tested it with ffplay instead, and found that this worked.
ffplay rtsp://192.168.20.31/live/0
There was some significant delay in the stream (>5s) which I was able to reduce using the -probesize flag:
ffplay -probesize 1000 rtsp://192.168.20.31/live/0
Here is a demo shot of the camera working:
With the camera tested and working it was time to move onto Wi-Fi integration.
Wifi Capabilities
The smaller Luckfox Pico boards do not have built in Wi-Fi modules, meaning I needed to come up with a solution for adding Wi-Fi to the board. After some research, I found that Luckfox does produce an SDIO-based Wi-Fi module for their smaller Pico boards. However, using this module would occupy the SD card slot, which I wanted to keep available for storage/boot purposes.
I happened to have a spare ESP32-S3 lying around and realised it could potentially serve as a Wi-Fi module. After some research, I found the ESP-Hosted project, which allows an ESP32 to function as a Wi-Fi peripheral with solid Linux support. This seemed like a promising way to add Wi-Fi capabilities to the Luckfox Pico Max.
Getting this to work was not straightforward—it required significant effort and troubleshooting. The details of the process are detailed in the next section.
Porting ESP-Hosted to Luckfox Pico
This section details the process of porting ESP-Hosted to the Luckfox Pico chronologically.
All about ESP-Hosted
According to the Github repository:
ESP-Hosted is an open source solution that provides a way to use Espressif SoCs and modules as a communication co-processor.
Essentially, ESP-Hosted offloads low-level Wi-Fi operations from the host, allowing the ESP32 to handle networking tasks. Since it includes cfg80211 support, we can use wpa_supplicant (yay for Buildroot fun).
ESP-Hosted comes in two flavors: esp_hosted_ng (next-generation) and esp_hosted_fg (first-generation). The ng version is recommended for Linux hosts due to its improved architecture, so I'll be using this in my port.
esp_hosted_ng consists of two main components: the host side and the ESP side. On the host side, we need to build and load the required kernel module and ensure that the necessary userspace configuration tools are available. On the ESP side, we need to configure the firmware and flash it onto the ESP32.
Let's start with the host side.
Host Setup
Luckfox SDK Setup
I started by setting up the Luckfox SDK. Since my PC runs Arch Linux, I decided to use a Docker-based build environment to avoid dependency headaches. The Docker image I’ll be using is based on one I set up while working through the Bootlin Buildroot tutorial. Below, I’ll outline the basic process for setting it up.
First, create a new working directory for the project and clone the Luckfox SDK, and ESP-Hosted
mkdir luckfox cd luckfox git clone https://github.com/LuckfoxTECH/luckfox-pico.git git clone esp-hosted
Next, create a Dockerfile with the following contents:
FROM ubuntu:24.04 # Set environment variables related to user ENV BR_USER=dev ENV BR_UID=1000 ENV BR_GID=1000 # Install dependencies RUN apt update && apt upgrade -y && apt install -y --no-install-recommends \ git \ ca-certificates \ 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 \ rsync \ curl \ wget \ cpio \ patch # Update user RUN mkdir /home/$BR_USER && \ usermod -d /home/$BR_USER -l $BR_USER ubuntu && \ groupmod -n $BR_USER ubuntu && \ chown $BR_UID:$BR_UID /home/$BR_USER WORKDIR /home/${BR_USER} USER ${BR_USER}:${BR_GID} CMD ["/bin/bash"]
This Dockerfile installs all necessary dependencies, renames the default user from ubuntu to dev, and switches to this user. Make sure the user has the same UID and GID as your local user to avoid file permission issues. Feel free to add any additional dependencies as needed.
Once you've created the Dockerfile, you need to build it. Make sure you have docker installed and that the docker daemon is running.
docker build -t picofox-dev .
This tags the built image as picofox-dev.
Now, run the container, binding the luckfox-pico directory to /home/dev/ inside the container,
and binding esp-hosted as subdirectory:
docker run -it -h picofox \ --mount type=bind,src=./luckfox-pico,dst=/home/dev/ \ --mount type=bind,src=./esp-hosted,dst=/home/dev/esp-hosted \ picofox-dev
While inside the container, install the cross-compilation toolchain:
cd tools/linux/toolchain/arm-rockchip830-linux-uclibcgnueabihf/ chmod 655 .bash_profile .bashrc # Required to prevent script failure source env_install_toolchain.sh
Once the toolchain is installed, do a test build:
cd ~ ./build.sh lunch
Because I am using a Pico Max, I selected the following options:
[6] RV1106_Luckfox_Pico_Max [1] SPI_NAND [0] Buildroot(Support Rockchip official features)
Next, start the build process:
./build.sh
This will take some time (about 30min on my Ryzen 7 3700X). While waiting, I recommend installing the flashing tool. Since USB passthrough can be tricky in Docker, this should be done outside the container.
Download the Luckfox flashing tool:
wget https://files.luckfox.com/wiki/Core3566/upgrade_tool_v2.17.zip unzip upgrade_tool_...
Move the tool to a system-wide location and make it executable:
# Add it to $PATH sam@raskolnikov:~/Downloads $ cd upgrade_tool_v2.17_for_linux/ sam@raskolnikov:~/Downloads/upgrade_tool_v2.17_for_linux $ ls config.ini ├№┴ю╨╨┐к╖в╣д╛▀╩╣╙├╬─╡╡.pdf revision.txt upgrade_tool sam@raskolnikov:~/Downloads/upgrade_tool_v2.17_for_linux $ sudo cp upgrade_tool /usr/local/bin/ sam@raskolnikov:~/Downloads/upgrade_tool_v2.17_for_linux $ sudo chmod +x /usr/local/bin/upgrade_tool
Finally, verify the installation:
sam@raskolnikov:~/Downloads/upgrade_tool_v2.17_for_linux $ sudo upgrade_tool -v Upgrade Tool v2.17
Once the build completes, the output files will be located in the luckfox-pico/IMAGES/ directory. Navigate into the latest subfolder and locate the update.img file.
Before flashing, the device needs to be put into bootloader mode. Follow these steps:
- Hold Reset.
- Hold Boot.
- Release Reset.
- Release Boot.
Now, flash the image:
sudo upgrade_tool uf /path/to/update.img
That's the basic process done. Let's move onto customisation of the image.
Adding userspace utilities
I mentioned earlier that we need to install wpa_supplicant. This application will allow us to configure our wifi interface. Additionally, we will install bluez5-utils and bluez5-tools , which will give us Bluetooth support should we decide to use it.
Another thing worth mentions here is that esp-hosted is actually supported in Buildroot. However, because the Luckfox SDK doesn't use Buildroot for compiling the kernel (only for rootfs as far as I can tell), we can't use this package directly.
The process for adding userspace utilities is outlined quite well on the Luckfox Wiki.
Buildroot configuration
We use Buildroot to add userspace utilities via the Target packages submenu.
First, launch Buildroot by running
./build.sh buildrootconfig
While in this menu, use / to search for items. Search for wpa_supplicant. Press the associated number to jump to the package, then type y to enable the package. Do the same for bluez5-utils
Once the modules are enabled, close the Buildroot menu, and save to the default location.
Configuring the kernel
Next, we need to add Bluetooth support to the kernel. Launch the Kernel config menu by running:
./build.sh kernelconfig
Navigate to Networking support and enable Bluetooth subsystem support. Close the menu and save to default location.
Finally, rebuild the kernel and Buildroot:
./build.sh
Loading kernel modules
ESP-hosted requires two kernel modules: esp32_*.ko and cfg80211.ko. We need to build and load both of these modules for the device to function properly.
Building cfg80211.ko
The source code for cfg80211 is included in the Luckfox SDK, but it is only built when certain boards are selected in the lunch menu.
To ensure the module is built, navigate to sysdrv/cfg and update package.mk. The CONFIG_SYSDRV_ENABLE_WIFI symbol needs to be enabled as shown below:
# Enable build wifi
CONFIG_SYSDRV_ENABLE_WIFI=y
$(eval $(call MACRO_CHECK_ENABLE_PKG, RK_ENABLE_WIFI))The kernel module will then be available at /oem/usr/ko/cfg80211.ko on the built image.
Porting esp32_spi.ko
We need to make some changes to esp-hosted-ng to get our kernel module working. The diffs are given below.
The patch below circumvents an import error.
diff --git a/esp_hosted_ng/host/main.c b/esp_hosted_ng/host/main.c index 9fc5c9b..a0cc5f0 100644 --- a/esp_hosted_ng/host/main.c +++ b/esp_hosted_ng/host/main.c @@ -1142,5 +1142,6 @@ MODULE_AUTHOR("Yogesh Mantri <yogesh.mantri@espressif.com>"); MODULE_AUTHOR("Kapil Gupta <kapil.gupta@espressif.com>"); MODULE_DESCRIPTION("Wifi driver for ESP-Hosted solution"); MODULE_VERSION(RELEASE_VERSION); +MODULE_IMPORT_NS(VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver); module_init(esp_init); module_exit(esp_exit);
This change avoids the following build errors:
ERROR: modpost: module esp32_spi uses symbol kernel_read from namespace VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver, but does not import it. ERROR: modpost: module esp32_spi uses symbol filp_open from namespace VFS_internal_I_am_really_a_filesystem_and_am_NOT_a_driver, but does not import it.
We also need to update the SPI driver to use a different pinout. The pinout I am using is:
| Port | Pico Pin | ESP32-S3 Pin |
| ---------- | -------- | ------------ |
| SPI0_CS0 | 12 | IO10 |
| SPI0_CLK | 14 | IO12 |
| SPI0_MOSI | 15 | IO11 |
| SPI0_MISO | 16 | IO13 |
| Handshake | 24 | IO2 |
| Data Ready | 25 | IO4 |
| RST | 26 | RST |
To support this change, the following patch is required:
diff --git a/esp_hosted_ng/host/spi/esp_spi.h b/esp_hosted_ng/host/spi/esp_spi.h index 7ce272c..5647304 100644 --- a/esp_hosted_ng/host/spi/esp_spi.h +++ b/esp_hosted_ng/host/spi/esp_spi.h @@ -9,9 +9,9 @@ #include "esp.h" -#define HANDSHAKE_PIN 22 +#define HANDSHAKE_PIN 64 #define SPI_IRQ gpio_to_irq(HANDSHAKE_PIN) -#define SPI_DATA_READY_PIN 27 +#define SPI_DATA_READY_PIN 65 #define SPI_DATA_READY_IRQ gpio_to_irq(SPI_DATA_READY_PIN) #define SPI_BUF_SIZE 1600
Finally, we need to enable the SPI device on the Luckfox Pico, and disable the existing SPI devices. Open the file config/dts_config, and update the SPI section as follows:
/**********SPI**********/ &spi0 { status = "okay"; spidev@0 { status = "disabled"; }; fbtft@0 { status = "disabled"; }; };
The rest of the file should remain unchanged.
Finishing up
Now that everything is setup, trigger a build:
./build.sh
and flash the image.
Next, we need to build the kernel module and copy it onto the device. To build, navigate to esp-hosted/esp_hosted_ng/host and use the command below to build the module:
make -j8 target=spi \ CROSS_COMPILE=/home/dev/tools/linux/toolchain/arm-rockchip830-linux-uclibcgnueabihf/bin/arm-rockchip830-linux-uclibcgnueabihf- \ KERNEL="/home/dev/sysdrv/source/objs_kernel" \ ARCH=arm
The target=spi directive indicates we are using SPI as the transport. The function of the other variables are discussed in esp_hosted_ng/rpi_ini.sh:
# CROSS_COMPILE -> Path to toolchain # KERNEL -> Place where kernel is checked out and built # ARCH -> Architecture
The Luckfox Pico series boards use Rockchip RV110x SoCs, which are ARM-based CPUs (ARCH=arm). These need to be cross-compiled with a specialised toolchain (CROSS_COMPILE). The KERNEL variable ensures the module is built against the correct kernel libraries.
Once you've built the kernel module, you need to copy it to the Pico. I do this using scp outside of Docker:
scp /path/to/esp32_spi.ko root@192.168.20.27:/root
Eventually I'll automate the building of ESP-Hosted, such that it is built and loaded as part of the ./build.sh command.
ESP Setup
This is probably the most-straightforward part of the process. I recommend completing the following steps outside of Docker. Navigate to esp-hosted/esp_hosted_ng/esp/esp_driver, and run:
cmake .
This sets up the ESP toolchain. Next, load the toolchain:
source esp-idf/export.sh
Finally, enter the network_adapter directory and build the project:
cd network_adapter
idf.py set-target esp32s3 # Make sure you set the target
idf.py buildYou can then flash the image onto the ESP32. I suggest using flash monitor and to verify that the everything works:
idf.py flash monitor
Integration
This section assumes you've flashed the customised image on the Pico, and copied the esp32_spi.ko module onto the device. It also assumes that you have flashed the ESP32 with the network_adapter program, and the that the devices are wired up using the following pinout:
| Port | Pico Pin | ESP32-S3 Pin |
| ---------- | -------- | ------------ |
| SPI0_CS0 | 12 | IO10 |
| SPI0_CLK | 14 | IO12 |
| SPI0_MOSI | 15 | IO11 |
| SPI0_MISO | 16 | IO13 |
| Handshake | 24 | IO2 |
| Data Ready | 25 | IO4 |
| RST | 26 | RST |
Loading the kernel modules
Before loading the kernel modules, I suggest monitoring the ESP32 via serial. This will give you a good indication whether everything is working on that device.
On a separate terminal, SSH into the Pico and run the following commands to load the kernel modules:
# Load cfg80211 insmod /oem/usr/ko/cfg80211.ko # Load esp32_spi insmod esp32_spi.ko resetpin=66 clockspeed=20
Note that here we specify a reset pin and SPI clock-speed (in MHz) for the kernel module.
Next check the kernel message buffer to validate that the driver has loaded correctly:
dmesg
The output should look something like this
[ 121.318777] cfg80211: Loading compiled-in X.509 certificates for regulatory database [ 121.337254] cfg80211: Loaded X.509 cert 'sforshee: 00b28ddf47aef9cea7' [ 121.337484] platform regulatory.0: Direct firmware load for regulatory.db failed with error -2 [ 121.337500] cfg80211: failed to load regulatory.db [ 178.083812] esp32_spi: spi_dev_init: Using SPI MODE 3 [ 178.084131] esp32_spi: spi_dev_init: ESP32 peripheral is registered to SPI bus [0],chip select [0], SPI Clock [20] [ 179.549670] esp32_spi: process_esp_bootup_event: Received ESP bootup event [ 179.549794] esp32_spi: process_event_esp_bootup: Bootup Event tag: 3 [ 179.549813] esp32_spi: esp_validate_chipset: Chipset=ESP32-S3 ID=09 detected over SPI [ 179.549823] esp32_spi: process_event_esp_bootup: Bootup Event tag: 2 [ 179.549831] esp32_spi: process_event_esp_bootup: Bootup Event tag: 0 [ 179.549839] esp32_spi: process_event_esp_bootup: Bootup Event tag: 1 [ 179.549849] esp32_spi: process_fw_data: ESP chipset's last reset cause: [ 179.549856] esp32_spi: print_reset_reason: POWERON_RESET [ 179.549868] esp32_spi: check_esp_version: ESP-Hosted Version: NG-1.0.3.0.6 [ 179.550344] esp32_spi: esp_reg_notifier: Driver init is ongoing [ 179.793651] esp32_spi: init_bt: ESP Bluetooth init [ 179.793992] esp32_spi: print_capabilities: Capabilities: 0xe8. Features supported are: [ 179.794008] esp32_spi: print_capabilities: * WLAN on SPI [ 179.794016] esp32_spi: print_capabilities: * BT/BLE [ 179.794023] esp32_spi: print_capabilities: - HCI over SPI [ 179.794032] esp32_spi: print_capabilities: - BLE only
If it doesn't, read the debugging tips section. If the module was loaded correctly, and established a link to the ESP32, the wlan0 interface should appear on your device:
[root@luckfox root]# ip a 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 scope host lo valid_lft forever preferred_lft forever 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq qlen 1000 link/ether 8e:c7:1b:f4:72:de brd ff:ff:ff:ff:ff:ff inet 192.168.20.31/24 brd 192.168.20.255 scope global eth0 valid_lft forever preferred_lft forever 3: usb0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast qlen 1000 link/ether b6:c0:0d:e2:23:51 brd ff:ff:ff:ff:ff:ff inet 172.32.0.93/16 brd 172.32.255.255 scope global usb0 valid_lft forever preferred_lft forever 4: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast qlen 1000 link/ether 34:85:18:51:be:14 brd ff:ff:ff:ff:ff:ff
Now, you can run wpa_supplicant to connect to your acess point. First create a config file /etc/wpa_supplicant.conf and add the following:
network={
ssid="Your Wifi SSID"
psk="Your Wifi Password"
}Then launch wpa_supplicant:
[root@luckfox root]# wpa_supplicant -B -i wlan0 -c /etc/wpa_supplicant.conf
Successfully initialized wpa_supplicant
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
nl80211: kernel reports: Registration to specific type not supported
rfkill: Cannot open RFKILL control deviceThis launches it in the background (-B flag) using the wlan0 interface (-i flag) using the specified configuration file.
Next, you can request a IP address using udhcpc:
[root@luckfox root]# udhcpc -i wlan0 udhcpc: started, v1.36.1 udhcpc: broadcasting discover udhcpc: broadcasting select for 192.168.20.32, server 192.168.20.1 udhcpc: lease of 192.168.20.32 obtained from 192.168.20.1, lease time 86400 deleting routers adding dns 192.168.20.150 adding dns 1.1.1.1 adding dns 192.168.20.1
Running ip a again, we can see our new IP address.
[root@luckfox root]# ip a ... 4: wlan0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast qlen 1000 link/ether 34:85:18:51:be:14 brd ff:ff:ff:ff:ff:ff inet 192.168.20.32/24 brd 192.168.20.255 scope global wlan0 valid_lft forever preferred_lft forever
If everything worked you should probably do some throughput testing. More on that in a bit.
Debugging tips
I ran into many errors when trying to set this up. The most insidious was the following.
[ 304.754034] esp32_spi: spi_dev_init: Using SPI MODE 2 [ 304.754505] esp32_spi: spi_dev_init: ESP32 peripheral is registered to SPI bus [0],chip select [0], SPI Clock [1] [ 306.231909] esp32_spi: process_rx_buf: offset_rcv[6] != exp[12], drop
This indicates a timing issue with the SPI interface. I tried different clock speeds, going form 1MHz up to 30MHz, but had no success. I checked the timing with a Saleae Logic 8 and something definitely looked off.
I ended up circumventing this by switching to SPI mode 3. This can be achieved by modifying the esp-hosted source code as follows
diff --git a/esp_hosted_ng/host/spi/esp_spi.c b/esp_hosted_ng/host/spi/esp_spi.c index 1519788..f9d8675 100644 --- a/esp_hosted_ng/host/spi/esp_spi.c +++ b/esp_hosted_ng/host/spi/esp_spi.c @@ -23,7 +23,7 @@ #define TX_RESUME_THRESHOLD (TX_MAX_PENDING_COUNT/5) extern u32 raw_tp_mode; -uint8_t g_spi_mode = SPI_MODE_2; +uint8_t g_spi_mode = SPI_MODE_3; static struct sk_buff *read_packet(struct esp_adapter *adapter); static int write_packet(struct esp_adapter *adapter, struct sk_buff *skb); static void spi_exit(void); diff --git a/esp_hosted_ng/host/spi/esp_spi.h b/esp_hosted_ng/host/spi/esp_spi.h index 7ce272c..5647304 100644
diff --git a/esp_hosted_ng/esp/esp_driver/network_adapter/main/spi_slave_api.c b/esp_hosted_ng/esp/esp_driver/network_adapter/main/spi_slave_api.c index 981c12d..4f4180b 100644 --- a/esp_hosted_ng/esp/esp_driver/network_adapter/main/spi_slave_api.c +++ b/esp_hosted_ng/esp/esp_driver/network_adapter/main/spi_slave_api.c @@ -43,7 +43,7 @@ static const char TAG[] = "FW_SPI"; #define MAKE_SPI_DMA_ALIGNED(VAL) (VAL += SPI_DMA_ALIGNMENT_BYTES - \ ((VAL)& SPI_DMA_ALIGNMENT_MASK)) -uint8_t g_spi_mode = SPI_MODE_2; +uint8_t g_spi_mode = SPI_MODE_3;
After applying these patches, you need to re-flash both the Pico and the ESP32. The logic analyser showed much better SPI timing.
Depending on your setup, you may need to tune the SPI speeds. This is discussed in the next section.
Throughput Testing
There are two ways to assess the throughput of the setup: using the raw_tp_mode kernel flag or running iperf3. The raw_tp_mode flag tests the PHY (physical layer) performance between the host and the ESP32 without involving Wi-Fi. In contrast, iperf3 measures actual network performance over Wi-Fi.
Raw Throughput Testing
To test raw throughput, load the kernel module with the raw_tp_mode parameter:
insmod esp32_spi.ko resetpin=66 clockspeed=20 raw_tp_mode=x
Where x determines the test mode:
0→ Normal mode (no raw throughput test)1→ Host to ESP322→ ESP32 to Host
Raw throughput testing helps determine whether performance bottlenecks stem from the SPI interface (PHY) or Wi-Fi itself.
Wi-Fi Throughput Testing with iperf3
First, ensure the Wi-Fi interface is active and SSH into the device over Wi-Fi. Since we want to measure only Wi-Fi performance, flush the eth0 IP address and confirm it is no longer assigned:
[root@luckfox root]# ip addr flush dev eth0 [root@luckfox root]# ip a 1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue qlen 1000 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 scope host lo valid_lft forever preferred_lft forever 2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq qlen 1000 link/ether 8e:c7:1b:f4:72:de brd ff:ff:ff:ff:ff:ff ...
To verify that only Wi-Fi is active, check the routing table:
[root@luckfox root]# ip route default via 192.168.20.1 dev wlan0 172.32.0.0/16 dev usb0 scope link src 172.32.0.93 192.168.20.0/24 dev wlan0 scope link src 192.168.20.32
Since there is no eth0 route, all traffic is now running over Wi-Fi.
The iperf3 utility should be installed on the Pico image by default. To test Wi-Fi speeds, first launch an iperf3 server on your main PC:
iperf3 -s
Then, on the Pico, run a download test (Pico → PC):
iperf3 -c <ip-of-iperf3-server>
To measure upload performance (PC → Pico), add the -R flag:
iperf3 -c <ip-of-iperf3-server> -R
Here were my test results for iperf3
# Download (Pico -> PC) [ ID] Interval Transfer Bitrate Retr [ 5] 0.00-10.00 sec 14.7 MBytes 12.3 Mbits/sec 0 sender [ 5] 0.00-10.46 sec 14.6 MBytes 11.7 Mbits/sec receiver # Upload (PC -> Pico, -R) [ ID] Interval Transfer Bitrate Retr [ 5] 0.00-10.29 sec 17.0 MBytes 13.9 Mbits/sec 0 sender [ 5] 0.00-10.00 sec 13.2 MBytes 11.1 Mbits/sec receiver
Wi-Fi speeds ranged between 11–14 Mbps, which is reasonable given the SPI-based transport.
Optimising Throughput
To increase throughput, increase the SPI clock speed.
On the host side, modify the clockspeed argument when loading the kernel module:
insmod esp32_spi.ko resetpin=66 clockspeed=<desired_speed> raw_tp_mode=0
On the ESP32, update the SPI clock configuration in the firmware. Modify the relevant macro in:
esp_hosted_ng/esp/esp_driver/network_adapter/main/spi_slave_api.c
After making changes, recompile and flash the ESP32 firmware.
Conclusion
This marks the first installment in what I intend to be a series documenting the development of a small embedded Linux camera system. In this phase, I successfully ported ESP-Hosted to the Luckfox Pico platform and optimised its throughput. The next step will focus on refining design requirements and building a more advanced prototype.