Using the Moddable SDK with ESP8266

Copyright 2016-2024 Moddable Tech, Inc.
Revised: January 9, 2024

This document provides a guide to building apps for the ESP8266 and ESP8266-based development boards with the Moddable SDK.

Overview

Before you can build applications, you need to:

Install the Moddable SDK and build its tools
Install the required drivers and development tools for the ESP8266 platform

The instructions below will have you verify your setup by running the helloworld example on your device using mcconfig, a command line tool that builds and runs Moddable applications.

See the Tools documentation for more information about mcconfig

When building with mcconfig, you specify your device target by providing the platform identifier of your development board to the -p argument. For example, use the following command to build for Moddable One:

mcconfig -d -m -p esp/moddable_one

A list of available ESP8266 subplatforms and their platform identifiers is provided in the Platforms section below.

Platforms

ESP8266 has the following features:

80 MHz processor
Wi-Fi
80 KB RAM
4 MB flash

The Moddable SDK supports many devices built on ESP8266. The following table lists each device, its platform identifier, a list of key features specific to the device, and links to additional resources.

Name	Platform identifier	Key features	Links
Moddable One	`esp/moddable_one` `simulator/moddable_one`	2.4" IPS display 240 x 320 QVGA 16-bit color Capacitive touch 14 External pins	Moddable One Developer Guide Moddable product page
Moddable Display 1	`esp/moddable_display_1` `simulator/moddable_one`	2.4" IPS display 240 x 320 QVGA 16-bit color Capacitive touch 14 External pins	Moddable Display Developer Guide Moddable product page
Node MCU ESP8266	`esp/nodemcu` `simulator/nodemcu`
Moddable Three	`esp/moddable_three` `simulator/moddable_three`	2.13" ePaper display 250 x 122 pixels 1-bit black and white 11 External pins	Moddable Three Developer Guide Moddable product page
Moddable Display 3	`esp/moddable_display_3` `simulator/moddable_three`	2.13" ePaper display 250 x 122 pixels 1-bit black and white 11 External pins	Moddable Display Developer Guide Moddable product page
Moddable Zero	`esp/moddable_zero`		Moddable Zero Developer Guide

We have also used many displays with the ESP8266 Node MCU board. The following table links to wiring guides and provides corresponding platform identifiers.

