Skip to content

Commit 32ebaca

Browse files
Adam-MaciugaAdam-Maciuga
committed
docs: added migration guide from v0.1
Listed all important changes from the v0.1 add-on version Signed-off-by: Adam Maciuga <adam.maciuga@nordicsemi.no>
1 parent f106db6 commit 32ebaca

5 files changed

Lines changed: 76 additions & 3 deletions

File tree

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ For architecture and integration details, see :ref:`knx_iot_addon`.
1919
knx-iot/overview/index
2020
knx-iot/addon
2121
setup
22+
migration
2223
knx-iot/samples
2324
config
2425
software_maturity

‎docs/migration.rst‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
.. _knx_iot_migration:
2+
3+
|addon| migration guide
4+
#######################
5+
6+
.. contents::
7+
:local:
8+
:depth: 3
9+
10+
This page describes the changes required to migrate your application between |addon| versions.
11+
12+
Updating from |addon| v0.1.0
13+
****************************
14+
15+
Stack API changes
16+
=================
17+
18+
Applications that call the `KNX IoT Point API Stack`_ directly must review the following changes:
19+
20+
* ``oc_core_set_device()`` was replaced by individual identity and version setters.
21+
Version setters now take a pointer to an ``oc_knx_version_info_t`` structure.
22+
* ``oc_core_set_device_res()`` must be called explicitly after the basic device identity is set and before the remaining device setup.
23+
It initializes the KNX resources and connectivity.
24+
* ``app_get_precalculated_spake_data()`` is required for the v1.1.0 SPAKE2+ verifier.
25+
A generated record must match the password, salt, and iteration count used by the application.
26+
* ``oc_device_info_t.serialnumber`` is a ``const char *`` rather than an ``oc_string_t``.
27+
Remove ``oc_string()`` wrappers around it.
28+
* Include port-layer headers such as ``oc_clock.h``, ``oc_connectivity.h``, ``oc_storage.h``, and ``dns-sd.h`` with the ``port/`` prefix.
29+
* ``knx_publish_service()`` was renamed to ``knx_dns_sd_update_service()``.
30+
31+
Kconfig changes
32+
===============
33+
34+
Remove legacy stack settings that are no longer exposed:
35+
36+
* ``KNXIOT_SPAKE2P_PSA``
37+
* ``KNXIOT_SPAKE2P_MBEDTLS``
38+
* ``KNXIOT_LIB_DEMO_APPS``
39+
* ``LIB_KNX_LOG_LEVEL``
40+
* ``OC_PRINT_ENABLED``
41+
* ``OC_USE_KNX_PORT_LAYER_ENABLED``
42+
* ``OC_REPLAY_PROTECTION_ENABLED``
43+
* ``KNX_LOG_TO_ZEPHYR``
44+
45+
Also remove ``MBEDTLS_DECLARE_PRIVATE_IDENTIFIERS`` from application configuration files.
46+
The SPAKE2+ implementation now handles the required Mbed TLS declarations internally.
47+
48+
For logging, use ``KNXIOT_DEBUG`` to compile the stack's debug code and ``KNXIOT_LOG_LEVEL`` to select the stack log level.
49+
``KNX_THREAD_STACK_SIZE`` remains available and now controls the add-on's stack event-loop thread.
50+
51+
Add-on API changes
52+
==================
53+
54+
Datapoint method flags
55+
----------------------
56+
57+
The ``methods`` member of ``knx_datapoint_t`` now uses add-on flags:
58+
59+
.. code-block:: c
60+
61+
.methods = KNX_DP_GET | KNX_DP_PUT,
62+
63+
Replace old uses of ``OC_GET`` and ``OC_PUT`` in datapoint definitions with ``KNX_DP_GET`` and ``KNX_DP_PUT``.
64+
65+
Programming mode and persisted state
66+
------------------------------------
67+
68+
Programming mode is runtime-only in the v1.1.0 integration and does not survive a restart.
69+
Applications must not rely on the stack restoring it from storage.

‎docs/release-notes.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ Release notes
66
For a detailed list on new features for a specific |addon| release, refer to the respective release notes documents.
77

88
The |addon| v\ |addon_version| is compatible with |NCS| v\ |ncs_version| and uses `KNX IoT Point API Stack`_ v\ |knx-iot_version|.
9+
For migration details between Point API stack revisions and addon versions, see the
10+
:ref:`KNX IoT migration guide <knx_iot_migration>`.
911

1012
The following table contains a full list of |addon| releases and related |NCS| and `KNX IoT Point API Stack`_ versions.
1113

‎docs/release_notes/release_notes_changelog.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,5 @@ The most relevant changes that are present on the main branch of the |addon|, as
1111
Changelog
1212
*********
1313

14-
|no_changes_yet_note|
14+
Updated KNX IoT Point API Stack to version 1.1.0.
15+
For information about how to adapt your applications, see the :ref:`KNX IoT migration guide <knx_iot_migration>`.

‎docs/shortcuts.txt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. ### Versions
22

33
.. |ncs_version| replace:: 3.4.0
4-
.. |knx-iot_version| replace:: 1.0.0
5-
.. |addon_version| replace:: 0.1.0
4+
.. |knx-iot_version| replace:: 1.1.0
5+
.. |addon_version| replace:: 0.1.99
66

77
.. |NCS| replace:: nRF Connect SDK
88
.. |addon| replace:: KNX IoT add-on

0 commit comments

Comments
 (0)