linux download tool without python (ESF-272)

[snowmouse]

Is your feature request related to a problem?

Our board runs Linux, and the application layer does not support Python. An external ESP32 C5 module is used, which requires the SDIO interface for firmware downloading. We need to adapt the ESP32 flashing tool for this setup. How should I proceed with this adaptation, and are there any documents or similar projects available for reference?

Describe the solution you'd like

Our board runs Linux, and the application layer does not support Python. An external ESP32 C5 module is used, which requires the SDIO interface for firmware downloading. We need to adapt the ESP32 flashing tool for this setup. How should I proceed with this adaptation, and are there any documents or similar projects available for reference?

Describe alternatives you've considered

No response

Additional context

No response

[github-actions]

Hi @snowmouse! Please be aware that (1) the following suggestions are generated by a bot and haven't been fact-checked by Espressif Systems, (2) burning eFuses and enabling security features are irreversible operations and can damage your ESP32 device. We hope that this message will help you until an Espressif Engineer looks at your issue.

---

You don’t have to use Python on the target system; there are two main approaches you can use on Linux without a Python runtime, and both already support ESP32‑C5 with SDIO download:

---

1. Use esp-serial-flasher (C library, SDIO support)

Espressif provides esp-serial-flasher, a C/C++ component that implements the esptool serial/SDIO protocol and is intended exactly for “host MCU / non‑Python” flashing use cases. The SDIO example explicitly lists ESP32‑C5 as a supported target.[esp-serial-flasher]

Key points:

• Supports SDIO download to targets with SDIO download support, including ESP32‑C5.[esp-serial-flasher]
• Implemented as a C component you can integrate into your own Linux application (no Python needed).
• Example flow:
  1. Initialize SDIO host (slot 1).
  2. Put ESP32‑C5 into joint download mode and call esp_loader_connect().
  3. Call esp_loader_flash_start() with size.
  4. Repeatedly call esp_loader_flash_write() until the whole image is written.[esp-serial-flasher]

The example project shows exactly how to wire an Espressif host SoC to an Espressif target over SDIO and how to structure the flashing sequence.[esp32_sdio_example]

This is the closest “ready‑made” reference for what you want to implement on your Linux board.

---

2. Use a non‑Python PC tool during production (if acceptable)

If flashing is only needed in production (not by your Linux application at runtime), you can:

• Use esptool from a development PC (Python‑based) or its pre‑built binaries (no Python install required on that PC).[esptool install]
• Or use other host‑side tools such as:
  • esptool.js (JavaScript / Node.js),
  • espflash (Rust),
  • OpenOCD (JTAG).[esptool alternatives]

But these are still “PC‑side” tools, not something you embed into your Linux application layer.

---

3. Reference designs for SDIO‑based host flashing

For SDIO specifically, there are two good reference designs:

1. esp-serial-flasher SDIO example – shows host‑side C code and SDIO wiring for flashing ESP32‑C5/ESP32‑C6 from another Espressif SoC.[esp32_sdio_example]
2. ESP‑Hosted SDIO setup – shows SDIO wiring and Linux host driver for using ESP32‑C5/C6/ESP32 as a Wi‑Fi/BT peripheral over SDIO.[SDIO setup]

While ESP‑Hosted is for runtime Wi‑Fi/BT, its SDIO hardware notes (pull‑ups, wiring, etc.) are directly applicable to your flashing setup.[SDIO setup]

---

4. If you need to implement the protocol yourself

If you decide not to use esp-serial-flasher and instead implement your own tool:

• The ESP32 serial/bootloader protocol is documented and used by esptool; Espressif recommends it as the reference for host‑side flashing implementations.[Firmware update FAQ]
• esp-serial-flasher is still the best concrete C reference implementation of that protocol over SDIO.

---

Recommended path for your use case

Given:

• Linux board, no Python in application layer.
• External ESP32‑C5, SDIO download required.

The recommended solution is:

