Configuring your application for a custom PCB

This guide demonstrates how to create your custom board files for your PCB for the nRF54H20 SoC.

Prepare your PCB 

First, you need to create your PCB for the nRF54H20 SoC.

Use the PCB layouts and component values provided by Nordic Semiconductor, especially for clock and power sources, considering the following limitations:

The DC/DC inductor must be present on the PCB for any of the supported power schemes. Use one of the following power supply options:
- VDDH higher than 2.05V.
- VDDH shorted to VDD at 1.8V
For the lowest sleep power consumption, use a 32 KHz crystal.
The P9 port cannot be used with internal or external pull-down resistors.
For optimal performance, the output impedance of the P6 and P7 ports should match the PCB and external device pin impedance.

Prepare the configuration files for your custom board in the nRF Connect SDK 

Use the nRF Connect for VS Code Extension Pack to generate a custom board skeleton.

Use the nRF54H20 DK board files found in sdk-zephyr/boards/nordic/nrf54h20dk as a reference point for configuring your own custom board.

See the following documentation pages for more information:

The Devicetree documentation to familiarize yourself with the devicetree language and syntax.
The Configuring the nRF54H20 SoC page for more information on how to configure your DTS files for the nRF54H20 SoC.
The Zephyr repository application page for more information on Zephyr application types.
The Adding your own code documentation for details on the best user workflows to add your own code to the nRF Connect SDK.

Caution

The configuration of board files is based on the nRF54H20 common SoC files located in sdk-zephyr/dts/vendor/nordic/. Each new nRF Connect SDK revision might change these files, breaking the compatibility with your custom board files created for previous revisions. Ensure the compatibility of your custom board files when migrating to a new nRF Connect SDK release.

See Board Porting Guide for more information.

Configure, generate, and program the BICR 

The nRF54H20 SoC requires valid Board Information Configuration Registers (BICR) configuration to function properly. The BICR are non-volatile memory (NVM) registers that contain information on how the nRF54H20 SoC must interact with other board elements, including the information about the power and clock delivery to the SoC. The power and clock control firmware uses this information to apply the proper regulator and oscillator configurations.

Caution

You must ensure that the configuration is correct. An incorrect configuration can damage your device.

BICR allows for the configuration of various components on your custom board, like the following:

Power scheme
Low-frequency oscillator (LFXO or LFRC)
High-frequency oscillator (HFXO)
GPIO ports power and drive control
Tamper switches
Active shield channels

When the BICR has not been programmed, all the registers contain 0xFFFFFFFF.

The LFOSC.LFXOCAL register is used by the device to store the calibration of the LFXO.

When you use the LFXO oscillator as the LFCLK clock source and LFOSC.LFXOCAL is set to 0xFFFFFFFF at device boot, the firmware calibrates the LFXO oscillator and writes the calibration data to the LFOSC.LFXOCAL register. This is useful when making a change on the PCB (for example, when changing the crystal), or after programming a new BICR configuration.

In this case, LFXO calibration is performed during startup. This process is fully automated and typically takes 3 to 3.5 seconds. The SoC must remain powered during this time to complete the procedure. Until calibration is complete, the SoC uses the LFRC oscillator. If calibration does not succeed, it will be repeated during the next startup procedure.

Configuring BICR in JSON for nRF54H20 SoC 

To configure BICR for your custom board based on the nRF54H20 SoC, use a JSON file.

Note

The following settings mostly map to the hardware reference in the nRF54H20 datasheet.

Sources

The following files define the JSON schema and provide examples for configuring BICR for the nRF54H20 DK:

JSON format definition: sdk-zephyr/soc/nordic/nrf54h/bicr/bicr-schema.json
BICR configuration example in JSON format: sdk-zephyr/boards/nordic/nrf54h20dk/bicr.json

You can use these files as a reference for your own BICR configuration.

The nRF Connect SDK build system uses the BICR configuration JSON files to generate the corresponding HEX file.

Caution

A mismatch between the board and the configuration values in BICR can damage the device or set it in an unrecoverable state.

Supply configuration

Supply options are configured in the power->scheme property. Two standard hardware layouts are supported.

This layout is configured as follows:

{
  "power": {
    "scheme": "VDDH_2V1_5V5"
  }
}

