Skip to content

Commit 81d23b4

Browse files
OleksandrChaikaOleksandrChaika
authored
Added migration guide from YAML to JSON (eclipse-leda#40)
* Added short migration guide from YAML to JSON * Fix review findings #1 * Fix review findings #2
1 parent 4b3ed59 commit 81d23b4

File tree

2 files changed

+128
-0
lines changed

2 files changed

+128
-0
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,7 @@ MQTT communication is done over 5 MQTT topics:
108108
| 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. |
109109

110110
Detailed description of Update Agent API can be found here: [link](docs/bfb.md).
111+
Migration guide for users from old YAML payloads to new JSON format can be found here: [link](docs/migration_guide.md).
111112

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

‎docs/migration_guide.md

+127
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# Migration guide from YAML payloads to JSON (bfb) protocol
2+
3+
## Background
4+
The communication protocol between SUA and backend was extended to support vehicle orchestration for large quantities of devices. Key differences are:
5+
* Transition from YAML to JSON
6+
* Fine-grained API (command-based approach instead of single-shot self-update)
7+
* Extension of statuses (for detailed reflection of success, progress or failure)
8+
Some fields are not relevant anymore meanwhile new were introduced. Below is a brief comparison between messages in YAML and in JSON format.
9+
10+
### Transition guide for current state message
11+
From the current state message in YAML payload there is only one field 'bundleVersion' which is relevant. The corresponding field in JSON variant is 'version' in 'softwareNodes' for the device image. *NOTE*: The actual name could differ depending on the distro configuration.
12+
```
13+
apiVersion: sdv.eclipse.org/v1
14+
kind: SelfUpdateBundle
15+
metadata:
16+
name: "self-update-bundle-example"
17+
spec:
18+
bundleVersion: 1.0
19+
```
20+
21+
```
22+
{
23+
"timestamp": 42,
24+
"payload": {
25+
"softwareNodes": [
26+
{
27+
"id": "self-update-agent",
28+
"version": "build-42",
29+
"name": "OTA NG Self Update Agent",
30+
"type": "APPLICATION"
31+
},
32+
{
33+
"id": "self-update:leda-deviceimage",
34+
"version": "1.0",
35+
"name": "Official Leda device image",
36+
"type": "IMAGE"
37+
}
38+
],
39+
"hardwareNodes": [],
40+
"associations": [
41+
{
42+
"sourceId": "self-update-agent",
43+
"targetId": "self-update:leda-deviceimage"
44+
}
45+
]
46+
}
47+
}
48+
```
49+
50+
### Transition guide for desired state message
51+
For the desired state message there are two relevant fields 'bundleDownloadUrl' and 'bundleVersion' for take-over. The corresponding values are 'version' under the 'components' and 'value' inside the object with 'key'='image'. *NOTE*: There could be multiple entries inside 'components' array and 'config' section. Your implementation has to search for 'os-image' and 'image' values respectively.
52+
```
53+
apiVersion: "sdv.eclipse.org/v1"
54+
kind: SelfUpdateBundle
55+
metadata:
56+
name: self-update-bundle-example
57+
spec:
58+
bundleDownloadUrl: http://url
59+
bundleName: arm64-bundle
60+
bundleTarget: base
61+
bundleVersion: 1.0
62+
```
63+
```
64+
{
65+
"activityId": "random-uuid-as-string",
66+
"timestamp": 123456789,
67+
"payload": {
68+
"domains": [
69+
{
70+
"id": "self-update",
71+
"components": [
72+
{
73+
"id": "os-image",
74+
"version": "1.1",
75+
"config": [
76+
{
77+
"key": "image",
78+
"value": "http://example.com/downloads/os-image-1.1.bin"
79+
}
80+
]
81+
}
82+
]
83+
}
84+
]
85+
}
86+
}
87+
```
88+
89+
### Transition guide for state feedback
90+
Below there is an example for state feedback ('techCode' is optional and available only in case of failure). For transition to JSON format all three fields from 'state' section are important (except 'techCode') and their corresponding places in JSON are 'status' and 'message' in sections 'payload' and 'actions', and 'progress' in section 'actions'. The detailed list of the available payload status and action status can be found in [link](docs/bfb.md) because for vehicle orchestration more sub-states were introduced for a fine-grained report of the self-update progress.
91+
```
92+
apiVersion: sdv.eclipse.org/v1
93+
kind: SelfUpdateBundle
94+
metadata:
95+
name: "self-update-bundle-example"
96+
spec:
97+
bundleDownloadUrl: "http://url"
98+
bundleName: "arm64-bundle"
99+
bundleTarget: base
100+
bundleVersion: 1.0
101+
state:
102+
message: Downloaded 10.0 MiB...
103+
name: downloading
104+
progress: 100
105+
techCode: 42
106+
```
107+
```
108+
{
109+
"activityId": "id",
110+
"timestamp": 42,
111+
"payload": {
112+
"status": "ACTIVATION_SUCCESS",
113+
"message": "Self-update agent has activated the new OS image.",
114+
"actions": [
115+
{
116+
"component": {
117+
"id": "self-update:os-image",
118+
"version": "1.0"
119+
},
120+
"status": "UPDATED",
121+
"progress": 0,
122+
"message": "Self-update agent has activated the new OS image."
123+
}
124+
]
125+
}
126+
}
127+
```

0 commit comments

Comments
 (0)