In this laboratory you will learn how to build and upload the NuttX OS on your ESP32 Sparrow boards. They use the WROVER modules, so we'll need to specify this when we build the OS binaries.

You can go ahead to section [Compiling NuttX].

If running on Windows, you must configure a Linux virtual machine through which to access the USB ports of the host. For this you can use the SO virtual machine - a light Ubuntu 20.04 image that comes only with a CLI - or download the latest official image of any other Linux distributions.

If available to you, you can use the VMware Workstation 16 pro which is the easiest to configure - just don't forget to add the USB controller to the VM.

If you do not have access to VMWare, please download VirtualBox. In order to ssh to your virtual machine, please do the following steps:

• add a second network adapter to the VM. The first must be a host-only device in order to provide connectivity from host to guest, while the second will be under NAT and will provide Internet acces.
• boot the virtual machine. Test with ping 8.8.8.8 that you have Internet connectivity
• add a static IP address on the second interface in the 192.168.56.0/56 subnetwork. For mine I used 192.168.56.56/24.

To connect the USB device to the VM instead of the host, head to the upper bar and select Devices > USB Devices > the UART controller .

Currently, the WSL subsystem does not provide native support for USB devices and you must use an open-source tool. Please refer to this for further details.

Follow the steps below in order to get your Linux machine properly configured:

• install the package dependencies
• download the toolchain, since we won't be able to compile with the standard gcc compiler
• clone the repositories: nuttx, nuttx-apps
• download the prebuilt partition table and bootloader. Alternatively, you can compile your own binaries but this tutorial does not cover it.
• compile the NuttX binary
• finally, flash the board

apt-get update
apt-get upgrade -y
apt-get install -y bison flex gettext texinfo libncurses5-dev libncursesw5-dev gperf automake libtool pkg-config build-essential gperf genromfs libgmp-dev libmpc-dev libmpfr-dev libisl-dev binutils-dev libelf-dev libexpat-dev gcc-multilib g++-multilib picocom u-boot-tools util-linux chrony libusb-dev libusb-1.0.0-dev kconfig-frontends python3-pip

wget https://github.com/espressif/crosstool-NG/releases/download/esp-12.2.0_20230208/xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz
tar -xf xtensa-esp32-elf-12.2.0_20230208-x86_64-linux-gnu.tar.xz
mkdir /opt/xtensa
mv xtensa-esp32-elf/ /opt/xtensa/
echo "export PATH=\$PATH:/opt/xtensa/xtensa-esp32-elf/bin" >> ~/.bashrc
source ~/.bashrc

mkdir ~/nuttxspace && cd ~/nuttxspace
git clone --branch=nuttx-12.5.1 https://github.com/apache/incubator-nuttx.git nuttx
git clone --branch=nuttx-12.5.1 https://github.com/apache/incubator-nuttx-apps.git apps

mkdir esp-bins
curl -L "https://github.com/espressif/esp-nuttx-bootloader/releases/download/latest/bootloader-esp32.bin" -o esp-bins/bootloader-esp32.bin
curl -L "https://github.com/espressif/esp-nuttx-bootloader/releases/download/latest/partition-table-esp32.bin" -o esp-bins/partition-table-esp32.bin

While this step is not necessary for the ESP32 Sparrow boards, please be aware that if you're compiling for a different hardware board, depending on the board version, you might be required to press down the `BOOT` button when flashing the memory - this puts the board in a download state instead of the default boot state. The button must be pressed down only when the connection is being established, as depicted below:

Use the following commands to install the necessary Python modules and configure the compile options needed for the WROVER module.

pip3 install esptool
pip3 install pyserial
cd ~/nuttxspace/nuttx
./tools/configure.sh esp32-wrover-kit:nsh

Continue compiling and uploading:

make EXTRAFLAGS="-DESP32_IGNORE_CHIP_REVISION_CHECK" -j<num_cores>
esptool.py erase_flash
make flash ESPTOOL_PORT=/dev/ttyUSB0 ESPTOOL_BAUD=115200 ESPTOOL_BINDIR=../esp-bins
picocom /dev/ttyUSB0 -b 115200

