Porting RIOT to ESP8266


I just want to let the community to know that I'm trying an ESP8266 port. At the moment

- the core's thread interface is implemented and tested, - the core's irq interface is implemented and tested, - GPIO handling module periph_gpio is implemented and tested, - small applications like ipc_pingpong with interrupts and some I/O are already working.

My next steps are to implement perihph_timer module (I'm currently working on), periph_uart module, periph_spi module and some networking.

I started with two different approaches that are both working until now

- a bare metal implementation, and - an implementation on top of the community SDK esp-open_sdk.

I really like the bare-metal implementation and would prefer this approach since it gives more control over the hardware, requires less resources and fits better RIOT-OS's core implementation approach. Furthermore, it is generic enough that it might run on other Xtensa processors.

However, once networking using the proprietary WIFI hardware is needed, it becomes unfortunately necessary to use proprietary SDK components. So it seems, that I will continue the SDK approach first.

Implementing RIOT-OS on top of the SDK is a bit tricky because the SDK already uses tasks to control the hardware timers, the WIFI hardware, the network connectivity, and so on. Therefore, it is necessary to give away the task control to the SDK from time to time to keep the SDK tasks alive. This is done by reimplementing the ets_run function, which is executed each time before the idle task of the RIOT-OS and after the timer interrupt handling.

One of the two hardware timers is used in the SDK, the other hardware timer is needed for PWM outputs. Therefore, RIOT OS timers are implemented as SDK software timers, which results in an pure accuracy of around 500 us.

That's the status for now and I hope that it might become interesting for someone. I will publish my changes at https://github.com/gschorcht/RIOT-Xtensa-ESP8266 and submit a pull request once I made some more progress.

Regards Gunar

This may or may not be useful, but a company called Whitecat have done a port of FreeRTOS to the ESP8266:


Hi Gunar,

That sounds great. I’m really looking forward to your port and can’t wait to upgrade some older ESP-projects to RIOT finally.

Thanks for working on that and letting us know. Feel free to ping me when the PR is ready and I’ll try to help with testing.




I just want to inform that I have commited a first working version of the RIOT port to ESP8266 to my fork at


Regards Gunar

Hi Gunar,

Cool, do you think you can get it in a state where you can provide a PR?

Cheers, Martine

(or, since I just saw that you provide ports for several board variations, several PRs)

Hi Martine,

yes, I will provide a PR as soon as I had a chance to test it with an external 802.15.4 module connected via SPI. Using the built-in WiFi interface will be more tricky, maybe it will never be possible.

But at the moment, I just wanted to make the code visible since some guys where already asking for.

Regards Gunar

Du you know, if your port will work on the ESP32 (the successor of the ESP8266), too?

cheers Mathias

I don’t think so.

ESP32 would need its own port since it uses a different xtensa toolchain…

That's true, it uses its own toolchain. But, at least some parts of the source code, e.g., thread and interrupt handling, could be reused. Handling of peripherals like GPIO, UART, SPI, I2C, timers a.s.o. are propably completely different. And, of course ESP32 is a dual core chip.

I will try the port to ESP32 once my ESP8266 port is stable enough.

Hi Gunar,


Hi Gunar,

may I ask you to tell us what is the current status ?



Hi Christiano,

I placed a PR on April, 11th which is still waiting for review. The status of ESP8266 port at that time is described in the pull request.


I also extended the dockerfile for riotdocker and sent a PR to integrate the toolchain. Once this PR is merged, murdock tests of ESP8266 should also pass.

In the meantime, I implemented a WiFi based netdev on top of ESP-NOW so that ESP8266 nodes can communicate using the GNRC network stack. Once, the inital version of the port is merged, I will place a PR for that.

Regards Gunar