Acknowledgement Orchestration

The topic describes how to monitor acknowledgements for Octave's file transfer feature.

The overall asset software-over-the-air (SOTA) operation using the Octave file transfer feature consists of three successive steps:

1. File sending from Octave Cloud to Octave Edge (under Octave scope).
2. File transfer from Octave Edge to Remote Asset (under asset scope).
3. File usage by the Remote Asset (under Remote Asset scope).

To monitor the overall operational state through to completion, these three steps need to be followed through their respective acknowledgments within a single data flow.

As these steps are successive and synchronous to follow the state change in a time-sensitive and Resource-efficient manner, it’s recommended to collect state changes by listening on a notification stream instead of using the Octave API.

The file-sending operation (Step 1), which is Octave dependent, has progress triggered through the /files/download/value Resource at Octave Edge level and operation state through the /<your company>/:inbox/devices Stream available in Octave Cloud.

The transfer (Step 2) and usage of the file (Step 3) are dependent on the Remote Asset and need to have their state change reported by the Remote Asset through a new, dedicated Resource.

Octave will then aggregate the state’s acknowledgment in a single stream that you can integrate into your device management application handling the file transfer.

Therefore, we recommend following the steps below that describe how to acknowledge the file transfer during the entire operation:

1. Create a file_ack Stream in your company to aggregate the state’s acknowledgment in a single Stream.

2. Create a Cloud Action with /<your company>/:inbox/devices as a source Stream and JavaScript code that filters and sends the state events you want to report in the /<your company>/file_ack Stream on each file-sending Event.
3. Create a Virtual Resource with a JSON type to capture and monitor download state information via the /virtual/file_dl_ack/value Resource (for details refer to Virtual Resources):

📘

Note

ORP allows the Remote Asset to write to resources under /files. Therefore, the Remote Asset can write transfer acknowledgements on an existing Resource such as /virtual/file_dl_ack/value. For example:

• Transfer state: WAITING, TRANSFERRING, SUCCESS, FAILURE, ABORTED
• Usage state: WAITING, USING, SUCCESS, FAILURE, ABORTED

4. Create a “file_dl_ack” Observation with an Edge Action destination on /virtual/file_dl_ack/value.

5. Create an Edge Action with file_dl_ack as the source Observation and JavaScript code that filters and sends the state events you want to report in /<your company>/file_ack stream on each file transfer and usage reported by your Remote Asset.

6. Create a Cloud Action on /<your company>/file_ack with JavaScript code that executes in the cloud on the event data (for details refer to Creating a Cloud Action).

7. Create a new Blueprint. This operation will create a new Blueprint based on the current configuration of the device you are configuring for file transfer. The Blueprint created will be applied to the device automatically after creation and you can use the same Blueprint to deploy to your other devices.

The following diagram depicts these steps:

📘

Note:

If you want to monitor the file sending progress between Octave Cloud and Octave Edge, you can create an Observation on the /files/download/value Resource which regularly reports the progress as a percentage and the remaining bytes. Be careful, if you create a Cloud Stream Observation this will trigger numerous billable messages. This may be acceptable during development/debugging but not for an operation. For an operation, consider creating an Edge Action to trigger on a threshold (e.g., 50% completed) or on an abnormal file duration (e.g., 1 MB in more than 1 hour).