Interface MCU Firmware¶

Overview¶

This guide walks you through building and running the Interface MCU Firmware which enables a CMSIS-DAP interface for debug and programming, a USB-UART bridge for terminal emulation and an Interface Shell for accessing board-specific functionality.

How it works¶

The nRF9151 Connect Kit comes with an on-board Interface MCU built using the nRF52820. The Interface MCU Firmware is running on the nRF52820. It implements a CMSIS-DAP interface for debugging and programming the nRF9151 SiP. It also exposes two USB CDC ACM devices, one acts as a UART bridge between the host and the nRF9151 SiP, the other enables an Interface Shell for accessing board-specific functionality such as battery charger settings.

The Interface MCU also comes pre-programmed with the UF2 Bootloader, an easy-to-use and self-upgradable bootloader that can be used to update the firmware by just copying the .uf2-format images to the flash drive without using an external programmer.

The following figure describes the functional architecture of the Interface MCU:

Requirements¶

Before you start buiding the application, check that you have the required hardware and software:

1x nRF9151 Connect Kit
1x USB-C Cable
A computer running macOS, Ubuntu, or Windows 10 or newer

Building the application¶

To build the application, follow the instructions in Getting Started Guide to set up your preferred building environment.

Use the following steps to build the Interface MCU Firmware on the command line.

Open a terminal window.
Go to NCS-Project/nrf9151-connectkit repository cloned in the Getting Started Guide.
Build the application using the west build command, specifying the board (following the -b option) as nrf9151_connectkit/nrf52820.
```
west build -p always -b nrf9151_connectkit/nrf52820 applications/ifmcu_firmware
```
The -p always option forces a pristine build, and is recommended for new users. Users may also use the -p auto option, which will use heuristics to determine if a pristine build is required, such as when building another application.
After building the application successfully, the firmware with the name zephyr.uf2 can be found in the build/ifmcu_firmware/zephyr directory.

Flashing the firmware¶

The application is compatible with the UF2 Bootloader, so that you can easily flash the firmware by just copying the zephyr.uf2 file to the flash drive without using an external programmer.

To flash the firmware, complete the following steps:

Push and hold the DFU/RST button and connect your board to the USB port of your computer. Release the DFU/RST button after your board is connected.
It will mount as a Mass Storage Device called UF2BOOT. The RGB LED is breathing in red.
Drag and drop zephyr.uf2 onto the UF2BOOT volume. The RGB LED blinks red rapidly during programming.
The application starts running after the firmware programming is completed.

Note

You may experience the following errors when copying the firmware to the UF2BOOT drive on macOS 14.5 or newer:

Terminal
$ cp build/ifmcu_firmware/zephyr/zephyr.uf2 /Volumes/UF2BOOT
cp: /Volumes/UF2BOOT/zephyr.uf2: fcopyfile failed: Input/output error
cp: /Volumes/UF2BOOT/zephyr.uf2: fchmod failed: No such file or directory

Currently you can ignore these errors as the firmware programming is completed and the application should work as expected.

Usage¶

Using the CMSIS-DAP Interface¶

You can use the CMSIS-DAP Interface to debug or program the nRF9151 SiP.

Before you start, a tool that supports the CMSIS-DAP protocol should be installed. pyOCD v0.36.0 or newer is highly recommended. pyOCD will be installed automatically after setting up your development environment in Getting Started Guide.

The following sections show the typical use cases with pyOCD:

To show the connected devices, use pyocd list:

Terminal
pyocd list
#   Probe/Board              Unique ID               Target
----------------------------------------------------------------
0   ZEPHYR IFMCU CMSIS-DAP   820D9A5F0E38432F280DB   ✔︎ nrf91
    Makerdiary               nRF9151 Connect Kit

To program the nRF9151 SiP application firmware, use pyocd load:
```
pyocd load -t nrf91 application.hex
```
To update the nRF9151 SiP modem firmware, run the following command:
```
pyocd cmd -t nrf91 -c 'nrf91-update-modem-fw -f mfw_nrf91x1_2.0.2.zip' # (1)!
```
1. If -f is specified, the modem firmware is written to the device, even if the correct version is already present.

To learn more about pyOCD, see the pyOCD Documentation.

Using the USB-UART Bridge¶

The first USB CDC ACM device that the Interface MCU exposes acts as a UART bridge between the host and the nRF9151 SiP.

To see the UART output, connect to the board with a terminal emulator, specifying the correct serial port that your computer uses to communicate with the nRF9151 SiP:

WindowsmacOSUbuntu

Start PuTTY.
Configure the correct serial port and click Open:

Open up a terminal and run:

screen <serial-port-name> 115200

Open up a terminal and run:

screen <serial-port-name> 115200

Tip

The default serial port settings are the following:

Baud rate	Data bits	Stop bits	Parity	Flow Control
115200	8	1	None	None

Using the Interface Shell¶

The seconnd USB CDC ACM device that the Interface MCU exposes enables an Interface Shell for accessing the board-specific functionality.

To interact with the Interface Shell, connect to the board with a terminal emulator, specifying the correct serial port that your computer uses to communicate with the shell:

WindowsmacOSUbuntu

Start PuTTY.
Configure the correct serial port and click Open:

Open up a terminal and run:

screen <serial-port-name> 115200

Open up a terminal and run:

screen <serial-port-name> 115200

Tip

The default serial port settings are the following:

Baud rate	Data bits	Stop bits	Parity	Flow Control
115200	8	1	None	None