This layout is configured as follows:

{
  "power": {
    "scheme": "VDD_VDDH_1V8"
  }
}

Inductor configuration

Each supported supply scheme includes an inductor. No additional configuration is needed beyond setting the power->scheme property.

GPIO power configuration

GPIO port assignments are specified within the ioPortPower object, with each mode explicitly indicated.

The available port configuration keys are the following:

Port	Port configuration key
P1	p1Supply
P2	p2Supply
P6	p6Supply
P7	p7Supply
P9	p9Supply

The supported operating modes for these ports are the following:

Supported operating mode	JSON configuration
Disconnected	DISCONNECTED
Shorted	SHORTED
External1v8	EXTERNAL_1V8
ExternalFull	EXTERNAL_FULL

The resulting JSON configuration is structured as follows:

{
  "ioPortPower": {
    "p1Supply": "EXTERNAL_1V8",
    "p2Supply": "EXTERNAL_1V8",
    "p6Supply": "EXTERNAL_1V8",
    "p7Supply": "EXTERNAL_1V8",
    "p9Supply": "EXTERNAL_FULL"
  }
}

GPIO power drive and impedance configuration

This section specifies the IO port impedance settings for P6 and P7.

The nRF54H20 SoC allows you to select from these supported impedance values:

33 Ohms
40 Ohms
50 Ohms
66 Ohms
100 Ohms

The configuration can be represented as follows:

{
  "ioPortImpedance": {
    "p6ImpedanceOhms": 50,
    "p7ImpedanceOhms": 50
  }
}

Low Frequency Oscillator (LFOSC) configuration

The JSON format is inside lfosc: { lfxo: { ... } }.

The following parameters are used in the LFOSC configuration:

accuracyPPM - Specifies the accuracy of the oscillator in parts per million (PPM). Supported values range from 20 to 500 PPM.
mode - Defines the oscillator mode. It can be CRYSTAL for crystal operation, EXT_SINE for external sine wave input, or EXT_SQUARE for external square wave input.
builtInLoadCapacitancePf - Specifies the built-in load capacitance in picofarads (pF). The valid range is from 1 to 25 pF. This parameter is only applied if builtInLoadCapacitors is set to true.
startupTimeMs - Defines the startup time for the LFXO oscillator in milliseconds. The valid range is from 1 to 4095 ms.

Note

This value is currently not used.
source - Specifies the low-frequency clock source. It can be LFXO when an external crystal oscillator is in place, or LFRC when an external crystal oscillator is not in place.

Note

If you select LFXO as the low-frequency clock source, the SoC performs an automated LFXO calibration during startup when no calibration has been stored yet (for example, when LFOSC.LFXOCAL is set to 0xFFFFFFFF after programming a new BICR configuration). This process takes approximately 3 to 3.5 seconds, during which the SoC must remain powered. Until calibration is complete, the SoC uses the LFRC oscillator. For more information, see Configure, generate, and program the BICR.

ACCURACY

The following are valid values for accuracyPPM:

20
30
50
75
100
150
250
500

MODE

The following are valid values for mode:

CRYSTAL
EXT_SINE
EXT_SQUARE

LOADCAP

The valid values for builtInLoadCapacitancePf are from 1 to 25 pF. This parameter is only applied if builtInLoadCapacitors is set to true.

TIME

The valid values for startupTimeMs are from 1 to 25 ms.

Note

This value is currently not used.

See the following example:

{
  "lfosc": {
    "source": "LFXO",
    "lfxo": {
      "mode": "CRYSTAL",
      "accuracyPPM": 20,
      "startupTimeMs": 600,
      "builtInLoadCapacitancePf": 15,
      "builtInLoadCapacitors": true
    }
  }
}

Source

The source option can be one of the following:

LFXO, when an external crystal oscillator is in place.
LFRC, when an external crystal oscillator is not in place.

This means that the device can use either LFRC or SYNTH as clock sources.

LFRC autocalibration configuration

The following parameters are used in the LFRC autocalibration configuration:

temp-interval - Specifies the interval between temperature measurements, expressed in 0.25-second increments.
temp-delta - Defines the temperature change, in 0.25-degree Celsius steps, that triggers a calibration event.
interval-max-count - Indicates the maximum number of measurement intervals allowed between calibrations, regardless of temperature variations.

