.. include:: ../substitutions.rst
.. _FWDev-rt1170:

Building the Firmware
=====================

PHYTEC provides firmware for the |product| based on the Zephyr Project - an open-source real-time operating system (RTOS) designed for resource-constrained devices. This section walks you through setting up your development environment and building the example firmware for the |product| Development Kit. Once built, the firmware can be used as a foundation for further development.

If you prefer not to build the software yourself or want to evaluate the development kit quickly, you can use one of the available :ref:`PreBuilts-rt1170`.

Requirements
------------

Before you begin, ensure the following system requirements are met:

* Ubuntu 20.04 LTS (or newer), 64-bit, with root privileges
  * Virtual environments such as VMWare Workstation, VMWare Player, or VirtualBox are supported
* At least 10 GB of free disk space
* Active internet connection

Host Setup
----------

Install the required host packages for Zephyr:

.. code-block:: console
   :substitutions:

   |host-prompt| sudo apt install --no-install-recommends git cmake ninja-build gperf ccache \
                               dfu-util device-tree-compiler wget python3-dev python3-pip \
                               python3-setuptools python3-tk python3-wheel xz-utils file \
                               make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

Installing the Zephyr SDK
~~~~~~~~~~~~~~~~~~~~~~~~~

For a minimal setup, download the SDK for only the required ``ARM32`` target:

.. code-block:: console
   :substitutions:

   |host-prompt| cd ~
   |host-prompt| wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v|sdk-version|/|sdk-tar-name|
   |host-prompt| wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v|sdk-version|/sha256.sum | shasum --check --ignore-missing
   |host-prompt| tar xvf |sdk-tar-name|

Enter the extracted SDK directory and run the setup script:

.. code-block:: console
   :substitutions:

   |host-prompt| cd zephyr-sdk-|sdk-version|
   |host-prompt| ./setup.sh -c -h -t arm-zephyr-eabi

Install the udev rules required for OpenOCD:

.. code-block:: console
   :substitutions:

   |host-prompt| sudo cp ~/zephyr-sdk-|sdk-version|/sysroots/x86_64-pokysdk-linux/usr/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d
   |host-prompt| sudo udevadm control --reload

Git Setup
~~~~~~~~~

If you haven't already configured Git on your host, run the following:

.. code-block:: console
   :substitutions:

   |host-prompt| git config --global user.email "your@email.com"
   |host-prompt| git config --global user.name "Your Name"

.. note::
   New to Git? Check out the official guide: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup

Source Directory Setup
~~~~~~~~~~~~~~~~~~~~~~

Create a dedicated directory for your Zephyr-based firmware development and navigate into it:

.. code-block:: console
   :substitutions:

   |host-prompt| mkdir -p ~/|release-name|/
   |host-prompt| cd ~/|release-name|/

Create a Python virtual environment and install the required tools:

.. code-block:: console
   :substitutions:

   |host-prompt| virtualenv .venv
   |host-prompt| source .venv/bin/activate
   |host-prompt| pip install west pyelftools pyocd

Clone the Zephyr example repository for the |product| and initialize all necessary submodules, including Zephyr and the NXP HAL:

.. code-block:: console
   :substitutions:

   |host-prompt| west init -m https://github.com/phytec/zephyr-phytec-rt1170-examples --mr |release-example-app-tag| .
   |host-prompt| west update
   |host-prompt| west zephyr-export

Building the Example Firmware
-----------------------------

Before building, source the Zephyr environment script:

.. code-block:: console
   :substitutions:

   |host-prompt| source zephyr/zephyr-env.sh

.. note::
   Remember to activate the Python virtual environment and source the Zephyr environment script each time you open a new terminal.

To build the default firmware for the Cortex-M7 core:

.. code-block:: console
   :substitutions:

   |host-prompt| west build -p auto -b phyboard_atlas/mimxrt1176/cm7 zephyr-phytec-rt1170-examples/app

To target the Cortex-M4 core instead, change the board name to ``phyboard_atlas/mimxrt1176/cm4``.

Optional: Enable the Zephyr shell or debugging features by specifying additional configuration files:

.. code-block:: console
   :substitutions:

   |host-prompt| west build -p auto -b phyboard_atlas/mimxrt1176/cm7 zephyr-phytec-rt1170-examples/app -- -DEXTRA_CONF_FILE="shell.conf debug.conf"

See chapter |ref-flash-fw| to learn how to flash the firmware.