Using the Moddable SDK with nRF52

Copyright 2021-2024 Moddable Tech, Inc.
Revised: January 9, 2024

This document is a guide to building apps for the nRF52840 SoC from Nordic using the Moddable SDK.

Overview
Platforms
- nrf52
Build Types
Setup instructions

• Installing
• Troubleshooting • Installing
• Troubleshooting • Installing
• Troubleshooting
Troubleshooting
Debugging Over Serial
Updating over BLE
Installing Apps via Serial
Debugging Native Code
Bootloader
- Installing the bootloader
- Updating the bootloader
nRF5 SDK modifications

Overview

Before you can build applications, you need to:

Install the Moddable SDK and build its tools
Install the required drivers and development tools for the nRF52 platform

The instructions below will have you verify your setup by running the helloworld example on your device using mcconfig, the command line tool to build and run applications using the Moddable SDK.

See the Tools documentation for more information about mcconfig

To build for Moddable Four, run mcconfig with nrf52/moddable_four for the platform identifier:

mcconfig -d -m -p nrf52/moddable_four

A list of available nRF52 subplatforms and their platform identifiers is in the Platforms section below.

Platforms

nRF52

nRF52840 has the following features:

64 MHz Cortex-M4 with FPU
BLE
256 KB RAM
1 MB Flash

Name	Platform identifier	Key features	Links
Moddable Four	`nrf52/moddable_four` `simulator/moddable_four`	- 1.28" 128x128 Monochrome - Sharp Mirror display - BLE - Jogdial - Accelerometer - Button and LED - CR2032 coin-cell power - 12 External GPIO pins	Moddable Four developer guide Moddable product page
Moddable Display 4	`nrf52/moddable_display_4` `simulator/moddable_four`	- 1.28" 128x128 Monochrome - Sharp Mirror display - BLE - Jogdial - Accelerometer - Button and LED - CR2032 coin-cell power - 12 External GPIO pins	Moddable Display developer guide Moddable product page
Nordic nRF52840 DK pca10056	`nrf52/dk`	- 4 LEDs - 4 Buttons - All pins accessible - BLE - CR2032 coin-cell power	Product page
Sparkfun Pro nRF52840 Mini	`nrf52/sparkfun`	- 1 LED - 1 Button - BLE - JST Power connector - Qwiic connector - 17 GPIO pins	Product page
Makerdiary nRF58240 MDK	`nrf52/makerdiary`	- 1 3-color LED - 1 Button - BLE - 12 GPIO pins	Product page
Seeed Studio XIAO nRF52840	`nrf52/xiao`	- 1 3-color LED - 1 Button - BLE - 11 GPIO pins	Product page
Adafruit ItsyBitsy nRF52840 Express	`nrf52/itsybitsy`	- 1 LED - 1 Button - BLE - 21 GPIO pins	Product page
ili9341	`nrf52/xiao_ili9341`	ili9341 QVGA display 320 x 240 16-bit color	Wiring Guide

Build Types

The nRF52 supports three kinds of builds: debug, instrumented, and release. Each is appropriate for different stages in the product development process. You select which kind of build you want from the command line when running mcconfig.

Note: Deep sleep APIs are only available instrumented and release builds.

Debug

A debug build is used for debugging JavaScript. In a debug build, the device will attempt to connect to xsbug at startup over USB or serial depending on the device configuration. Symbols will be included for native gdb debugging.

The -d option on the mcconfig command line selects a debug build.

Instrumented

An instrumented build is used for debugging native code. In an instrumented build, the JavaScript debugger is disabled. The instrumentation data usually available in xsbug is output to the serial console once a second. Deep sleep APIs are available in an instrumented build.

The -i option on the mcconfig command line selects an instrumented build.

Release

A release build is for production. In a release build, the JavaScript debugger is disabled, instrumentation statistics are not collected, and serial console output is suppressed. Deep sleep APIs are available in a release build.

Omitting both the -d and -i options on the mcconfig command line selects a release. Note that -r specifies display rotation rather than selecting a release build.

macOS

