Develop Network Applications for ESP8266 using Mongoose in Linux

Let’s discuss how to start developing network applications for ESP8266 chip using Mongoose Embedded Web Server in Linux. I will use Ubuntu, but all things can be easily adapted for any Linux distribution.

Who is who

Since you started reading this article, I assume you know about Linux, ESP8266 and Mongoose. So only a short intro.


Inexpensive chip with integrated WiFi, developed by Expressif. If you want to dive into more detail, check out the official site.


Mongoose is a complete multi-protocol library with a core of under 40kB developed by Cesanta. Find mode information about it on the Cesanta site.


Really? :-)

Connecting ESP8266 to your computer

Ok, we first need to connect the ESP8266 chip to your computer. You can do it in several ways.


If you have a NodeMCU module, with onboard UART-to-USB converter all you have to do is connect the module to computer via USB. KISS!

Connecting with external UART-USB converter

If your ESP module doesn’t have an internal UART-USB converter you need an external one. There are a tons of them - just google it.

Select one that works with Linux (basically, most of them) and has a 3.3V pin and remember: most of UART-USB convertors have pins for both 3.3V and 5V but you should not connect ESP to 5V pins. This device is not voltage tolerant and it is possible to burn out your module.

Now connect (ESP -> Convertor):

VCC -> 3.3V


RX0 -> TX (not RX)

TX0 -> RX

CH_PD -> 3.3V

Connecting with Arduino

If you don’t have a UART-USB converter, but have Arduino with 3.3V pins you can easily use it to connect ESP:

  1. Connect Arduino to computer via USB
  2. Connect Arduino’s RESET to its GND: it is required to disable the host processor, because we need only UART-USB module
  3. Connect ESP (ESP -> Arduino)
    1. VCC -> 3.3V
    2. GND -> GND
    3. RX0 -> RX0 (not TX)
    4. TX0 -> TX
    5. CH_PD -> 3.3V

Verifying connection

If your connection is ok, ESP should appear as a new tty device. Usually, NodeMCU and ESP connected via UART-USB convertor appear as /dev/ttyUSBx (x = 0, 1, 2 etc) and Arduino’s version appears as /dev/ttyACMx (x = 0, 1, 2 etc)

You can use command dmesg | grep usb to find your device.

For example, after connection of NodeMCU you’ll see something like that:


[  1496.765417] usb 2-3.3: new full-speed USB device number 15 using xhci_hcd
[ 1496.867729] usb 2-3.3: New USB device found, idVendor=10c4, idProduct=ea60
[ 1496.867736] usb 2-3.3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[ 1496.867740] usb 2-3.3: Product: CP2102 USB to UART Bridge Controller
[ 1496.867743] usb 2-3.3: Manufacturer: Silicon Labs
[ 1496.867745] usb 2-3.3: SerialNumber: 4202
[ 1497.900384] usbcore: registered new interface driver usbserial
[ 1497.900423] usbcore: registered new interface driver usbserial_generic
[ 1497.900457] usbserial: USB Serial support registered for generic
[ 1497.903897] usbcore: registered new interface driver cp210x
[ 1497.903989] usbserial: USB Serial support registered for cp210x
[ 1497.904382] usb 2-3.3: cp210x converter now attached to ttyUSB0

As you can see, NodeMCU is now available as /dev/ttyUSB0.

As a  final check, use any terminal to connect to a new device; I’m going to use picocom. This is a lightweight terminal. In Ubuntu it can be installed with: 

sudo apt install picocom


picocom /dev/ttyUSB0 -b 115200

If everything is ok, you should see “Terminal ready” in picocom output.

Fixing “Access Denied” error

If picocom says “Access Denied” that usually means, that the current user is not member of the dialout group: in Linux, in order to access serial ports user must be a member of this group.


sudo usermod -aG docker $USER

command, logout, login back in and try to connect ESP again. “Access denied” should be gone.

Building Mongoose

Download latest Mongoose release from here.

Mongoose is shipped with an example for ESP8266 and RTOS SDK. Turorial and sample code for it is located here.

Note: ESP8266 has two version of SDK. The first is a non-OS and the second is RTOS based. In this article I’ll use the latter. To find the differences between them, google or read this answer at the official forum.

To build the example you have two options:

  1. Use docker and ready-to-use docker images
  2. Install SDK and toolchain on your computer

