DOCUMENTATION DEVICES nRF52
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

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.

Table of Contents

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

    1. Install the Moddable SDK tools by following the instructions in the Getting Started document.

    2. Create an nrf5 directory in your home directory at ~/nrf5 for required third party SDKs and tools.

    3. 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:

      Catalina Developer Options

    4. 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.

    5. 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.

    6. 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
      
    7. 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.

    8. 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
      
    9. Verify the setup by building helloworld for your device target:

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

    Troubleshooting

    Windows

    Installing

    1. Install the Moddable SDK tools by following the instructions in the Getting Started document.

    2. 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
      
    3. 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.

    4. 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.

    5. 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.

    6. 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
      
    7. Download and run the Python installer for Windows. Choose the default options.

    8. Edit the system PATH environment variable to include the Python directories:

      C:\Python27
      C:\Python27\Scripts
      
    9. 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

    1. Install the Moddable SDK tools by following the instructions in the Getting Started document.

    2. Create a nrf5 directory in your home directory at ~/nrf5 for required third party SDKs and tools.

      cd $HOME
      mkdir nrf5
      cd nrf5
      
    3. 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.

    4. 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.

    5. 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.

    6. 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
      
    7. 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:

    1. Modify your bootloader board.h file
    2. Build and install the bootloader
    3. 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.

    1. Ensure that your nRF52 device has version 8 (or later) of the Moddable fork of the AdaFruit bootloader.
    2. Build your project firmware into an update package
    3. Transfer the update package to your mobile device
    4. Put the target device into DFU OTA mode
    5. 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:

    1. Open the filter

    2. Enable Nordic DFU Service

    3. Enable "Remove Unconnectable"

    4. Connect to the AdaDFU device
       

    5. Select the DFU tab

    6. Click the "Connect" button When the device has connected,

    7. Click "Open Document Picker"
       

    8. Choose your upload package

    9. Press the "Start" button
       

    10. The Status area will display "Starting" for some time as the flash area is erased.

    11. After the area is erased, the status changes to "Uploading" and progress will be displayed as the upload continues.
       

    12. 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:

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

    2. 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
      
    3. Connect both your device and debugger USB ports to your computer. Both USB ports can be connected to the computer via a USB hub.

    4. 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
      
    5. 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...
      
    6. 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)
      
    7. 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.

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

    2. Fetch the bootloader repository:

      git clone https://github.com/Moddable-OpenSource/Adafruit_nRF52_Bootloader --recurse-submodules
      
    3. 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
    4. Install to your device. First install the SoftDevice, then flash the bootloader:

      make BOARD=moddable_four sd
      make BOARD=moddable_four flash
      
    5. 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.

    6. 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:

    1. 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.

    2. 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
      
    3. 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"
    4. 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))
      
    5. 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;
      }