The Moddable SDK build for nRF52 currently uses Nordic nRF5 SDK v17.0.2.

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create an nrf5 directory in your home directory at ~/nrf5 for required third party SDKs and tools.
If you use macOS Catalina (version 10.15) or later, add an exemption to allow Terminal (or your alternate terminal application of choice) to run software locally that does not meet the system's security policy. Without this setting, the precompiled GNU Arm Embedded Toolchain downloaded in the next step will not be permitted to run.

To set the security policy exemption for Terminal, go to Security & Privacy System Preferences, select the Privacy tab, choose Developer Tools from the list on the left, and then tick the checkbox for Terminal or the alternate terminal application from which you will be building Moddable SDK apps. The end result should look like this:
On x86 Mac, Download version 12.2.1 AArch32 bare-metal target (arm-none-eabi) of the GNU Arm Embedded Toolchain from the Arm Developer website. Uncompress the archive and move the arm-gnu-toolchain-12.2.rel1-darwin-x86_64-arm-none-eabi directory into the nrf5 directory.
On Arm-based Mac, Download version 12.2.1 AArch32 bare-metal target (arm-none-eabi) of the GNU Arm Embedded Toolchain from the Arm Developer website. Uncompress the archive and move the arm-gnu-toolchain-12.2.rel1-darwin-arm64-arm-none-eabi directory into the nrf5 directory.
Moddable Four uses a modified Adafruit nRF52 Bootloader that supports the UF2 file format for flashing firmware to a device. Moddable uses the uf2conv.py Python tool from Microsoft that packages the UF2 binary for transfer to the device. Download the uf2conv tool. Move or copy the uf2conv.py file into the nrf5 directory.

Use chmod to change the access permissions of uf2conv to make it executable.
```
cd ~/nrf5
chmod 755 uf2conv.py
```
Download the Nordic nRF5 SDK with Moddable Four modifications.

Unzip the archive and copy the nRF5_SDK_17.0.2_d674dde directory into the nrf5 directory.

FYI – See the section nRF5 SDK modifications for information on the modifications to the nRF5 SDK. These modifications have already been applied to the archive you just downloaded.
Setup the NRF_SDK_DIR environment variable to point at the nRF5 SDK directory:
```
export NRF_SDK_DIR=$HOME/nrf5/nRF5_SDK_17.0.2_d674dde
```

Verify the setup by building helloworld for your device target:

cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p nrf52/<YOUR_SUBPLATFORM_HERE>

Troubleshooting

If the macOS DISK NOT EJECTED PROPERLY remain on your screen, you can download and use the ejectfix.py tool to make them auto-dismiss.

See the article at the Adafruit blog for details.

Windows

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create a nrf5 directory in your %USERPROFILE% directory, e.g. C:\Users\<your-user-name> for required third party SDKs and tools.
```
cd %USERPROFILE%
mkdir nrf5
cd nrf5
```
Download version 12.2.1 AArch32 bare-metal target (arm-none-eabi) of the GNU Arm Embedded Toolchain from the Arm Developer website. Uncompress the archive and move the arm-gnu-toolchain-12.2.rel1-mingw-w64-i686-arm-none-eabi directory into the nrf5 directory.
Moddable Four uses a modified Adafruit nRF52 Bootloader that supports the UF2 file format for flashing firmware to a device. uf2conv.py is a Python tool from Microsoft that packages the UF2 binary for transfer to the device. Download the uf2conv tool. Move or copy the uf2conv.py file into the nrf5 directory.
Download the Nordic nRF5 SDK with Moddable Four modifications.

Unzip the archive and copy the nRF5_SDK_17.0.2_d674dde directory into the nrf5 directory.

FYI – See the section nRF5 SDK modifications for information on the modifications to the nRF5 SDK. These modifications have already been applied to the archive you just downloaded.
Setup the NRF52_SDK_PATH environment variable to point at your nRF5 SDK directory:
```
set NRF52_SDK_PATH = %USERPROFILE%\nrf5\nRF5_SDK_17.0.2_d674dde
```
Download and run the Python installer for Windows. Choose the default options.
Edit the system PATH environment variable to include the Python directories:
```
C:\Python27
C:\Python27\Scripts
```

Verify the setup by building helloworld for your device target:

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

Troubleshooting

Linux

Installing

