[HELP] ESP32 Support for PX4 on NuttX 12.12

[henrykotze]

Description

am currently working on getting PX4 running on the ESP32 with NuttX 12.12.0, and I’m reaching out for guidance on some linking issues I am encountering.

There is a draft PR for updating PX4’s NuttX version to 12.12.0: PX4/PX4-Autopilot#26215

I would like to extend this update to include ESP32 support so that I can take advantage of the many improvements between NuttX 10.3 and 12.12 in our PX4-based solution on ESP32.

Background

I previously got PX4 running on the ESP32 with NuttX 10.3 (PX4 main branch). This required collecting contributions from multiple sources and adding some final adjustments. The main challenge was compiling and linking PX4 with NuttX, and I still don’t fully understand why certain object files need to be explicitly included during linking.

---

Current Status

I am now trying to compile PX4 with NuttX 12.12 for ESP32. My efforts so far include:

Using the esp32-devkitc:wifinsh board configuration as a base.

Aligning configuration options with stable PX4 boards (e.g., STM32) to ensure consistency.

Verifying my board configuration is correct under:
PX4-Autopilot/boards/espressif/esp32/nuttx-config/nsh/defconfig

The compilation fails during the linking stage, even though compilation of individual object files succeeds.

Im receiving the following error during linking:

/home/henry/.espressif/tools/xtensa-esp-elf/esp-13.2.0_20240530/xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/13.2.0/../../../../xtensa-esp-elf/bin/ld: warning: cannot find entry symbol __start; not setting start address
Memory region         Used Size  Region Size  %age Used
             ROM:       65504 B    4194272 B      1.56%
     iram0_0_seg:        1040 B       168 KB      0.60%
     irom0_0_seg:       65520 B    3342304 B      1.96%
     dram0_0_seg:          0 GB     180736 B      0.00%
     drom0_0_seg:          0 GB    4194272 B      0.00%
    rtc_iram_seg:          0 GB         8 KB      0.00%
    rtc_slow_seg:          0 GB         4 KB      0.00%
rtc_reserved_seg:          0 GB         24 B      0.00%
      extmem_seg:          0 GB         4 MB      0.00%
[536/538] Generating ../../espressif_esp32_default.bin

I also had linking issues regarding the standard C library functions:

