Hardware Requirements

The examples were tested with the ESP32 and ESP8266 modules , shown in Figure 1-1.

These hardware components are shown in Figure 1-2. More information on where you can purchase them is provided in the chapters where they’re discussed.

The examples that use the Poco renderer (Chapter 9) or the Piu user interface framework (Chapter 10) can be run on the hardware simulator on your computer, but it’s highly recommended that you use an actual display and run them on your ESP32 or ESP8266. If you’re comfortable wiring together components on a breadboard, here’s what you need:

• An ILI9341 QVGA touch display (Figure 1-3), which is available on eBay and elsewhere online; search for “spi display 2.4 touch” and you should find several inexpensive options. Note that although this display works well, there are many other choices. The Moddable SDK includes built-in support for several other displays of varying cost and quality; see the documentation/displays directory of the Moddable SDK for more information.

• A breadboard.

• Male-to-female jumper wires.

If you’d rather not do the wiring yourself, you can purchase a Moddable One or Moddable Two from the Moddable website. Moddable One is an ESP8266 wired to a capacitive touch screen; Moddable Two is an ESP32 wired to the same touch screen. Both come as ready-to-use development kits in a compact form factor. Figure 1-4 shows a Moddable One.

The Moddable SDK also supports ESP32-based development kits with built-in screens. A popular choice is the M5Stack FIRE, shown in Figure 1-5. See the Moddable SDK repository on GitHub for more information about supported development kits.

Software Requirements

You can choose whichever code editor you prefer. There are many JavaScript-friendly editors, including Visual Studio Code, Sublime Text 3, and Atom.

The next sections explain how to download the example code files and set up the Moddable SDK and build tools for your device.

Downloading the Example Code

All the examples are available at https://github.com/Moddable-OpenSource/iot-product-dev-book. You can download the example code using the git command line tool.

You also need to set the EXAMPLES environment variable to point at your local copy of the examples repository, as follows:

Setting Up Your Build Environment

Before building and running the examples, follow the instructions in the “Moddable SDK – Getting Started” document in the documentation directory of the Moddable SDK. This document provides step-by-step instructions for installing, configuring, and building the Moddable SDK for macOS, Linux, and Windows, as well as instructions for installing tools you need in order to work with the ESP32 and ESP8266.

Using xsbug

The xsbug debugger provides source-level debugging of JavaScript code running on the XS JavaScript engine. It connects to devices via USB and has a graphical user interface (shown in Figure 1-6) to make it easy to use.

Similar to other debuggers, xsbug supports setting breakpoints and browsing source code, the call stack, and variables. It also provides real-time instrumentation to track memory usage and to profile application and resource consumption.

When you’re developing for a microcontroller, the build system automatically opens xsbug before launching your application on the target device.

Important Features for Examples in This Book

This book doesn’t refer to xsbug often because the examples have already been debugged. However, xsbug is an invaluable tool as you create your own applications. The most important xsbug features used in this book are as follows:

• Machine tabs – Each XS virtual machine connected to xsbug gets its own tab in the upper left of the window (as highlighted by the dashed border in Figure 1-7). Clicking a tab changes the left pane to the machine tab view, where you can view instrumentation, use control buttons, and more.

• Control buttons – These graphically labeled buttons (highlighted by the dotted border in the figure) at the top of the machine tab view control the virtual machine. From left to right, they are Kill, Break, Run, Step, Step In, and Step Out.

• Console – It’s often useful to be able to view diagnostic messages during execution of an application. The trace function writes messages to the debug console in the bottom right of xsbug.

See the xsbug document in the documentation/xs directory of the Moddable SDK for full documentation of all the features of xsbug.

Running Examples

The examples in the repository for this book are organized by chapter, each one having several examples. To make it faster to build and launch the examples, each chapter has its own host, which contains the software environment needed to run the examples for that chapter; the host is the collection of JavaScript modules, configuration variables, and other software available for your application to use. Because space is very limited in microcontrollers, it isn’t possible to have a single host that contains all the modules used in the examples in this book.

You can think of the host as essentially the base application. The web browser is the host when you run JavaScript in a web browser; Node.js is the host when you run JavaScript on a web server.

Installing the host separately, rather than installing the host and example together, significantly speeds up development, by minimizing the amount of software that needs to be downloaded. Installing a host on your device typically takes between 30 and 90 seconds. Once that’s done, you can install most examples in just a few seconds, because the host already contains the device firmware and JavaScript modules required by the examples.

