Skip to content

Commit eaf1b3c

Browse files
OleksandrChaikaOleksandrChaika
authored
Merge pull request eclipse-leda#29 from SoftwareDefinedVehicle/feature/fine_grained_api
Implemented fine-grained API for self-update
2 parents 8178142 + fc345af commit eaf1b3c

File tree

93 files changed

+1604
-1311
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

93 files changed

+1604
-1311
lines changed

Diff for: ‎.github/actions/build-native-binary/action.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ runs:
4848
build-essential libcurl4-openssl-dev \
4949
binutils-aarch64-linux-gnu gcc-9-aarch64-linux-gnu g++-9-aarch64-linux-gnu \
5050
python3 python3-pip python3-setuptools python3-wheel ninja-build python3-pip \
51-
libselinux1-dev libmount-dev libmount1 libblkid-dev
51+
libselinux1-dev libmount-dev libmount1 libblkid-dev mosquitto mosquitto-clients
5252
pip3 install meson
5353
shell: bash
5454

Diff for: ‎.gitmodules

-3
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@
44
[submodule "3rdparty/paho.mqtt.cpp"]
55
path = 3rdparty/paho.mqtt.cpp
66
url = https://github.com/eclipse/paho.mqtt.cpp.git
7-
[submodule "3rdparty/mini-yaml"]
8-
path = 3rdparty/mini-yaml
9-
url = https://github.com/jimmiebergmann/mini-yaml.git
107
[submodule "3rdparty/curl"]
118
path = 3rdparty/curl
129
url = https://github.com/curl/curl.git

Diff for: ‎.ort.yml

-3
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,6 @@ excludes:
2424
- pattern: "3rdparty/googletest/**"
2525
reason: "TEST_OF"
2626
comment: "Google test framework, not included in production release."
27-
- pattern: "3rdparty/mini-yaml/test/**"
28-
reason: "TEST_OF"
29-
comment: "Mini yaml test setup, not included in production release."
3027
- pattern: "3rdparty/openssl/wycheproof/**"
3128
reason: "TEST_OF"
3229
comment: "Crypto library testing, not included in production release."

Diff for: ‎3rdparty/CMakeLists.txt

-3
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,6 @@ add_subdirectory(./paho.mqtt.cpp)
1212
add_dependencies(paho-mqttpp3 paho-mqtt3a)
1313
add_dependencies(paho-mqttpp3 paho-mqtt3c)
1414

15-
add_library(mini-yaml SHARED ./mini-yaml/yaml/Yaml.cpp)
16-
install(TARGETS mini-yaml LIBRARY DESTINATION lib)
17-
1815
set(CMAKE_PREFIX_PATH ${CMAKE_BINARY_DIR}/lib/pkgconfig)
1916
find_package(OpenSSL REQUIRED)
2017
set(CURL_USE_OPENSSL ON)

Diff for: ‎3rdparty/mini-yaml

-1
This file was deleted.

Diff for: ‎Dockerfile.amd64

-1
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,6 @@ COPY --from=build /work/dist_amd64/bin/sdv-self-update-agent /sua/bin/sdv-self-u
6060
COPY --from=build /work/dist_amd64/lib/libpaho-mqttpp3.so.1 /sua/lib/
6161
COPY --from=build /work/dist_amd64/lib/libpaho-mqtt3a.so.1 /sua/lib/
6262
COPY --from=build /work/dist_amd64/lib/libpaho-mqtt3c.so.1 /sua/lib/
63-
COPY --from=build /work/dist_amd64/lib/libmini-yaml.so /sua/lib/
6463
COPY --from=build /work/dist_amd64/lib/libcurl.so /sua/lib/
6564
COPY --from=build /work/dist_amd64/lib/libcrypto.so.3 /sua/lib/
6665
COPY --from=build /work/dist_amd64/lib/libssl.so.3 /sua/lib/

Diff for: ‎Dockerfile.arm64

-1
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,6 @@ COPY --from=build /work/dist_arm64/bin/sdv-self-update-agent /sua/bin/sdv-self-u
6060
COPY --from=build /work/dist_arm64/lib/libpaho-mqttpp3.so.1 /sua/lib/
6161
COPY --from=build /work/dist_arm64/lib/libpaho-mqtt3a.so.1 /sua/lib/
6262
COPY --from=build /work/dist_arm64/lib/libpaho-mqtt3c.so.1 /sua/lib/
63-
COPY --from=build /work/dist_arm64/lib/libmini-yaml.so /sua/lib/
6463
COPY --from=build /work/dist_arm64/lib/libcurl.so /sua/lib/
6564
COPY --from=build /work/dist_arm64/lib/libcrypto.so.3 /sua/lib/
6665
COPY --from=build /work/dist_arm64/lib/libssl.so.3 /sua/lib/

Diff for: ‎README.md

+65-37
Original file line numberDiff line numberDiff line change
@@ -24,62 +24,90 @@ 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%
34-
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
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
41+
s ->> s: Download bundle
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 with percentage)
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 temporary 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 5 MQTT topics:
6184