/home/henry/git/PX4-Autopilot/src/lib/cdev/CDev.cpp:246:(.text._ZN4cdev4CDev4pollEP4fileP6pollfdb+0x5e): undefined reference to `memset'
/home/henry/.espressif/tools/xtensa-esp-elf/esp-13.2.0_20240530/xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/13.2.0/../../../../xtensa-esp-elf/bin/ld: NuttX/nuttx/libs/libc/libc.a(lib_strncat.o): in function `strncat':
/home/henry/git/PX4-Autopilot/platforms/nuttx/NuttX/nuttx/libs/libc/string/lib_strncat.c:43:(.text.strncat+0x6): undefined reference to `strlen'

---

Key Areas Relevant to Linking

CMake startup objects / library linking
PX4-Autopilot/platforms/nuttx/CMakeLists.txt
https://github.com/henrykotze/PX4-Autopilot/blob/0f20b703d148586090d9eea0857372af1b4cdd06/platforms/nuttx/CMakeLists.txt#L245
I have added a dedicated section for handling ESP32-specific linking.

Linker scripts / memory layout
PX4-Autopilot/boards/espressif/esp32/nuttx-config/scripts/

Compiler options / toolchain definitions
PX4-Autopilot/platforms/nuttx/NuttX/Make.defs.in
I added ifdef "NuttX" checks and toolchain options for Xtensa:
https://github.com/henrykotze/PX4-Autopilot/blob/0f20b703d148586090d9eea0857372af1b4cdd06/platforms/nuttx/NuttX/Make.defs.in#L61

else ifeq ($(CONFIG_ARCH_XTENSA),y)
    include $(TOPDIR)/arch/xtensa/src/lx7/Toolchain.defs

---

Repository and Build Info

Branch being compiled: esp32-nuttx-12-12-0

Build command:

make espressif_esp32

Toolchain: xtensa-esp-elf-gcc (crosstool-NG esp-13.2.0_20240530) 13.2.0

---

Request for Assistance

I would greatly appreciate if someone could:

Attempt compiling PX4 for ESP32 with NuttX 12.12 using the branch above.

Assist in debugging the linking issues I am encountering.

My current suspicion is that certain startup and ESP32-specific object files are not being linked correctly, despite being included in the CMake configuration. Any guidance on proper linking order or missing objects would be extremely helpful.

Verification

• I have verified before submitting the report.

[eren-terzioglu]

Hi,

Seems you are using old version of toolchain. Please use our suggested toolchain version

[cederom]

@fdcavalcanti @tmedicci can you please take a look? :-)

[cederom]

TLDR: @henrykotze please try to build using ESP-IDF-v5.5 (GCC 14.2).

Tests on my side:

1. Host:

% uname -a
FreeBSD hexagon 14.3-RELEASE-p7 FreeBSD 14.3-RELEASE-p7 GENERIC amd64

% xtensa-esp32-elf-gcc --version
xtensa-esp32-elf-gcc (crosstool-NG esp-2021r2-patch5) 8.4.0
Copyright (C) 2018 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

% git branch
* (HEAD detached at nuttx-12.12.0)

2. esp32-devkitc:nsh:

% ./tools/configure.sh -B esp32-devkitc:nsh
(..)
#
# configuration written to .config
#
hexagon% gmake -j24
Create version.h
LN: platform/board to /XXX/nuttx/nuttx-apps.git/platform/dummy
Cloning Espressif HAL for 3rd Party Platforms
Clone: chip/esp-hal-3rdparty Register: dd
Register: nsh
Register: sh
Espressif HAL for 3rd Party Platforms: 4eed03a15b2678a81dfd1ed0f3bde042b1fdd4c4
Espressif HAL for 3rd Party Platforms: initializing submodules...
Applying patches...
LD: nuttx
Memory region         Used Size  Region Size  %age Used
             ROM:      207320 B    4194272 B      4.94%
     iram0_0_seg:       30856 B       168 KB     17.94%
     irom0_0_seg:      141784 B    3342304 B      4.24%
     dram0_0_seg:       11744 B     180736 B      6.50%
     drom0_0_seg:       77676 B    4194272 B      1.85%
    rtc_iram_seg:          0 GB         8 KB      0.00%
    rtc_slow_seg:          0 GB         4 KB      0.00%
rtc_reserved_seg:          24 B         24 B    100.00%
      extmem_seg:          0 GB         4 MB      0.00%
CP: nuttx.hex
MKIMAGE: ESP32 binary
esptool.py -c esp32 elf2image --ram-only-header -fs 4MB -fm dio -ff "40m" -o nuttx.bin nuttx
esptool.py v4.10.0
Creating esp32 image...
Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended.
Merged 1 ELF section
Successfully created esp32 image.
Generated: nuttx.bin

2. esp32-devkitc:wifinsh:

% ./tools/configure.sh -B esp32-devkitc:wifinsh
  Copy files
  Select CONFIG_HOST_BSD=y
  Refreshing...
(..)
#
# configuration written to .config
#

% gmake -j24
Create version.h
LN: platform/board to /XXX/nuttx/nuttx-apps.git/platform/dummy
Downloading: v1.7.12.tar.gz
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0   0     0   0     0     0     0  --:--:-- --:--:-- --:--:--     0Cloning Espressif HAL for 3rd Party Platforms
  0     0   0     0   0     0     0     0  --:--:-- --:--:-- --:--:--     0
100 348294   0 348294   0     0 428963     0  --:--:-- --:--:-- --:--:-- 428963
Unpacking: v1.7.12.tar.gz -> cJSON
Register: dd
Register: nsh
Register: sh
Register: ping
Register: wapi
Register: renew
Register: telnetd
Espressif HAL for 3rd Party Platforms: 4eed03a15b2678a81dfd1ed0f3bde042b1fdd4c4
Espressif HAL for 3rd Party Platforms: initializing submodules...
Applying patches...
CC:  stdio/lib_fputws.c common/espressif/esp_wifi_event_handler.c: In function 'esp_evt_work_cb':
common/espressif/esp_wifi_event_handler.c:208:13: error: a label can only be part of a statement and a declaration is not a statement
             wifi_event_sta_disconnected_t *event =
             ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
common/espressif/esp_wifi_event_handler.c:210:13: error: expected expression before 'wifi_err_reason_t'
             wifi_err_reason_t reason = event->reason;
             ^~~~~~~~~~~~~~~~~
In file included from common/espressif/esp_wifi_event_handler.c:29:
common/espressif/esp_wifi_event_handler.c:212:64: error: 'reason' undeclared (first use in this function); did you mean 'read'?
             wlinfo("Wi-Fi station disconnected, reason: %u\n", reason);
                                                                ^~~~~~
common/espressif/esp_wifi_event_handler.c:212:64: note: each undeclared identifier is reported only once for each function it appears in
CC:  chip/esp-hal-3rdparty/components/mbedtls/mbedtls/library/ecp_curves.c gmake[1]: *** [Makefile:146: esp_wifi_event_handler.o] Error 1
gmake[1]: *** Waiting for unfinished jobs....
CC:  string/lib_bsdmemccpy.c gmake: *** [tools/LibTargets.mk:170: arch/xtensa/src/libarch.a] Error 2
gmake: *** Waiting for unfinished jobs....

3. Let's try on master:

% git checkout master
% ./tools/configure.sh -B esp32-devkitc:wifinsh
  Copy files
  Select CONFIG_HOST_BSD=y
  Refreshing...
(..)
#
# configuration written to .config
#

% gmake -j24
Create version.h
LN: platform/board to /XXX/nuttx/nuttx-apps.git/platform/dummy
Downloading: v1.7.12.tar.gz
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0   0     0   0     0     0     0  --:--:-- --:--:-- --:--:--     0Cloning Espressif HAL for 3rd Party Platforms
  0     0   0     0   0     0     0     0  --:--:-- --:--:-- --:--:--     0
100 348294   0 348294   0     0 493534     0  --:--:-- --:--:-- --:--:-- 493534
Unpacking: v1.7.12.tar.gz -> cJSON
Register: telnetd
Register: nsh
Register: sh
Register: dd
Register: ping
Register: renew
Register: wapi
Espressif HAL for 3rd Party Platforms: b9472bd56b916cced7447e25c2b2e1390d7e0d90
Espressif HAL for 3rd Party Platforms: initializing submodules...
Applying patches...
common/espressif/esp_wifi_event_handler.c: In function 'esp_evt_work_cb':
common/espressif/esp_wifi_event_handler.c:208:13: error: a label can only be part of a statement and a declaration is not a statement
             wifi_event_sta_disconnected_t *event =
             ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~
common/espressif/esp_wifi_event_handler.c:210:13: error: expected expression before 'wifi_err_reason_t'
             wifi_err_reason_t reason = event->reason;
             ^~~~~~~~~~~~~~~~~
CC:  stdio/lib_vfscanf.c In file included from common/espressif/esp_wifi_event_handler.c:29:
common/espressif/esp_wifi_event_handler.c:212:64: error: 'reason' undeclared (first use in this function); did you mean 'read'?
             wlinfo("Wi-Fi station disconnected, reason: %u\n", reason);
                                                                ^~~~~~
common/espressif/esp_wifi_event_handler.c:212:64: note: each undeclared identifier is reported only once for each function it appears in
CC:  stdio/lib_tmpfile.c gmake[1]: *** [Makefile:146: esp_wifi_event_handler.o] Error 1
gmake[1]: *** Waiting for unfinished jobs....
gmake: *** [tools/LibTargets.mk:170: arch/xtensa/src/libarch.a] Error 2
gmake: *** Waiting for unfinished jobs....

4. Let's try to update build tools to ESP-IDF-v5.5 (GCC 14.2):

• Note that I use natively FreeBSD not Linux. Its a hacky way of working with ESP's Linux build tools. I patched upstream to use Linux binaries on FreeBSD by detecting FreeBSD as Linux because it can run Linux ELF binaries. I did not manage to install full esp-idf python env (5.5-3.11) because of dependencies problems these are not provided as packages here too who cares about anything other than Linux ;-) Anyways the compiler is all I need :-)

(idf5.5_py3.11_env) % idf_tools.py list
* xtensa-esp-elf-gdb: GDB for Xtensa
  - 16.3_20250913 (recommended, installed)
* riscv32-esp-elf-gdb: GDB for RISC-V
  - 16.3_20250913 (recommended, installed)
* xtensa-esp-elf: Toolchain for 32-bit Xtensa based on GCC
  - esp-14.2.0_20251107 (recommended, installed)
* esp-clang: Toolchain for all Espressif chips based on clang (optional)
  - esp-19.1.2_20250312 (recommended)
* esp-clang-libs: Standalone Clang shared libraries distribution (optional)
  - esp-19.1.2_20250312 (recommended)
* riscv32-esp-elf: Toolchain for 32-bit RISC-V based on GCC
  - esp-14.2.0_20251107 (recommended, installed)
* esp32ulp-elf: Toolchain for ESP32 ULP coprocessor
  - 2.38_20240113 (recommended, installed)
* cmake: CMake build system (optional)
  - 3.30.2 (recommended)
  - 3.16.3 (supported)
* openocd-esp32: OpenOCD for ESP32
  - v0.12.0-esp32-20251215 (recommended)
* ninja: Ninja build system (optional)
  - 1.12.1 (recommended)
* esp-rom-elfs: ESP ROM ELFs
  - 20241011 (recommended)
* qemu-xtensa: QEMU for Xtensa (optional)
  - esp_develop_9.2.2_20250817 (recommended)
* qemu-riscv32: QEMU for RISC-V (optional)
  - esp_develop_9.2.2_20250817 (recommended)

% xtensa-esp32-elf-gcc --version
xtensa-esp-elf-gcc (crosstool-NG esp-14.2.0_20251107) 14.2.0
Copyright (C) 2024 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

% git checkout nuttx-12.12.0
HEAD is now at 54b5a8f2c3 LICENSE: update NuttX-PublicDomain SPDX identifier

% ./tools/configure.sh -B esp32-devkitc:wifinsh
  Copy files
  Select CONFIG_HOST_BSD=y
  Refreshing...
(..)
#
# configuration written to .config
#

% gmake -j24
Create version.h
LN: platform/board to /XXX/nuttx/nuttx-apps.git/platform/dummy
Downloading: v1.7.12.tar.gz
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0   0     0   0     0     0     0  --:--:-- --:--:-- --:--:--     0Cloning Espressif HAL for 3rd Party Platforms
  0     0   0     0   0     0     0     0  --:--:-- --:--:-- --:--:--     0
100 348294 100 348294   0     0 599598     0  --:--:-- --:--:-- --:--:--  1668k
Unpacking: v1.7.12.tar.gz -> cJSON
Register: wapi
Register: nsh
Register: dd
Register: sh
Register: telnetd
Register: renew
Register: ping
Espressif HAL for 3rd Party Platforms: 4eed03a15b2678a81dfd1ed0f3bde042b1fdd4c4
Espressif HAL for 3rd Party Platforms: initializing submodules...
Applying patches...
CPP:  (..): nuttx
Memory region         Used Size  Region Size  %age Used
             ROM:      732544 B    4194272 B     17.47%
     iram0_0_seg:      106664 B       168 KB     62.00%
     irom0_0_seg:      601472 B    3342304 B     18.00%
     dram0_0_seg:       81672 B     180736 B     45.19%
     drom0_0_seg:      140888 B    4194272 B      3.36%
    rtc_iram_seg:           0 B         8 KB      0.00%
    rtc_slow_seg:           0 B         4 KB      0.00%
rtc_reserved_seg:          24 B         24 B    100.00%
      extmem_seg:           0 B         4 MB      0.00%
CP: nuttx.hex
MKIMAGE: ESP32 binary
esptool.py -c esp32 elf2image --ram-only-header -fs 4MB -fm dio -ff "40m" -o nuttx.bin nuttx
esptool.py v4.10.0
Creating esp32 image...
Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended.
Merged 1 ELF section
Successfully created esp32 image.
Generated: nuttx.bin

5. Now let's try esp32-devkitc:wifinsh on Linux with ESP-IDF-v5.5:

• Note that I am using Debian12 debootstrapped on top of FreeBSD :-)

$ uname -a
Linux hexagon 5.15.0 FreeBSD 14.3-RELEASE-p7 GENERIC x86_64 GNU/Linux

$ cd ~/.espressif/esp-idf.git/
$ git fetch --all
$ git checkout release/v5.5
$ ./install.sh <-- all went fine because linux
$ . ~/.espressif/esp-idf.git/export.sh
Checking "python3" ...
Python 3.11.2
"python3" has been detected
Activating ESP-IDF 5.5
Setting IDF_PATH to '/home/cederom/.espressif/esp-idf.git'.
* Checking python version ... 3.11.2
* Checking python dependencies ... OK
* Deactivating the current ESP-IDF environment (if any) ... OK
* Establishing a new ESP-IDF environment ... OK
* Identifying shell ... bash
* Detecting outdated tools in system ... OK - no outdated tools found
* Shell completion ... Autocompletion code generated

Done! You can now compile ESP-IDF projects.
Go to the project directory and run:

  idf.py build

$ cd tools/
$ ./idf_tools.py list
* xtensa-esp-elf-gdb: GDB for Xtensa
  - 16.3_20250913 (recommended, installed)
* riscv32-esp-elf-gdb: GDB for RISC-V
  - 16.3_20250913 (recommended, installed)
* xtensa-esp-elf: Toolchain for 32-bit Xtensa based on GCC
  - esp-14.2.0_20251107 (recommended, installed)
* esp-clang: Toolchain for all Espressif chips based on clang (optional)
  - esp-19.1.2_20250312 (recommended)
* esp-clang-libs: Standalone Clang shared libraries distribution (optional)
  - esp-19.1.2_20250312 (recommended)
* riscv32-esp-elf: Toolchain for 32-bit RISC-V based on GCC
  - esp-14.2.0_20251107 (recommended, installed)
* esp32ulp-elf: Toolchain for ESP32 ULP coprocessor
  - 2.38_20240113 (recommended, installed)
* cmake: CMake build system (optional)
  - 3.30.2 (recommended)
  - 3.16.3 (supported)
* openocd-esp32: OpenOCD for ESP32
  - v0.12.0-esp32-20251215 (recommended, installed)
* ninja: Ninja build system (optional)
  - 1.12.1 (recommended)
* esp-rom-elfs: ESP ROM ELFs
  - 20241011 (recommended, installed)
* qemu-xtensa: QEMU for Xtensa (optional)
  - esp_develop_9.2.2_20250817 (recommended)
* qemu-riscv32: QEMU for RISC-V (optional)
  - esp_develop_9.2.2_20250817 (recommended)

$ xtensa-esp32-elf-gcc --version
xtensa-esp-elf-gcc (crosstool-NG esp-14.2.0_20251107) 14.2.0
Copyright (C) 2024 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


$ cd XXX/nuttx.git
$ git checkout nuttx-12.12.0
HEAD is now at 54b5a8f2c3 LICENSE: update NuttX-PublicDomain SPDX identifier

$ ./tools/configure.sh esp32-devkitc:wifinsh
  Copy files
  Select CONFIG_HOST_LINUX=y
  Refreshing...
(..)
#
# configuration written to .config
#

$ make -j
Create version.h
Cloning Espressif HAL for 3rd Party Platforms
Clone: chip/esp-hal-3rdparty Downloading: v1.7.12.tar.gz
LN: platform/board to /XXX/nuttx/nuttx-apps.git/platform/dummy
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100  340k    0  340k    0     0   436k      0 --:--:-- --:--:-- --:--:--  436k
Unpacking: v1.7.12.tar.gz -> cJSON
Register: renew
Register: nsh
Register: sh
Register: telnetd
Register: dd
Register: ping
Register: wapi
Espressif HAL for 3rd Party Platforms: 4eed03a15b2678a81dfd1ed0f3bde042b1fdd4c4
Espressif HAL for 3rd Party Platforms: initializing submodules...
Applying patches...
LD: nuttx
Memory region         Used Size  Region Size  %age Used
             ROM:      732544 B    4194272 B     17.47%
     iram0_0_seg:      106664 B       168 KB     62.00%
     irom0_0_seg:      601472 B    3342304 B     18.00%
     dram0_0_seg:       81672 B     180736 B     45.19%
     drom0_0_seg:      140888 B    4194272 B      3.36%
    rtc_iram_seg:           0 B         8 KB      0.00%
    rtc_slow_seg:           0 B         4 KB      0.00%
rtc_reserved_seg:          24 B         24 B    100.00%
      extmem_seg:           0 B         4 MB      0.00%
CP: nuttx.hex
MKIMAGE: ESP32 binary
esptool.py -c esp32 elf2image --ram-only-header -fs 4MB -fm dio -ff "40m" -o nuttx.bin nuttx
esptool.py v4.11.dev2
Creating esp32 image...
Image has only RAM segments visible. ROM segments are hidden and SHA256 digest is not appended.
Merged 1 ELF section
Successfully created esp32 image.
Generated: nuttx.bin

[tmedicci]

Thanks for the tests @cederom !

Indeed, I tried it myself without any problems with wifinsh defconfig and the recommended toolchain. These defconfigs are also tested daily on our internal pipeline.

About the errors, @henrykotze :

/home/henry/.espressif/tools/xtensa-esp-elf/esp-13.2.0_20240530/xtensa-esp-elf/bin/../lib/gcc/xtensa-esp-elf/13.2.0/../../../../xtensa-esp-elf/bin/ld: warning: cannot find entry symbol __start; not setting start address
Memory region         Used Size  Region Size  %age Used
             ROM:       65504 B    4194272 B      1.56%
     iram0_0_seg:        1040 B       168 KB      0.60%
     irom0_0_seg:       65520 B    3342304 B      1.96%
     dram0_0_seg:          0 GB     180736 B      0.00%
     drom0_0_seg:          0 GB    4194272 B      0.00%
    rtc_iram_seg:          0 GB         8 KB      0.00%
    rtc_slow_seg:          0 GB         4 KB      0.00%
rtc_reserved_seg:          0 GB         24 B      0.00%
      extmem_seg:          0 GB         4 MB      0.00%
[536/538] Generating ../../espressif_esp32_default.bin

Probably the entry symbol, referent to this function isn't being compiled. This is the firmware entrypoint and it's mandatory.

About the libc functions: there are a bunch of functions defined in the ESP32's ROM memory. Those are defined by a specific linker script by the esp-hal-3rdparty repository. They are linked here. When building NuttX, it would be available at arch/xtensa/src/chip/esp-hal-3rdparty/components/esp_rom/esp32/ld/esp32.rom.libc-funcs.ld. You either need to clone it and use it by yourself or use NuttX's building system and include this linker file. Please note that each version of NuttX is bound to a specific version of the HAL repository here. Make sure you checkout to this version.

[henrykotze]

Hi All,

Thank you so much for the feedback. Greatly appreciate it. I will proceed with the suggestions, and report back given anything new.