Use these parameters to precisely control the LFRC autocalibration behavior.

Datasheet register field

Datasheet field	JSON variable	JSON value
TEMPINTERVAL (A)	`tempMeasIntervalSeconds`	4
TEMPDELTA (B)	`tempDeltaCalibrationTriggerCelsius`	0.5
INTERVALMAXNO (C)	`maxMeasIntervalBetweenCalibrations`	2
ENABLE	`calibrationEnabled`

LFRC autocalibration is not configured in the JSON configuration files for the DK, as the default values (4, 0.5 and 2) will be good enough for most use-cases. However, the example would be as follows:

{
  "lfrccal": {
    "calibrationEnabled": true,
    "tempMeasIntervalSeconds": 4,
    "tempDeltaCalibrationTriggerCelsius": 0.5,
    "maxMeasIntervalBetweenCalibrations": 2
  }
}

Note

Use the default values unless a custom calibration profile is needed.
tempDeltaCalibrationTriggerCelsius - In the JSON BICR format, the maximum allowable value for this field is 31.75 °C.

HFXO configuration and startup

The following table maps configuration options for HFXO modes:

Datasheet register field	JSON variable (within `hfxo`)
HFXO.CONFIG: MODE	mode
HFXO.CONFIG: LOADCAP	builtInLoadCapacitancePf
HFXO.STARTUPTIME: TIME	startupTimeUs (depends on `builtInLoadCapacitors` being `true`)

hfxo-mode

Datasheet (MODE)	JSON (mode)
Crystal	CRYSTAL

The current standard configuration for the DK is as follows:

{
  "hfxo": {
    "mode": "CRYSTAL",
    "startupTimeUs": 850,
    "builtInLoadCapacitors": true,
    "builtInLoadCapacitancePf": 14
  }
}

Generate the BICR binary 

To generate the BICR binary, you must first set the Kconfig option CONFIG_SOC_NRF54H20_GENERATE_BICR to y. When running west build for the cpuapp core, the build system creates the relevant HEX file (bicr.hex) at build time.

Note

If the build system is unable to locate the bicr.json file inside your custom board’s directory, the build system will skip it.

You can find the generated bicr.hex file in the build_dir/<sample>/zephyr/.

Program the BICR binary 

After the nRF Connect SDK build system generates the BICR binary, you must flash this binary manually. The content of BICR should be loaded to the SoC only once and should not be erased nor modified unless the PCB layout changes. To manually program the generated bicr.hex file to the SoC, use nRF Util as follows:

nrfutil device program --options chip_erase_mode=ERASE_NONE --firmware bicr.hex --core Application --serial-number <serial_number>

You only need to follow this programming process once, assuming the PCB configuration applied through the BICR is correct the first time. However, it is also possible to reprogram the BICR while in the LCS RoT. This can be useful, for example, when adjusting the configuration as the PCB design gets refined or modified, requiring the process to be repeated.

Note

After you program the BICR, the LFCLK calibrates on first boot. Do not expect accurate LFCLK timing for about 3.5 to 4 seconds. If calibration does not complete, the system controller (sysctrl) starts calibration on the next boot.

Validate the BICR binary

After programming the BICR binary onto the device, validate whether the BICR works with your device as follows:

Reset the device:

nrfutil device reset --reset-kind RESET_PIN --serial-number <serial_number>

When in LCS EMPTY, use nrfutil to validate the BICR status by reading the memory:
```
nrfutil device x-read --address 0x2F88FF1C --serial-number 1051164514 --core Secure
```
nrfutil returns the BICR loading status using one of the following values:
- 0x289CFB73: BICR applied without error. This indicates that the power configuration of the BICR is valid and you can proceed to the next step.
- 0xD78213DF: BICR application was skipped. This indicates that no BICR was programmed to the device. Revisit the previous step to ensure the programming command was executed, and that the BICR was correctly generated.
- 0xCE68C97C: BICR application failed. This indicates that there is an issue with the BICR, but in most cases this can be recovered by programming the correct BICR for your board.
- Error: This indicates that the device is likely suffering from severe power issues after applying the BICR. This state is likely unrecoverable.

Read the BICR from the device

