Skip to content

Commit a2d5d48

Browse files
OleksandrChaikaOleksandrChaika
committed
Update documentation
1 parent 114fd1b commit a2d5d48

7 files changed

+97
-39
lines changed

‎README.md

+53-25
Original file line numberDiff line numberDiff line change
@@ -24,57 +24,85 @@ sequenceDiagram
2424
participant m as MQTT Broker
2525
participant s as SUA
2626
participant r as RAUC
27+
2728
s -->> m: connect
28-
loop Wait for message: selfupdate/desiredstate
29+
30+
loop Wait for OTA trigger
31+
2932
Note left of s: Initial start
30-
s ->> m: selfupdate/currentstate
33+
s ->> m: Current state (installed version from booted partition)
34+
3135
Note left of s: Trigger for OTA
32-
m ->> s: selfupdate/desiredstate
33-
s ->> m: selfupdate/desiredstatefeedback: downloading 0%
36+
m ->> s: Desired state request (new version and url to bundle)
37+
s ->> m: Feedback (update actions are identified)
38+
39+
Note left of s: Command for Download
40+
m ->> s: Download command
3441
s ->> s: download bundle
35-
s ->> m: selfupdate/desiredstatefeedback: downloading 51%
36-
s ->> r: install
37-
s ->> m: selfupdate/desiredstatefeedback: installing 0%
38-
r ->> r: install
39-
r ->> s: share progress: e.g. 51%
40-
s ->> m: selfupdate/desiredstatefeedback: installing 51%
41-
r ->> s: installation ready
42-
s ->> m: selfupdate/desiredstatefeedback: installed
43-
s ->> m: selfupdate/desiredstatefeedback: idle
42+
s ->> m: Feedback (downloading/downloaded/failed)
43+
44+
Note left of s: Command for Update
45+
m ->> s: Update command
46+
s ->> r: Flash image to partition
47+
r ->> r: Flashing...
48+
s ->> m: Feedback (updating + %)
49+
r ->> s: Flash completed/failed
50+
s ->> m: Feedback (updated/failed)
51+
52+
Note left of s: Command for Activate
53+
m ->> s: Activate command
54+
s ->> r: Switch partitions (booted <-> other)
55+
r ->> s: Switch completed/failed
56+
s ->> m: Feedback (activated/failed)
57+
58+
Note left of s: Command for Cleanup
59+
m ->> s: Cleanup command
60+
s ->> s: Remove temp files
61+
s ->> m: Cleanup completed + status from previously failed state<br>(completed/failed)
62+
4463
end
4564
```
4665

4766
```mermaid
4867
stateDiagram
4968
Uninitialized --> Connected: Connected
50-
Connected --> Downloading: Start
51-
Downloading --> Installing: Bundle version OK
52-
Installing --> Installed: Install complete
53-
Installing --> Failed: RAUC write failed
54-
Downloading --> Failed: Version mismatch/download failed
55-
Installed --> Idle
56-
Failed --> Idle
69+
Connected --> Identified: Start (OTA trigger)
70+
Identified --> Downloading: Command download
71+
Identified --> Failed: If OTA trigger is invalid
72+
Downloading --> Updating: Command update
73+
Downloading --> Failed: If download has failed
74+
Updating --> Activate: Command activate
75+
Updating --> Failed: If update has failed
76+
Activate --> Cleanup: Command cleanup
77+
Activate --> Failed: If activate has failed
78+
Failed --> Cleanup: Command cleanup
79+
Cleanup --> Idle
5780
```
5881
Important: Uninitialized state is the default entry state or state in case connection is lost. To simplify reading of the diagram arrows from other states to Unitialized have been removed.
5982

60-
MQTT communication is done via 3 MQTT topics:
83+
MQTT communication is done over 4 MQTT topics:
6184

62-
## selfupdate/desiredstate
85+
## Trigger OTA
6386
| Topic | Direction | Description |
6487
|-------| -------- | ----------- |
6588
| selfupdate/desiredstate | IN | This message triggers the update process. The payload shall contain all data necessary to obtain the update bundle and to install it. |
6689

67-
## selfupdate/currentstate
90+
## Trigger self-update step/action
91+
| Topic | Direction | Description |
92+
|-------| -------- | ----------- |
93+
| selfupdate/desiredstate/command | IN | This message triggers the single step in update process (download/flash/activate/cleanup). |
94+
95+
## Report current state
6896
| Topic| Direction | Description |
6997
|------| -------- | ----------- |
7098
| selfupdate/currentstate | OUT | This message is being sent either once on SUA start or as an answer to response received by selfupdate/currentstate/get. It contains information about currently installed OS version. |
7199

72-
## selfupdate/currentstate/get
100+
## Get current state
73101
| Topic| Direction | Description |
74102
|------| -------- | ----------- |
75103
| selfupdate/currentstate/get | IN | This message can be received at any point of time. Indicates that SUA should send back version of installed OS as current state. |
76104

77-
## selfupdate/desiredstatefeedback
105+
## Report status of self-update process
78106
| Topic| Direction | Description |
79107
|------| -------- | ----------- |
80108
| selfupdate/desiredstatefeedback | OUT | This message is being sent by SUA to share current progress of triggered update process. This is the *OUT* counterpart of *selfupdate/desiredstate* input message. |

‎docs/bfb.md

+44-14
Original file line numberDiff line numberDiff line change
@@ -97,22 +97,52 @@ MQTT Topic: selfupdate/desiredstatefeedback
9797
}
9898
```
9999

