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.
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.
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. |
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.
SDK and Host Environment Setup
To build and run apps on Moddable Four, you'll need to:
- Install the Moddable SDK
- Install nRF5 tools
- 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.
-
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.
-
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.
-
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.
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.