1. Integrate esp-serial-flasher into your Linux application as a C component.
2. Use the SDIO example as a template for:
   • SDIO host initialization on your SoC,
   • calling esp_loader_connect(), esp_loader_flash_start(), esp_loader_flash_write() with your own binaries.[esp-serial-flasher; [esp32_sdio_example](https://github.com/espressif/esp-serial-flasher/blob/master/examples/esp32_sdio_example/README.md)]
3. Follow the SDIO pull‑up and wiring guidance from the SDIO hardware docs and ESP‑Hosted SDIO setup.[esp-serial-flasher; [SDIO setup](https://github.com/espressif/esp-hosted/blob/master/esp_hosted_fg/docs/Linux_based_host/SDIO_setup.md)]

If you reply on GitHub, you can point the customer directly to:

• esp-serial-flasher component and its SDIO example.
• The SDIO hardware notes in the ESP‑Hosted SDIO setup document.

[Dzarda7]

Hello @snowmouse, happy to hear that you want to use this library. I noticed that SDIO flashing is starting to gain popularity. We did not tested any other port yet other than ESP-IDF for SDIO, but there is no reason it should not work.

There is a description on how to add support for a new platform. There you can see what functions needs to be implemented. You can take a look how esp32_sdio_port.c and esp32_sdio_port.h is implemented and take inspiration there. Also here is the esp32_sdio_example. It should not be that hard I believe if you find appropriate library or direct kernel syscalls to communicate with SDIO on linux, it should not be a problem. I am not really familiar with SDIO on linux so this part you would have to determine yourself. I believe that used functions depends whether it will be kernel modul or user-space app. Here you can see how a new port is added even with example. Only difference is that you need to specify SERIAL_FLASHER_INTERFACE_SDIO. If you won't be sure, feel free to open PR and I can take a look.

I would start testing with contributing to esp-serial-flasher library option as this should be simpler to set up, then it can be simply modified as submodule.

I plan to rewrite raspberry port to be generic linux port, so I will also consider adding support for SDIO, but not sure when or if.

[snowmouse]

I opened esp32_sdio_example to compile and got a bunch of errors, including some undefined structures. I want to understand in what format SDIO needs to send flashing data, whether it is written by blocks or by byte, and so on.

[Dzarda7]

esp32_sdio_example works for me, just tested and no issue. Did you provide the binaries to the example? Regarding the communication. You should not need to take care of it, this library sends the necessary data, you only implement read write and some other functions, but if you are interested, the communication description is kinda described here this way it is implemented in protocol_sdio.c.

[snowmouse]

esp_loader_error_t loader_initialize_conn(esp_loader_connect_args_t *connect_args)
{
s_sip_seq_tx = 0;

RETURN_ON_ERROR(initialize_connection(connect_args));

RETURN_ON_ERROR(slave_detect_chip());

RETURN_ON_ERROR(slave_init_link());

RETURN_ON_ERROR(slave_upload_stub());

loader_port_delay_ms(STUB_BOOT_TIMEOUT);

RETURN_ON_ERROR(initialize_connection(connect_args));

RETURN_ON_ERROR(slave_init_link());

RETURN_ON_ERROR(stub_wait_ready(STUB_DEFAULT_TIMEOUT, false));

esp_stub_set_running(true);

s_sip_seq_tx = 0;

return ESP_LOADER_SUCCESS;

}
after slave_upload_stub(), I read reg SD_IO_CCCR_FN_ENABLE failed ? I do not konw what reason.
And what sdmmc_card_init do?

[snowmouse]

Why do we need to execute the initialize_connection function twice，and I use sdio interface，I cannot see the implementation of the sdmmc_card_init function, what does this function do？

[Dzarda7]

You are able to upload stub and then it fails? initialize_connection needs to be done twice because first connection is established with ROM and when stub is uploaded, it needs to be initialized too.

sdmmc_card_init is ESP-IDF function that basically handles ESP SDIO slave initialization, this is function that you need to implement in loader_port_sdio_card_init. I will consider better documentation of this, thanks for raising this question. Feel free to ask more questions, I am ready to help.

[snowmouse]

When I flash more than 2MB of space, an error occurs, while flashing within 2MB works fine. The module used is esp32c5, and the flash size obtained by the esp_loader_flash_detect_size function is 8MB. What could be the reason for this? Could it be that the stub code is limiting the size?

[Dzarda7]

@snowmouse You are right, this is the bug. I will investigate and fix ASAP, thanks.

[snowmouse]

Thank you very much! The project timeline is tight, hopefully it won't take too long

[Dzarda7]

I believe I have this fixed, after review it will be merged. Should not take more than day or two. BTW we started merging changes for release v2, so you would need to use branch v1 into which I will backport this. You do not need this to be released right? Commit in the branch is enough.

[snowmouse]

Excellent, I tried the v1 branch you provided but couldn't access it. Has it not been uploaded yet?