Flashing the board could be also done by using

 esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 write_flash 0x1000 ../esp-bins/bootloader-esp32.bin 0x8000 ../esp-bins/partition-table-esp32.bin 0x10000 nuttx.bin 

If the parameters are correct, you should see a log similar to the one below:

Finally, the boot log on the ESP32 board should look like this:

ESP32 boards incorporate an RF (Radio Frequency) module through which they can use Wi-Fi, Bluetooth and BLE (Bluetooth Low Energy). Since all three technologies operate at the 2.4GHz frequency, we cannot receive and send data at the same time on Wi-Fi and Bluetooth. To make this possible, time-division multiplexing is used.

In Wi-Fi communication, a device can have one of the following roles:

• Router - defines a new network;
• Access Point (AP) - a device that is part of a network, connects to the router, but is used to create subnets, e.g. a smartphone with the hotspot option configured;
• Station (STA) - a simple device connected to the network.

In the previous section, we finished our first compilation of the NuttX OS, using the default configuration for ESP32 WROVER boards with nsh, which includes the default terminal and minimal features. In NuttX, the ESP32 can run both as a station and as an access point (software access point - SoftAP - because communication management happens within the operating system, not in the hardware). Configurations like esp32-wrover-kit:wifi allow the board to function only as a station, but there is also esp32-devkitc:sta_softap, for example, which provides support for both station and SoftAP.

In order to connect the ESP32 board to an existing Wi-Fi network identified using <myssid>:<mypassword>, use the commands below:

ifup wlan0
wapi psk wlan0 <mypasswd> 3
wapi essid wlan0 <myssid> 1
renew wlan0

Because wapi essid only sets the network name internally, in order to connect to the network and obtain an IP address an explicit command is required - renew wlan0.

To configure ESP32 to run as a SoftAP (via the second available network interface - wlan1), a similar set of commands is needed:

ifup wlan1
dhcpd_start wlan1
wapi psk wlan1 <mypasswd> 3
wapi essid wlan1 nuttxapp 1

In this way, the nuttxapp network is created, also protected by WPA2 and CCMP, with the password <mypasswd>. dhcpd_start starts the dhcpd daemon, which will run a DHCP server and assign an IP to all connected devices.

A more detailed description of the API exposed by WAPI (e.g., wapi show wlan0), as well as how to connect to an unsecured network (open network), can be found here.

Additionally, another useful command to investigate the status of network interfaces is ifconfig, similar to the one in Linux.

To be able to run the exercises, you need to compile NuttX using esp32-devkitc:sta_softap, for which you will need to manually enable a few other configs, listed below. In order to modify the initial configuration, use the make menuconfig command after configuring ESP32 as sta_softap, and before starting the compilation process.

• CONFIG_NET_ROUTE=y
• CONFIG_NET_IPFORWARD=y
• CONFIG_NET_NAT=y
• CONFIG_SYSTEM_IPTABLES=y

1. Connect the ESP32 to the university network and test with ping 8.8.8.8 that you have internet access. Use the wlan0 interface.

Run the route command and inspect its output. It will be relevant to exercise 3.

2. Configure the board to run in SoftAP mode and connect your laptop to the network to test. Use the wlan1 interface. Run the route command again and notice how the routing table has changed.

3. After exercise 2, the laptop is connected to the ESP32, but has no internet access. You can test this from CMD (Windows)/terminal (Linux) using ping 8.8.8.8. Next, follow the steps below to fix the internet access issue:

1. From ESP32 run the command ping 8.8.8.8 again. Notice that you have no internet access. Configuring wlan1 as a SoftAP has broken the routing table, as can be seen from the output of the route command.
2. Set the default routing rule using the command addroute default 192.168.0.1 wlan0. ESP32 is connected to the internet again, you can test using ping.
3. The last step involves adding a rule in iptables to apply NAT on each packet routed by ESP32: iptables -t nat -A POSTROUTING -o wlan0 -j MASQUERADE.
4. Test from your personal laptop using ping, and from your browser connect to www.google.com.

• Robert Alexa's excellent tutorial on which most of the lab is based
• Embedtronix tutorial for ESP32-WROOM
• Official NuttX build tutorial
• Official NuttX ESP32 build tutorial
• Sara Monteiro's tutorial
• WAPI (Wireless API)
• Esp32, NuttX and bridged networking