You can read the BICR from the nRF54H20 SoC to verify the configuration stored on the device. This can be useful for confirming that the BICR was programmed correctly, or for comparing the on-device configuration against your source bicr.json file.

To read the current BICR configuration from a device, complete the following steps:

Read the BICR memory area using nRF Util:

nrfutil device read --address 0x0FFF87B0 --bytes 0x40 --to-file bicr_readout.hex

Convert the HEX file to JSON format using the bicrgen.py script:

python <NRF_CONNECT_SDK>/zephyr/soc/nordic/nrf54h/bicr/bicrgen.py --input bicr_readout.hex --output decoded_bicr.json --svd <NRF_CONNECT_SDK>/modules/hal/nordic/nrfx/bsp/stable/mdk/nrf54h20_application.svd

The output file decoded_bicr.json contains the BICR information stored on the device.

Provision the nRF54H20 IronSide SE binaries 

After programming the BICR, the nRF54H20 SoC requires the provisioning of the nRF54H20 IronSide SE binaries, a bundle containing the precompiled firmware for the Secure Domain and System Controller.

Note

To program the nRF54H20 IronSide SE binaries on your nRF54H20 SoC-based device, your device must be in lifecycle state (LCS) EMPTY. This means that this is likely the first use of your nRF54H20 DK.

Devices already provisioned using SUIT-based binaries and in LCS RoT cannot be transitioned back to LCS EMPTY. For more information, see IronSide SE ABI compatibility.

To provision the nRF54H20 IronSide SE binaries to the nRF54H20 SoC, complete the following steps:

Download the latest nRF54H20 IronSide SE binaries. You can find the version compatible with your nRF Connect SDK version listed on the IronSide SE ABI compatibility page.

Note

On MacOS, ensure that the ZIP file is not unpacked automatically upon download.
Move the .zip bundle to a folder of your choice, then run nRF Util to program the binaries using the following command:
```
nrfutil device x-provision-nrf54h --firmware <path-to_bundle_zip_file> --serial-number <serial_number>
```

Transition the nRF54H20 SoC to RoT 

The nRF54H20 SoC comes with its lifecycle state (LCS) set to EMPTY. To operate correctly, you must transition its lifecycle state to Root of Trust (RoT).

Caution

The forward transition to LCS RoT is permanent. After the transition, you cannot transition backward to LCS EMPTY.

To transition the LCS to RoT, do the following:

Set the LCS of the nRF54H20 SoC to RoT using the following command:
```
nrfutil device x-adac-lcs-change --life-cycle rot --serial-number <serial_number>
```
If issues occur during bundle programming, the system returns an ADAC_FAILURE error.

After the LCS transition, reset the device:

nrfutil device reset --reset-kind RESET_PIN --serial-number <serial_number>

Create or modify your application for your custom board 

You can now create or modify your application for your custom board. When doing so, consider the following:

When reusing the nRF Connect SDK applications and samples, you must provide board-specific overlay files when such files are needed. For more information on configuration overlays, see Configuring and building.

However, on the nRF54H20 SoC, the application might require board overlays for multiple cores. In this case, ensure that these overlays are consistent with each other.
When creating a new application specific to your new board, DTS board files can contain all necessary configurations, and no overlay file is needed. However, the same limitations regarding the consistency and UICR configuration apply, but should be kept on the board files level.
You must manually program the BICR if it has been modified.

For more information on nRF Connect SDK application development, see Application development. For more information on nRF54H20 SoC development, see Developing with nRF54H Series.

Update the nRF54H20 IronSide SE binaries 

Caution

It is not possible to update the nRF54H20 binaries from a SUIT-based (up to 0.9.6) to an IronSide-SE-based (2x.x.x) version.

To update the nRF54H20 IronSide SE binaries (versions 2x.x.x, based on IronSide SE) using the debugger on a nRF54H20 SoC, use the west ncs-ironside-se-update command. This command takes the nRF54H20 IronSide SE binary ZIP file and uses the IronSide SE update service to update both the IronSide SE and IronSide SE Recovery (or optionally just one of them).

For more information on how to use the ncs-ironside-se-update command, see Updating IronSide SE. For more information on the nRF54H20 IronSide SE binaries, see IronSide SE ABI compatibility.