You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
### Integration with `arduino-cli` and core platforms
314
314
315
-
#### Discovery tool install and launch
315
+
In this section we will see how discvoeries are distributed and integrated with Arduino platforms.
316
316
317
-
Discovery tools should be built natively for each OS and the CLI should run the correct tool for the running OS. This infrastracture is already available for platform tools so the most natural way forward is to distribute the discoveries as tools within core platforms (in the same way we do for `gcc` or `avrdude`).
317
+
#### Discovery tool distribution
318
318
319
-
3rd party platforms may add other discoveries by providing them as tools dependencies for their platform and by adding a directive to their `platform.txt` that informs the CLI that a new discovery is available.
319
+
The discovery tools must be built natively for each OS and the CLI should run the correct tool for the running OS.
320
320
321
-
```
322
-
discovery.DISCOVERY_ID.pattern=DISCOVERY_RECIPE
323
-
```
321
+
The distribution infrastracture is already available for platform tools, like compilers and uploaders, through `package_index.json` so, the most natural way forward is to distribute also the discoveries in the same way.
322
+
3rd party developers should provide their discovery tools by adding them as resources in the `tools` section of `package_index.json` (at the `packages` level).
324
323
325
-
The CLI will look for directives matching the above pattern. `DISCOVERY_ID` must be replaced by a unique identifier for the particular discovery and `DISCOVERY_RECIPE` must be replaced by the command line to run to launch the discovery. An example could be:
324
+
Let's see how this looks into a `package_index.json`example:
in this case the platform provides a new `teensy` discovery and the command line tool named `teensy_ports` is launched with the `-J2` parameter to start the discovery tool.
363
+
In this case we are adding an hypotetical `ble-discovery` version `1.0.0` to the toolset of the vendor `arduino`. From now on, we can uniquely refer to this discovery with the pair `PACKAGER` and `DISCOVERY_NAME`, in this case `arduino` and `ble-discovery` respectively.
333
364
334
-
#### Using a discovery made by a 3rd party
365
+
The compressed archive of the discovery must contain only a single executable file (the discovery itself) inside a single root folder. This is mandatory since the CLI will run this file automatically when the discovery is started.
366
+
367
+
#### Discovery tools integration
368
+
369
+
Each core platform must refer to the specific discovery tools they need by adding them a new `discoveryDependencies` field of the `package_index.json`. Let's look again at the previous example:
370
+
371
+
```diff
372
+
{
373
+
"packages": [
374
+
{
375
+
"name": "arduino",
376
+
"maintainer": "Arduino",
377
+
"websiteURL": "http://www.arduino.cc/",
378
+
379
+
"platforms": [
380
+
{
381
+
"name": "Arduino AVR Boards",
382
+
"architecture": "avr",
383
+
"version": "1.6.2",
384
+
...
385
+
"toolsDependencies": [
386
+
{
387
+
"packager": "arduino",
388
+
"name": "arm-none-eabi-gcc",
389
+
"version": "4.8.3-2014q1"
390
+
},
391
+
{
392
+
"packager": "arduino",
393
+
"name": "CMSIS",
394
+
"version": "4.5.0"
395
+
},
396
+
...
397
+
],
398
+
+ "discoveryDependencies": [ <--- Discoveries used in the platform
399
+
+ {
400
+
+ "packager": "arduino",
401
+
+ "name": "ble-discovery"
402
+
+ <--- Version is not required!
403
+
+ }
404
+
+ ]
405
+
},
406
+
407
+
{
408
+
"name": "Arduino SAMD Boards",
409
+
"architecture": "samd",
410
+
"version": "1.6.18",
411
+
...
412
+
"toolsDependencies": [ ... ],
413
+
+ "discoveryDependencies": [ ... ]
414
+
}
415
+
416
+
],
417
+
"tools": [
418
+
{
419
+
"name": "arm-none-eabi-gcc",
420
+
"version": "4.8.3-2014q1",
421
+
"systems": [ ... ]
422
+
},
423
+
{
424
+
"name": "ble-discovery",
425
+
"version": "1.0.0",
426
+
"systems": [ ... ]
427
+
}
428
+
],
429
+
}
430
+
}
431
+
}
432
+
```
335
433
336
-
A platform may opt to depend on a discovery developed by a 3rd party instead of writing and maintaining his own. Since writing a good-quality cross-platform discovery is very hard and time consuming, we expect this option to be used by the majority of developers.
434
+
Adding the needed discoveries in the `discoveryDependencies` allows the CLI to install them together with the platform. Also, differently from the other `toolsDependencies`, the version is not required since it will always be used the latest version available.
337
435
338
-
To depend on a 3rd party discovery the platformmust add the following directive in the `platform.txt`file:
436
+
Finally, to actually bind a discovery to a platform, we must also declare in the `platform.txt`that we want to use that specific discovery with the direcive:
The `PACKAGER:ARCHITECTURE:DISCOVERY_ID` field represents a unique identifier to a 3rd party discovery in particular the `PACKAGER:ARCHITECTURE:...` part is the same as in the FQBN for the boards.
353
-
354
-
For example if a platform needs the `network` discovery from the Arduino AVR platform it may specify it with:
450
+
in our specific example the directive should be:
355
451
356
452
```
357
-
discovery.required=arduino:avr:network
453
+
discovery.required=arduino:ble-discovery
358
454
```
359
455
360
-
#### built-in discoveries and backward compatibliity consideration
456
+
#### Using a discovery made by a 3rd party
457
+
458
+
A platform developer may opt to depend on a discovery developed by a 3rd party instead of writing and maintaining his own.
459
+
460
+
Since writing a good-quality cross-platform discovery is very hard and time consuming, we expect this option to be the one used by the majority of the developers.
361
461
362
-
Some discoveries like the Arduino `serial-discovery` or the Arduino `network-discovery` must be always available, so they will be part of the `builtin` platform package and installed without the need to be part of a real platform (`builtin:builtin` is a dummy package that we use to install tools that are not part of any platforms like `ctags` for example).
462
+
#### Direct discovery integration (not recommended)
463
+
464
+
A discovery may be directly added to a platform, without passing through the `discoveryDependencies` in `package_index.json`, using the following directive in the `platform.txt`:
465
+
466
+
```
467
+
discovery.DISCOVERY_ID.pattern=DISCOVERY_RECIPE
468
+
```
363
469
364
-
If a platform requires the builtin discoveries it must declare the usage with:
470
+
`DISCOVERY_ID` must be replaced by a unique identifier for the particular discovery and `DISCOVERY_RECIPE`must be replaced by the command line to launch the discovery. An example could be:
For backward compatibility, if a platform does not declare any discovery (using the `discovery.*` properties in `platform.txt`) it will automatically use all the builtin discoveries. This will allow all legacy platforms to softly migrate to pluggable discovery.
477
+
in this case the platform provides a new `teensy` discovery and the command line tool named `teensy_ports` is launched with the `-J2` parameter to start the discovery tool. In this case the command line pattern may contain any extra parameter in the formula: this is different from the discoveries installed through the `discoveryDependencies` field that are run automatically without any command line parameter.
478
+
479
+
This kind of integration may turn out useful:
480
+
481
+
- during the development of a platform (because providing a full `package_index.json` may be cumbersome)
482
+
- if the discovery is specific for a platform and can not be used by 3rd party
483
+
484
+
Anyway, since this kind of integration does not allow reusing a discovery between different platforms, we do not recommend its use.
372
485
373
-
#### Duplicate discoveries
486
+
#### built-in discoveries and backward compatibliity considerations
487
+
488
+
Some discoveries like the Arduino `serial-discovery` or the Arduino `network-discovery` must be always available, so they will be part of the `builtin` package and installed without the need to be part of a real package (`builtin` is a dummy package that we use to install tools that are not part of any platforms like `ctags` for example).
489
+
490
+
If a platform requires the builtin discoveries it must declare it with:
491
+
492
+
```
493
+
discovery.required.0=builtin:serial_discovery
494
+
discovery.required.1=builtin:network_discovery
495
+
```
374
496
375
-
It may happen that different 3rd party platforms provides the same discovery or different versions of the same discovery or, worse, different version of the same discovery launched with different parameters.
497
+
For backward compatibility, if a platform does not declare any discovery (using the `discovery.*` properties in `platform.txt`) it will automatically inherits all the builtin discoveries. This will allow all legacy non-pluggable platforms to migrate to pluggable discovery without disruption.
376
498
377
-
We can partially handle this if the `DISCOVERY_ID` field in `platform.txt` is well defined: from the CLI we could group together the platforms that requires the same discovery and launch the latest version available just once. How the different 3rd party will agree on the `DISCOVERY_ID` value population is TBD.
499
+
#### Conflicting discoveries
378
500
379
-
In case different discoveries provide conflicting information (for example if two discoveries provide different information for the same port address) we could partially mitigate the issue by giving priority to the discovery that is used by the package of the selected board.
501
+
In case different discoveries provide conflicting information (for example if two discoveries provide different information for the same port) we could partially mitigate the issue by giving priority to the discovery that is used by the package of the selected board.
0 commit comments