Moddable Four Developer Guide

Copyright 2021-2024 Moddable Tech, Inc.
Revised: April 20, 2024

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

• About Moddable Four
  • Components
  • Pinout
  • Pin Information
• SDK and Host Environment Setup
• Building and Deploying Apps
• Using Moddable Four
• Troubleshooting
• Development Resources
  • Simulator
  • Examples
  • Documentation
  • Support
  • Updates

Moddable Four is a low-power, Bluetooth LE development board that makes it easy for developers to experiment with the Moddable SDK. It is available to purchase on the Moddable website.

The two main components of Moddable Four are the nRF52840 module and mirror display. The nRF52840 module includes a BLE antenna, 1 MB Flash, and 256 KB RAM. The Sharp mirror display is a 128x128 black and white display that uses the ls013b4dn04 display driver.

It also includes an integrated LIS3DH accelerometer, jog dial, and CR2032 battery connector.

Note: LCD-PWR / GPIO23 is not for use as a general GPIO. It is used to provide power to a sensor and to the screen.

• Writing 0 to GPIO23 emits 3.3V on LCD-PWR, which also gives power to the screen.
• Writing 1 to GPIO23 turns off the the pin and the screen.

Moddable Four is a 3.3V device. 5V power is regulated to 3.3V by a AP2112K-3.3 voltage regulator (see data sheet for specs). Testing of Moddable Four has been with typical 5V 0.5amp USB source power.

Power can be supplied to Moddable Four via the following:

• 5V - Micro USB connector
• 5V - VIN on pin 14 or external header
• 3.3V - 3.3V on pin 16 of external header
• 3V - CR2032 battery

Power provided by the CR2032 battery connector can be turned on and off with the sliding switch.

The 6-pin JTAG connector can be used for gdb debugging or flashing a new bootloader onto Moddable Four. Please see the nrf52 Platform document for details.

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

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

After you've setup your environment and nRF5 tools, take the following steps to install an application on your Moddable Four.

1. Attach your Moddable Four 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. Put the device into programming mode by double-tapping the RESET button.

   Programming mode is indicated by the LED indicator blinking regularly at boot time. A disk named MODDABLE4 will also appear on your desktop.

   

   Note: If you do not program your device within a short period, it will reboot to the installed application.

3. 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 nrf52/moddable_four with mcconfig to build for Moddable Four. Build the piu/balls example:

   cd $MODDABLE/examples/piu/balls
   mcconfig -d -m -p nrf52/moddable_four
   

   The examples readme contains additional information about other commonly used mcconfig arguments for screen rotation and more.

   Use the platform -p sim/moddable_four with mcconfig to build for the Moddable Four simulator.

The hardware and software in Moddable Four have been carefully designed to work together to support many kinds of applications without additional hardware. The hardware features include:

• LED
• Back button
• Jog dial
• Display power
• Display dither
• Display rotation
• Accelerometer
• Energy Management

This code snippet shows the use of Moddable Four's' Host object to turn on the LED when the back button is pressed.

let led = new Host.LED.Default;

new Host.Button({
    pin: Host.pins.button,
    onPush() {
        led.write(this.pressed);
    }
});

new Host.JogDial({
    onTurn(delta) {
	    trace(`Turn ${delta}\n`);
    },
    onPushAndTurn(delta) {
        trace(`Push and Turn ${delta}\n`);
    },
    onPush(value) {
        trace(`Button ${value}\n`);
    }
});

Note: The delta values provided by the jog dial respect the screen rotation (see Display Rotation) and so are negated when the screen rotation is 180 degrees.

To use the Moddable Four display, the LCD power pin must be enabled. In the moddable_four/setup-target.js file, the screen is enabled if the autobacklight config variable is set:

if (config.autobacklight)
    Digital.write(config.lcd_power_pin, 0);

The Sharp memory display in Moddable Four uses the ls013b4dn04 display driver. By default, the display driver is configured to dither images as it converts from 8-bit gray to black and white for the display. The driver uses the Atkinson dither algorithm which is fast, high quality, and well suited to animation.

While low, there is some runtime cost to dither. For applications that want to maximize frame rate, minimize computation, reduce code size, and reduce RAM use, dithering may be completely disabled in the driver by setting the appropriate define in the project manifest:

    "defines": {
        "ls013b4dn04": {
            "dither": 0
        }
    },

