Software Update using Hawkbit

content/en/docs/configuration/certificate-authority.md

@@ -64,16 +64,16 @@ gRPC API of the Certificate Authority service as defined [here](https://github.c
 
 ### HTTP API
 
- HTTP Certificate Authority APIs as defined by [swagger](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/plgd-dev/hub/main/certificate-authority/pb/service.swagger.json).
- The configuration `apis.http.tls` and `apis.http.authorization` are inherited from the gRPC API.
-
- | Property | Type | Description | Default |
- | ---------- | -------- | -------------- | ------- |
- | `apis.http.address` | string | `Listen specification <host>:<port> for http client connection.` | `"0.0.0.0:9101"` |
- | `apis.http.readTimeout` | string | `The maximum duration for reading the entire request, including the body by the server. A zero or negative value means there will be no timeout.` | `8s` |
- | `apis.http.readHeaderTimeout` | string | `The amount of time allowed to read request headers by the server. If readHeaderTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout.` | `4s` |
- | `apis.http.writeTimeout` | string | `The maximum duration before the server times out writing of the response. A zero or negative value means there will be no timeout.` | `16s` |
- | `apis.http.idleTimeout` | string | `The maximum amount of time the server waits for the next request when keep-alives are enabled. If idleTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout.` | `30s` |
+HTTP Certificate Authority APIs as defined by [swagger](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/plgd-dev/hub/main/certificate-authority/pb/service.swagger.json).
+The configuration `apis.http.tls` and `apis.http.authorization` are inherited from the gRPC API.
+
+| Property | Type | Description | Default |
+| ---------- | -------- | -------------- | ------- |
+| `apis.http.address` | string | `Listen specification <host>:<port> for http client connection.` | `"0.0.0.0:9101"` |
+| `apis.http.readTimeout` | string | `The maximum duration for reading the entire request, including the body by the server. A zero or negative value means there will be no timeout.` | `8s` |
+| `apis.http.readHeaderTimeout` | string | `The amount of time allowed to read request headers by the server. If readHeaderTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout.` | `4s` |
+| `apis.http.writeTimeout` | string | `The maximum duration before the server times out writing of the response. A zero or negative value means there will be no timeout.` | `16s` |
+| `apis.http.idleTimeout` | string | `The maximum amount of time the server waits for the next request when keep-alives are enabled. If idleTimeout is zero, the value of readTimeout is used. If both are zero, there is no timeout.` | `30s` |
 
 ### Signer
 

content/en/docs/configuration/cloud2cloud-connector.md

@@ -50,7 +50,7 @@ A configuration template is available in [cloud2cloud-connector/config.yaml](htt
 | `apis.http.scopes` | string array | `List of required scopes.` | `""` |
 | `apis.http.authorization.authority` | string | `Authority is the address of the token-issuing authentication server. Services will use this URI to find and retrieve the public key that can be used to validate the token’s signature.` | `""` |
 | `apis.http.authorization.audience` | string | `Identifier of the API configured in your OAuth provider.` | `""` |
-| `apis.http.authorization.ownerClaim` | string | | `Claim used to identify owner of the device.` | `"sub"` |
+| `apis.http.authorization.ownerClaim` | string | `Claim used to identify owner of the device.` | `"sub"` |
 | `apis.http.authorization.redirectURL` | string | `External redirect url to acquire authorization code.` | `""` |
 | `apis.http.authorization.http.maxIdleConns` | int | `It controls the maximum number of idle (keep-alive) connections across all hosts. Zero means no limit.` | `16` |
 | `apis.http.authorization.http.maxConnsPerHost` | int | `It optionally limits the total number of connections per host, including connections in the dialing, active, and idle states. On limit violation, dials will block. Zero means no limit.` | `32` |

content/en/docs/deployment/device-provisioning-service/advanced.md

@@ -47,43 +47,43 @@ In the process of acquiring a device access token from the OAuth server, the Dev
 1. Create an OAuth client for DPS in KeyCloak with the following configuration:
 
    - Settings:
-     - Enabled: On
-     - Client Protocol: openid-connect
-     - Access Type: confidential
-     - Service Accounts Enabled: On
-     - Authorization Enabled: On
+      - Enabled: On
+      - Client Protocol: openid-connect
+      - Access Type: confidential
+      - Service Accounts Enabled: On
+      - Authorization Enabled: On
 
    - Credentials:
-     - Client Authenticator: Client Id and Secret
-     - Secret: `<MY_DPS_CLIENT_SECRET>`
+      - Client Authenticator: Client Id and Secret
+      - Secret: `<MY_DPS_CLIENT_SECRET>`
 
    - Mapper:
-     - Create a custom `Hardcoded claim` mapper:
-       - Token Claim Name: `<OWNER_CLAIM>`
-       - Claim value: `<OWNER>`
-       - Claim JSON Type: String
-       - Add to access token: On
-       - Add to userinfo: On
+      - Create a custom `Hardcoded claim` mapper:
+         - Token Claim Name: `<OWNER_CLAIM>`
+         - Claim value: `<OWNER>`
+         - Claim JSON Type: String
+         - Add to access token: On
+         - Add to userinfo: On
 
 2. Create a WWW OAuth client with a mapper that adds the `<OWNER_CLAIM>` claim to the user JWT token. You can use the `User Property` mapper with the following configuration to map the `id` property to the `<OWNER_CLAIM>` claim:
 
    - Settings:
-     - Enabled: On
-     - Client Protocol: openid-connect
-     - Access Type: public
-     - Standard Flow Enabled: On
-     - Valid Redirect URIs: `[ https://www.example.com/*,... ]`
-     - Backchannel Logout Session Required: On
-     - OpenID Connect Compatibility Modes:
-       - Use Refresh Tokens: On
+      - Enabled: On
+      - Client Protocol: openid-connect
+      - Access Type: public
+      - Standard Flow Enabled: On
+      - Valid Redirect URIs: `[ https://www.example.com/*,... ]`
+      - Backchannel Logout Session Required: On
+      - OpenID Connect Compatibility Modes:
+         - Use Refresh Tokens: On
 
    - Mapper:
-     - Property: id
-     - Token Claim Name: `<OWNER_CLAIM>`
-     - Claim JSON Type: String
-     - Add to ID token: On
-     - Add to access token: On
-     - Add to userinfo: On
+      - Property: id
+      - Token Claim Name: `<OWNER_CLAIM>`
+      - Claim JSON Type: String
+      - Add to ID token: On
+      - Add to access token: On
+      - Add to userinfo: On
 
 In the helm chart, add the following configuration:
 

content/en/docs/features/control-plane/software-update.md

@@ -0,0 +1,119 @@
+---
+title: 'Firmware Update'
+description: 'Firmware Update using Iotivty-lite and Hawkbit server'
+date: '2022-12-19'
+lastmod: '2022-12-19'
+categories: [features]
+keywords: [firmware, update]
+menu:
+  docs:
+    parent: features
+    weight: 30
+toc: true
+---
+
+## Compile ESP32 port of iotivity-lite
+
+1. Follow <https://github.com/iotivity/iotivity-lite/tree/master/port/esp32>
+2. When running `idf.py menuconfig` go to IoTivity Example Configuration, set up your Wi-Fi and enable `PLGD_DEV_HAWKBIT`
+3. After building ESP32 port the directory iotivity-lite/port/esp32/build should contain file named example.bin
+
+## Software update using hawkbit
+
+### Prepare Hawkbit Update
+
+You set up your own Hawkbit instance (see: [Hawkbit documentation](https://www.eclipse.org/hawkbit/)) or use the the instance running at hawkbit.try.plgd.cloud.
+
+Create a software Module:
+
+1. Go to Upload section
+2. Create a new Software Module
+3. Upload example.bin to this new Software Module
+
+![Software update](../static/software-update-upload.png)
+
+Create a distribution:
+
+1. Go to Distributions section
+2. Create a new Distribution
+  ![Software update distribution](../static/software-update-distribution.png)
+3. Connect your Software Module to the Distribution by dragging the software module item to the new distribution
+  ![software-update-distribution-update-connect](../static/software-update-distribution-connect.png)
+
+Create a target filter to match your device(s):
+
+Since our example uses a single device we can use a simple filter that matches all devices, to create a more precise filter see <https://eclipse.dev/hawkbit/ui/#target-filter-management>
+
+1. Go to Target Filters section
+2. Create a target filter to match your device
+
+![Target filter](../static/software-update-target-filter.png)
+
+To execute the update we only need to create a Rollout and apply it to a device. To do that we need our device to register to hawkbit server.
+
+### Connecting your device to hawkbit server
+
+The update is controlled on the device using Software Update (`/oc/swu`) resource, which has the following properties:
+
+```C
+typedef struct oc_swupdate_t
+{
+  oc_string_t purl;    ///< package URL, source of the software package
+  oc_string_t nv;      ///< new version, new available software version
+  oc_string_t signage; ///< signage method of the software package
+  oc_swupdate_action_t swupdateaction; ///< action to execute
+  oc_swupdate_state_t swupdatestate;   ///< state of the software update
+  int swupdateresult;                  ///< result of the software update
+  oc_clock_time_t lastupdate;          ///< time of the last software update
+  oc_clock_time_t updatetime; ///< scheduled time to execute swupdateaction
+} oc_swupdate_t;
+```
+
+To obtain additional information about the firmware update, you can inspect the read-only Hawkbit resource (available at `/hawkbit`).
+
+In the following example, we will utilize a local instance of the [client-application](https://github.com/plgd-dev/client-application) running on port 18080 to examine and configure an ESP32 device.
+
+However, when using the client-application we can onboard the device to <try.plgd.cloud>, which uses certificates signed by the same certificate authority. Onboarding the device will add a CA certificate to verify the server certificates.
+
+To ensure that the connection is established with [https://hawkbit.try.plgd.cloud](https://hawkbit.try.plgd.cloud), we need to verify the server's certificate using the `esp-http-client` interface. To achieve this, it is necessary to add a Certificate Authority (CA) certificate to verify the server certificate on the device. This can be accomplished by adding the certificate through the `/oic/sec/cred` resource.
+
+Alternatively, when using the `client-application`, onboarding the device to `try.plgd.cloud` can be performed. This environment employs certificates signed by the same Certificate Authority. Onboarding the device to `try.plgd.cloud` will automatically add a CA certificate for verifying server certificates.
+
+Ensure that when examining the `/oic/sec/cred` resource, you have at least one certificate with the `credusage` of `oic.sec.cred.trustca` or `oic.sec.cred.mfgtrustca`. If there are multiple CA certificates, they will be concatenated together in PEM string format.
+
+![Certificate to verify server](../static/software-update-server-certificate.png)
+
+Configure the package URL (`purl`) property of the `/oc/swu` resource to contain the address of your running Hawkbit server. The value can be specified in one of two formats:
+
+1. SERVER_URL/TENANT_ID/controller/v1/CONTROLLER_ID (Example: <https://hawkbit.try.plgd.cloud:443/default/controller/v1/esp32>)
+2. SERVER_URL/TENANT_ID (Example: <https://hawkbit.try.plgd.cloud:443/default>)
+<!-- TODO: 3. SERVER_URL (Example: <https://hawkbit.try.plgd.cloud:443>) default to `devowneruuid`, but hawkbit doesn't seem to accept the format -->
+
+ If the `CONTROLLER_ID` is not set, its value defaults to the device permanent ID (`piid` property value from device info).
+
+Update the `idle` action and set `"now"` as the update time to create a valid `/oc/swu` update request:
+
+```json
+{
+  "swupdateaction":"idle",
+  "updatetime": "now",
+  "purl": "https://hawkbit.try.plgd.cloud:443/default/controller/v1/esp32"
+}
+```
+
+![Register device](../static/software-update-register-device-to-hawkbit.png)
+
+Once the package URL value is set then the device will start polling the Hawkbit server for actions to execute. (The polling interval 60 seconds by default, but once the device successfully connects to Hawkbit server, it will receive the polling interval from Hawkbit.)
+The device should now appear in the hawkbit server.
+
+![Registered device](../static/software-update-registered-device.png)
+
+### Execute Hawkbit Update
+
+To execute a software update, we'll create an update rollout:
+
+1. Go to Rollout section
+2. Create a new Rollout
+  ![Software update rollout](../static/software-update-rollout.png)
+
+TODO: run rollout