The Moddable SDK gives you the tools to create IoT devices that support installable apps, use JavaScript to speed firmware development, and integrate a modern touch screen user experience. You can find the latest Getting Started here. For your convenience the version here is specific to ESP32 and IoT-Bus.
Copyright 2016-2018 Moddable Tech, Inc.
Revised: July 10, 2018
This document provides an introduction to getting started building apps with the Moddable SDK. It describes how to configure the host build environments, install the required SDKs, drivers and development tools, build applications, and use xsbug, the JavaScript source code debugger.
The Moddable SDK requires macOS Sierra version 10.12 or newer and Xcode version 9 or newer.
Download the Moddable repository, or use the git
command line tool as follows:
git clone https://github.com/Moddable-OpenSource/moddable
Setup the MODDABLE
environment variable to point at your local Moddable SDK repository directory and edit the PATH
environment variable in your ~/.profile
to include the build directory:
export MODDABLE="/Users//Projects/moddable"
export PATH="${MODDABLE}/build/bin/mac/release:$PATH"
Build the Moddable command line tools, simulator, and debugger from the command line:
cd ${MODDABLE}/build/makefiles/mac
make
Launch the xsbug
debugger from the command line:
open ${MODDABLE}/build/bin/mac/release/xsbug.app
Verify the host environment setup by building the starter helloworld
application for the desktop simulator target:
cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p mac
Complete "Host environment setup" for macOS.
Create an esp32
directory in your home directory at ~/esp32
for required third party SDKs and tools.
Download and install the Silicon Labs CP210x USB to UART VCP driver.
Download the esptool. Untar the package and rename the directory esptool
. Copy the esptool
directory into the ~/esp32
directory.
Download and untar the ESP32 GCC toolchain. Copy the extracted xtensa-esp32-elf
directory into your ~/esp32
directory.
Clone the ESP-IDF
GitHub repository into your ~/esp32
directory. Make sure to specify the --recursive
option:
cd ~/esp32
git clone --recursive https://github.com/espressif/esp-idf.git
Update the PATH
environment variable in your ~/.profile
to include the toolchain directory:
export PATH=$PATH:$HOME/esp32/xtensa-esp32-elf/bin
Connect the ESP32 device to your macOS host with a USB cable and determine the serial port of the ESP32 device.
To determine the serial port, examine the list of devices before and after plugging in your ESP32 device and note the new serial port that shows up. To see a list of serial devices, use the following command in Terminal:
ls /dev/cu.*
Set the UPLOAD_PORT
environment variable in your ~/.profile
to the ESP32 serial port:
export UPLOAD_PORT=/dev/cu.SLAB_USBtoUART
Verify the setup by building helloworld
for the esp32
target:
cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p esp32
Note that the first time you build an application for the ESP32 target, the toolchain may prompt you to enter configuration options. If this happens, accept the defaults.
The Moddable SDK requires Windows 7 Pro SP1 or newer and Microsoft Visual Studio Community 2017 or newer.
Download Microsoft Visual Studio 2017 Community Edition installer. Launch the installer, choose the "Desktop development for C++" option and install.
Download the Moddable repository, or use the git
command line tool as follows:
git clone https://github.com/Moddable-OpenSource/moddable
Setup the MODDABLE
environment variable to point at your local Moddable SDK repository directory:
set MODDABLE=C:\Users\\Projects\moddable
Edit the system PATH
environment variable to include the build directory:
%MODDABLE%\build\bin\win\release
Environment variables should be set from the System Control Panel. The steps required vary depending on the Windows OS version.
Launch the "Developer Command Prompt for VS 2017" command line console. Build the Moddable command line tools, simulator, and debugger from the command line:
cd %MODDABLE%\build\makefiles\win
build
Launch the xsbug
debugger from the command line:
xsbug
Verify the host environment setup by building the starter helloworld
application for the desktop simulator target:
cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p win
Complete "Host environment setup" for Windows.
Download and install the Silicon Labs CP210x USB to UART VCP driver.
Download the Espressif all-in-one Windows toolchain and MSYS2 zip archive. Copy the extracted msys32
directory into your home %USERPROFILE%
directory, e.g. C:\Users\\msys32
.
Open a MSYS2 MINGW32 terminal window from a Windows command line console:
%USERPROFILE%\msys32\mingw32.exe
From the MINGW32 terminal window, create an esp
directory in the home ~
directory:
mkdir ~/esp
Clone the ESP-IDF
GitHub repository into the ~/esp
directory. Make sure to specify the --recursive
option:
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
Create a new script file esp32_moddable.sh
in your %USERPROFILE%\msys32\etc\profile.d\
directory. Add an export command for the ESP-IDF path to the script file:
export IDF_PATH="C:/Users//msys32/home//esp/esp-idf"
Connect the ESP32 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.
Set the BASE_DIR
, UPLOAD_PORT
and SERIAL2XSBUG
Windows environment variables to your %USERPROFILE%
directory, device COM port and serial2xsbug.exe tool path. Note that forward slashes are required in the tool path:
set BASE_DIR=%USERPROFILE%
set UPLOAD_PORT=COM3
set SERIAL2XSBUG=/c/Users//Projects/moddable/build/bin/win/release/serial2xsbug.exe
Launch the "Developer Command Prompt for VS 2017" command line console. Verify the setup by building helloworld
for the esp32
target:
cd %MODDABLE%\examples\helloworld
mcconfig -d -m -p esp32
The mcconfig tool launches a MINGW32 shell to configure the ESP32 firmware build. After this configuration completes, the MINGW32 shell closes and control is returned back to the Developer Command Prompt. Press any key to complete the build and Flash the binary to the device. Another MINGW32 shell opens to complete the build.
Note that the first time you build an application for the ESP32 target, the toolchain may prompt you to enter configuration options. If this happens, accept the defaults.
The Moddable SDK has been tested on the Ubuntu 16.04 LTS (64-bit) and Raspberry Pi Desktop (32-bit) operating systems. These setup instructions assume that a GCC toolchain has already been installed.
Install the development version of the GTK+ 3 library:
sudo apt-get install libgtk-3-dev
Download the Moddable repository, or use the git
command line tool as follows:
git clone https://github.com/Moddable-OpenSource/moddable
Setup the MODDABLE
environment variable in your ~/.bashrc
file to point at your local Moddable SDK repository directory:
MODDABLE=~/Projects/moddable
export MODDABLE
Build the Moddable command line tools, simulator, and debugger from the command line:
cd $MODDABLE/build/makefiles/lin
make
Update the PATH
environment variable in your ~/.bashrc
to include the tools directory:
export PATH=$PATH:$MODDABLE/build/bin/lin/release
Install the Screen Test desktop simulator and xsbug debugger applications:
cd $MODDABLE/build/makefiles/lin
make install
When prompted, enter your sudo
password to copy the application's desktop, executable and icon files into the standard /usr/share/applications
, /usr/bin
, and /usr/share/icon/hicolor
directories.
Launch the xsbug debugger:
xsbug
Verify the host environment setup by building the starter helloworld
application for the desktop simulator target:
cd $MODDABLE/examples/helloworld
mcconfig -d -m -p lin
Complete "Host environment setup" for Linux.
Create an esp32
directory in your home directory at ~/esp32
for required third party SDKs and tools.
Download the esptool compatible with your Linux host. Untar the package and rename the directory esptool
. Copy the esptool
directory into the ~/esp32
directory.
Download and untar the 64-bit or 32-bit ESP32 GCC toolchain compatible with your Linux host. Copy the extracted xtensa-esp32-elf
directory into your ~/esp32
directory.
Clone the ESP-IDF
GitHub repository into your ~/esp32
directory. Make sure to specify the --recursive
option:
cd ~/esp32
git clone --recursive https://github.com/espressif/esp-idf.git
Install the packages required to compile with the ESP-IDF
:
sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
Update the PATH
environment variable in your ~/.bashrc
to include the toolchain directory:
export PATH=$PATH:$HOME/esp32/xtensa-esp32-elf/bin
Connect the ESP32 device to your Linux host with a USB cable.
Determine the USB device path used by the ESP32 device, e.g. /dev/ttyUSB0
:
ls /dev
Set the UPLOAD_PORT
environment variable in your ~/.bashrc
to the ESP32 serial port:
UPLOAD_PORT=/dev/ttyUSB0
export UPLOAD_PORT
Verify the setup by building helloworld
for the esp32
target:
cd $MODDABLE/examples/helloworld
mcconfig -d -m -p esp32
The ESP32 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 ESP32, add your user to thedialout
group:
sudo adduser dialout
sudo reboot
Note that the first time you build an application for the ESP32 target, the toolchain may prompt you to enter configuration options. If this happens, accept the defaults.
The xsbug
JavaScript source level debugger is built as part of the Moddable SDK build described above. xsbug
is a full featured debugger that supports debugging modules and applications for XS platforms. The xsbug
debugger is automatically launched when deploying debug builds and connects to devices via USB or over Wi-Fi. Similar to other debuggers, xsbug
supports setting breakpoints, browsing source code, the call stack and variables. The xsbug
debugger additionally provides real-time instrumentation to track memory usage and profile application and resource consumption.
For additional details on xsbug
please refer to the xsbug document.