Install the Moddable SDK tools by following the instructions in the Getting Started document.
Create a nrf5 directory in your home directory at ~/nrf5 for required third party SDKs and tools.
```
cd $HOME
mkdir nrf5
cd nrf5
```
Download version 12.2.1 AArch32 bare-metal target (arm-none-eabi) of the GNU Arm Embedded Toolchain from the Arm Developer website. Uncompress the archive and move the arm-gnu-toolchain-12.2.rel1-x86_64-arm-none-eabi directory into the nrf5 directory.
Moddable Four uses a modified Adafruit nRF52 Bootloader that supports the UF2 file format for flashing firmware to a device. uf2conv.py is a Python tool from Microsoft that packages the UF2 binary for transfer to the device. Download the uf2conv tool. Move or copy the uf2conv.py file into the nrf5 directory.
Download the Nordic nRF5 SDK with Moddable Four modifications.

Unzip the archive and copy the nRF5_SDK_17.0.2_d674dde directory into the nrf5 directory.

FYI – See the section nRF5 SDK modifications for information on the modifications to the nRF5 SDK. These modifications have already been applied to the archive you just downloaded.
Setup the NRF_SDK_DIR environment variable to point at the nRF5 SDK directory:
```
export NRF_SDK_DIR=$HOME/nrf5/nRF5_SDK_17.0.2_d674dde
```

Verify the setup by building helloworld for your device target:

cd ${MODDABLE}/examples/helloworld
mcconfig -d -m -p nrf52/<YOUR_SUBPLATFORM_HERE>

Linux Troubleshooting

When you're trying to install applications, you may experience roadblocks in the form of errors or warnings; this section explains some common issues on Linux and how to resolve them.

For other issues that are common on macOS, Windows, and Linux, see the Troubleshooting section at the bottom of this document.

Permission denied

The nrf52 communicates with the Linux host via the ttyACM0 device. On Ubuntu Linux the ttyACM0 device is owned by the dialout group. If you get a permission denied error when trying to connect to the xsbug debugger, add your user to the dialout group:

sudo adduser <username> dialout
sudo reboot

Permission problems with `MODDABLE4` or other `nrf52` disk

When the nrf52 device is in programming mode (ie. double-press the reset button), it should appear on the desktop. If there are permissions problems, try the following command to mount the disk:

udisksctl mount -b /dev/sdb -t FAT

Troubleshooting

Stack overflow

region RAM overflowed with stack

If you are building an application and the link fails with an error arm-none-eabi/bin/ld: region RAM overflowed with stack, you will need to reduce the amount of RAM allocated to the heap.

By default, NRF52_HEAP_SIZE is set to 0x35000.

In your application manifest, you can change the NRF52_HEAP_SIZE allocation:

    "build": {
        "NRF52_HEAP_SIZE": "0x30000"
     }

Application too large