Using Docker

This is simpler and I believe the better way. Cesanta’s docker images contains everything you need to build Mongoose for ESP (and not just Mongoose only - any ESP application). So, you don’t need to install stuff locally and you can easily share you code with friends and colleagues so they will be able to build your firmware and get the exact the same result.

The docker installation guide is available here. Try, it is really simple, you just need to add the docker repository to your Linux and install it as a usual program with apt.

Once docker is installed go to the mongoose/examples/ESP8266_RTOS folder and run

On the first build docker will download the required image. It may take a while, depending on your internet channel. But, once is completed in ./bin folder you’ll find two .bin files.

That is the firmware. You did this!

Using local SDK

If docker is too simple for you or for any reason you want to use locally installed tools, you can do that as well.

It is a bit harder and boring, but nothing too complicated. Especially, given that Cesanta built  some tools for you and you don’t need to build them from source.

This is how it works:

  1. Clone ESP RTOS SDK from this repo. The example makefile looks for it in the /opt/ESP8266_RTOS_SDK folder, thus, you can either put a cloned repo to this folder or modify the path to it before building the example (see below).
  2. Download xtensa-lx106-elf.tar.bz2 from this public folder.
  3. Unpack xtensa-lx106-elf.tar.bz2 file. For example, to /opt folder:

    sudo tar -xvf xtensa-lx106-elf.tar.bz2 -C /opt

  4. Modify your PATH variable, for example, it you unpacked toolchain to /opt folder use the following command:

    export PATH=/opt/xtensa-lx106-elf/bin:$PATH

(also I’d recommend to add this command to your .bashrc or .profile folders, to keep the changes after system reboot)

Now run:

$ export SDK_PATH=/opt/ESP8266_RTOS_SDK  # Put your path to SDK here
$ export BIN_PATH=./bin; mkdir ./bin
$ make clean; make BOOT=none APP=0 SPI_SPEED=40 SPI_MODE=dio SPI_SIZE_MAP=0

And now, if everything is installed correctly you’ll have the firmware in ./bin folder

You did it again!

Flashing ESP

There are a lot of tools available to flash ESP8266. We are going to use esptool. To use it, clone this repo and add the path to in your PATH variable (this is optional, and just convenient).

Now, disconnect picocom, if still connected (Hint: press Ctrl+A; Ctrl+D to exit from it) and run: --port /dev/ttyUSB0 --baud 230400 \
   write_flash --flash_mode=dio --flash_size=4m \
   0x00000 ${BIN_PATH}/eagle.flash.bin \
   0x20000 ${BIN_PATH}/eagle.irom0text.bin \
   0x7e000 ${SDK_PATH}/bin/esp_init_data_default.bin

Important note: if your module is not a NodeMCU, you need to ground GPIO0 before flashing (grounding GPIO0 switches the module to flashing mode). After flashing, disconnect GPIO0 from ground and restart ESP.

If no errors occured, you’ll see the output like this:


Erasing flash...

Took 0.58s to erase flash block

Wrote 35840 bytes at 0x00000000 in 1.8 seconds (157.5 kbit/s)...

Erasing flash...

Took 2.02s to erase flash block

Wrote 301056 bytes at 0x00020000 in 15.4 seconds (156.7 kbit/s)...

Erasing flash...

Took 0.11s to erase flash block

Wrote 1024 bytes at 0x0007e000 in 0.1 seconds (163.5 kbit/s)...


Ready! Now the device is flashed with your firmware.

First results

Now you should see a “Mongoose” WiFi network appear. The example sets up an AP. Use password “Mongoose” to connect, then navigate to, and you will see a “Hello, world” greeting page.

Congratulations! You just run Web Server on ESP8266!

Next steps

Next steps depend on you. You can use the described example as a starting point.  

Look to its user_main.c file. It sets up a WiFi access point and starts web server. You can easily change the AP mode to a station mode (and connect to your WiFi network) and use the Mongoose API to implement whatever you want. This is a common way to use Mongoose, so, you can use another Mongoose example to build your program and have http, tcp, udp, mqtt and more more more features on your ESP device.

Use Espressif documents (for example this one) to learn how to rule ESP8266 WiFi module (and not WiFi only) and Mongoose documentation to discover Mongoose features.

Punks not dead!

Share this page:

0 Comment(s)