100+
## Command for single self-update action/step
101+
This message contains information about SUA action - what must be done as a single step - download, update, activate, cleanup.
102+
MQTT Topic: selfupdate/desiredstate/command
103+
```
104+
{
105+
"activityId": "random-uuid-as-string",
106+
"timestamp": 123456789,
107+
"payload": {
108+
"baseline": "BASELINE NAME",
109+
"command": "command_type"
110+
}
111+
}
112+
```
113+
100114
## Description of statuses
101115
Following combination of payload_status and action_status are possible:
102-
| payload_status | action_status | Description |
103-
|----------------|---------------|-------------|
104-
| IDENTIFYING | | SUA has received request for update and evaluating it |
105-
| IDENTIFIED | | SUA has received request for update and will try to perform an update |
106-
| RUNNING | DOWNLOADING | Downloading an image |
107-
| RUNNING | DOWNLOAD_SUCCESS | Image is downloaded without errors |
108-
| RUNNING | INSTALLING | Installing an image |
109-
| INCOMPLETE | UPDATE_FAILURE | One of these has failed: download, update or self-update was rejected. Message will contain detailed description what has happened |
110-
| COMPLETED | UPDATE_SUCCESS | Self-update succeeded |
116+
| payload_status | action_status | Description |
117+
|-----------------------|------------------|-------------|
118+
| IDENTIFYING | | SUA has received request for update and evaluating it |
119+
| IDENTIFICATION_FAILED | | SUA has received request for update and unable to perform self-update |
120+
| IDENTIFIED | IDENTIFIED | SUA has received request for update and will try to perform an update |
121+
| DOWNLOADING | DOWNLOADING | Downloading an image |
122+
| DOWNLOAD_SUCCESS | DOWNLOAD_SUCCESS | Image is downloaded without errors |
123+
| DOWNLOAD_FAILURE | DOWNLOAD_FAILURE | Image was not downloaded |
124+
| UPDATING | UPDATING | Installing an image |
125+
| UPDATE_SUCCESS | UPDATING | Image installed |
126+
| UPDATE_FAILURE | UPDATE_FAILURE | Image was not installed due to error |
127+
| ACTIVATING | UPDATING | SUA is activating partition with new image |
128+
| ACTIVATION_SUCCESS | UPDATED | SUA has activated partition with new image |
129+
| ACTIVATION_FAILURE | UPDATE_FAILURE | SUA has failed to activate partition with new image |
130+
| COMPLETE | UPDATE_SUCCESS | Self-update finished without errors |
131+
| INCOMPLETE | UPDATE_FAILURE<br>DOWNLOAD_FAILURE | Self-update is incomplete. Action status and action<br>message will preserve error from one of the previous steps: download/flash/activate.|
132+
133+
## Description of command types
134+
| command | description |
135+
|----------|-------------|
136+
| DOWNLOAD | Start download of bundle |
137+
| UPDATE | Flash image to partition |
138+
| ACTIVATE | Make 'other' partition bootable |
139+
| CLEANUP | Remove temporary files |
111140

112141
## Description of other fields
113-
| name | description |
114-
|------|-------------|
142+
| name | description |
143+
|------------|-------------|
115144
| activityId | Random UUID as string (needs to be taken from desiredstate message and passed back in all feedback messages) |
116-
| timestamp | Epoch time |
117-
| version | Reflects version of SUA running on the device, OS version or bundle version |
118-
| progress | Percentage value of download/install progress |
145+
| timestamp | Epoch time |
146+
| version | Reflects version of SUA running on the device, OS version or bundle version |
147+
| progress | Percentage value of download/install progress |
148+

‎docs/testing/mqtt/command_activate.json renamed to ‎docs/testing/mqtt/command-activate.json

File renamed without changes.

‎docs/testing/mqtt/command_cleanup.json renamed to ‎docs/testing/mqtt/command-cleanup.json

File renamed without changes.

‎docs/testing/mqtt/command_download.json renamed to ‎docs/testing/mqtt/command-download.json

File renamed without changes.

‎docs/testing/mqtt/command_rollback.json renamed to ‎docs/testing/mqtt/command-rollback.json

File renamed without changes.

‎docs/testing/mqtt/command_update.json renamed to ‎docs/testing/mqtt/command-update.json

File renamed without changes.

0 commit comments

Comments
 (0)