Some applications want dithering enabled on some screens but not others. Those applications will leave dithering enabled in the driver, and use the dither property of the driver to turn dithering on and off at runtime.

screen.dither = true;
screen.dither = false;

The ls013b4dn04 display driver in Moddable Four provides support for 0 and 180 degree rotation. 180 degree rotation is useful when the display is mounted upside down. The default is 0. The rotation may be set at build time or at runtime.

To set the rotation at build time, include driverRotation in the config section of the manifest:

	"config": {
		"driverRotation": 180
	},

To set the rotation At runtime, change the rotation property of the screen global.

screen.rotation = 180

Setting the rotation at runtime does not immediately update the display. Your application must force an update after setting the rotation.

import Timer from "timer";

let acc = new Host.Accelerometer;

Timer.repeat(() => {
    let sample = acc.sample();
    trace(`sample x: ${sample.x}, y: ${sample.y}, z: ${sample.z}\n`);
}, 100);

Note: The accelerometer values respect the screen rotation (see Display Rotation), so x and y are negated when the screen rotation is 180 degrees.

Moddable Four is designed to run on coin-cell batteries for long periods of time. The hardware is carefully designed to achieve maximum energy efficiency. Here is the energy used in various operating modes:

• Idle mode - 3.7 uA - RAM maintained, waiting for user input, between screens and sensor readings.
• Deep sleep - 1.85 uA - No software running. Automatically wake after a specified duration. Only retention RAM maintained.
• Wake on digital - 1.9 uA - Like deep sleep, but also wakes up on state change of digital input
• Wake on analog - 2.7 uA - Like deep sleep, but also wakes when an analog input crosses a specified threshold

There are many energy management APIs available on Moddable Four. These include:

• Deep sleep
• Retention RAM
• Wake on digital
• Wake on timer
• Wake on analog
• Wake on motion (using accelerometer)

See the nRF52 Low Power Notes for details. Examples of different sleep and wakeup modes can be found in $MODDABLE/build/devices/nrf52/examples/sleep.

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

The Moddable SDK simulator, mcsim, includes a Moddable Four simulator. To use it, use the sim/moddable_four platform when building with mcconfig:

mcconfig -d -m -p sim/moddable_four

The simulator includes controls for many of the unique hardware features of Moddable Four. Use "Show Controls" and "Hide Controls" in the View menu to toggle their visibility.

You can also use your computer's keyboard to control the jog dial and button:

• Jog dial clockwise – up arrow
• Jog dial counter-clockwise – down arrow
• Jog dial press – enter
• Back button – delete

The Moddable Four simulator renders images in 8-bit grayscale, which matches how Moddable Four hardware renders images off-screen. The display driver in Moddable Four then converts the 8-bit grayscale images to monochrome (1-bit) for display with optional dithering.

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

Many of the examples that use Commodetto and Piu are designed for colored QVGA screens. While they will run on Moddable Four, the colors will be dithered when rendered and some screens may be cropped. Not every example is compatible with Moddable Four hardware. Some examples are designed to test specific display and touch drivers that are not compatible with the Moddable Four display and give a build error.

Documentation for the nRF5 device and SDK can be found on the Nordic Semiconductor Infocenter. Of particular interest is the documentation for the Nordic nRF5 SDK v17.0.2, which is available here.

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:

• Using the Moddable SDK with nRF52 explains how to get set-up for development, supported devices, and more.
• nRF52 Low Power Notes describes the techniques and APIs to maximize battery life by minimizing power consumption.
• The commodetto directory, which contains resources related to Commodetto--a bitmap graphics library that provides a 2D graphics API--and Poco, a lightweight rendering engine.
• The piu directory, which contains resources related to Piu, our user interface framework for creating complex, responsive layouts.
• The pins directory, which contains resources related to supported hardware protocols (digital, analog, PWM, I²C, etc.). A number of drivers for common off-the-shelf sensors and corresponding example apps are also available.

If you have questions, we're here to help. If you've encountered a bug, recommend you open an issue. If you have a question, start a discussion or ask us on our Gitter. 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 and discussions before opening a new one.

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.