Wiring guide	Platform identifier
Adafruit OLED	`esp/adafruit_oled`
Adafruit ST7735	`esp/adafruit_st7735`
Crystalfontz monochrome ePaper	`esp/crystalfontz_monochrome_epaper`
Sharp memory LCD (2.7")	`esp/sharp_memory`
Sharp memory LCD (1.3")	`esp/sharp_memory_square`
SparkFun TeensyView	`esp/sparkfun_teensyview`
Switch Science reflective LCD	`esp/switch_science_reflective_lcd`
BuyDisplay CTP	`esp/buydisplay_ctp`

macOS

The Moddable SDK build for ESP8266 currently uses ESP8266 Arduino Core 2.3.0 and ESP8266_RTOS_SDK v3.2.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create an esp directory in your home directory at ~/esp for required third party SDKs and tools.
If you are running macOS 10.15 (Catalina) or earlier, download and install the Silicon Labs CP210x USB to UART VCP driver.

If you run macOS Catalina, an extra step is required to enable the VCP driver. If you see a popup that says "System Extension Blocked" during installation, follow the instructions in the dialog to enable the extension in Security & Privacy System Preferences.

If you are using macOS 10.16 (Big Sur) or later, you do not need to install the VCP driver.
If you use macOS Catalina (version 10.15) or later, add an exemption to allow Terminal (or your alternate terminal application of choice) to run software locally that does not meet the system's security policy. Without this setting, the precompiled Xtensa toolchain you will download in the next step will not be permitted to run.

To set the security policy exemption for Terminal, go into the Security & Privacy System Preferences, select the Privacy tab, choose Developer Tools from the list on the left, and then tick the checkbox for Terminal or the alternate terminal application from which you will be building Moddable SDK apps. The end result should look like this:
Download and untar the Xtensa lx106 architecture GCC toolchain. Copy the toolchain directory into the ~/esp directory.
Download the ESP8266 core for Arduino repository. Copy the extracted esp8266-2.3.0 folder into your ~/esp directory.

Clone the ESP8266 SDK based on FreeRTOS repository into the ~/esp directory:

cd ~/esp
git clone https://github.com/espressif/ESP8266_RTOS_SDK.git

We need version 3.2:

cd ESP8266_RTOS_SDK
git checkout release/v3.2

Install Python and the required Python packages. We've used brew and pip to install the additional components:
```
brew install python
sudo easy_install pip
pip install --user pyserial
```
Connect the ESP8266 to your computer with a USB cable.

Verify the setup by building helloworld for your device target:

cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p esp/<YOUR_SUBPLATFORM_HERE>

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues on macOS and how to resolve them.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

Device not connected/recognized

The following error messages mean that the device is not connected to your computer or the computer doesn't recognize the device.

error: cannot access /dev/cu.SLAB_USBtoUART
error: cannot access /dev/usbserial-0001

There are a few reasons this can happen:

Your device is not plugged into your computer. Make sure it's plugged in when you run the build commands.
You have a USB cable that is power only. Make sure you're using a data sync-capable USB cable.
The computer does not recognize your device. To fix this problem, follow the instructions below.

Unplug the device and enter the following command.

ls /dev/cu*

Then plug in the device and repeat the same command. If nothing new appears in the terminal output, the device isn't being recognized by your computer.

If you are running macOS 10.15 or earlier, make sure you have the correct VCP driver installed. If you are running macOS 10.16 or later, you do not need to install the VCP driver.

If it is recognized, you now have the device name and you need to edit the UPLOAD_PORT environment variable. Enter the following command, replacing /dev/cu.SLAB_USBtoUART with the name of the device on your system.

export UPLOAD_PORT=/dev/cu.SLAB_USBtoUART

Updating

To ensure that your build environment is up to date, perform the following steps:

Download the ESP8266 core for Arduino repository. Copy the extracted esp8266-2.3.0 folder into your ~/esp directory.
Update your cloned copy of the ESP8266 SDK based on FreeRTOS and select the release/v3.2 branch:
```
cd ~/esp/ESP8266_RTOS_SDK
git fetch
git checkout release/v3.2
git pull
```
If you have existing ESP8266 build output in $MODDABLE/build/bin/esp or $MODDABLE/build/tmp/esp, delete those directories:
```
cd $MODDABLE/build
rm -rf bin/esp
rm -rf tmp/esp
```

Verify the setup by building helloworld for your device target:

cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p esp/<YOUR_SUBPLATFORM_HERE>

Windows

The Moddable SDK build for ESP8266 currently uses ESP8266 Arduino Core 2.3.0 and ESP8266_RTOS_SDK v3.2.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create an esp directory in your home %USERPROFILE% directory, e.g. C:\Users\<your-user-name>.
Download and install the Silicon Labs CP210x USB to UART VCP driver. The driver zip file contains x64 and x86 versions of the installer. Most modern PCs run 64-bit Windows and should use the x64 version of the VCP driver. If you run a 32-bit version of Windows, use the x86 version of the driver. (You can determine if your computer is running a 64-bit version of Windows by checking "About your PC" in System Settings.)
Download the esptool. Unzip the archive and copy the esptool.exe executable from the esptool-0.4.13-win32 directory into the esp directory.
Download and unzip the Cygwin toolchain support package. Copy the cygwin directory into the esp directory.
Download and unzip the Xtensa lx106 architecture GCC toolchain. Copy the xtensa-lx106-elf directory into the esp directory.
Download the ESP8266 core for Arduino repository. Copy the extracted esp8266-2.3.0 folder into your esp directory.

Clone the ESP8266 SDK based on FreeRTOS repository into the ~/esp directory:

cd %USERPROFILE%\esp
git clone https://github.com/espressif/ESP8266_RTOS_SDK.git

We need version 3.2:

cd ESP8266_RTOS_SDK
git checkout release/v3.2

Download and run the Python installer for Windows. Choose the default options.
Open the "Environment Variables" dialog of the Control Panel app by following these instructions. From that dialog: - Edit the Path System Variable to include the Python executable directories and the cygwin\bin directory.
- Variable name: Path
- Variable value (add to the existing list): C:\Python27
- Variable value (add to the existing list): C:\Python27\Scripts

> Note: You will need to add additional environment variables in a later step, after installing pyserial. But be sure to hit `OK` on the Environment Variables dialog and apply your changes here before continuing.

Open a "Command Prompt" window and install the pyserial Python Serial Port Extension:
```
pip install pyserial
```
Connect the ESP8266 to your computer with a USB cable.
Launch the Windows Device Manager, open the "Ports (COM & LPT)" section, and verify the "Silicon Labs CP210x USB to UART Bridge" is displayed. Note the COM port (e.g. COM3) for the next step.

The Device Manager interface may vary depending on the Windows OS version.
Open the "Environment Variables" dialog of the Control Panel app by following these instructions. From that dialog:
- Create a User Variable called BASE_DIR and set it to `%USERPROFILE%
  - Variable name: BASE_DIR
  - Variable value: %USERPROFILE%
- Create a User Variable called UPLOAD_PORT and set it to the COM port you identified in Step 13
  - Variable name: UPLOAD_PORT
  - Variable value (edit as necessary): COM3
- Edit the Path User Variable to include the cygwin\bin directory.
  - Variable name: Path
  - Variable value (add to the existing list): %BASE_DIR%\esp\cygwin\bin
Launch the "x86 Native Tools Command Prompt for VS 2019" command line console. Verify the setup by building helloworld for your device target:
```
cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p esp/<YOUR_SUBPLATFORM_HERE>
```

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues on Windows and how to resolve them.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

Device not connected/recognized

The following error messages mean that the device is not connected to your computer or the computer doesn't recognize the device.

error: cannot access /dev/cu.SLAB_USBtoUART
error: cannot access /dev/usbserial-0001

There are a few reasons this can happen:

Your device is not plugged into your computer. Make sure it's plugged in when you run the build commands.
You have a USB cable that is power only. Make sure you're using a data sync-capable USB cable.
The computer does not recognize your device. To fix this problem, follow the instructions below.

Check the list of USB devices in Device Manager. If your device shows up as an unknown device, make sure you have the correct VCP driver installed.

If your device shows up on a COM port other than COM3, you need to edit the UPLOAD_PORT environment variable. Enter the following command, replacing COM3 with the appropriate device COM port for your system.

set UPLOAD_PORT=COM3

Updating

To ensure that your build environment is up to date, perform the following steps:

Download the ESP8266 core for Arduino repository. Copy the extracted esp8266-2.3.0 folder into your esp directory.
Update your cloned copy of the ESP8266 SDK based on FreeRTOS and select the release/v3.2 branch:
```
cd %USERPROFILE%\esp\ESP8266_RTOS_SDK
git fetch
git checkout release/v3.2
git pull
```
If you have existing ESP8266 build output in %MODDABLE%\build\bin\esp or %MODDABLE%\build\tmp\esp, delete those directories. For instance, using the "x86 Native Tools Command Prompt for VS 2019" command line console:
```
cd %MODDABLE%\build
rmdir /S /Q bin\esp
rmdir /S /Q tmp\esp
```
Launch the "x86 Native Tools Command Prompt for VS 2019" command line console. Verify the setup by building helloworld for your device target:
```
cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p esp
```

Linux

The Moddable SDK build for ESP8266 currently uses ESP8266 Arduino Core 2.3.0 and ESP8266_RTOS_SDK v3.2.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create an esp directory in your home directory at ~/esp for required third party SDKs and tools.
Download and untar the Xtensa lx106 architecture GCC toolchain. Copy the toolchain directory into the ~/esp directory.
Download the ESP8266 core for Arduino repository. Copy the extracted esp8266-2.3.0 folder into your ~/esp directory.

Clone the ESP8266 SDK based on FreeRTOS repository into the ~/esp directory:

cd ~/esp
git clone https://github.com/espressif/ESP8266_RTOS_SDK.git

We need version 3.2:

cd ESP8266_RTOS_SDK
git checkout release/v3.2

Install Python and the required Python packages. We've used pip to install the additional components.

For Ubuntu 20:

sudo apt-get install python-is-python3 python3-pip python3-serial

For Ubuntu versions prior to 20:

sudo apt-get install python
sudo easy_install pip
pip install --user pyserial

Connect the ESP8266 to your computer with a USB cable.

Verify the setup by building helloworld for your device target:

cd $MODDABLE/examples/helloworld
mcconfig -d -m -p esp/<YOUR_SUBPLATFORM_HERE>

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues and how to resolve them on Linux.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

Permission denied

The ESP8266 communicates with the Linux host via the ttyUSB0 device. On Ubuntu Linux the ttyUSB0 device is owned by the dialout group. If you get a permission denied error when flashing the ESP8266, add your user to the dialout group:

sudo adduser <username> dialout
sudo reboot

Device not connected/recognized

The following error messages mean that the device is not connected to your computer or the computer doesn't recognize the device.

error: cannot access /dev/cu.SLAB_USBtoUART
error: cannot access /dev/usbserial-0001

There are a few reasons this can happen:

Your device is not plugged into your computer. Make sure it's plugged in when you run the build commands.
You have a USB cable that is power only. Make sure you're using a data sync-capable USB cable.
The computer does not recognize your device. To fix this problem, follow the instructions below.

Unplug the device and enter the following command.

ls /dev/cu*

Then plug in the device and repeat the same command. If nothing new appears in the terminal output, the device isn't being recognized by your computer.

If you are running macOS 10.15 or earlier, make sure you have the correct VCP driver installed. If you are running macOS 10.16 or later, you do not need to install the VCP driver.

If it is recognized, you now have the device name and you need to edit the UPLOAD_PORT environment variable. Enter the following command, replacing /dev/cu.SLAB_USBtoUART with the name of the device on your system.

export UPLOAD_PORT=/dev/cu.SLAB_USBtoUART

Updating

To ensure that your build environment is up to date, perform the following steps:

Download the ESP8266 core for Arduino repository. Copy the extracted esp8266-2.3.0 folder into your ~/esp directory.
Update your cloned copy of the ESP8266 SDK based on FreeRTOS and select the release/v3.2 branch:
```
cd ~/esp/ESP8266_RTOS_SDK
git fetch
git checkout release/v3.2
git pull
```
If you have existing ESP8266 build output in $MODDABLE/build/bin/esp or $MODDABLE/build/tmp/esp, delete those directories:
```
cd $MODDABLE/build
rm -rf bin/esp
rm -rf tmp/esp
```
If you have updated to Ubuntu 20.04 or newer (or to any Linux distribution that defaults to Python 3) since initially installing the Moddable SDK, install additional Python 3 components:
```
sudo apt-get install python-is-python3 python3-pip python3-serial
```

Verify the setup by building helloworld for your device target:

cd $MODDABLE/examples/helloworld
mcconfig -d -m -p esp/<YOUR_SUBPLATFORM_HERE>

Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues and how to resolve them.

Incompatible baud rate

The following warning message is normal and is no cause for concern.

warning: serialport_set_baudrate: baud rate 921600 may not work

However, sometimes the upload starts but does not complete. You can tell an upload is complete after the progress bar traced to the console goes to 100%. For example:

........................................................... [ 16% ]
........................................................... [ 33% ]
........................................................... [ 49% ]
........................................................... [ 66% ]
........................................................... [ 82% ]
........................................................... [ 99% ]
..                                                         [ 100% ]

There are a few reasons the upload may fail partway through:

You have a faulty USB cable.
You have a USB cable that does not support higher baud rates.
You're using a board that requires a lower baud rate than the default baud rate that the Moddable SDK uses.

To solve the last two problems above, you can change to a slower baud rate as follows:

Open $MODDABLE/tools/mcconfig/make.esp.mk.
Find this line, which sets the upload speed to 921600:
```
UPLOAD_SPEED ?= 921600
```
Set the speed to a smaller number. For example:
```
UPLOAD_SPEED ?= 115200
```

ESP8266 Arduino version 2.4

The Moddable SDK on ESP8266 is hosted by the ESP8266 core for Arduino. The Moddable SDK uses version 2.3. Version 2.4 is supported as well. At this time, we do not recommend using version 2.4 as it requires more ROM and more RAM without providing significant benefits for most uses of the Moddable SDK. The team responsible for ESP8266 core for Arduino is aware of these issues and actively working to address them.

You can use version 2.4 today if building on macOS or Linux.

Follow the instructions above, but use the version 2.4 of ESP8266 Core for Arduino.

In ${MODDABLE}/tools/mcconfig/make.esp.mk change:

 ESP_SDK_RELEASE ?= esp8266-2.3.0

to:

 ESP_SDK_RELEASE ?= esp8266-2.4.0

Do a clean build of tools by deleting the contents of ${MODDABLE}/build/bin/esp/ and ${MODDABLE}/build/tmp/esp/ and building as above.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

esp8266.md

esp8266.md

Using the Moddable SDK with ESP8266

Table of Contents

Overview

Platforms

macOS

Installing

Troubleshooting

Device not connected/recognized

Updating

Windows

Installing

Troubleshooting

Device not connected/recognized

Updating

Linux

Installing

Troubleshooting

Permission denied

Device not connected/recognized

Updating

Troubleshooting

Incompatible baud rate

ESP8266 Arduino version 2.4

Files

esp8266.md

Latest commit

History

esp8266.md

File metadata and controls

Using the Moddable SDK with ESP8266

Table of Contents

Overview

Platforms

macOS

Installing

Troubleshooting

Device not connected/recognized

Updating

Windows

Installing

Troubleshooting

Device not connected/recognized

Updating

Linux

Installing

Troubleshooting

Permission denied

Device not connected/recognized

Updating

Troubleshooting

Incompatible baud rate

ESP8266 Arduino version 2.4