62-
## selfupdate/desiredstate
85+
## Trigger OTA
6386
| Topic | Direction | Description |
64-
|-------| -------- | ----------- |
87+
|-------|-----------|-------------|
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
68-
| Topic| Direction | Description |
69-
|------| -------- | ----------- |
70-
| 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. |
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). |
7194

72-
## selfupdate/currentstate/get
73-
| Topic| Direction | Description |
74-
|------| -------- | ----------- |
75-
| 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. |
95+
## Report current state
96+
| Topic | Direction | Description |
97+
|-------|-----------|-------------|
98+
| 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 the currently installed OS version. |
7699

77-
## selfupdate/desiredstatefeedback
78-
| Topic| Direction | Description |
79-
|------| -------- | ----------- |
80-
| 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. |
100+
## Get current state
101+
| Topic | Direction | Description |
102+
|-------|-----------|-------------|
103+
| selfupdate/currentstate/get | IN | This message can be received at any point of time. Indicates that SUA should send back the version of the installed OS as current state. |
104+
105+
## Report status of self-update process
106+
| Topic | Direction | Description |
107+
|-------|-----------|-------------|
108+
| selfupdate/desiredstatefeedback | OUT | This message is being sent by SUA to share the current progress of the triggered update process. This is the *OUT* counterpart of *selfupdate/desiredstate* input message. |
81109

82-
SUA supports 2 protocols depending on configuration: [link](docs/k8s.md) for Kubernetes-based Custom Objects or [link](docs/bfb.md) for Update Agent API.Default protocol is bfb.
110+
Detailed description of Update Agent API can be found here: [link](docs/bfb.md).
83111

84112
# Checkout
85113
SUA links to some 3rd party libraries, which are fetched as submodules, therefore the cloning shall be performed with recursive option:

Diff for: ‎docs/bfb.md

+45-15
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
101-
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 |
115+
Following combinations of payload_status and action_status are possible:
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 is 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 the downloaded 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 the partition with new image |
128+
| ACTIVATION_SUCCESS | UPDATED | SUA has activated the partition with new image |
129+
| ACTIVATION_FAILURE | UPDATE_FAILURE | SUA has failed to activate the 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 (in seconds since January 1, 1970) |
146+
| version | Reflects version of SUA running on the device, OS version or bundle version |
147+
| progress | Percentage value of download/install progress |
148+

Diff for: ‎docs/k8s.md

-76
This file was deleted.

Diff for: ‎docs/testing/README.md

+5-4
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,11 @@ python3 -m http.server --bind 127.0.0.1 5555
5252

5353
## Simulate sending the MQTT Start messages
5454

55-
The content of the yaml file shall be adjusted, so that url of hosted bundle is valid.
55+
The content of the json file shall be adjusted, so that url of hosted bundle is valid.
5656

5757
```
58-
mosquitto_pub -t "selfupdate/desiredstate" -f docs/testing/mqtt/start.yaml
58+
mosquitto_pub -t "selfupdate/desiredstate" -f docs/testing/mqtt/start.json
59+
mosquitto_pub -t "selfupdate/desiredstate/command" -f docs/testing/mqtt/command-download.json
5960
```
6061

6162
## Subscribe to MQTT feedback messages
@@ -98,7 +99,7 @@ docker build -t host .
9899
docker run -it --network=my-network -p 5555:5555 --name fileserver host
99100
```
100101

101-
The bundle file will be available under: `fileserver:5555/bundle` url, so the value in `start.yaml` shall be adjusted.
102+
The bundle file will be available under: `fileserver:5555/bundle` url, so the value in `start.json` shall be adjusted.
102103

103104
## Deploy SUA
104105

@@ -137,7 +138,7 @@ and locate the `IPAddress` value.
137138
# HowTo send the Start signal to trigger the process
138139

139140
```
140-
mosquitto_pub -t "selfupdate/desiredstate" -f docs/testing/mqtt/start.yaml -h ipAddress_of_mosquitto_container
141+
mosquitto_pub -t "selfupdate/desiredstate" -f docs/testing/mqtt/start.json -h ipAddress_of_mosquitto_container
141142
```
142143

143144
After sending this signal, you should be able to observe the SUA behavior on the console.

Diff for: ‎docs/testing/mqtt/command-activate.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"activityId": "random-uuid-as-string",
3+
"timestamp": 123456789,
4+
"payload": {
5+
"baseline": "BASELINE NAME",
6+
"command": "ACTIVATE"
7+
}
8+
}

Diff for: ‎docs/testing/mqtt/command-cleanup.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"activityId": "random-uuid-as-string",
3+
"timestamp": 123456789,
4+
"payload": {
5+
"baseline": "BASELINE NAME",
6+
"command": "CLEANUP"
7+
}
8+
}

Diff for: ‎docs/testing/mqtt/command-download.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"activityId": "random-uuid-as-string",
3+
"timestamp": 123456789,
4+
"payload": {
5+
"baseline": "BASELINE NAME",
6+
"command": "DOWNLOAD"
7+
}
8+
}

Diff for: ‎docs/testing/mqtt/command-rollback.json

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"activityId": "random-uuid-as-string",
3+
"timestamp": 123456789,
4+
"payload": {
5+
"baseline": "BASELINE NAME",
6+
"command": "ROLLBACK"
7+
}
8+
}

0 commit comments

Comments
 (0)