Merge branch 'docs/added-zcl-ota-upgrade' into 'main'

docs: added ZCL ota-upgrade user guide

See merge request espressif/esp-zigbee-sdk!151

docs/en/developing.rst

@@ -215,107 +215,6 @@ Initialize Zigbee stack by using :cpp:func:`esp_zb_init`, start Zigbee stack by
 
 After Zigbee stack is running, by checking different signals that stack provided, user could start BDB commissioning by using :cpp:func:`esp_zb_bdb_start_top_level_commissioning`.
 
-2.3.4 An OTA_Upgrade example
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This section demonstrates OTA upgrade process in client and server sides and how to create ota_file.bin as reference.
-
-See example:
-
-:project_file:`ota_client <examples/esp_zigbee_ota/ota_client/main/esp_ota_client.c>`
-
-:project_file:`ota_server <examples/esp_zigbee_ota/ota_server/main/esp_ota_server.c>`
-
-
-2.3.4.1 Data Model
-^^^^^^^^^^^^^^^^^^
-Client Data Model:
-
-In the client side, we use :cpp:func:`esp_zb_ep_list_add_ep` to add ESP_OTA_CLIENT_ENDPOINT to endpoint list.
-
-We create client cluster and add client attribute use :cpp:func:`esp_zb_ota_cluster_create` and we create client parameters use :cpp:func:`esp_zb_ota_client_parameter`.
-
-The :cpp:type:`esp_zb_ota_cluster_cfg_t` contains mandatory attributes for OTA client and the :cpp:type:`esp_zb_ota_upgrade_client_parameter_t` contains parameters for OTA client.
-
-The details and definitions see in the API reference chapter below.
-
-Data model looks like:
-
-.. figure:: ../_static/ota_client.png
-    :align: center
-    :alt: ESP Zigbee Data Model
-    :figclass: align-center
-
-Server Data Model:
-
-In the server side, we use :cpp:func:`esp_zb_ep_list_add_ep` to add ESP_OTA_SERVER_ENDPOINT to endpoint list.
-
-We create server cluster and add server parameters use :cpp:func:`esp_zb_ota_server_parameter`. The :cpp:type:`esp_zb_ota_upgrade_server_parameter_t` contains parameters for OTA server.
-
-The details and definitions see in the API reference chapter below.
-
-Data model looks like:
-
-.. figure:: ../_static/ota_server.png
-    :align: center
-    :alt: ESP Zigbee Data Model
-    :figclass: align-center
-
-Configure the OTA server for initialization with :c:macro:`ESP_ZB_OTA_CONFIG()`, see :cpp:type:`esp_zb_ota_cfg_t` definition in the API reference chapter below.
-
-Initialize the OTA cluster (server part) and load the ota file by using :cpp:func:`esp_zb_ota_server_init`. OTA server starts and insert ota file to upgrade mechanism by using :cpp:func:`esp_zb_ota_server_start`.
-
-
-2.3.4.2 OTA Upgrade Process
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- After server starts, server send OTA image notify (20 sec after startup - it is scheduled in application) to client. Then client send the query image request to server.
-- On receipt of the query image request, server initializes by loading the client that holds the three field values (manufacturer code, image type and new file version). If the client values matches with server values, server send response back to client. Otherwise, it shall discard the command and no further processing shall continue.
-
-Following diagram explains the OTA upgrade process in detail:
-
-.. figure:: ../_static/zigbee-ota-upgrade-process.png
-    :align: center
-    :alt: ESP Zigbee OTA Upgrade
-    :figclass: align-center
-
-- There will be ``OTA_UPGRADE_OFFSET_TIME``, calculated by the difference between upgrade time and current time and use it as upgrade delay between client finished receiving image from server and start to apply new image.
-- Server gets the upgrade bin file (ota_file.bin) and transmit it through OTA process. After OTA finish, the client receive the upgrade bin file and trigger restart. For details see the esp_ota_client :project_file:`README <examples/esp_zigbee_ota/ota_client/README.md>`.
-- It would take approximately 15-20 minutes to complete the OTA upgrade process with default upgrade bin file (ota_file.bin). Time will be varies depends on the size of the ota upgrade image file.
-
-2.3.4.3 ota_file.bin
-^^^^^^^^^^^^^^^^^^^^
-ota_file.bin is upgrade bin file for client side to upgrade, bin file can be generated by compiling any other user project. Default name is (ota_file.bin) that corresponds to the name and type configured in :project_file:`esp_ota_server.h <examples/esp_zigbee_ota/ota_server/main/esp_ota_server.h>` and place it under :project:`ota_server <examples/esp_zigbee_ota/ota_server>`.
-
-Default upgrade bin file (ota_file.bin) is only valid for target ``esp32h2``. It is just for demo purpose.
-
-The user has to provide the upgrade file for client side if they want to upgrade based on their project and target selected. Place it under :project:`ota_server <examples/esp_zigbee_ota/ota_server>`. The filename and filetype should corresponds to file configuration in :project_file:`esp_ota_server.h <examples/esp_zigbee_ota/ota_server/main/esp_ota_server.h>` by modifying it accordingly.
-
-2.3.4.4 Partition Table
-^^^^^^^^^^^^^^^^^^^^^^^
-The OTA example use a pre-defined partition table which supports two app partitions: ``factory`` and ``OTA_0``. Please refer to :project_file:`partitions <examples/esp_zigbee_ota/ota_client/partitions.csv>` for more information.
-
-On first boot, the bootloader will load the image contained on the ``factory`` partition (i.e. the example image). This triggers an OTA upgrade. A new image will save into the ``OTA_0`` partition. Next, it updates the ``ota_data`` partition to indicate which image should boot after the next reset. Upon reset, the bootloader reads the contents of the ``ota_data`` partition to determine which image is selected to upgrade.
-
-2.3.4.5 OTA Upgrade Status Callback
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-OTA upgrade status callback for client is registered in :cpp:func:`esp_zb_device_add_ota_upgrade_status_cb` to allow the user get OTA upgrade process status. See :cpp:type:`esp_zb_zcl_ota_upgrade_status_t`.
-
-.. code-block:: c
-
-   static void esp_zb_ota_upgrade_status_cb (esp_zb_zcl_ota_upgrade_status_t status)
-   {
-      ESP_LOGI(TAG, "OTA upgrade status:%d", status);
-   }
-
-2.3.4.6 Zigbee Stack Configuring and Starting
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In this example, a Zigbee end-device is configured to ota_client :c:macro:`ESP_ZB_ZED_CONFIG()` and a Zigbee coordinator is configured to ota_server :c:macro:`ESP_ZB_ZC_CONFIG()`, see :cpp:type:`esp_zb_cfg_t` definition in the API reference chapter below.
-
-Initialize Zigbee stack by using :cpp:func:`esp_zb_init`, start Zigbee stack by using :cpp:func:`esp_zb_start` and main loop of the Zigbee stack by using :cpp:func:`esp_zb_main_loop_iteration`.
-
-After Zigbee stack is running, by checking different signals that stack provided, user could start BDB commissioning by using :cpp:func:`esp_zb_bdb_start_top_level_commissioning`.
-
-.. todo::
-   2.3.5 Adding customized devices
 
 2.4 Debugging
 -------------

docs/en/user-guide/index.rst

@@ -10,3 +10,4 @@ This section provides a guide to the ESP Zigbee SDK, detailing common usage scen
    aps
    zcl_custom
    zcl_groups
+   zcl_ota_upgrade