ld: region FLASH overflowed with .data and user data
section '.text' will not fit in region 'FLASH'
ld: region `FLASH' overflowed by 2285384 bytes

If you are building an application and the link fails with an error like those above, your application is too large. Reduce the size of the application resources or restructure your code.

Advanced

Debugging Over Serial

Custom devices and some development boards may not have a USB port for debugging.

The Moddable SDK can connect to xsbug over a serial connection.

`manifest.json` changes

In the build section, ensure the following settings:

"USE_USB": "0",
"FTDI_TRACE": "-DUSE_FTDI_TRACE=0"

In the defines section, set up a debugger clause, setting up pins and baudrate:

"debugger": {
    "tx_pin": "NRF_GPIO_PIN_MAP(0,30)",
    "rx_pin": "NRF_GPIO_PIN_MAP(0,31)",
    "baudrate": "NRF_UARTE_BAUDRATE_460800"
},

Environment changes

Set the DEBUGGER_PORT environment variable to refer to your serial adapter and set the DEBUGGER_SPEED.

export DEBUGGER_PORT=/dev/cu.usbserial-0001
export DEBUGGER_SPEED=460800

Build and install the application.

Connect to the debugger

If xsbug is not running, launch it:

macOS:

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

On Windows and Linux you can just type:

xsbug

Run serial2xsbug to connect:

serial2xsbug $DEBUGGER_PORT $DEBUGGER_SPEED 8N1

Reset the device, and it will connect to xsbug.

Installing apps via Serial

The bootloader and Moddable SDK support installation of firmware using the serial port. Note that a build of the bootloader supports either programming via USB or Serial but not both.

To install via serial, you need to take the follow steps:

Modify your bootloader board.h file
Build and install the bootloader
Build your Moddable apps with a special target

These steps are explained in detail below.

Bootloader

The bootloader needs to be built specifically for the device being targeted. You need to modify the BOARD definitions file and use a build define.

`BOARD` definitions

Add this section to the src/boards/<boardname>/board.h file:

//--------------------------------------------------------------------+
// UART update
//--------------------------------------------------------------------+
#define RX_PIN_NUMBER      31
#define TX_PIN_NUMBER      30
#define CTS_PIN_NUMBER     0
#define RTS_PIN_NUMBER     0
#define HWFC               false

Set the RX_PIN_NUMBER and TX_PIN_NUMBER to the appropriate values for your board.

The status LED is useful as it blinks rapidly when the device is in programming mode. It is defined as LED_PRIMARY_PIN in this file.

Build line

When building the bootloader, add SERIAL_DFU=1 to the build line. For example:

make BOARD=<boardname> SERIAL_DFU=1 flash

See below for more details on building the bootloader.

Moddable application build target

In order to install over the serial port instead of USB, use either of the targets installDFU or debugDFU.

mcconfig -d -m -p nrf52/<boardname> -t debugDFU

installDFU simply installs the app to your device.

debugDFU installs the app, launches xsbug, and then connects to it with serial2xsbug.

Installation is done by mcconfig using Adafruit's adafruit-nrfutil.

Setup

Install Adafruit's adafruit-nrfutil as described at the github repository:

https://github.com/adafruit/Adafruit_nRF52_nrfutil

Set the environment variable UPLOAD_PORT to the serial port that is connected to your device.

export UPLOAD_PORT=/dev/cu.usbserial-0001

Device target

In the device target's manifest.json file, ensure that the debugger tx and rx pins and baudrate are defined.

The manifest.json file is located at $MODDABLE/build/devices/nrf52/targets/<boardname>/manifest.json.

In the "defines" section:

"defines": {
	"debugger": {
		"tx_pin": "30",
		"rx_pin": "31",
		"baudrate": "NRF_UARTE_BAUDRATE_921600"
	},
...

Build and install

The device needs to be in firmware update mode in order to receive the installation. Double-tap the reset button to put the device into programming mode. The status LED will blink rapidly.

mcconfig -d -m -p nrf52/<boardname> -t debugDFU

After the build information scrolls by, the console will progress to installing:

Sending DFU start packet
Sending DFU init packet
Sending firmware file
########################################
########################################
...
########################################
###########################
Activating new firmware

DFU upgrade took 69.43805122375488s
Device programmed.

Updating nRF52 over BLE (DFU OTA)

The Moddable SDK supports updating nRF52 firmware over BLE using Nordic's "nRF Connect for Mobile" apps on iOS and Android. This works with Moddable Four and other supported nRF52-powered boards.

These are the five steps to prepare your device and update the nRF52 firmware over BLE.

Ensure that your nRF52 device has version 8 (or later) of the Moddable fork of the AdaFruit bootloader.
Build your project firmware into an update package
Transfer the update package to your mobile device
Put the target device into DFU OTA mode
Use "nRF Connect for Mobile" to install the firmware onto the device wirelessly with BLE

The following sections explain these steps in detail.

Note: If the OTA firmware update fails, the device will reboot to DFU OTA mode until software has been successfully updated.

1) Ensure your nRF52 device has version 8.1 of the Bootloader

Put your device into Programming mode (double-tap the reset button) and open the volume that appears on your desktop. Open the INFO_UF2.TXT file. Look for

Bootloader: Moddable 8.1
Date: Nov  8 2023

If the version is earlier than 8.1, update your bootloader.

Update the nRF52 Bootloader

You can update your Moddable nRF52 Bootloader with a prebuilt version for your board, or you can customize it and build it yourself.

The Moddable Four Bootloader can be found in the repository at $MODDABLE/build/devices/nrf52/bootloader/. Put your device into Programming mode and copy the current.uf2 file to the device.

If you've got a different device, build and install the updated bootloader to your nRF52 device by first configuring, then building the Bootloader.

Use the Moddable fork of the Adafruit nRF52 bootloader. The minimum version to use for DFU OTA is version 8.

Configure the Bootloader

You can configure the bootloader to check the state of a GPIO pin during boot to put the device into DFU OTA mode.

Set the BUTTON_DFU define in your board.h file to specify which GPIO to use. The board.h file is located in Adafruit_nRF52_Bootloader/src/boards/<boardname>/board.h.

If you do not define a GPIO, you can programmatically set the device to reboot in DFU OTA mode. See below

Build and install the Bootloader using USB

For devices that communicate over USB, build the bootloader update file:

cd .../Adafruit_nRF52_Bootloader
rm -rf _build
git pull --rebase
make BOARD=moddable_four bootloaderuf2

Put your device into Programming mode and copy the current.uf2 file to the device:

cp current.uf2 /Volumes/MODDABLE4

Or Build and install the Bootloader using JTAG for a UART device

For devices that update over serial, use JTAG to push install the new bootloader:

cd .../Adafruit_nRF52_Bootloader
rm -rf _build
git pull --rebase
make SERIAL_DFU=1 BOARD=test flash

Note: With SERIAL_DFU=1, the example above is for a device that uses serial instead of USB for programming. Installing this bootloader will disable updating over USB.

2) Build an update package

Build your application with the -t ble-package target. The build will complete and indicate where the ble-package.zip file can be found.

 % cd .../my_app
 % mcconfig -d -m -p nrf52/moddable_four -t ble-package
 ....
 # Packaging .../my_app/xs_nrf52.hex for BLE
Zip created at .../my_app/ble-package.zip

3) Transfer the package to your mobile

Transfer the ble-package.zip file to your mobile device so that it can be accessed by "nRF Connect for Mobile".

4) Put the device in DFU OTA mode

When the device is in DFU OTA mode, the status LED will double-blink regularly.

Put nRF52 into Update Mode (programmatically)

Put the nRF52 device into BLE DFU update mode by calling the nrf52_rebootToOTA() C function. The $(MODDABLE)/build/devices/nrf52/examples/BLE_DFU app is an example of how to use it from an app.

cd $MODDABLE/build/devices/nrf52/examples/BLE_DFU
mcconfig -d -m -p nrf52/moddable_four

Put nRF52 into Update Mode (GPIO)

If your device and bootloader have a button defined as the BUTTON_DFU, hold that button and reset the device.

5) Use nRF Connect for Mobile to Wirelessly update device

Once the nRF52 is in BLE DFU update mode, use the nRF Connect for Mobile to transfer the firmware contained in the ble-package.zip file to the nRF52 device.

Launch the application and follow these steps:

Open the filter
Enable Nordic DFU Service
Enable "Remove Unconnectable"
Connect to the AdaDFU device
Select the DFU tab
Click the "Connect" button When the device has connected,
Click "Open Document Picker"
Choose your upload package
Press the "Start" button
The Status area will display "Starting" for some time as the flash area is erased.
After the area is erased, the status changes to "Uploading" and progress will be displayed as the upload continues.
When the transfer has completed, "Success!" is displayed. The device will reboot to the newly install firmware image.

Debugging Native Code

As with all Moddable platforms, you can debug script code using xsbug over the USB serial interface with Moddable Four. For more information, see the xsbug documentation. For native code source level debugging, you can use GDB.

Debugging native code on the Moddable Four requires a Nordic nRF52840-DK board, Segger J-Link Plus or compatible device.

For example, connect your Moddable Four to the nRF52840-DK board as follows:

nRF52840 DK	Moddable Four
SWD CLK	SWDCLK
SWD IO	SWDIO
RESET	RESET	(optional)
GND DETECT	GND
VTG	3V3

If you have a Segger J-Link Plus, the connections to the J-Link are as follows:

Moddable Four	J-Link
SWDCLK	TCK
SWDIO	TMS
RESET	RESET	(optional)
GND	GND
3V3	VTref

GDB is the GNU debugger widely used on Unix-like build hosts to debug native code. GDB is included in the Arm Embedded Toolchain archive downloaded during the SDK and Host Environment Setup step.

GDB communicates with the nRF58240 device via a J-Link connection in the nRF52840-DK board, Segger j-link Plus or other J-Link compatible device. Take the following steps to install/configure the required tools and launch GDB:

Install the nRF Command Line Tools. Make sure the JLinkGDBServer is somewhere in your $PATH.

Create a GDB startup command text file gdb_cmds.txt in the nrf5 directory with the following contents:

target remote localhost:2331
mon speed 10000
mon flash download=1
load
break main
mon reset 0
continue

Connect both your device and debugger USB ports to your computer. Both USB ports can be connected to the computer via a USB hub.
Build the Moddable app that includes the native code you plan to debug. For this example, we build the BLE heart-rate-server example:
```
cd $MODDABLE/examples/network/ble/heart-rate-server
mcconfig -d -m -p nrf52/moddable_four -t build
```

Launch the J-Link GDB server from a command line console:

JLinkGDBServer -device nRF52840_xxAA -if swd -port 2331

The GDB server will connect to the nRF52840-DK target and wait for a client connection:

Connecting to J-Link...
J-Link is connected.
Firmware: J-Link OB-SAM3U128-V2-NordicSemi compiled Mar 17 2020 14:43:00
Hardware: V1.00
S/N: 683214408
Checking target voltage...
Target voltage: 3.30 V
Listening on TCP/IP port 2331
Connecting to target...Connected to target
Waiting for GDB connection...

From a second command line console, launch the GDB client, passing the application ELF and GDB startup command text files as command line arguments:

arm-none-eabi-gdb $MODDABLE/build/tmp/nrf52/moddable_four/debug/heart-rate-server/xs_nrf52.out -x ~/nrf5/gdb_cmds.txt

The GDB server connects with the client, downloads the application and stops at the breakpoint main specified in the GDB setup command file:

Breakpoint 1 at 0x46550: file /Users/<user>/Projects/moddable/build/devices/nrf52/xsProj/main.c, line 149.
Resets core & peripherals via SYSRESETREQ & VECTRESET bit.

Breakpoint 1, main () at /Users/<user>/Projects/moddable/build/devices/nrf52/xsProj/main.c:149

149     clock_init();
(gdb)

At the (gdb) prompt, type c to continue execution and/or set other breakpoints, etc...

Bootloader

Applications using the Moddable SDK running on the nRF52 SoC typically use a modified Adafruit nRF52 Bootloader that supports the UF2 file format for flashing firmware to a device.

Programming mode

If the device has a debug build of a Moddable SDK app installed, the Moddable tools can automatically set the device to programming mode so you do not have to manually reset the board.

Otherwise double-tap the reset button on the device to put it into programming mode. The on-board LED blinks every second and a USB disk named MODDABLE4 appears on your desktop.

Drag a .uf2 file to the MODDABLE4 disk to program it.

Note: The bootloader can be updated in the same way.

Note: The disk that appears may be named MODDABLEnRF

Installing the bootloader the first time

To use a nRF52840 device with the Moddable SDK, you will have to install the bootloader to that device. This will replace the functionality of the previous bootloader.

Note: The Moddable Four has the bootloader pre-installed.

Note: You may brick your device.

You will need a Segger J-Link or equivalent to program the bootloader for the first time. Once a Moddable bootloader is installed, you can use the UF2 installation method.

Connect your device to the J-Link in the same way that you would for the debugger. See the Debugging Native Code section.

Fetch the bootloader repository:

git clone https://github.com/Moddable-OpenSource/Adafruit_nRF52_Bootloader --recurse-submodules

Build for your device
```
cd Adafruit_nRF52_Bootloader
make BOARD=moddable_four
```
Note: The following BOARD configurations have been updated to support Moddable.
- moddable_four
- moddable_itsybitsy_nrf52
- moddable_makerdiary_nrf52
- moddable_pca10056
- moddable_sparkfun52840
- moddable_xiao
Install to your device. First install the SoftDevice, then flash the bootloader:
```
make BOARD=moddable_four sd
make BOARD=moddable_four flash
```
Double-tap the reset button to set the device to Programming mode. The LED will blink regularly, and the MODDABLEnRF volume will appear on the desktop.

You can now program the device.
Once a Moddable bootloader has been installed on your device, you can use the bootloaderuf2 Makefile target to build an update file and copy the file to your device.

Build the bootloader with the bootloaderuf2 target
```
cd .../Adafruit_nRF52_Bootloader
make BOARD=moddable_four bootloaderuf2
```
Put your device into Programming mode and copy the current.uf2 file to your device.

nRF5 SDK Modifications

Moddable Four requires a few small adjustments to the Nordic nRF5 SDK. You can use the prepared SDK at Nordic nRF5 SDK.

Or you can make your own by following these steps to modify the SDK:

Download the Nordic nRF5 SDK by taking the following steps:
- Select v17.0.2 from the nRF5 SDK versions section.
- Uncheck all SoftDevices.
- Click the Download Files button at the bottom of the page. You should see the same selection as in the image below.
The downloaded archive is named DeviceDownload.zip. Unzip the archive and copy the nRF5_SDK_17.0.2_d674dde directory into the nrf5 directory.
Setup the NRF_SDK_DIR environment variable to point at the nRF5 SDK directory:
```
export NRF_SDK_DIR=$HOME/nrf5/nRF5_SDK_17.0.2_d674dde
```
Add a board definition file for the Moddable Four to the Nordic nRF5 SDK. The board definition file includes Moddable Four LED, button and pin definitions. To add the Moddable Four board definition file, take the following steps:
- The moddable_four.h board definition file is found in $MODDABLE/build/devices/nrf52/config/moddable_four.h. Copy the moddable_four.h file to the Nordic nRF5 SDK components/boards/ directory.
```
cp $MODDABLE/build/devices/nrf52/config/moddable_four.h $NRF_SDK_DIR/components/boards
```
- Modify $NRF_SDK_DIR/components/boards/boards.h, adding the following before #elif defined(BOARD_CUSTOM):
```
#elif defined (BOARD_MODDABLE_FOUR)
  #include "moddable_four.h"
