DOCUMENTATION DEVICES Moddable Four
Overview
Getting Started
BASE
Reference
Worker
Setup modules
COMMODETTO
Reference
Poco Renderer
Outlines
Creating Fonts
Crypt
Data
DEVICES
Moddable One
Moddable Two
Moddable Three
Moddable Four
Moddable Six
ESP32
ESP8266
nRF52
nRF52 Low Power Notes
Raspberry Pi Pico
M5Core Ink
M5Paper
Wasm
SiLabs Gecko
QCA4020
Moddable Zero
Moddable Display Developer Guide
DISPLAYS
Overview
Adafruit 1.8" ST7735
Adafruit OLED Display
BuyDisplay 2.8" CTP - ESP8266
Crystalfontz ePaper
DotStar
Generic 1.44"
Generic 2.4" & 2.8" (Resistive Touch) - ESP32
Generic 2.4" & 2.8" (Resistive Touch) - ESP8266
Generic 2.4" & 2.8" (Resistive Touch) - Pico
Sharp Memory
Sharp Memory Screen 1.3"
SparkFun TeensyView
Switch Science Reflective LCD
DRIVERS
DESTM32S display
DotStar display
ILI9341 display
LPM013M126A display
LS013B4DN04 display
MCP230XX GPIO expander
NeoStrand
SSD1306 display
SSD1351 display
ST7735 display
Files
IO
TC53 IO
Firmata
NETWORK
Reference
TLS (SecureSocket)
BLE
Ethernet
Web Things
PINS
Reference
Audio Output
PIU
Reference
Localization
Keyboard
Expanding Keyboard
Die Cut
Using After Effects Motion Data
TOOLS
Reference
Manifest
Defines in Manifests
Testing
XS
Handle
JavaScript language considerations on embedded devices using the XS engine
Mods – User Installed Extensions
ROM Colors
Using XS Preload to Optimize Applications
XS Conformance
XS Marshalling
XS Platforms
XS in C
XS linker warnings
xsbug
xst
XS Compartment
XS Profiler
XS Scopes

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.

Table of Contents

About Moddable Four

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.

Components

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.

Pinout

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.

Pin Information

16-pin External Header Description

Name Function Description
LCD-PWR
GPIO23
Power GPIO23 is used to turn power on for the screen and sensors connected to this pin. 3.3v
GPIO3
ADC1
I/O
Analog
Connects to nrf52 GPIO3. ADC Channel 1
GPIO4
ADC2
I/O
Analog
Connects to nrf52 GPIO4. ADC Channel 2
GPIO5
ADC3
I/O
Analog
Connects to nrf52 GPIO5. ADC Channel 3
GPIO17 I/O Connects to nrf52 GPIO17
GPIO22 I/O Connects to nrf52 GPIO22
GPIO28
ADC4
I/O
Analog
Connects to nrf52 GPIO28. ADC Channel 4
GPIO29
ADC5
I/O
Analog
Connects to nrf52 GPIO29. ADC Channel 5
GPIO30
ADC6
I/O
Analog
Connects to nrf52 GPIO30. ADC Channel 6
GPIO31
ADC7
I/O
Analog
Connects to nrf52 GPIO31. ADC Channel 7
GPIO27
SCL
I/O
I2C
Connects to nrf52 GPIO27
I2C Clock
Accelerometer
GPIO26
SDA
I/O
I2C
Connects to nrf52 GPIO26
I2C Data
Accelerometer
RST Reset Reset device
VIN Power VIN is a 5V pin that can be used to power Moddable Four. If the board is powered by USB, this pin can be used to provide that 5V power. This is an unregulated pin; VIN is a direct connection to the 5V input sources. Connects to other 5V inputs and AP2112K voltage regulator.
GND GND Connects to GND
3.3V Power 3.3V input and output. Connects to nRF52 3.3V input and other 3.3V devices. Regulated output power if board is 5V powered via micro USB, VIN external connector or USB. 3.3V can also be provided by the CR2032 coin cell.

Power

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.

6-pin JTAG connector

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.

SDK and Host Environment Setup

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.

Building and Deploying Apps

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.

    Moddable Four disk

    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.

Using Moddable Four

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

LED and Back button

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);
    }
});

Jog Dial

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.

Display Power

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);

Display Dither

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;

Display Rotation

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.

Accelerometer

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.

Energy Management

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.

Troubleshooting

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

Development Resources

Simulator

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.

Examples

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

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.

Support

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.

Updates

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.