Type Tab to list all supported commands. When you type a command with --help, the terminal shows its usage, for example charger --help. For more information about the commands, see the Interface Shell Command Reference.

Terminal

ifsh:~$
  bootloader  cfgsync     charger     clear       device      help
  history     i2c         kernel      rem         reset       resize
  retval      settings    shell       simdet      temp        version
  viosel
ifsh:~$ charger --help
charger - Charger commands
          Please refer to TI BQ25180 Datasheet for more details.
Subcommands:
  chgdis  : Charge Disable
             Usage: charger chgdis [value: 0|1]
  sysreg  : Get or Set SYS Voltage
             Usage: charger sysreg [mode: 0-7]
             [mode: 0-7] - VBAT+225mV(>=3.8V)|4.4V|4.5V|4.6V|4.7V|4.8V|4.9V|VBUS
  ichg  : Get or Set Fast Charge Current (0-1000mA)
             Usage: charger ichg [current_ma: 0-1000]
  vbatreg  : Get or Set Battery Regulation Voltage (3500-4650mV)
             Usage: charger vbatreg [voltage_mv: 3500-4650]
  ilim  : Get or Set Input Current Limit
             Usage: charger ilim [level: 0-7]
             [level: 0-7] - 50mA|100mA|200mA|300mA|400mA|500mA|700mA|1100mA
  status  : Get Charging Status

Interface Shell Command Reference¶

The following table describes all supported commands of the Interface Shell:

Command	Description
`bootloader`	Enter Interface MCU UF2 Bootloader.
`cfgsync`	Store settings to the non-volatile memory. Only `charger` and `viosel` commands can affect the settings.
`charger chgdis [0\|1]`	Charge Disable `0` (default): Battery Charging Enabled `1`: Battery Charging Disabled
`charger sysreg [0-7]`	Get or Set SYS Voltage `0`: VBAT + 225 mV (3.8 V minimum) `1`: 4.4V `2` (default): 4.5V `3`: 4.6V `4`: 4.7V `5`: 4.8V `6`: 4.9V `7`: VBUS
`charger ichg [0-1000]`	Get or Set Fast Charge Current (0-1000mA). Default 100mA.
`charger vbatreg [3500-4650]`	Get or Set Battery Regulation Voltage (3500-4650mV). Default 4200mV.
`charger ilim [0-7]`	Get or Set Input Current Limit `0`: 50mA `1`: 100mA `2`: 200mA `3`: 300mA `4`: 400mA `5` (default): 500mA `6`: 700mA `7`: 1100mA
`charger status`	Get Charging Status.
`clear`	Clear shell screen.
`device list`	List all configured devices in the devicetree.
`help`	Show help information.
`history`	Show command history.
`i2c scan <device>`	Scan I2C devices. Use `device list` to get the I2C bus name `<device>`.
`i2c recover <device>`	Recovery I2C bus. Use `device list` to get the I2C bus name `<device>`.
`i2c read <device> <addr> <reg> [<bytes>]`	Read bytes from an I2C device. Use `device list` to get the I2C bus name `<device>`.
`i2c read_byte <device> <addr> <reg>`	Read a byte from an I2C device. Use `device list` to get the I2C bus name `<device>`.
`i2c direct_read <device> <addr> [<bytes>]`	Read byte stream directly from an I2C device without writing a register address first. Use `device list` to get the I2C bus name `<device>`.
`i2c write <device> <addr> <reg> [<byte1>, ...]`	Write bytes to an I2C device. Use `device list` to get the I2C bus name `<device>`.
`i2c write_byte <device> <addr> <reg> <value>`	Write a byte to an I2C device. Use `device list` to get the I2C bus name `<device>`.
`i2c speed <device> <speed>`	Configure I2C bus speed. Use `device list` to get the I2C bus name `<device>`.
`kernel cycles`	Get Kernel cycles.
`kernel reboot`	Reboot kernel.
`kernel sleep <ms>`	Kernel sleeps for millisecond.
`kernel thread list`	List kernel threads.
`kernel thread stacks`	List threads stack usage.
`rem`	Ignore lines beginning with 'rem '.
`reset [nrf52820]`	Reset nRF52820.
`reset nrf9151`	Reset nRF9151 SiP.
`resize`	Console gets terminal screen size or assumes `default` in case the readout fails. It must be executed after each terminal width change to ensure correct text display.
`resize default`	Assume 80 chars screen width and send this setting to the terminal.
`retval`	Print return value of most recent command.
`settings list [subtree]`	List all settings in a subtree (omit to list all).
`settings read [type] <name>`	Read a specific setting. `type`: `string` or `hex` (default: `hex`)
`settings write [type] <name> <value>`	Write to a specific setting. `type`: `string` or `hex` (default: `hex`)
`settings delete <name>`	Delete a specific setting.
`shell backends`	List active shell backends.
`shell backspace_mode`	Toggle backspace key mode. Some terminals are not sending separate escape code for backspace and delete key. This command forces shell to interpret delete key as backspace.
`shell colors`	Toggle colored syntax.
`shell vt100`	Toggle vt100 commands.
`shell prompt`	Toggle prompt.
`shell echo`	Toggle shell echo.
`shell stats reset`	Reset shell statistics for the Logger module.
`shell stats show`	Get shell statistics for the Logger module.
`simdet`	Display nano-SIM Card status.
`temp`	Get the die temperature of the nRF52820.
`version [-a\|--all]`	Show Interface MCU version. Use `-a` or `--all` option to show more details.
`viosel [0\|1]`	Get or set VIO voltage `0` (default): 3.3V `1`: 1.8V