Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Cannot retrieve contributors at this time

Moddable Three Developer Guide

Copyright 2019-2022 Moddable Tech, Inc.
Revised: March 22, 2022

This document provides information about Moddable Three, including details about its pins and other components, how to build and deploy apps, and links to other development resources.

Table of Contents

About Moddable Three

Moddable Three is a hardware module that makes it easy for developers to experiment with the Moddable SDK on inexpensive hardware. It is available to purchase on the Moddable website.


The two main components of Moddable Three are the ESP8266 module and ePaper screen. The ESP8266 module includes a Wi-Fi antenna and 4 MB of flash storage memory. The ePaper screen is a 122 x 250 black and white display.

<a id="pinout"


SDK and Host Environment Setup

To build and run apps on Moddable Three, you'll need to:

  1. Install the Moddable SDK
  2. Install ESP8266 tools
  3. Follow the instructions in the Building and Deploying Apps section below.

Building and Deploying Apps

After you've set up your host environment and ESP8266 tools, take the following steps to install an application on your Moddable Three.

  1. Attach your Moddable Three to your computer with a micro USB cable.

    Make sure you're using a data sync–capable cable, not one that is power-only.

  2. Build and deploy the app with mcconfig.

    mcconfig is the command line tool to build and launch Moddable apps on microcontrollers and the simulator. Full documentation of mcconfig is available here.

    Use the platform -p esp/moddable_three with mcconfig to build for Moddable Three. For example, to build the piu/love-e-ink example:

    cd $MODDABLE/examples/piu/love-e-ink
    mcconfig -d -m -p esp/moddable_three

    The examples readme contains additional information about other commonly used mcconfig arguments for screen rotation, Wi-Fi configuration, and more.

    Use the platform -p simulator/moddable_three with mcconfig to build for the Moddable Three simulator.


See the Troubleshooting section of the ESP8266 documentation for a list of common issues and how to resolve them.

Development Resources


The Moddable SDK has over 150 example apps that demonstrate how to use its many features. Most of these examples run on Moddable Three.

That said, many of the examples that use Commodetto and Piu are designed for colored screens with a faster refresh rate. In addition, not every example is compatible with Moddable Three hardware. For example, the ESP8266 does not have BLE capabilities so BLE examples do not build or run. Some examples are designed to test specific display and touch drivers that are not compatible with the Moddable Three display and give a build error.


All the documentation for the Moddable SDK is in the documentation directory. The documentation, examples, and modules directories share a common structure to make it straightforward to locate information. Some of the highlights include:

  • The commodetto subdirectory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine.
  • The piu subdirectory, which contains resources related to Piu, a user interface framework that makes it easier to create complex, responsive layouts.
  • The networking subdirectory, which contains networking resources related to network sockets and a variety of standard, secure networking protocols built on sockets including HTTP/HTTPS, WebSockets, DNS, SNTP, and telnet
  • The pins subdirectory, which contains resources related to supported hardware protocols (digital, analog, PWM, I2C, etc.). A number of drivers for common off-the-shelf sensors and corresponding example apps are also available.


If you have questions, we recommend you open an issue. We'll respond as quickly as practical, and other developers can offer help and benefit from the answers to your questions. Many questions have already been answered, so please try searching previous issues before opening a new issue.


The best way to keep up with what we're doing is to follow us on Twitter (@moddabletech). We post announcements about new posts on our blog there, along with other Moddable news.