If you have any questions or issues related to these resources, please Ask a new question, and the NXP support team can address it there.
Custom board
The Zephyr repository includes support for dozens of NXP development boards. When creating a custom board, it is best to start with the closest development board using an SOC from the same family, clone that board folder, rename as the new board, and modify to match the hardware. More resources for custom boards include:
Zephyr Project Board Porting Guide
NXP blog: Creating a Custom Zephyr Board for the i.MX RT685
See section "Generating a board pinctrl" on this page
If changing memory settings from the cloned development board, see Memory details with Zephyr.
With MCUXpresso for VS Code, as of v25.3.72, out-of-tree boards are not supported when importing Zephyr applications. This feature will be added soon. In the meantime, there is a workaround.
Unsupported SOC part number
A common challenge when creating a custom board is that not every SOC part number sold by NXP is supported in Zephyr today.
Support in Zephyr is based on boards, not directly by SOCs. A board name must be specified when building a Zephyr application. Then the board files include the SOC used on that board. These are the NXP boards supported in Zephyr. The Zephyr documentation framework does not have similar pages for SOCs.
NXP contributes Zephyr support for development boards. One development board usually supports a family of SOCs. The development board usually has the superset SOC on the board, which offers the most features/memory of that family. For example, MIMXRT1060-EVK board is used to develop with the i.MX RT106x family, and uses the superset RT1062 part number. Other part numbers in a family are very similar to the superset, but may lack some features, have less memory, or less pins in a smaller package.
Since Zephyr support is based on boards, and the SOCs on the boards are supported, today there are many other similar SOC part numbers that are not directly supported in Zephyr. Here are some options to manage this when creating a custom board:
Base the custom board on the development board supported in Zephyr, and use the same SOC part number on the custom board. That SOC is already available in Zephyr to enable the development board.
Use an SOC in the same family on the circuit board, but configure the Zephyr custom board to use the superset SOC on the development board. For example, the circuit board uses an RT1061 part number, but the custom board files use the same RT1062 part number from the MIMXRT1060-EVK. The advantage of this option is Zephyr does not require any additional SOC support. The superset likely has all the features and memory available for the SOC on the circuit board. Then the custom board files can modify the devicetree and Kconfig by disabling peripherals that are not available, and reducing memory sizes as needed. SOC pinctrl files are available for most SOCs in supported families, found in the HAL_NXP repo. Usually the custom board can include the SOC pinctrl file for the exact part number used.
Use an SOC in the same family, but contribute all the SOC files needed in Zephyr. For example, the circuit board uses an RT1061 part number, so the developer adds the RT1061 part number option to the Zephyr repo, and configures the custom board to use that RT1061 part number. This option requires more effort and some comfort with the Zephyr repo, but some Zephyr users may prefer this option. And if a new SOC is enabled like this, it can be contributed upstream to the Zephyr repo.
The SOC options discussed above assume a board for the SOC family is already supported in Zephyr, which enables at least one SOC in that family. If trying to port Zephyr to a new family of SOCs with no board support, that can take significantly more effort. To minimize porting effort, it is best to start with a family of SOCs already supported on a board.
Pinctrl
Zephyr uses pinctrl to configure the pins and pinmux settings of an SOC. Typically, each board has a pinctrl file with the default pinctrl settings for that board. For example, this is the mimxrt1060_evk-pinctrl.dtsi. NXP also has pinctrl files for each SOC, like mimxrt1062dvl6a-pinctrl.dtsi. The SOC pinctrl files are located in the HAL_NXP repo and provide all the pinmux options for each pin, which makes it easier and more readable to select the pinmux option in the board pinctrl file. For the NXP boards, the board pinctrl file includes the SOC pinctrl file like this:
#include <nxp/nxp_imx/rt/mimxrt1062dvl6a-pinctrl.dtsi>
Generating a board pinctrl
New board pinctrl files are usually created when creating a new board. Board pinctrl files can always be created by hand. But generating the file can be convenient, especially since NXP offers the Pins Tool included in the MCUXpresso Config Tool. The Pins Tool has a GUI to help select all the desired signals used by the application, and configure the pinmux and pin settings. Starting with release v25.03, the Config Tool can generate Zephyr board pinctrl files for the i.MX RT1xxx and MCX devices. More devices supported in Zephyr will be added in later releases. To learn how to generating a board pinctrl file, see the Config Tool User Guide.
For other devices not yet supported in the Config Tool, NXP has a Python script to help generate a board pinctrl file. These scripts will eventually be replaced by the Config Tool and deprecated. The script uses the same Config Tool above to configure the pins of a board, and then extracts the pin information from a file and generates the board pinctrl file. The scripts are included in the HAL_NXP repo and documented with this Readme.
If generation is not an option, then the board pinctrl must be hand written. The best option is to find a board pinctrl file for a similar SOC, and modify as needed.
New out-of-tree application
The Zephyr repository is full of samples and tests applications, which are helpful to learn how to use a driver, subsystem, or module. When creating a new application, a new Git repo can be created for the app, and West can be used to pull in the Zephyr repo as a module. Applications frequently use West’s T2 Star topology with Zephyr. These example repos are a good reference when creating your application repo:
Zephyr Project’s example-application repo, includes an out-of-tree board and driver
NXP repository of Zephyr demos and examples
NXP Pro Support repository of Zephyr examples
Return to Zephyr Knowledge Hub
View full article