```
Add SPIM3 support:

The nRF5 SDK has a file integration/nrfx/legacy/apply_old_config.h that needs a small change. Add || NRFX_SPIM3_ENABLED after the NRFX_SPIM2_ENABLED as shown in the line below:
```
#define NRFX_SPIM_ENABLED \
(SPI_ENABLED && (NRFX_SPIM0_ENABLED || NRFX_SPIM1_ENABLED || NRFX_SPIM2_ENABLED || NRFX_SPIM3_ENABLED))
```

Enable LE secure connection support:

Disable the stack overflow check in the nrf_stack_info_overflowed function In the Nordic SDK nrf_stack_info.h file:

__STATIC_INLINE bool nrf_stack_info_overflowed(void)
{
#if 0
    if (NRF_STACK_INFO_GET_SP() < NRF_STACK_INFO_BASE)
    {
        return true;
    }
#endif
    return false;
}

Files

nrf52.md

Latest commit

History

nrf52.md

File metadata and controls

Using the Moddable SDK with nRF52

Table of Contents

Overview

Platforms

nRF52

Build Types

Debug

Instrumented

Release

macOS

Installing

Troubleshooting

Windows

Installing

Troubleshooting

Linux

Installing

Linux Troubleshooting

Permission denied

Permission problems with MODDABLE4 or other nrf52 disk

Troubleshooting

Stack overflow

Application too large

Advanced

Debugging Over Serial

manifest.json changes

Environment changes

Connect to the debugger

Installing apps via Serial

Bootloader

BOARD definitions

Build line

Moddable application build target

Setup

Device target

Build and install

Updating nRF52 over BLE (DFU OTA)

1) Ensure your nRF52 device has version 8.1 of the Bootloader

Update the nRF52 Bootloader

Configure the Bootloader

Build and install the Bootloader using USB

Or Build and install the Bootloader using JTAG for a UART device

2) Build an update package

3) Transfer the package to your mobile

4) Put the device in DFU OTA mode

Put nRF52 into Update Mode (programmatically)

Put nRF52 into Update Mode (GPIO)

5) Use nRF Connect for Mobile to Wirelessly update device

Debugging Native Code

Bootloader

Programming mode

Installing the bootloader the first time

nRF5 SDK Modifications

Permission problems with `MODDABLE4` or other `nrf52` disk

`manifest.json` changes

`BOARD` definitions