Skip to content

Commit 298ea05

Browse files
cmagliecmaglie
committed
Updated migration guide
1 parent 4707ce2 commit 298ea05

File tree

1 file changed

+388
-0
lines changed

1 file changed

+388
-0
lines changed

Diff for: ‎docs/UPGRADING.md

+388
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,394 @@
22

33
Here you can find a list of migration guides to handle breaking changes between releases of the CLI.
44

5+
## 0.18.0
6+
7+
### Breaking changes in gRPC API and CLI JSON output.
8+
9+
Starting from this release we applied a more rigorous and stricter naming conventions in gRPC API following the official
10+
guidelines: https://developers.google.com/protocol-buffers/docs/style
11+
12+
We also started using a linter to implement checks for gRPC API style errors.
13+
14+
This provides a better consistency and higher quality API but inevitably introduces breaking changes.
15+
16+
### gRPC API breaking changes
17+
18+
Consumers of the gRPC API should regenerate their bindings and update all structures naming where necessary. Most of the
19+
changes are trivial and falls into the following categories:
20+
21+
- Service names have been suffixed with `...Service` (for example `ArduinoCore` -> `ArduinoCoreService`)
22+
- Message names suffix has been changed from `...Req`/`...Resp` to `...Request`/`...Response` (for example
23+
`BoardDetailsReq` -> `BoardDetailsRequest`)
24+
- Enumerations now have their class name prefixed (for example the enumeration value `FLAT` in `LibraryLayout` has been
25+
changed to `LIBRARY_LAYOUT_FLAT`)
26+
- Use of lower-snake case on all fields (for example: `ID` -> `id`, `FQBN` -> `fqbn`, `Name` -> `name`,
27+
`ArchiveFilename` -> `archive_filename`)
28+
- Package names are now versioned (for example `cc.arduino.cli.commands` -> `cc.arduino.cli.commands.v1`)
29+
- Repeated responses are now in plural form (`identification_pref` -> `identification_prefs`, `platform` -> `platforms`)
30+
31+
### arduino-cli JSON output breaking changes
32+
33+
Consumers of the JSON output of the CLI must update their clients if they use one of the following commands:
34+
35+
- in `core search` command the following fields have been renamed:
36+
37+
- `Boards` -> `boards`
38+
- `Email` -> `email`
39+
- `ID` -> `id`
40+
- `Latest` -> `latest`
41+
- `Maintainer` -> `maintainer`
42+
- `Name` -> `name`
43+
- `Website` -> `website`
44+
45+
The new output is like:
46+
47+
```
48+
$ arduino-cli core search Due --format json
49+
[
50+
{
51+
"id": "arduino:sam",
52+
"latest": "1.6.12",
53+
"name": "Arduino SAM Boards (32-bits ARM Cortex-M3)",
54+
"maintainer": "Arduino",
55+
"website": "http://www.arduino.cc/",
56+
"email": "[email protected]",
57+
"boards": [
58+
{
59+
"name": "Arduino Due (Native USB Port)",
60+
"fqbn": "arduino:sam:arduino_due_x"
61+
},
62+
{
63+
"name": "Arduino Due (Programming Port)",
64+
"fqbn": "arduino:sam:arduino_due_x_dbg"
65+
}
66+
]
67+
}
68+
]
69+
```
70+
71+
- in `board details` command the following fields have been renamed:
72+
73+
- `identification_pref` -> `identification_prefs`
74+
- `usbID` -> `usb_id`
75+
- `PID` -> `pid`
76+
- `VID` -> `vid`
77+
- `websiteURL` -> `website_url`
78+
- `archiveFileName` -> `archive_filename`
79+
- `propertiesId` -> `properties_id`
80+
- `toolsDependencies` -> `tools_dependencies`
81+
82+
The new output is like:
83+
84+
```
85+
$ arduino-cli board details arduino:avr:uno --format json
86+
{
87+
"fqbn": "arduino:avr:uno",
88+
"name": "Arduino Uno",
89+
"version": "1.8.3",
90+
"properties_id": "uno",
91+
"official": true,
92+
"package": {
93+
"maintainer": "Arduino",
94+
"url": "https://downloads.arduino.cc/packages/package_index.json",
95+
"website_url": "http://www.arduino.cc/",
96+
"email": "[email protected]",
97+
"name": "arduino",
98+
"help": {
99+
"online": "http://www.arduino.cc/en/Reference/HomePage"
100+
}
101+
},
102+
"platform": {
103+
"architecture": "avr",
104+
"category": "Arduino",
105+
"url": "http://downloads.arduino.cc/cores/avr-1.8.3.tar.bz2",
106+
"archive_filename": "avr-1.8.3.tar.bz2",
107+
"checksum": "SHA-256:de8a9b982477762d3d3e52fc2b682cdd8ff194dc3f1d46f4debdea6a01b33c14",
108+
"size": 4941548,
109+
"name": "Arduino AVR Boards"
110+
},
111+
"tools_dependencies": [
112+
{
113+
"packager": "arduino",
114+
"name": "avr-gcc",
115+
"version": "7.3.0-atmel3.6.1-arduino7",
116+
"systems": [
117+
{
118+
"checksum": "SHA-256:3903553d035da59e33cff9941b857c3cb379cb0638105dfdf69c97f0acc8e7b5",
119+
"host": "arm-linux-gnueabihf",
120+
"archive_filename": "avr-gcc-7.3.0-atmel3.6.1-arduino7-arm-linux-gnueabihf.tar.bz2",
121+
"url": "http://downloads.arduino.cc/tools/avr-gcc-7.3.0-atmel3.6.1-arduino7-arm-linux-gnueabihf.tar.bz2",
122+
"size": 34683056
123+
},
124+
{ ... }
125+
]
126+
},
127+
{ ... }
128+
],
129+
"identification_prefs": [
130+
{
131+
"usb_id": {
132+
"vid": "0x2341",
133+
"pid": "0x0043"
134+
}
135+
},
136+
{ ... }
137+
],
138+
"programmers": [
139+
{
140+
"platform": "Arduino AVR Boards",
141+
"id": "parallel",
142+
"name": "Parallel Programmer"
143+
},
144+
{ ... }
145+
]
146+
}
147+
```
148+
149+
- in `board listall` command the following fields have been renamed:
150+
151+
- `FQBN` -> `fqbn`
152+
- `Email` -> `email`
153+
- `ID` -> `id`
154+
- `Installed` -> `installed`
155+
- `Latest` -> `latest`
156+
- `Name` -> `name`
157+
- `Maintainer` -> `maintainer`
158+
- `Website` -> `website`
159+
160+
The new output is like:
161+
162+
```
163+
$ arduino-cli board listall Uno --format json
164+
{
165+
"boards": [
166+
{
167+
"name": "Arduino Uno",
168+
"fqbn": "arduino:avr:uno",
169+
"platform": {
170+
"id": "arduino:avr",
171+
"installed": "1.8.3",
172+
"latest": "1.8.3",
173+
"name": "Arduino AVR Boards",
174+
"maintainer": "Arduino",
175+
"website": "http://www.arduino.cc/",
176+
"email": "[email protected]"
177+
}
178+
}
179+
]
180+
}
181+
```
182+
183+
- in `board search` command the following fields have been renamed:
184+
185+
- `FQBN` -> `fqbn`
186+
- `Email` -> `email`
187+
- `ID` -> `id`
188+
- `Installed` -> `installed`
189+
- `Latest` -> `latest`
190+
- `Name` -> `name`
191+
- `Maintainer` -> `maintainer`
192+
- `Website` -> `website`
193+
194+
The new output is like:
195+
196+
```
197+
$ arduino-cli board search Uno --format json
198+
[
199+
{
200+
"name": "Arduino Uno",
201+
"fqbn": "arduino:avr:uno",
202+
"platform": {
203+
"id": "arduino:avr",
204+
"installed": "1.8.3",
205+
"latest": "1.8.3",
206+
"name": "Arduino AVR Boards",
207+
"maintainer": "Arduino",
208+
"website": "http://www.arduino.cc/",
209+
"email": "[email protected]"
210+
}
211+
}
212+
]
213+
```
214+
215+
- in `lib deps` command the following fields have been renamed:
216+
217+
- `versionRequired` -> `version_required`
218+
- `versionInstalled` -> `version_installed`
219+
220+
The new output is like:
221+
222+
```
223+
$ arduino-cli lib deps Arduino_MKRIoTCarrier --format json
224+
{
225+
"dependencies": [
226+
{
227+
"name": "Adafruit seesaw Library",
228+
"version_required": "1.3.1"
229+
},
230+
{
231+
"name": "SD",
232+
"version_required": "1.2.4",
233+
"version_installed": "1.2.3"
234+
},
235+
{ ... }
236+
]
237+
}
238+
```
239+
240+
- in `lib search` command the following fields have been renamed:
241+
242+
- `archivefilename` -> `archive_filename`
243+
- `cachepath` -> `cache_path`
244+
245+
The new output is like:
246+
247+
```
248+
$ arduino-cli lib search NTPClient --format json
249+
{
250+
"libraries": [
251+
{
252+
"name": "NTPClient",
253+
"releases": {
254+
"1.0.0": {
255+
"author": "Fabrice Weinberg",
256+
"version": "1.0.0",
257+
"maintainer": "Fabrice Weinberg \[email protected]\u003e",
258+
"sentence": "An NTPClient to connect to a time server",
259+
"paragraph": "Get time from a NTP server and keep it in sync.",
260+
"website": "https://github.com/FWeinb/NTPClient",
261+
"category": "Timing",
262+
"architectures": [
263+
"esp8266"
264+
],
265+
"types": [
266+
"Arduino"
267+
],
268+
"resources": {
269+
"url": "https://downloads.arduino.cc/libraries/github.com/arduino-libraries/NTPClient-1.0.0.zip",
270+
"archive_filename": "NTPClient-1.0.0.zip",
271+
"checksum": "SHA-256:b1f2907c9d51ee253bad23d05e2e9c1087ab1e7ba3eb12ee36881ba018d81678",
272+
"size": 6284,
273+
"cache_path": "libraries"
274+
}
275+
},
276+
"2.0.0": { ... },
277+
"3.0.0": { ... },
278+
"3.1.0": { ... },
279+
"3.2.0": { ... }
280+
},
281+
"latest": {
282+
"author": "Fabrice Weinberg",
283+
"version": "3.2.0",
284+
"maintainer": "Fabrice Weinberg \[email protected]\u003e",
285+
"sentence": "An NTPClient to connect to a time server",
286+
"paragraph": "Get time from a NTP server and keep it in sync.",
287+
"website": "https://github.com/arduino-libraries/NTPClient",
288+
"category": "Timing",
289+
"architectures": [
290+
"*"
291+
],
292+
"types": [
293+
"Arduino"
294+
],
295+
"resources": {
296+
"url": "https://downloads.arduino.cc/libraries/github.com/arduino-libraries/NTPClient-3.2.0.zip",
297+
"archive_filename": "NTPClient-3.2.0.zip",
298+
"checksum": "SHA-256:122d00df276972ba33683aff0f7fe5eb6f9a190ac364f8238a7af25450fd3e31",
299+
"size": 7876,
300+
"cache_path": "libraries"
301+
}
302+
}
303+
}
304+
],
305+
"status": 1
306+
}
307+
```
308+
309+
- in `board list` command the following fields have been renamed:
310+
311+
- `FQBN` -> `fqbn`
312+
- `VID` -> `vid`
313+
- `PID` -> `pid`
314+
315+
The new output is like:
316+
317+
```
318+
$ arduino-cli board list --format json
319+
[
320+
{
321+
"address": "/dev/ttyACM0",
322+
"protocol": "serial",
323+
"protocol_label": "Serial Port (USB)",
324+
"boards": [
325+
{
326+
"name": "Arduino Nano 33 BLE",
327+
"fqbn": "arduino:mbed:nano33ble",
328+
"vid": "0x2341",
329+
"pid": "0x805a"
330+
},
331+
{
332+
"name": "Arduino Nano 33 BLE",
333+
"fqbn": "arduino-dev:mbed:nano33ble",
334+
"vid": "0x2341",
335+
"pid": "0x805a"
336+
},
337+
{
338+
"name": "Arduino Nano 33 BLE",
339+
"fqbn": "arduino-dev:nrf52:nano33ble",
340+
"vid": "0x2341",
341+
"pid": "0x805a"
342+
},
343+
{
344+
"name": "Arduino Nano 33 BLE",
345+
"fqbn": "arduino-beta:mbed:nano33ble",
346+
"vid": "0x2341",
347+
"pid": "0x805a"
348+
}
349+
],
350+
"serial_number": "BECC45F754185EC9"
351+
}
352+
]
353+
$ arduino-cli board list -w --format json
354+
{
355+
"type": "add",
356+
"address": "/dev/ttyACM0",
357+
"protocol": "serial",
358+
"protocol_label": "Serial Port (USB)",
359+
"boards": [
360+
{
361+
"name": "Arduino Nano 33 BLE",
362+
"fqbn": "arduino-dev:nrf52:nano33ble",
363+
"vid": "0x2341",
364+
"pid": "0x805a"
365+
},
366+
{
367+
"name": "Arduino Nano 33 BLE",
368+
"fqbn": "arduino-dev:mbed:nano33ble",
369+
"vid": "0x2341",
370+
"pid": "0x805a"
371+
},
372+
{
373+
"name": "Arduino Nano 33 BLE",
374+
"fqbn": "arduino-beta:mbed:nano33ble",
375+
"vid": "0x2341",
376+
"pid": "0x805a"
377+
},
378+
{
379+
"name": "Arduino Nano 33 BLE",
380+
"fqbn": "arduino:mbed:nano33ble",
381+
"vid": "0x2341",
382+
"pid": "0x805a"
383+
}
384+
],
385+
"serial_number": "BECC45F754185EC9"
386+
}
387+
{
388+
"type": "remove",
389+
"address": "/dev/ttyACM0"
390+
}
391+
```
392+
5393
## 0.16.0
6394

7395
### Change type of `CompileReq.ExportBinaries` message in gRPC interface

0 commit comments

Comments
 (0)