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.

Moddable SDK – Getting Started

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.

macOS

Host environment setup

The Moddable SDK requires macOS Sierra version 10.12 or newer and Xcode version 9 or newer.

1. Download and install Xcode. Launch Xcode to install additional command line components when prompted.

2. Download the Moddable repository, or use the git command line tool as follows:

   git clone https://github.com/Moddable-OpenSource/moddable
   

3. Setup the MODDABLE environment variable to point at your local Moddable SDK repository directory and edit the PATHenvironment variable in your ~/.profile to include the build directory:

   export MODDABLE="/Users//Projects/moddable"
   export PATH="${MODDABLE}/build/bin/mac/release:$PATH"
   

4. Build the Moddable command line tools, simulator, and debugger from the command line:

   cd ${MODDABLE}/build/makefiles/mac
   make
   

5. Launch the xsbug debugger from the command line:

   open ${MODDABLE}/build/bin/mac/release/xsbug.app
   

6. 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

IoT-Bus setup

1. Complete "Host environment setup" for macOS.

2. Create an esp32 directory in your home directory at ~/esp32 for required third party SDKs and tools.

3. Download and install the Silicon Labs CP210x USB to UART VCP driver.

4. Download the esptool. Untar the package and rename the directory esptool. Copy the esptool directory into the ~/esp32 directory.

5. Download and untar the ESP32 GCC toolchain. Copy the extracted xtensa-esp32-elf directory into your ~/esp32directory.

6. 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
   

7. Update the PATH environment variable in your ~/.profile to include the toolchain directory:

   export PATH=$PATH:$HOME/esp32/xtensa-esp32-elf/bin
   

8. 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.*
   

9. Set the UPLOAD_PORT environment variable in your ~/.profile to the ESP32 serial port:

   export UPLOAD_PORT=/dev/cu.SLAB_USBtoUART
   

10. 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.

Windows

Host environment setup

The Moddable SDK requires Windows 7 Pro SP1 or newer and Microsoft Visual Studio Community 2017 or newer.

1. Download Microsoft Visual Studio 2017 Community Edition installer. Launch the installer, choose the "Desktop development for C++" option and install.

2. Download the Moddable repository, or use the git command line tool as follows:

   git clone https://github.com/Moddable-OpenSource/moddable
   

3. Setup the MODDABLE environment variable to point at your local Moddable SDK repository directory:

   set MODDABLE=C:\Users\\Projects\moddable
   

4. 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.

5. 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
   

6. Launch the xsbug debugger from the command line:

   xsbug
   

7. 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

IoT-Bus setup

1. Complete "Host environment setup" for Windows.

2. Download and install the Silicon Labs CP210x USB to UART VCP driver.

3. 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.

4. Open a MSYS2 MINGW32 terminal window from a Windows command line console:

   %USERPROFILE%\msys32\mingw32.exe
   

5. From the MINGW32 terminal window, create an esp directory in the home ~ directory:

   mkdir ~/esp
   

6. 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
   

7. 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"
   

8. Connect the ESP32 to your computer with a USB cable.

9. 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.

10. 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
    

11. 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.

Linux

Host environment setup

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.

1. Install the development version of the GTK+ 3 library:

   sudo apt-get install libgtk-3-dev
   

2. Download the Moddable repository, or use the git command line tool as follows:

   git clone https://github.com/Moddable-OpenSource/moddable
   

3. Setup the MODDABLE environment variable in your ~/.bashrc file to point at your local Moddable SDK repository directory:

   MODDABLE=~/Projects/moddable
   export MODDABLE
   

4. Build the Moddable command line tools, simulator, and debugger from the command line:

   cd $MODDABLE/build/makefiles/lin
   make
   

5. Update the PATH environment variable in your ~/.bashrc to include the tools directory:

   export PATH=$PATH:$MODDABLE/build/bin/lin/release
   

6. 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.

7. Launch the xsbug debugger:

   xsbug
   

8. 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

IoT-Bus setup

1. Complete "Host environment setup" for Linux.

2. Create an esp32 directory in your home directory at ~/esp32 for required third party SDKs and tools.

3. Download the esptool compatible with your Linux host. Untar the package and rename the directory esptool. Copy the esptool directory into the ~/esp32 directory.

4. 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.

5. 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
   

6. 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 
   

7. Update the PATH environment variable in your ~/.bashrc to include the toolchain directory:

   export PATH=$PATH:$HOME/esp32/xtensa-esp32-elf/bin
   

8. Connect the ESP32 device to your Linux host with a USB cable.

9. Determine the USB device path used by the ESP32 device, e.g. /dev/ttyUSB0:

   ls /dev
   

10. Set the UPLOAD_PORT environment variable in your ~/.bashrc to the ESP32 serial port:

    UPLOAD_PORT=/dev/ttyUSB0
    export UPLOAD_PORT
    

11. 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 the dialout 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.

Debugging applications

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 xsbugdebugger 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.