| orphan: |
|---|
Migration guide for |NCS| v2.7.0
This document describes the changes required or recommended when migrating your application from |NCS| v2.6.0 to |NCS| v2.7.0.
The following changes are mandatory to make your application work in the same way as in previous releases.
This section describes the changes related to samples and applications.
.. toggle::
For all applications using the :file:`dfu_application.zip` file generated by the |NCS| build system:
* Make sure that your DFU host tools support the :file:`dfu_application.zip` file with the new format version (``1``).
If the tools do not support the new format version and you cannot update them, you can manually align the content of the zip archive generated with format version ``1`` to version ``0``:
* Build your application in the same configuration with the |NCS| v2.6 release to obtain a reference file :file:`dfu_application.zip` with format version ``0``.
* Manually align the content of the :file:`dfu_application.zip` file generated with format version ``1``:
* Align the properties described in the :file:`manifest.json` file.
Make sure to update all of the fields that are used by the selected DFU host tool.
* Rename the binary files that are included in the zip archive to match the file names used by the updated manifest.
The binary file content is interoperable across |NCS| releases.
.. toggle::
All samples and applications built for multi-core SoCs were migrated to use :ref:`ipc_radio` as the default image for the network core (on nRF5340) or the radio core (on nRF54H20).
The samples previously built for those cores are no longer used in the default builds: :zephyr:code-sample:`bluetooth_hci_ipc`, :zephyr:code-sample:`nrf_ieee802154_rpmsg`, ``nRF5340: Multiprotocol RPMsg``, and :ref:`ble_rpc_host`.
.. toggle::
* The :ref:`nrf53_audio_app` has removed all references to bt_ll_acs_nrf53 and will now only support the default controller :ref:`ug_ble_controller_softdevice` (:ref:`softdevice_controller_iso`).
:ref:`ug_ble_controller_softdevice` is included and built automatically.
Make sure to remove references to LE Audio controller for nRF5340 from your application and transition to the new controller.
.. toggle::
* :ref:`wifi_shell_sample` sample:
* The parameters of the ``connect`` and ``ap enable`` commands have been updated.
Check the updated parameters using the ``-h`` help option of the command.
.. toggle::
The AT command parsing has been updated to utilize the :ref:`at_cmd_custom_readme` library.
If you have introduced custom AT commands to the SLM, you need to update the command parsing to use the new library.
See the :ref:`slm_extending` page for more information.
.. toggle::
* :ref:`radio_test` sample:
* The CLI command ``fem tx_power_control <tx_power_control>`` replaces ``fem tx_gain <tx_gain>`` .
This change applies to the sample built with the :ref:`CONFIG_RADIO_TEST_POWER_CONTROL_AUTOMATIC <CONFIG_RADIO_TEST_POWER_CONTROL_AUTOMATIC>` set to ``n``.
.. toggle::
With the inheritance of Zephyr's :ref:`zephyr:sysbuild` in the |NCS| :ref:`configuration_system_overview_sysbuild`, some changes are provided to the Matter samples and applications:
* :kconfig:option:`CONFIG_CHIP_FACTORY_DATA_BUILD` Kconfig option is deprecated and you need to use the ``SB_CONFIG_MATTER_FACTORY_DATA_GENERATE`` Kconfig option instead to enable or disable creating the factory data set during building a Matter sample.
To enable factory data support on your device, you still need to set the :kconfig:option:`CONFIG_CHIP_FACTORY_DATA` to ``y``.
* Factory data output files are now located in the ``<application_name>/zephyr/`` directory within the build directory.
* :kconfig:option:`CONFIG_CHIP_FACTORY_DATA_MERGE_WITH_FIRMWARE` Kconfig option is deprecated in sysbuild and you need to use the ``SB_CONFIG_MATTER_FACTORY_DATA_MERGE_WITH_FIRMWARE`` Kconfig option instead to enable or disable merging the factory data HEX file with the final firmware HEX file.
* ``SB_CONFIG_MATTER_OTA`` Kconfig option has been added to enable or disable generating Matter OTA package during the building process.
* :kconfig:option:`CONFIG_CHIP_OTA_IMAGE_FILE_NAME` Kconfig option is deprecated and you need to use the ``SB_CONFIG_MATTER_OTA_IMAGE_FILE_NAME`` Kconfig option instead to define Matter OTA output filename.
.. note::
If you want to build a sample without using sysbuild, you need to use the old Kconfig options.
This section describes the changes related to libraries.
.. toggle::
For applications using the :ref:`lib_mqtt_helper` library:
* The ``CONFIG_MQTT_HELPER_CERTIFICATES_FILE`` is now replaced by :kconfig:option:`CONFIG_MQTT_HELPER_CERTIFICATES_FOLDER`.
The new option is a folder path where the certificates are stored.
The folder path must be relative to the root of the project.
If you are using the :ref:`lib_mqtt_helper` library, you must update the Kconfig option to use the new option.
* When using the :kconfig:option:`CONFIG_MQTT_HELPER_PROVISION_CERTIFICATES` Kconfig option, the certificate files must be in standard PEM format.
This means that the PEM files need not be converted to string format anymore.
.. toggle::
For applications using :ref:`fem_al_lib`:
* The function :c:func:`fem_tx_power_control_set` replaces the function :c:func:`fem_tx_gain_set`.
* The function :c:func:`fem_default_tx_output_power_get` replaces the function :c:func:`fem_default_tx_gain_get`.
.. toggle::
For applications using :ref:`nrf_modem_lib_readme`:
* The option :kconfig:option:`CONFIG_NRF_MODEM_LIB_TRACE_BACKEND_UART_ZEPHYR` is now deprecated.
To enable the UART trace backend, use the ``nrf91-modem-trace-uart`` snippet instead, or add a similar configuration in application overlays.
The snippet is located in :file:`snippets/nrf91-modem-trace-uart/`.
The following changes are recommended for your application to work optimally after the migration.
.. toggle::
For applications using build types:
* The :makevar:`CONF_FILE` used for :ref:`app_build_additions_build_types` is now deprecated and is being replaced with the :makevar:`FILE_SUFFIX` variable, inherited from Zephyr.
For more information, see :ref:`app_build_file_suffixes`, :ref:`cmake_options`, and the :ref:`related Zephyr documentation <zephyr:application-file-suffixes>`.
If your application uses build types, it is recommended to update the :file:`sample.yaml` to use the new variable instead of :makevar:`CONF_FILE`.
For applications using child images:
* With the inheritance of Zephyr's :ref:`sysbuild in the |NCS| <configuration_system_overview_sysbuild>`, parent-child image support is deprecated.
If your application uses parent and child images, it is recommended to migrate your application to sysbuild before the multi-image builds are removed in one of the upcoming |NCS| releases.
See `Migrating from multi-image builds to sysbuild`_.
See the :ref:`documentation in Zephyr <zephyr:sysbuild>` for more information about sysbuild.
.. toggle::
* For the Matter samples and applications:
* All Partition Manager configuration files (:file:`pm_static` files) have been removed from the :file:`configuration` directory.
Instead, a :file:`pm_static_<BOARD>` file has been created for each target board and placed in the samples' directories.
Setting the ``PM_STATIC_YML_FILE`` argument in the :file:`CMakeLists.txt` file has been removed, as it is no longer needed.
* Configuration files :file:`Kconfig.mcuboot.defaults`, :file:`Kconfig.hci_ipc.defaults`, and :file:`Kconfig.multiprotocol_rpmsg.defaults` that stored a default configuration for the child images have been removed.
This was done because of the :ref:`configuration_system_overview_sysbuild` integration and the child images deprecation.
The Matter samples and applications have been migrated to use sysbuild, though you can still use the child images.
To migrate an application from the previous to the new version and keep using child images, complete the following steps:
1. Copy the content of the image configuration file :file:`prj.conf` located in the :file:`sysbuild/<image_name>` directory (for example, :file:`sysbuild/mcuboot`) to the :file:`prj.conf` file located in the :file:`child_image/<image_name>` directory.
#. Copy the content of the board configuration file located in the :file:`sysbuild/<image_name>/boards` directory (for example, :file:`sysbuild/mcuboot/boards/nrf52840dk_nrf52840.conf`) to the board file located in the :file:`child_image/<image_name>/boards` directory.
* All Partition Manager configuration files (:file:`pm_static` files) with the suffix ``release`` have been removed from all samples.
Those files are now redundant, since the new build system allows using the file without the additional suffix if you use :makevar:`FILE_SUFFIX` and it is available in the project's directory.
For example, if you add ``-DFILE_SUFFIX=release`` to the CMake arguments while building an |NCS| Matter sample on the ``nrf52840dk/nrf52840`` target, the file :file:`pm_static_nrf52840dk_nrf52840.yaml` will be used as a fallback.
This means that the file :file:`pm_static_nrf52840dk_nrf52840_release.yaml` with the exact same contents is not needed anymore.
The :makevar:`CONF_FILE` argument is deprecated, but if you want to keep using it within your project, you need to create the :file:`pm_static_nrf52840dk_nrf52840_release.yaml` file and copy the content of the :file:`pm_static_nrf52840dk_nrf52840.yaml` file to it.
This section describes the changes related to libraries.
.. toggle::
* Many event defines have received new values.
If you are using the values directly in your application, you need to check the events listed in :file:`lwm2m_carrier.h`.
The most likely place these changes are needed is :ref:`serial_lte_modem` application, where :ref:`SLM_AT_CARRIER` are relying on the value of the defines instead of the names.