Update ONU sw update documentation
Change-Id: Id922d6072f64effdc9355ec55b00515e97db3ee0
diff --git a/ONU_Upgrade_Notes.md b/ONU_Upgrade_Notes.md
index 1f005c5..63c1f9b 100644
--- a/ONU_Upgrade_Notes.md
+++ b/ONU_Upgrade_Notes.md
@@ -1,9 +1,13 @@
# Notes on ONU upgrade procedures using the openonu-go adapter
Openonu-go adapter supports the download and activation of new ONU software from some external http(s) server to the ONUs over the OMCI channel.
There are three relevant voltctl (image) commands for the ONU upgrade procedure:
-- voltctl device image [list](#image-state-display)
-- voltctl device image [download](#image-download-from-http(s)-server-to-the-OnuAdapter)
-- voltctl device image [activate](#image-download-from-onuadapter-to-onu-and-activation)
+- voltctl device onuimage [list](#images-list-on-the-Onu)
+- voltctl device onuimage [status](#image-status-display)
+- voltctl device onuimage [download](#image-download-from-http(s)-server-to-the-Onu)
+- voltctl device onuimage [activate](#image-activation-on-the-onu)
+- voltctl device onuimage [commit](#image-commit-on-the-onu)
+- voltctl device onuimage [abort](#image-activity-abort)
+
The complete ONU upgrade process consists of:
- downloading the requested ONU Image from some http(s) server that must be reachable from the VOLTHA stack
@@ -21,76 +25,170 @@
voltctl device list -f Type~brcm_openomci_onu
```
+## Images list on the Onu
-## Image state display
+The syntax of the complete voltctl command is:
+```bash
+voltctl device onuimage list <onu-device-id>
+```
+This command displays OMIC information on the active and standby images on the device.
+
+Here is some example output for this command:
+```bash
+VERSION ISCOMMITED ISACTIVE ISVALID PRODUCTCODE HASH
+090140.1.0.304 true true true 00000000000000000000000000000000
+090140.9.9.308 false false false 00000000000000000000000000000000
+```
+The command output lists:
+- the `VERSION` the version of each image
+- the `ISCOMMITED` is the image commited on the ONU
+- the `ISACTIVE` is the image active on the ONU
+- the `ISVALID` is the image valide for that ONU
+- the `PRODUCTCODE` infomration about the image that can be provided by the ONU via OMCI. (optional)
+- the `HASH` infomration about the image that can be provided by the ONU via OMCI. (optional)
+
+All the attributes specified in the output of this command are retrieved from the ONU via OMCI as per G.988 specification.
+
+## Image status display
The syntax of the complete voltctl command is:
```
-voltctl device image list <onu-device-id>
+voltctl device onuimage status <image-version> <onu-device-ids>
```
+with:
+- `<image-version>`: version of the image, e.g `090140.1.0.304`.
+- `<onu-device-ids>`: set of devices for which to display the status of the given image.
Here is some example output for this command:
-```
-NAME URL CRC DOWNLOADSTATE IMAGEVERSION LOCALDIR IMAGESTATE FILESIZE
-software-image.img http://bbsim0:50074/images 0 DOWNLOAD_SUCCEEDED /tmp IMAGE_UNKNOWN 0
-timg1.img http://bbsim0:50074/images 0 DOWNLOAD_FAILED /tmp IMAGE_UNKNOWN 0
+```bash
+DEVICEID IMAGESTATE.VERSION IMAGESTATE.DOWNLOADSTATE IMAGESTATE.REASON IMAGESTATE.IMAGESTATE
+420792c1-84fb-465a-a775-283e54247be9 090140.1.0.304 DOWNLOAD_SUCCEEDED NO_ERROR IMAGE_INACTIVE
```
The command output lists:
- the `DOWNLOADSTATE` with values defined in the protobuf implementation for the [image download](https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L106)
- the `IMAGESTATE` with values defined in the protobuf implementation for the [image activation](https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L125)
+- the `REASON` with values defined in the protobuf implementation for the [image failure reasons](https://github.com/opencord/voltha-protos/blob/v4.0.11/protos/voltha_protos/device.proto#L116)
-The `IMAGEVERSION` is not displayed here, it is anyway ignored for the download and activation process. The `FILESIZE` is not updated in this release.
+This command exposes the status of operations in relation to an image on one or multiple devices.
-In above example output the given states indicate that for image software-image.img the download to the openonu-go adapter was correctly started or even finished but no download to the ONU was yet started, while for image timg1.img some problem for the download to the openonu-go adapter was detected.
+In above example output the given states indicate that for image software-image.img the download first to the openonu-go adapter
+and then to the ONU was correctly done. The image is in the inactive ONU partition (not yet activated).
-## Image download from http(s) server to the OnuAdapter
+## Image download from http(s) server to the Onu
The syntax of the complete voltctl command is:
```
-voltctl device image download <onu-device-id> <image-name> <http-url> <version-string> <crc> <local-path>
+voltctl device onuimage download <image-version> <image-url> <image-vendor> <activate-on-success> <commit-on-success> <crc> <onu-device-ids>
```
with:
-- `<image-name>`: name of the image as available on the http(s) server, possible format `<identifier>.<extension>`, example for above `list` command was "software-image.img"
-- `<http-url>`: http(s) URL of the server path, including the http request indication, example for above `list` command was ```"http://bbsim0:50074/images"```
-- `<version-string>`: version indication, ignored in this release, but must be present, example: "v1.0.0 0"
-- `<crc>`: not used in this release, should be set to 0
-- `<local-path>`: path of the openonu-go adapter to where the downloaded file is to be stored, including linux path slash notation, recommendation is to use "\tmp"
+- `<image-version>`: version of the image, e.g `090140.1.0.304`.
+- `<image-url>`: A full path of the location of the image in a given location, e.g. `http://10.103.21.52:8080/downloads/090140.1.0.304.img `.
+- `<image-vendor>`: the ONU vendor for which the image can be used, e.g. `SCOM`.
+- `<activate-on-success>`: activate the image automatically if the download is successful.
+- `<commit-on-success>`: commits the image automatically on succesful reboot of the ONU after activation.
+- `<crc>`: the crc of the image as described in OMCI specification. Can be set to `0`, in which case the onu adapter will compute it.
+- `<onu-device-ids>`: set of devices on which to activate the given image.
-The processing of the command can basically be verified with above given image [list](#image-state-display) command, where the `DOWNLOADSTATE` defines the progress of this activity. Note that in this release the state DOWNLOAD_SUCCEEDED does not really indicate that the file was really downloaded, but the download could be correctly started. Depending on the file size and the IP connectivity the transfer may take some seconds up to minutes.
-In this release it is still recommended to check the real success of the download by waiting for or finding some appropriate multiple-element info log level output of the openonu-go adapter like this:
+A sample output of this command is:
+
+```bash
+DEVICEID IMAGESTATE.VERSION IMAGESTATE.DOWNLOADSTATE IMAGESTATE.REASON IMAGESTATE.IMAGESTATE
+420792c1-84fb-465a-a775-283e54247be9 090140.1.0.304 DOWNLOAD_STARTED NO_ERROR IMAGE_DOWNLOADING
```
-"caller":"onuadaptercore/adapter_download_manager.go:210","msg":"written file size is","length":31654,"file":"/tmp/software-image.img"
-```
+
+This command downloads the given image on one or multiple devices. First it fetches the image from and http(s) server
+if the image is not already present in the openonu adapter. It then transfers the image to the device via OMCI,
+placing it in the `standby` partition.
+
+The processing of the command can basically be verified with above given image [status](#image-status-display) command,
+where the `DOWNLOADSTATE` defines the progress of this activity.
+Depending on the file size and the IP connectivity the transfer may take some seconds up to minutes.
+Image status directly on the ONU device can always be performed by the [list](#images-list-on-the-onu) command.
The download fails e.g. in case the image cannot be found on the server, in which case the `DOWNLOADSTATE` goes to "DOWNLOAD_FAILED"
+If the `ActivateOnSuccess` flag is set the adapter will automatically activate the image upon successful download to the ONU.
+If the `CommitOnSuccess` flag is set the adapter will automatically commit the image upon successful reboot of the ONU.
-## Image download from OnuAdapter to ONU and activation
+
+## Image activation on the onu
The syntax of the complete voltctl command is:
```
-voltctl device image activate <onu-device-id> <image-name> <version-string> <crc> <local-path>
+voltctl device onuimage activate <image-version> <commit-on-success> <onu-device-ids>
```
with:
-- `<image-name>`: name of the image, the same identifier as used in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter) command
-- `<version-string>`: version indication, the same identifier as used in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter) command, not used in this release
-- `<crc>`: not used in this release, should be set to 0 like in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter) command
-- `<local-path>`: path of the openonu-go adapter from where the file is downloaded for sending it over the OMCI channel to the ONU, the same identifier as used in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter) command
+- `<image-version>`: version of the image, the same identifier as used in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter) and [activate](image-activation-on-the-onu) command
+- `<commit-on-success>`: commits the image automatically if activation is successful.
+- `<onu-device-ids>`: set of devices on which to activate the given image.
-The processing of the command can basically be verified with above given image [list](#image-state-display) command, where the `IMAGESTATE` defines the progress of this activity. Note that in this release the state IMAGE_ACTIVE does not really indicate that the image was really activated on the ONU, but the transfer over the OMCI channel was correctly started. Depending on the file size and further ONU dependent file handling parameters the transfer may take some minutes.
-The correct complete file transfer and start of the activation of the image can be verified by waiting for or finding some appropriate multiple-element info log level output of the openonu-go adapter like this:
+A sample output of this command is:
+
+```bash
+DEVICEID IMAGESTATE.VERSION IMAGESTATE.DOWNLOADSTATE IMAGESTATE.REASON IMAGESTATE.IMAGESTATE
+420792c1-84fb-465a-a775-283e54247be9 090140.1.0.304 DOWNLOAD_SUCCEEDED NO_ERROR IMAGE_ACTIVATING
+ ```
+
+This command activates the given image on one or multiple devices, if the requested image is in the inactive ONU partition.
+This implies the switching of the active partition and reboot of the ONU. Effectively moves the image from the `standby` to
+the `active` partition. The previously `standby` image will be active after the ONU re-start.
+If the image for which the `activate` request arrives is already in the `active` partition no action will be taken.
+
+The processing of the command can be verified by checking the `IMAGESTATE` in the initial output of the command and then
+in result of the above given image [status](#image-status-display) command.
+Image status directly on the ONU device can always be performed by the [list](#images-list-on-the-onu) command.
+
+If the `CommitOnSuccess` flag is set the adapter will automatically commit the image upon successful reboot of the ONU.
+
+
+## Image commit on the Onu
+
+The syntax of the complete voltctl command is:
```
-"caller":"onuadaptercore/omci_onu_upgrade.go:474","msg":"OnuUpgradeFsm activate SW"
+voltctl device onuimage commit <image-version> <onu-device-ids>
```
-This shall lead to an autonomous reset of the ONU, which should indicate the previously downloaded image as active after the ONU re-start. If the initial OMCI processing is correctly handled by the ONU, the image is automatically committed by the openonu-go adapter.
-In this release it is still recommended to check the real success of the image activation and commitment after ONU reboot by waiting for or finding some appropriate multiple-element info log level output of the openonu-go adapter like this:
+with:
+- `<image-version>`: version of the image, the same identifier as used in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter) and [activate](image-activation-on-the-onu) command
+- `<onu-device-ids>`: set of devices on which to commit the given image.
+
+A sample output of this command is:
+
+```bash
+DEVICEID IMAGESTATE.VERSION IMAGESTATE.DOWNLOADSTATE IMAGESTATE.REASON IMAGESTATE.IMAGESTATE
+420792c1-84fb-465a-a775-283e54247be9 090140.1.0.304 DOWNLOAD_UNKNOWN NO_ERROR IMAGE_COMMITTING
```
-"caller":"onuadaptercore/omci_onu_upgrade.go:920","msg":"requested SW image committed, releasing OnuUpgrade"
+This command commits the given image on one or multiple devices. The commit command confirms the image on the `active` partition
+to be the default one upon reboot.
+
+The processing of the command can be verified by checking the `IMAGESTATE` in the initial output of the command and then
+in result of the above given image [status](#image-status-display) command.
+
+The result of this command in the [list](#images-list-on-the-onu) should be that the desired image is also printed on the
+active partition and its `IsCommitted` and `IsActive` flags are set to true.
+
+## Image activity abort
+
+The syntax of the complete voltctl command is:
+```
+voltctl device onuimage abort <image-version> <onu-device-ids>
+```
+with:
+- `<image-version>`: version of the image, the same identifier as used in the [download](#image-download-from-http(s)-server-to-the-OnuAdapter)
+ [activate](image-activation-on-the-onu) and [commit](image-commit-on-the-onu) commands
+- `<onu-device-ids>`: set of devices on which to abort image processing.
+
+A sample output of this command is:
+
+```bash
+DEVICEID IMAGESTATE.VERSION IMAGESTATE.DOWNLOADSTATE IMAGESTATE.REASON IMAGESTATE.IMAGESTATE
+420792c1-84fb-465a-a775-283e54247be9 090140.1.0.304 DOWNLOAD_UNKNOWN NO_ERROR IMAGE_ACTIVATION_ABORTING
```
-## Future work
-Some improvements are already planned for the general handling of software upgrade.
-This must of course include a simple possibility to verify if the download or activation was really done.
-Moreover some extra commands for separate OMCI download and activation are considered to enable time independent processing for these activities.
-The commands for removing the images are still missing and unused command parameters may be removed.
+This command aborts any upgrade related activity that the adapter is performing in relation to the given image for the one or multiple devices.
+This command does not imply any automated activity by the system to bring the ONU upgrade status to a previous or more consistent state.
+If required some further commands can be used to try to bring the ONU into the desired upgrade state.
+
+The processing of the command can be verified with above given image [status](#image-status-display) command,
+where the `IMAGESTATE` defines the progress of this activity.
+Image status directly on the ONU device can always be performed by the [list](#images-list-on-the-onu) command.
diff --git a/VERSION b/VERSION
index 3a3cd8c..259bb26 100755
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-1.3.1
+1.3.2-dev