The next sections walk you through the entire process of installing a host and then an example, starting with helloworld. Note that in the context of this book, installing an application causes the application to then run on the device.

Installing the Host

The first step is to flash the device to install the host. The source code for each chapter’s host is available to read in the host directory , if you’re curious. To use the host, all you really need to know is that it includes all the modules necessary for the corresponding examples.

You use the mcconfig command line tool to flash the device.

Confirming the Host Was Installed

Once the host is installed, it writes the message shown in Figure 1-8 to the debug console.

Installing helloworld

You use mcrun to install examples.

Finishing Up

You should immediately break into xsbug once the application is installed. Click the Run button to see the message Hello, World written to the debug console, as shown in Figure 1-9.

If everything goes well, you can move on to the “Conclusion” section of this chapter if you’re working with a bare NodeMCU board. If you want to add a display—which is highly recommended—continue with the “Adding a Display” section instead.

If you ran into issues, see the next section.

Troubleshooting

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

Device Not in Bootloader Mode

This issue is not uncommon if you’re using certain ESP32-based boards. Status messages stop being traced briefly when you attempt to flash the device, and after several seconds you receive this error message:

A fatal error occurred: Failed to connect to ESP32: Timed out waiting for packet header

If the device is not in bootloader mode, you cannot flash the device. If you’re using a NodeMCU module, follow these steps every time you flash :

1. 1.

   Unplug the device.

    
2. 2.

   Hold down the BOOT button (circled in Figure 1-10).

    
3. 3.

   Plug the device into your computer.

    
4. 4.

   Enter the mcconfig command.

    
5. 5.

   Wait a few seconds and release the BOOT button.

    

Adding a Display

The examples in this book are designed for a display with 240 x 320 or 320 x 240 resolution (for example, QVGA). These displays are typically between 2.2" and 3.5" in size and were common in early smart phones. Displays of other sizes may be connected to these microcontrollers, but this size is a good match for the capabilities of these microcontrollers.

The following sections show how to connect the ILI9341 QVGA touch display to the ESP32 or ESP8266. If you’re using a development board like the Moddable One or Moddable Two, you can skip to the “Installing helloworld-gui” section.

Connecting a Display to the ESP32

Table 1-1 and Figure 1-11 show how to connect a display to the ESP32.

Table 1-1

Wiring to connect display to ESP32

ILI9341 Display	ESP32
SDO/MISO	GPIO12
LED	3.3V
SCK	GPIO14
SDI/MOSI	GPIO13
CS	GPIO15
DC	GPIO2
RESET	3.3V
GND	GND
VCC	3.3V
T_DO	GPIO12
T_DIn	GPIO13
T_CLK	GPIO14
T_IRQ	GPIO23
T_CS	GPIO18

Connecting a Display to the ESP8266

Table 1-2 and Figure 1-12 show how to connect a display to the ESP8266.

Table 1-2

Wiring to connect display to ESP8266

ILI9341 Display	ESP8266
SDO/MISO	GPIO12
LED	3.3V
SCK	GPIO14
SDI/MOSI	GPIO13
CS	GPIO15
DC	GPIO2
RESET	3.3V
GND	GND
VCC	3.3V
T_DO	GPIO12
T_DIn	GPIO13
T_CLK	GPIO14
T_IRQ	GPIO16
T_CS	GPIO0

Installing helloworld-gui

The helloworld-gui example is a version of helloworld that displays text on the screen. If you wired a display to a device yourself, reflashing the device with the helloworld-gui application is a good way to test whether the wiring is correct.

The commands to use are very similar to the ones used to install helloworld. The only difference is the platform identifier. The platform identifier tells the build system to include the proper display and touch drivers. If you’re using a Moddable One, the platform identifier is esp/moddable_one; for a Moddable Two, it’s esp32/moddable_two. If you added a display according to the instructions in the preceding sections, the platform identifier is either esp32/moddable_zero or esp/moddable_zero.

If you specify the correct platform and your wiring is correct, you will see the screen shown in Figure 1-13.

Conclusion

Now that your development environment is set up and you’re familiar with the process of installing this chapter’s examples on your device, you’re ready to try some more examples!

At this point, you have all the materials and skills you need to follow along with Chapters 2 through 10. These chapters are independent of each other, so you can read them in any order. As you start working with the examples in a chapter, be sure to install that chapter’s host or you’ll encounter errors when launching the examples. Once you feel comfortable with the APIs of the Moddable SDK, you can move on to Chapter 11, which covers more advanced topics.