Merge pull request #2581 from didier-wenzek/docs/add-legacy-section

Add a legacy documentation section

.gitignore

@@ -37,10 +37,6 @@ tests/PySys/**/*.err
 tests/PySys/**/Output/
 **/*venv*
 
-# Files generated by mdbook-pagetoc and not customized
-docs/theme/index.hbs
-docs/theme/pagetoc.js
-
 # Symlink used when building docs in tedge-docs repo
 docs/src/src
 

docs/src/references/c8y-firmware-management.md → docs/src/legacy/c8y-firmware-management.md

@@ -1,14 +1,19 @@
 ---
 title: Firmware Management
-tags: [Reference, Firmware]
+tags: [Firmware, Legacy]
 sidebar_position: 9
 ---
 
-# Device Firmware Management using Cumulocity
+# Child-Device Firmware Management using Cumulocity (legacy API)
 
-Thin-edge provides an operation plugin to
-[manage device firmware using Cumulocity](https://cumulocity.com/guides/users-guide/device-management/#firmware-repo).
-Firmware management is currently supported only for child devices and not for the main tedge device.
+Thin-edge provides a legacy operation plugin to
+[manage device firmware using Cumulocity](https://cumulocity.com/guides/users-guide/device-management/#firmware-repo)
+on child devices.
+
+:::caution
+- This operation plugin only supports firmware update on child devices and not on the main tedge device.
+- This is a legacy API. For new developments, the recommended approach is to implement a [custom workflow](../references/agent/operation-workflow.md).
+:::
 
 - The firmware update operations are defined and triggered from Cumulocity
 - Thin-edge acts as the proxy between Cumulocity and the child device
@@ -35,6 +40,13 @@ Operation files for child devices must be created as part of their bootstrap pro
 
 ## Configuration
 
+Support for this plugin is disabled by default and must be explicitly enabled on the c8y mapper.
+
+```sh
+sudo tedge config set c8y.enable.firmware_update true
+sudo systemctl restart tedge-mapper-c8y.service
+```
+
 The plugin supports a single tedge configuration named `firmware.child.update.timeout`,
 that defines the amount of time the plugin wait for a child device to finish a firmware update once the request is delivered.
 The default timeout value (in seconds) is `3600` and can be updated with:

docs/src/operate/c8y/child_device_config_management_agent.md → docs/src/legacy/child_device_config_management_agent.md

@@ -1,6 +1,6 @@
 ---
 title: Child Device Configuration Management
-tags: [Extend, Cumulocity, Child Device, Configuration]
+tags: [Cumulocity, Configuration, Legacy]
 sidebar_position: 6
 ---
 
@@ -54,7 +54,7 @@ This bootstrapping is a 3 step process:
 1. Notify thin-edge about the upload via MQTT
 
 The child device agent needs to capture the list of configuration files that needs be managed from the cloud
-in a `c8y-configuration-plugin.toml` file in the same format as specified in the [configuration management documentation](config_management_plugin.md) as follows:
+in a `c8y-configuration-plugin.toml` file in the same format as specified in the [configuration management documentation](../operate/c8y/config_management_plugin.md) as follows:
 
 ```toml title="file: c8y-configuration-plugin.toml"
 files = [
@@ -66,14 +66,12 @@ files = [
 * `path` is the full path to the configuration file on the child device file system.
 * `type` is a unique alias for each file entry which will be used to represent that file in Cumulocity UI
 
-The child device agent needs to upload this file to thin-edge [File Transfer Service][fts] with an HTTP PUT request
+The child device agent needs to upload this file to thin-edge [File Transfer Service](../references/tedge-file-transfer-service.md) with an HTTP PUT request
 to the URL: `http://{fts-address}:8000/tedge/file-transfer/{child-id}/c8y-configuration-plugin`
 
-* {fts-address}` is the address of the thin-edge.io device on which the [File Transfer Service][fts] is running
+* `{fts-address}` is the address of the thin-edge.io device on which the [File Transfer Service](../references/tedge-file-transfer-service.md) is running
 * `{child-id}` is the child-device-id
 
-[fts]: ../../references/tedge-file-transfer-service.md
-
 Once the upload is complete, the agent should notify thin-edge about the upload by sending the following MQTT message:
 
 ```sh te2mqtt formats=v1
@@ -222,10 +220,3 @@ a "failed" status update must be sent instead, to the same topic as follows:
   "path": "/child/local/fs/path" 
 }
 ```
-
-## References
-
-* Configuration Management [documentation](config_management_plugin.md)
-* Reference implementation of a [child device agent](https://github.com/thin-edge/thin-edge.io_examples/tree/main/child-device-agent) written in Python to demonstrate the contract described in this document.
-
-

docs/src/operate/c8y/child_device_firmware_management.md → docs/src/legacy/child_device_firmware_management.md

@@ -1,17 +1,21 @@
 ---
 title: Child Device Firmware Management
-tags: [Operate, Cumulocity, Child Device, Firmware]
+tags: [Cumulocity, Firmware, Legacy]
 sidebar_position: 7
 ---
 
 # Enable firmware management on child devices with Cumulocity
 
+:::caution
+- This is a legacy API. For new developments, the recommended approach is to implement a [custom workflow](../references/agent/operation-workflow.md).
+:::
+
 Firmware management can be enabled for child devices using the `c8y-firmware-plugin`.
 This thin-edge plugin coordinates the firmware update operation handling with Cumulocity,
 by establishing secure communication with the cloud,
 managing firmware file downloads, which are typically large files, even over flaky networks,
 caching the downloaded files for re-use across multiple child devices etc.
-For more details on the inner workings of this plugin, refer to the [reference guide](../../references/c8y-firmware-management.md).
+For more details on the inner workings of this plugin, refer to the [reference guide](c8y-firmware-management.md).
 
 In order to install the firmware itself on the child device,
 an additional piece of software must be developed by the child device owner as well,
@@ -24,7 +28,7 @@ The responsibilities of the child device connector are:
 * Download and apply the updated firmware from thin-edge
 * Send status updates on the progress of the firmware update operation to thin-edge
 
-Handling the above mentioned responsibilities involves
+Handling the above-mentioned responsibilities involves
 multiple interactions with thin-edge over its MQTT and HTTP APIs.
 In cases where the child device connector is installed alongside thin-edge on the same device,
 these APIs can be accessed via a local IP or even `127.0.0.1`.
@@ -41,7 +45,7 @@ provides firmware management support for that device.
 ## Declare firmware management support of child device
 
 At first, the child device needs to declare that it supports firmware management from Cumulocity
-using the [supported operations API](supported_operations.md) of thin-edge
+using the [supported operations API](../operate/c8y/supported_operations.md) of thin-edge
 by simply creating an empty operations file on the thin-edge device as follows:
 
 ```sh

docs/src/legacy/index.md

@@ -0,0 +1,19 @@
+---
+title: Legacy
+tags: [Legacy]
+sidebar_position: 9
+---
+
+import DocCardList from '@theme/DocCardList';
+
+Thin-edge 1.0 introduced a set of breaking changes that might affect plugins and extensions implemented on previous versions.
+
+In most cases, a compatibility layer has been introduced to smooth the transition.
+For instance, any measurement published by an extension on the former topic `tedge/measurement`
+is republished by the **tedge-agent** to the topic `te/device/main///m/`
+which is dedicated to untyped measurements for the main device.
+
+However, the compatibility layers don't address all the breaking changes and, in any case, they will be deprecated medium-term.
+Here are the developer guides to port a legacy extension to the new thin-edge API. 
+
+<DocCardList />