Here you can find a list of migration guides to handle breaking changes, deprecations, and bugfixes that may cause problems between releases of the CLI.
The build cache path specified with compile --build-cache-path or build_cache.path now affects also sketches.
Previously the specified build cache path only affected cores and it was ignored for sketches. This is now fixed and both cores and sketches are cached in the given directory.
Previously if a build path was specified a cached core could have been used from the global build cache path resulting in a partial build inside the given build path.
Now if a build path is specified, the global build cache path is ignored and the full build is done in the given build path.
The change above, makes the compile --build-cache-path flag useless. It is kept just for backward compatibility.
Previously the build_cache.path was in $TMP/arduino. Now it has been moved to the specific OS user's cache folder,
for example in Linux it happens to be $HOME/.cache/arduino.
Now compiled cores are cached under the cores subdir of the path specified in --build-cache-path, previously it was
saved under the core subdir. The new behaviour is coherent with the default cache directory /tmp/arduino/cores/...
when the cache directory is not set by the user.
The Arduino CLI configuration file now supports only the YAML format.
The Settings API has been heavily refactored. Here a quick recap of the new methods:
-
SettingsGetValuereturns the value of a setting given the key. The returned value is a string encoded in JSON, or YAMLmessage SettingsGetValueRequest { // The key to get string key = 1; // The format of the encoded_value (default is // "json", allowed values are "json" and "yaml) string value_format = 2; } message SettingsGetValueResponse { // The value of the key (encoded) string encoded_value = 1; }
-
SettingsSetValuechange the value of a setting. The value may be specified in JSON, YAML, or as a command-line argument. Ifencoded_valueis an empty string the setting is deleted.message SettingsSetValueRequest { // The key to change string key = 1; // The new value (encoded), no objects, // only scalar, or array of scalars are // allowed. string encoded_value = 2; // The format of the encoded_value (default is // "json", allowed values are "json", "yaml", // and "cli") string value_format = 3; }
-
SettingsEnumeratereturns all the available keys and their type (string,int,[]string...) -
ConfigurationOpenreplaces the current configuration with the one passed as argument. Differently fromSettingsSetValue, this call replaces the whole configuration. -
ConfigurationSaveoutputs the current configuration in the specified format. The configuration is not saved in a file, this call returns just the content, it's a duty of the caller to store the content in a file. -
ConfigurationGetreturn the current configuration in a structured gRPC messageConfiguration.
The previous gRPC Setting rpc call may be replaced as follows:
- The old
SettingsMergerpc call can now be done troughSettingsSetValue. - The old
SettingsDeleterpc call can now be done troughSettingsSetValuepassing thekeyto delete with an emptyvalue. - The old
SettingsGetAllrpc call has been replaced byConfigurationGetthat returns a structured messageConfigurationwith all the settings populated. - The old
SettingsWriterpc call has been removed. It is partially replaced byConfigurationSavebut the actual file save must be performed by the caller.
Previously the methods implementing the Arduino business logic were available in the global namespace
github.com/arduino/arduino-cli/commands/* and could be called directly.
The above is no more true. All the global commands.* functions have been converted to methods of the
arduinoCoreServerImpl struct that implements the gRPC ArduinoCoreServer interface. The configuration is now part of
the server internal state. Developers may create a "daemon-less" server by calling the commands.NewArduinoCoreServer()
function and can use the returned object to call all the needed gRPC functions.
The methods of the ArduinoCoreServer are generated through the gRPC protobuf definitions, some of those methods are
gRPC "streaming" methods and requires a streaming object to be passed as argument, we provided helper methods to create
these objects.
For example if previously we could call commands.Init like this:
// old Init signature
func Init(req *rpc.InitRequest, responseCallback func(r *rpc.InitResponse)) error { ... }
// ...
// Initialize instance
if err := commands.Init(&rpc.InitRequest{Instance: req.GetInstance()}, respCB); err != nil {
return err
}now the responseCallback must be wrapped into an rpc.ArduinoCoreService_InitServer, and we provided a method exactly
for that:
// new Init method
func (s *arduinoCoreServerImpl) Init(req *rpc.InitRequest, stream rpc.ArduinoCoreService_InitServer) error { ... }
/// ...
// Initialize instance
initStream := InitStreamResponseToCallbackFunction(ctx, respCB)
if err := srv.Init(&rpc.InitRequest{Instance: req.GetInstance()}, initStream); err != nil {
return err
}Each gRPC method has an helper method to obtain the corresponding ArduinoCoreService_*Server parameter. Here a simple,
but complete, example:
package main
import (
"context"
"fmt"
"io"
"log"
"github.com/arduino/arduino-cli/commands"
rpc "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1"
"github.com/sirupsen/logrus"
)
func main() {
// Create a new ArduinoCoreServer
srv := commands.NewArduinoCoreServer()
// Disable logging
logrus.SetOutput(io.Discard)
// Create a new instance in the server
ctx := context.Background()
resp, err := srv.Create(ctx, &rpc.CreateRequest{})
if err != nil {
log.Fatal("Error creating instance:", err)
}
instance := resp.GetInstance()
// Defer the destruction of the instance
defer func() {
if _, err := srv.Destroy(ctx, &rpc.DestroyRequest{Instance: instance}); err != nil {
log.Fatal("Error destroying instance:", err)
}
fmt.Println("Instance successfully destroyed")
}()
// Initialize the instance
initStream := commands.InitStreamResponseToCallbackFunction(ctx, func(r *rpc.InitResponse) error {
fmt.Println("INIT> ", r)
return nil
})
if err := srv.Init(&rpc.InitRequest{Instance: instance}, initStream); err != nil {
log.Fatal("Error during initialization:", err)
}
// Search for platforms and output the result
searchResp, err := srv.PlatformSearch(ctx, &rpc.PlatformSearchRequest{Instance: instance})
if err != nil {
log.Fatal("Error searching for platforms:", err)
}
for _, platformSummary := range searchResp.GetSearchOutput() {
installed := platformSummary.GetInstalledRelease()
meta := platformSummary.GetMetadata()
fmt.Printf("%30s %8s %s\n", meta.GetId(), installed.GetVersion(), installed.GetName())
}
}The yaml option of the --format flag is no more supported. Use --format json if machine parsable output is needed.
gRPC: The type field has been renamed to types in the cc.arduino.cli.commands.v1.PlatformRelease message.
Rebuilding the gRPC bindings from the proto files requires to rename all access to type field as types.
By the way, the wire protocol is not affected by this change, existing clients should work fine without modification.
Since the type field may contain multiple values has been renamed to types to better express this aspect.
Previously:
$ arduino-cli core list --json | jq '.platforms[4].releases."1.8.13"'
{
"name": "Arduino SAMD (32-bits ARM Cortex-M0+) Boards",
"version": "1.8.13",
"type": [
"Arduino"
],
...
Now:
$ arduino-cli core list --json | jq '.platforms[4].releases."1.8.13"'
{
"name": "Arduino SAMD (32-bits ARM Cortex-M0+) Boards",
"version": "1.8.13",
"types": [
"Arduino"
],
...
Previously the field export_binaries was a google.protobuf.BoolValue. We used this type because it expresses this
field's optional nature (that is, it could be true, false, and null if not set).
Now the field is an optional bool, since the latest protobuf protocol changes now allows optional fields.
The following responses message:
cc.arduino.cli.commands.v1.PlatformInstallResponsecc.arduino.cli.commands.v1.PlatformDownloadResponsecc.arduino.cli.commands.v1.PlatformUninstallResponsecc.arduino.cli.commands.v1.PlatformUpgradeResponsecc.arduino.cli.commands.v1.DebugResponsecc.arduino.cli.commands.v1.LibraryDownloadResponsecc.arduino.cli.commands.v1.LibraryInstallResponsecc.arduino.cli.commands.v1.LibraryUpgradeResponsecc.arduino.cli.commands.v1.LibraryUninstallResponsecc.arduino.cli.commands.v1.LibraryUpgradeAllResponsecc.arduino.cli.commands.v1.ZipLibraryInstallResponsecc.arduino.cli.commands.v1.GitLibraryInstallResponsecc.arduino.cli.commands.v1.MonitorResponse
now use the oneof clause to make the stream nature of the message more explicit. Just to give an example, the
PlatformInstallResponse message has been changed from:
message PlatformInstallResponse {
// Progress of the downloads of the platform and tool files.
DownloadProgress progress = 1;
// Description of the current stage of the installation.
TaskProgress task_progress = 2;
}to:
message PlatformInstallResponse {
message Result {
// Empty message, reserved for future expansion.
}
oneof message {
// Progress of the downloads of the platform and tool files.
DownloadProgress progress = 1;
// Description of the current stage of the installation.
TaskProgress task_progress = 2;
// The installation result.
Result result = 3;
}
}The other messages have been changed in a similar way.
The gRPC cc.arduino.cli.commands.v1.UpdateIndexResponse and UpdateLibrariesIndexResponse have changed.
The responses coming from the update index commands:
message UpdateIndexResponse {
// Progress of the package index download.
DownloadProgress download_progress = 1;
}
message UpdateLibrariesIndexResponse {
// Progress of the libraries index download.
DownloadProgress download_progress = 1;
}are now more explicit and contains details about the result of the operation:
message UpdateIndexResponse {
message Result {
// The result of the packages index update.
repeated IndexUpdateReport updated_indexes = 1;
}
oneof message {
// Progress of the package index download.
DownloadProgress download_progress = 1;
// The result of the index update.
Result result = 2;
}
}
message UpdateLibrariesIndexResponse {
message Result {
// The result of the libraries index update.
IndexUpdateReport libraries_index = 1;
}
oneof message {
// Progress of the libraries index download.
DownloadProgress download_progress = 1;
// The result of the index update.
Result result = 2;
}
}The IndexUpdateReport message contains details for each index update operation performed:
message IndexUpdateReport {
enum Status {
// The status of the index update is unspecified.
STATUS_UNSPECIFIED = 0;
// The index has been successfully updated.
STATUS_UPDATED = 1;
// The index was already up to date.
STATUS_ALREADY_UP_TO_DATE = 2;
// The index update failed.
STATUS_FAILED = 3;
// The index update was skipped.
STATUS_SKIPPED = 4;
}
// The URL of the index that was updated.
string index_url = 1;
// The result of the index update.
Status status = 2;
}The message Profile has been replaced with SketchProfile in the InitResponse.profile field:
message InitResponse {
oneof message {
Progress init_progress = 1;
google.rpc.Status error = 2;
// Selected profile information
SketchProfile profile = 3;
}
}Previously the LoadSketchResponse containted all the information about the sketch:
message LoadSketchResponse {
string main_file = 1;
string location_path = 2;
repeated string other_sketch_files = 3;
repeated string additional_files = 4;
repeated string root_folder_files = 5;
string default_fqbn = 6;
string default_port = 7;
string default_protocol = 8;
repeated SketchProfile profiles = 9;
SketchProfile default_profile = 10;
}Now all the metadata have been moved into a specific Sketch message:
message LoadSketchResponse {
Sketch sketch = 1;
}
message Sketch {
string main_file = 1;
string location_path = 2;
repeated string other_sketch_files = 3;
repeated string additional_files = 4;
repeated string root_folder_files = 5;
string default_fqbn = 6;
string default_port = 7;
string default_protocol = 8;
repeated SketchProfile profiles = 9;
SketchProfile default_profile = 10;
}We're dropping the builtin.tools support. It was the equivalent of Arduino IDE 1.x bundled tools directory.
Previously the MonitorRequest was a single message used to open the monitor, to stream data, and to change the port
configuration:
message MonitorRequest {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Port to open, must be filled only on the first request
Port port = 2;
// The board FQBN we are trying to connect to. This is optional, and it's
// needed to disambiguate if more than one platform provides the pluggable
// monitor for a given port protocol.
string fqbn = 3;
// Data to send to the port
bytes tx_data = 4;
// Port configuration, optional, contains settings of the port to be applied
MonitorPortConfiguration port_configuration = 5;
}Now the meaning of the fields has been clarified with the oneof clause, making it more explicit:
message MonitorRequest {
oneof message {
// Open request, it must be the first incoming message
MonitorPortOpenRequest open_request = 1;
// Data to send to the port
bytes tx_data = 2;
// Port configuration, contains settings of the port to be changed
MonitorPortConfiguration updated_configuration = 3;
// Close message, set to true to gracefully close a port (this ensure
// that the gRPC streaming call is closed by the daemon AFTER the port
// has been successfully closed)
bool close = 4;
}
}
message MonitorPortOpenRequest {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Port to open, must be filled only on the first request
Port port = 2;
// The board FQBN we are trying to connect to. This is optional, and it's
// needed to disambiguate if more than one platform provides the pluggable
// monitor for a given port protocol.
string fqbn = 3;
// Port configuration, optional, contains settings of the port to be applied
MonitorPortConfiguration port_configuration = 4;
}Now the message field MonitorPortOpenRequest.open_request must be sent in the first message after opening the
streaming gRPC call.
The identification number of the fields has been changed, this change is not binary compatible with old clients.
The following golang modules are no longer available as public API:
github.com/arduino/arduino-cli/arduinogithub.com/arduino/arduino-cli/buildcachegithub.com/arduino/arduino-cli/client_examplegithub.com/arduino/arduino-cli/configurationgithub.com/arduino/arduino-cli/docsgengithub.com/arduino/arduino-cli/executilsgithub.com/arduino/arduino-cli/i18ngithub.com/arduino/arduino-cli/table
Most of the executils library has been integrated inside the go-paths library github.com/arduino/go-paths-helper.
The other packages are not intended for usage outside the Arduino CLI, we will keep them internal to allow future
breaking changes as needed.
-
arduino-cli lib list --format jsonresults are now wrapped underinstalled_librarieskey{ "installed_libraries": [ {...}, {...} ] } -
arduino-cli lib examples --format jsonresults are now wrapped underexampleskey{ "examples": [ {...}, {...} ] } -
arduino-cli core search --format jsonandarduino-cli core list --format jsonresults are now wrapped underplatformskey{ "platforms": [ {...}, {...} ] } -
arduino-cli config init --format jsonnow correctly returns a json object containg the config path{ "config_path": "/home/user/.arduino15/arduino-cli.yaml" } -
arduino-cli config dump --format jsonresults are now wrapped underconfigkey{ "config": { ... } } -
arduino-cli board search --format jsonresults are now wrapped underboardskey{ "boards": [ {...}, {...} ] } -
arduino-cli board list --format jsonresults are now wrapped underdetected_portskey{ "detected_ports": [ {...}, {...} ] } -
arduino-cli sketch newnow correctly returns a json object containing the sketch path{ "sketch_path": "/tmp/my_sketch" }
Previously, the config dump CLI command returned the effective configuration, including both the values explicitly set
via the configuration file and environment variables as well as the values provided by defaults.
It now only returns the explicitly set configuration data.
Use config get <configuration key> to get the effective value of the configuration
The CompilerResponse message has been refactored to made explicit which fields are intended for streaming the build
process and which fields are part of the build result.
The old CompilerResponse:
message CompileResponse {
// The output of the compilation process (stream)
bytes out_stream = 1;
// The error output of the compilation process (stream)
bytes err_stream = 2;
// The compiler build path
string build_path = 3;
// The libraries used in the build
repeated Library used_libraries = 4;
// The size of the executable split by sections
repeated ExecutableSectionSize executable_sections_size = 5;
// The platform where the board is defined
InstalledPlatformReference board_platform = 6;
// The platform used for the build (if referenced from the board platform)
InstalledPlatformReference build_platform = 7;
// Completions reports of the compilation process (stream)
TaskProgress progress = 8;
// Build properties used for compiling
repeated string build_properties = 9;
// Compiler errors and warnings
repeated CompileDiagnostic diagnostics = 10;
}
has been split into a CompilerResponse and a BuilderResult:
message CompileResponse {
oneof message {
// The output of the compilation process (stream)
bytes out_stream = 1;
// The error output of the compilation process (stream)
bytes err_stream = 2;
// Completions reports of the compilation process (stream)
TaskProgress progress = 3;
// The compilation result
BuilderResult result = 4;
}
}
message BuilderResult {
// The compiler build path
string build_path = 1;
// The libraries used in the build
repeated Library used_libraries = 2;
// The size of the executable split by sections
repeated ExecutableSectionSize executable_sections_size = 3;
// The platform where the board is defined
InstalledPlatformReference board_platform = 4;
// The platform used for the build (if referenced from the board platform)
InstalledPlatformReference build_platform = 5;
// Build properties used for compiling
repeated string build_properties = 7;
// Compiler errors and warnings
repeated CompileDiagnostic diagnostics = 8;
}
with a clear distinction on which fields are streamed.
The gRPC response cc.arduino.cli.commands.v1.UploadUsingProgrammerResponse and cc.arduino.cli.commands.v1.BurnBootloaderResponse has been changed.
The old messages:
message UploadUsingProgrammerResponse {
// The output of the upload process.
bytes out_stream = 1;
// The error output of the upload process.
bytes err_stream = 2;
}
message BurnBootloaderResponse {
// The output of the burn bootloader process.
bytes out_stream = 1;
// The error output of the burn bootloader process.
bytes err_stream = 2;
}
now have the oneof clause that makes explicit the streaming nature of the response:
message UploadUsingProgrammerResponse {
oneof message {
// The output of the upload process.
bytes out_stream = 1;
// The error output of the upload process.
bytes err_stream = 2;
}
}
message BurnBootloaderResponse {
oneof message {
// The output of the burn bootloader process.
bytes out_stream = 1;
// The error output of the burn bootloader process.
bytes err_stream = 2;
}
}
We've added a new field called compatible. This field indicates if the current platform release is installable or not.
It may happen that a platform doesn't have a dependency available for an OS/ARCH, in such cases, if we try to install
the platform it will fail. The new field can be used to know upfront if a specific release is installable.
We've modified the behavior of latest_version. Now this field indicates the latest version that can be installed in
the current OS/ARCH.
Previously, we showed the latest version without checking if all the dependencies were available in the current OS/ARCH. Now, the latest version will always point to an installable one even if a newer incompatible one is present.
We now show in the version column the latest installable version. If none are available then we show a n/a label.
The corresponding command with --format json now returns the same output of
arduino-cli core search --all --format json.
Previously, we'd have tried the installation/upgrade of a core even if all the required tools weren't available in the
current OS/ARCH. Now we check this upfront, and allowing the installation of incompatible versions only if a user
explicitly provides it like: core install arduino:renesas_uno@1.0.2
gRPC service cc.arduino.cli.settings.v1 has been removed, and all RPC calls have been migrated to cc.arduino.cli.commands.v1
The service cc.arduino.cli.settings.v1 no longer exists and all existing RPC calls have been moved to the
cc.arduino.cli.commands.v1 service adding a Settings prefix to the names of all messages. The existing RPC calls:
rpc GetAll(GetAllRequest) returns (GetAllResponse)rpc Merge(MergeRequest) returns (MergeResponse)rpc GetValue(GetValueRequest) returns (GetValueResponse)rpc SetValue(SetValueRequest) returns (SetValueResponse)rpc Write(WriteRequest) returns (WriteResponse)rpc Delete(DeleteRequest) returns (DeleteResponse)
are now renamed to:
rpc SettingsGetAll(SettingsGetAllRequest) returns (SettingsGetAllResponse)rpc SettingsMerge(SettingsMergeRequest) returns (SettingsMergeResponse)rpc SettingsGetValue(SettingsGetValueRequest) returns (SettingsGetValueResponse)rpc SettingsSetValue(SettingsSetValueRequest) returns (SettingsSetValueResponse)rpc SettingsWrite(SettingsWriteRequest) returns (SettingsWriteResponse)rpc SettingsDelete(SettingsDeleteRequest) returns (SettingsDeleteResponse)
The query field has been removed, use search_args instead.
Below is an example of the response containing an object with all possible keys set.
[
{
"id": "arduino:avr",
"maintainer": "Arduino",
"website": "http://www.arduino.cc/",
"email": "packages@arduino.cc",
"indexed": true,
"manually_installed": true,
"deprecated": true,
"releases": {
"1.6.2": {
"name": "Arduino AVR Boards",
"version": "1.6.2",
"type": [
"Arduino"
],
"installed": true,
"boards": [
{
"name": "Arduino Robot Motor"
}
],
"help": {
"online": "http://www.arduino.cc/en/Reference/HomePage"
},
"missing_metadata": true,
"deprecated": true
},
"1.8.3": { ... }
},
"installed_version": "1.6.2",
"latest_version": "1.8.3"
}
]The old behavior was a bit misleading to the client because, to list all the available versions for each platform, we
used to use the latest as it was describing the current platform version. We introduced a new message:
PlatformSummary, with the intent to make the response more straightforward and less error-prone.
message PlatformSearchResponse {
// Results of the search.
repeated PlatformSummary search_output = 1;
}
// PlatformSummary is a structure containing all the information about
// a platform and all its available releases.
message PlatformSummary {
// Generic information about a platform
PlatformMetadata metadata = 1;
// Maps version to the corresponding PlatformRelease
map<string, PlatformRelease> releases = 2;
// The installed version of the platform, or empty string if none installed
string installed_version = 3;
// The latest available version of the platform, or empty if none available
string latest_version = 4;
}The new response contains an array of PlatformSummary. PlatformSummary contains all the information about a platform
and all its available releases. Releases contain all the PlatformReleases of a specific platform, and the key is the
semver string of a specific version. We've added the installed_version and latest_version to make more convenient
the access of such values in the map. A few notes about the behavior of the releases map:
- It can be empty if no releases are found
- It can contain a single-release
- It can contain multiple releases
- If in the request we provide the
manually_installed=true, the key of such release is an empty string.
Removed gRPC API: cc.arduino.cli.commands.v1.PlatformList, PlatformListRequest, and PlatformListResponse.
The following gRPC API have been removed:
cc.arduino.cli.commands.v1.PlatformList: you can use the already available gRPC methodPlatformSearchto perform the same task. Setting theall_versions=trueandmanually_installed=truein thePlatformSearchRequestreturns all the data needed to produce the same result of the old api.cc.arduino.cli.commands.v1.PlatformListRequest.cc.arduino.cli.commands.v1.PlatformListResponse.
The old Platform and other information such as name, website, and email... contained details about the currently
installed version and the latest available. We noticed an ambiguous use of the latest field, especially when such a
message came in the PlatformSearchResponse response. In that use case, the latest field contained the specific version
of a particular platform: this is a hack because the value doesn't always reflect the meaning of that property. Another
inconsistent case occurs when a platform maintainer changes the name of a particular release. We always pick the value
from the latest release, but this might not be what we want to do all the time. We concluded that the design of that
message isn't something to be considered future-proof proof, so we decided to modify it as follows:
// Platform is a structure containing all the information about a single
// platform release.
message Platform {
// Generic information about a platform
PlatformMetadata metadata = 1;
// Information about a specific release of a platform
PlatformRelease release = 2;
}
// PlatformMetadata contains generic information about a platform (not
// correlated to a specific release).
message PlatformMetadata {
// Platform ID (e.g., `arduino:avr`).
string id = 1;
// Maintainer of the platform's package.
string maintainer = 2;
// A URL provided by the author of the platform's package, intended to point
// to their website.
string website = 3;
// Email of the maintainer of the platform's package.
string email = 4;
// If true this Platform has been installed manually in the user' sketchbook
// hardware folder
bool manually_installed = 5;
// True if the latest release of this Platform has been deprecated
bool deprecated = 6;
// If true the platform is indexed
bool indexed = 7;
}
// PlatformRelease contains information about a specific release of a platform.
message PlatformRelease {
// Name used to identify the platform to humans (e.g., "Arduino AVR Boards").
string name = 1;
// Version of the platform release
string version = 5;
// Type of the platform.
repeated string type = 6;
// True if the platform is installed
bool installed = 7;
// List of boards provided by the platform. If the platform is installed,
// this is the boards listed in the platform's boards.txt. If the platform is
// not installed, this is an arbitrary list of board names provided by the
// platform author for display and may not match boards.txt.
repeated Board boards = 8;
// A URL provided by the author of the platform's package, intended to point
// to their online help service.
HelpResources help = 9;
// This field is true if the platform is missing installation metadata (this
// happens if the platform has been installed with the legacy Arduino IDE
// <=1.8.x). If the platform miss metadata and it's not indexed through a
// package index, it may fail to work correctly in some circumstances, and it
// may need to be reinstalled. This should be evaluated only when the
// PlatformRelease is `Installed` otherwise is an undefined behaviour.
bool missing_metadata = 10;
// True this release is deprecated
bool deprecated = 11;
}To address all the inconsistencies/inaccuracies we introduced two messages:
PlatformMetadatacontains generic information about a platform (not correlated to a specific release).PlatformReleasecontains information about a specific release of a platform.
debugging_supported field has been removed from gRPC cc.arduino.cli.commands.v1.BoardDetails and board details command in CLI
The debugging_supported field has been removed, since the possibility to debug is determined by:
- the board selected
- the board option selected
- the programmer selected
the board details command has no sufficient information to determine it. If you need to determine if a specific
selection of board + option + programmer supports debugging, use the gRPC call
cc.arduino.cli.commands.v1.GetDebugConfig: if the call is successful, it means that the debugging is supported.
The string field server_configuration.script is now an array and has been renamed scripts, here an example:
{
"executable": "/tmp/arduino/sketches/002050EAA7EFB9A4FC451CDFBC0FA2D3/Blink.ino.elf",
"toolchain": "gcc",
"toolchain_path": "/home/user/.arduino15/packages/arduino/tools/arm-none-eabi-gcc/7-2017q4/bin/",
"toolchain_prefix": "arm-none-eabi",
"server": "openocd",
"server_path": "/home/user/.arduino15/packages/arduino/tools/openocd/0.10.0-arduino7/bin/openocd",
"server_configuration": {
"path": "/home/user/.arduino15/packages/arduino/tools/openocd/0.10.0-arduino7/bin/openocd",
"scripts_dir": "/home/user/.arduino15/packages/arduino/tools/openocd/0.10.0-arduino7/share/openocd/scripts/",
"scripts": [
"/home/user/Workspace/arduino-cli/internal/integrationtest/debug/testdata/hardware/my/samd/variants/arduino:mkr1000/openocd_scripts/arduino_zero.cfg"
]
}
}The fields toolchain_configuration and server_configuration are no more generic map<string, string> but they have
changed type to goog.protobuf.Any, the concrete type is assigned at runtime based on the value of toolchain and
server fields respectively.
For the moment:
- only
gccis supported fortoolchain, and the concrete type fortoolchain_configurationisDebugGCCToolchainConfiguration. - only
openocdis supported forserver, and the concrete type forserver_configurationisDebugOpenOCDServerConfiguration
More concrete type may be added in the future as more servers/toolchains support is implemented.
The gRPC service cc.arduino.cli.debug.v1 has been removed and all gRPC messages and rpc calls have been moved to
cc.arduino.cli.commands.v1.
The gRPC message DebugConfigRequest has been renamed to the proper GetDebugConfigRequest.
All the generated API has been updated as well.
The gRPC message BoardListWatchRequest has been changed from:
message BoardListWatchRequest {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
// Set this to true to stop the discovery process
bool interrupt = 2;
}
to
message BoardListWatchRequest {
// Arduino Core Service instance from the `Init` response.
Instance instance = 1;
}
rpc BoardListWatch(BoardListWatchRequest)
returns (stream BoardListWatchResponse);
Previously the UploadResponse was used only to stream the tool output:
message UploadResponse {
// The output of the upload process.
bytes out_stream = 1;
// The error output of the upload process.
bytes err_stream = 2;
}
Now the API logic has been clarified using the oneof clause and another field has been added providing an
UploadResult message that is sent when a successful upload completes.
message UploadResponse {
oneof message {
// The output of the upload process.
bytes out_stream = 1;
// The error output of the upload process.
bytes err_stream = 2;
// The upload result
UploadResult result = 3;
}
}
message UploadResult {
// When a board requires a port disconnection to perform the upload, this
// field returns the port where the board reconnects after the upload.
Port updated_upload_port = 1;
}
The Upload method signature has been changed from:
func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) error { ... }to:
func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) (*rpc.UploadResult, error) { ... }Now an UploadResult structure is returned together with the error. If you are not interested in the information
contained in the structure you can safely ignore it.
The package inventory is no more a public golang API.
board list --watch command JSON output changed from:
{
"type": "add",
"address": "COM3",
"label": "COM3",
"protocol": "serial",
"protocol_label": "Serial Port (USB)",
"hardwareId": "93B0245008567CB2",
"properties": {
"pid": "0x005E",
"serialNumber": "93B0245008567CB2",
"vid": "0x2341"
},
"boards": [
{
"name": "Arduino Nano RP2040 Connect",
"fqbn": "arduino:mbed_nano:nanorp2040connect"
}
]
}
to:
{
"eventType": "add",
"matching_boards": [
{
"name": "Arduino Nano RP2040 Connect",
"fqbn": "arduino:mbed_nano:nanorp2040connect"
}
],
"port": {
"address": "COM3",
"label": "COM3",
"protocol": "serial",
"protocol_label": "Serial Port (USB)",
"properties": {
"pid": "0x005E",
"serialNumber": "93B0245008567CB2",
"vid": "0x2341"
},
"hardware_id": "93B0245008567CB2"
}
}
Sketch name specifications have been updated to achieve cross-platform compatibility.
Existing sketch names violating the new constraint need to be updated.
The function github.com/arduino/arduino-cli/commands.LoadSketch has been moved to package
github.com/arduino/arduino-cli/commands/sketch.LoadSketch. You must change the import accordingly.
The gRPC cc.arduino.cli.commands.v1.Compile command now return expanded build_properties by default. If you want the
unexpanded build_properties you must set to true the field do_not_expand_build_properties in the
CompileRequest.
The command compile --show-properties now returns the expanded build properties, with the variable placeholders
replaced with their current value. If you need the unexpanded build properties you must change the command line to
compile --show-properties=unexpanded.
Before:
$ arduino-cli board details -b arduino:avr:uno --show-properties | grep ^tools.avrdude.path
tools.avrdude.path={runtime.tools.avrdude.path}
Now:
$ arduino-cli board details -b arduino:avr:uno --show-properties | grep ^tools.avrdude.path
tools.avrdude.path=/home/megabug/.arduino15/packages/arduino/tools/avrdude/6.3.0-arduino17
$ arduino-cli board details -b arduino:avr:uno --show-properties=unexpanded | grep ^tools.avrdude.path
tools.avrdude.path={runtime.tools.avrdude.path}
golang API: method github.com/arduino/arduino-cli/arduino/cores/Board.GetBuildProperties changed signature
The method:
func (b *Board) GetBuildProperties(userConfigs *properties.Map) (*properties.Map, error) { ... }now requires a full FQBN object;
func (b *Board) GetBuildProperties(fqbn *FQBN) (*properties.Map, error) { ... }Existing code may be updated from:
b.GetBuildProperties(fqbn.Configs)to
b.GetBuildProperties(fqbn)
Configuration file lookup in current working directory and its parents is dropped. The command line flag --config-file
must be specified to use an alternative configuration file from the one in the data directory.
For text format (default), the command prints now a single table for platforms and libraries instead of two separate
tables.
Similarly, for JSON and YAML formats, the command prints now a single valid object, with platform and libraries
top-level keys. For example, for JSON output:
$ arduino-cli outdated --format json
{
"platforms": [
{
"id": "arduino:avr",
"installed": "1.6.3",
"latest": "1.8.6",
"name": "Arduino AVR Boards",
...
}
],
"libraries": [
{
"library": {
"name": "USBHost",
"author": "Arduino",
"maintainer": "Arduino \u003cinfo@arduino.cc\u003e",
"category": "Device Control",
"version": "1.0.0",
...
},
"release": {
"author": "Arduino",
"version": "1.0.5",
"maintainer": "Arduino \u003cinfo@arduino.cc\u003e",
"category": "Device Control",
...
}
}
]
}
It was a legacy and undocumented feature that is now useless. The corresponding field in gRPC CompileRequest.vid_pid
has been removed as well.
golang API: method github.com/arduino/arduino-cli/arduino/libraries/Library.LocationPriorityFor removed
That method was outdated and must not be used.
The following method in github.com/arduino/arduino-cli/commands/core:
func GetPlatforms(req *rpc.PlatformListRequest) ([]*rpc.Platform, error) { ... }has been changed to:
func PlatformList(req *rpc.PlatformListRequest) (*rpc.PlatformListResponse, error) { ... }now it better follows the gRPC API interface. Old code like the following:
platforms, _ := core.GetPlatforms(&rpc.PlatformListRequest{Instance: inst})
for _, i := range platforms {
...
}must be changed as follows:
// Use PlatformList function instead of GetPlatforms
platforms, _ := core.PlatformList(&rpc.PlatformListRequest{Instance: inst})
// Access installed platforms through the .InstalledPlatforms field
for _, i := range platforms.InstalledPlatforms {
...
}The post_install script now runs when a tool is correctly installed and the CLI is in "interactive" mode. This
behavior can be configured.
golang API: methods in github.com/arduino/arduino-cli/arduino/cores/packagemanager changed signature
The following methods in github.com/arduino/arduino-cli/arduino/cores/packagemanager:
func (pme *Explorer) InstallTool(toolRelease *cores.ToolRelease, taskCB rpc.TaskProgressCB) error { ... }
func (pme *Explorer) RunPostInstallScript(platformRelease *cores.PlatformRelease) error { ... }have changed. InstallTool requires the new skipPostInstall parameter, which must be set to true to skip the post
install script. RunPostInstallScript does not require a *cores.PlatformRelease parameter but requires a
*paths.Path parameter:
func (pme *Explorer) InstallTool(toolRelease *cores.ToolRelease, taskCB rpc.TaskProgressCB, skipPostInstall bool) error {...}
func (pme *Explorer) RunPostInstallScript(installDir *paths.Path) error { ... }The sketch name submitted via the sketch new command of the CLI or the gRPC command
cc.arduino.cli.commands.v1.NewSketch are now validated. The applied rules follow the
sketch specifications.
Existing sketch names violating the new constraint need to be updated.
The daemon CLI command no longer allows to set a custom ip for the gRPC communication. Currently there is not enough
bandwith to support this feature. For this reason, the --ip flag has been removed.
The board attach CLI command has changed behaviour: now it just pick whatever port and FQBN is passed as parameter and
saves it in the sketch.yaml file, without any validity check or board autodetection.
The sketch.json file is now completely ignored.
The cc.arduino.cli.commands.v1.BoardAttach gRPC command has been removed. This feature is no longer available through
gRPC.
The following methods in github.com/arduino/arduino-cli/commands/upload:
func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) (*rpc.UploadResponse, error) { ... }
func UsingProgrammer(ctx context.Context, req *rpc.UploadUsingProgrammerRequest, outStream io.Writer, errStream io.Writer) (*rpc.UploadUsingProgrammerResponse, error) { ... }do not return anymore the response (because it's always empty):
func Upload(ctx context.Context, req *rpc.UploadRequest, outStream io.Writer, errStream io.Writer) error { ... }
func UsingProgrammer(ctx context.Context, req *rpc.UploadUsingProgrammerRequest, outStream io.Writer, errStream io.Writer) error { ... }The following method in github.com/arduino/arduino-cli/commands/compile:
func Compile(ctx context.Context, req *rpc.CompileRequest, outStream, errStream io.Writer, progressCB rpc.TaskProgressCB, debug bool) (r *rpc.CompileResponse, e error) { ... }do not require the debug parameter anymore:
func Compile(ctx context.Context, req *rpc.CompileRequest, outStream, errStream io.Writer, progressCB rpc.TaskProgressCB) (r *rpc.CompileResponse, e error) { ... }The package cli has been made internal. The code in this package is no more public API and can not be directly
imported in other projects.
golang API change in github.com/arduino/arduino-cli/arduino/libraries/librariesmanager.LibrariesManager
The following LibrariesManager.InstallPrerequisiteCheck methods have changed prototype, from:
func (lm *LibrariesManager) InstallPrerequisiteCheck(indexLibrary *librariesindex.Release, installLocation libraries.LibraryLocation) (*paths.Path, *libraries.Library, error) { ... }
func (lm *LibrariesManager) InstallZipLib(ctx context.Context, archivePath string, overwrite bool) error { ... }to
func (lm *LibrariesManager) InstallPrerequisiteCheck(indexLibrary *librariesindex.Release, installLocation libraries.LibraryLocation) (*paths.Path, *libraries.Library, error) { ... }
func (lm *LibrariesManager) InstallZipLib(ctx context.Context, archivePath *paths.Path, overwrite bool) error { ... }InstallPrerequisiteCheck now requires an explicit name and version instead of a librariesindex.Release, because
it can now be used to check any library, not only the libraries available in the index. Also the return value has
changed to a LibraryInstallPlan structure, it contains the same information as before (TargetPath and ReplacedLib)
plus Name, Version, and an UpToDate boolean flag.
InstallZipLib method archivePath is now a paths.Path instead of a string.
The packagemanager.Explorer method FindToolsRequiredForBoard:
func (pme *Explorer) FindToolsRequiredForBoard(board *cores.Board) ([]*cores.ToolRelease, error) { ... }has been renamed to `FindToolsRequiredForBuild:
func (pme *Explorer) FindToolsRequiredForBuild(platform, buildPlatform *cores.PlatformRelease) ([]*cores.ToolRelease, error) { ... }moreover it now requires the platform and the buildPlatform (a.k.a. the referenced platform core used for the
compile) instead of the board. Usually these two value are obtained from the Explorer.ResolveFQBN(...) method.
The following gRPC API have been removed:
cc.arduino.cli.commands.v1.UpdateCoreLibrariesIndex: you can use the already available gRPC methodsUpdateIndexandUpdateLibrariesIndexto perform the same tasks.cc.arduino.cli.commands.v1.Outdated: you can use the already available gRPC methodsPlatformListandLibraryListto perform the same tasks.cc.arduino.cli.commands.v1.Upgrade: you can use the already available gRPC methodsPlatformUpgradeandLibraryUpgradeto perform the same tasks.
The golang API implementation of the same functions has been removed as well, so the following function are no more available:
github.com/arduino/arduino-cli/commands.UpdateCoreLibrariesIndex(...)
github.com/arduino/arduino-cli/commands/outdated.Outdated(...)
github.com/arduino/arduino-cli/commands/upgrade.Upgrade(...)
you can use the following functions as a replacement to do the same tasks:
github.com/arduino/arduino-cli/commands.UpdateLibrariesIndex(...)
github.com/arduino/arduino-cli/commands.UpdateIndex(...)
github.com/arduino/arduino-cli/commands/core.GetPlatforms(...)
github.com/arduino/arduino-cli/commands/lib.LibraryList(...)
github.com/arduino/arduino-cli/commands/lib.LibraryUpgrade(...)
github.com/arduino/arduino-cli/commands/lib.LibraryUpgradeAll(...)
github.com/arduino/arduino-cli/commands/core.PlatformUpgrade(...)
The following functions:
func Init(instance *rpc.Instance) []error { }
func InitWithProfile(instance *rpc.Instance, profileName string, sketchPath *paths.Path) (*rpc.Profile, []error) { }no longer return the errors array:
func Init(instance *rpc.Instance) { }
func InitWithProfile(instance *rpc.Instance, profileName string, sketchPath *paths.Path) *rpc.Profile { }The errors are automatically sent to output via feedback package, as for the other Init* functions.
In the structure github.com/arduino/arduino-cli/arduino/libraries.Library the field:
RealNamehas been renamed toNameNamehas been renamed toDirName
Now Name is the name of the library as it appears in the library.properties file and DirName it's the name of the
directory containing the library. The DirName is usually the name of the library with non-alphanumeric characters
converted to underscore, but it could be actually anything since the directory where the library is installed can be
freely renamed.
This change improves the overall code base naming coherence since all the structures involving libraries have the Name
field that refers to the library name as it appears in the library.properties file.
You must use the name field instead.
The [*].library.real_name field has been removed.
You must use the [*].library.name field instead.
The [*].library.realname field has been removed.
You must use the [*].library.name field instead.
github.com/arduino/arduino-cli/arduino/libraries/librariesmanager.LibrariesManager.Install removed parameter installLocation
The method:
func (lm *LibrariesManager) Install(indexLibrary *librariesindex.Release, libPath *paths.Path, installLocation libraries.LibraryLocation) error { ... }no more needs the installLocation parameter:
func (lm *LibrariesManager) Install(indexLibrary *librariesindex.Release, libPath *paths.Path) error { ... }The install location is determined from the libPath.
github.com/arduino/arduino-cli/arduino/libraries/librariesmanager.LibrariesManager.FindByReference now returns a list of libraries.
The method:
func (lm *LibrariesManager) FindByReference(libRef *librariesindex.Reference, installLocation libraries.LibraryLocation) *libraries.Library { ... }has been changed to:
func (lm *LibrariesManager) FindByReference(libRef *librariesindex.Reference, installLocation libraries.LibraryLocation) libraries.List { ... }the method now returns all the libraries matching the criteria and not just the first one.
The structure librariesmanager.LibraryAlternatives has been removed. The libraries.List object can be used as a
replacement.
The gRPC message cc.arduino.cli.commands.v1.DownloadProgress has been changed from:
message DownloadProgress {
// URL of the download.
string url = 1;
// The file being downloaded.
string file = 2;
// Total size of the file being downloaded.
int64 total_size = 3;
// Size of the downloaded portion of the file.
int64 downloaded = 4;
// Whether the download is complete.
bool completed = 5;
}
to
message DownloadProgress {
oneof message {
DownloadProgressStart start = 1;
DownloadProgressUpdate update = 2;
DownloadProgressEnd end = 3;
}
}
message DownloadProgressStart {
// URL of the download.
string url = 1;
// The label to display on the progress bar.
string label = 2;
}
message DownloadProgressUpdate {
// Size of the downloaded portion of the file.
int64 downloaded = 1;
// Total size of the file being downloaded.
int64 total_size = 2;
}
message DownloadProgressEnd {
// True if the download is successful
bool success = 1;
// Info or error message, depending on the value of 'success'. Some examples:
// "File xxx already downloaded" or "Connection timeout"
string message = 2;
}
The new message format allows a better handling of the progress update reports on downloads. Every download now will report a sequence of message as follows:
DownloadProgressStart{url="https://...", label="Downloading package index..."}
DownloadProgressUpdate{downloaded=0, total_size=103928}
DownloadProgressUpdate{downloaded=29380, total_size=103928}
DownloadProgressUpdate{downloaded=69540, total_size=103928}
DownloadProgressEnd{success=true, message=""}
or if an error occurs:
DownloadProgressStart{url="https://...", label="Downloading package index..."}
DownloadProgressUpdate{downloaded=0, total_size=103928}
DownloadProgressEnd{success=false, message="Server closed connection"}
or if the file is already cached:
DownloadProgressStart{url="https://...", label="Downloading package index..."}
DownloadProgressEnd{success=true, message="Index already downloaded"}
About the go-lang API the following functions in github.com/arduino/arduino-cli/commands:
func UpdateIndex(ctx context.Context, req *rpc.UpdateIndexRequest, downloadCB rpc.DownloadProgressCB) (*rpc.UpdateIndexResponse, error) { ... }have changed their signature to:
func UpdateIndex(ctx context.Context, req *rpc.UpdateIndexRequest, downloadCB rpc.DownloadProgressCB, downloadResultCB rpc.DownloadResultCB) error { ... }UpdateIndex do not return anymore the latest UpdateIndexResponse (beacuse it was always empty).
Breaking changes in golang API github.com/arduino/arduino-cli/arduino/cores/packagemanager.PackageManager
The PackageManager API has been heavily refactored to correctly handle multitasking and concurrency. Many fields in
the PackageManager object are now private. All the PackageManager methods have been moved into other objects. In
particular:
- the methods that query the
PackageManagerwithout changing its internal state, have been moved into the newExplorerobject - the methods that change the
PackageManagerinternal state, have been moved into the newBuilderobject.
The Builder object must be used to create a new PackageManager. Previously the function NewPackageManager was used
to get a clean PackageManager object and then use the LoadHardware* methods to build it. Now the function
NewBuilder must be used to create a Builder, run the LoadHardware* methods to load platforms, and finally call the
Builder.Build() method to obtain the final PackageManager.
Previously we did:
pm := packagemanager.NewPackageManager(...)
err = pm.LoadHardware()
err = pm.LoadHardwareFromDirectories(...)
err = pm.LoadHardwareFromDirectory(...)
err = pm.LoadToolsFromPackageDir(...)
err = pm.LoadToolsFromBundleDirectories(...)
err = pm.LoadToolsFromBundleDirectory(...)
pack = pm.GetOrCreatePackage("packagername")
// ...use `pack` to tweak or load more hardware...
err = pm.LoadPackageIndex(...)
err = pm.LoadPackageIndexFromFile(...)
err = pm.LoadHardwareForProfile(...)
// ...use `pm` to implement business logic...Now we must do:
var pm *packagemanager.PackageManager
{
pmb := packagemanager.Newbuilder(...)
err = pmb.LoadHardware()
err = pmb.LoadHardwareFromDirectories(...)
err = pmb.LoadHardwareFromDirectory(...)
err = pmb.LoadToolsFromPackageDir(...)
err = pmb.LoadToolsFromBundleDirectories(...)
err = pmb.LoadToolsFromBundleDirectory(...)
pack = pmb.GetOrCreatePackage("packagername")
// ...use `pack` to tweak or load more hardware...
err = pmb.LoadPackageIndex(...)
err = pmb.LoadPackageIndexFromFile(...)
err = pmb.LoadHardwareForProfile(...)
pm = pmb.Build()
}
// ...use `pm` to implement business logic...It's not mandatory but highly recommended, to drop the Builder object once it has built the PackageManager (that's
why in the example the pmb builder is created in a limited scope between braces).
To query the PackagerManager now it is required to obtain an Explorer object through the
PackageManager.NewExplorer() method.
Previously we did:
func DoStuff(pm *packagemanager.PackageManager, ...) {
// ...implement business logic through PackageManager methods...
... := pm.Packages
... := pm.CustomGlobalProperties
... := pm.FindPlatform(...)
... := pm.FindPlatformRelease(...)
... := pm.FindPlatformReleaseDependencies(...)
... := pm.DownloadToolRelease(...)
... := pm.DownloadPlatformRelease(...)
... := pm.IdentifyBoard(...)
... := pm.DownloadAndInstallPlatformUpgrades(...)
... := pm.DownloadAndInstallPlatformAndTools(...)
... := pm.InstallPlatform(...)
... := pm.InstallPlatformInDirectory(...)
... := pm.RunPostInstallScript(...)
... := pm.IsManagedPlatformRelease(...)
... := pm.UninstallPlatform(...)
... := pm.InstallTool(...)
... := pm.IsManagedToolRelease(...)
... := pm.UninstallTool(...)
... := pm.IsToolRequired(...)
... := pm.LoadDiscoveries(...)
... := pm.GetProfile(...)
... := pm.GetEnvVarsForSpawnedProcess(...)
... := pm.DiscoveryManager(...)
... := pm.FindPlatformReleaseProvidingBoardsWithVidPid(...)
... := pm.FindBoardsWithVidPid(...)
... := pm.FindBoardsWithID(...)
... := pm.FindBoardWithFQBN(...)
... := pm.ResolveFQBN(...)
... := pm.Package(...)
... := pm.GetInstalledPlatformRelease(...)
... := pm.GetAllInstalledToolsReleases(...)
... := pm.InstalledPlatformReleases(...)
... := pm.InstalledBoards(...)
... := pm.FindToolsRequiredFromPlatformRelease(...)
... := pm.GetTool(...)
... := pm.FindToolsRequiredForBoard(...)
... := pm.FindToolDependency(...)
... := pm.FindDiscoveryDependency(...)
... := pm.FindMonitorDependency(...)
}Now we must obtain the Explorer object to access the same methods, moreover, we must call the release callback
function once we complete the task:
func DoStuff(pm *packagemanager.PackageManager, ...) {
pme, release := pm.NewExplorer()
defer release()
... := pme.GetPackages()
... := pme.GetCustomGlobalProperties()
... := pme.FindPlatform(...)
... := pme.FindPlatformRelease(...)
... := pme.FindPlatformReleaseDependencies(...)
... := pme.DownloadToolRelease(...)
... := pme.DownloadPlatformRelease(...)
... := pme.IdentifyBoard(...)
... := pme.DownloadAndInstallPlatformUpgrades(...)
... := pme.DownloadAndInstallPlatformAndTools(...)
... := pme.InstallPlatform(...)
... := pme.InstallPlatformInDirectory(...)
... := pme.RunPostInstallScript(...)
... := pme.IsManagedPlatformRelease(...)
... := pme.UninstallPlatform(...)
... := pme.InstallTool(...)
... := pme.IsManagedToolRelease(...)
... := pme.UninstallTool(...)
... := pme.IsToolRequired(...)
... := pme.LoadDiscoveries(...)
... := pme.GetProfile(...)
... := pme.GetEnvVarsForSpawnedProcess(...)
... := pme.DiscoveryManager(...)
... := pme.FindPlatformReleaseProvidingBoardsWithVidPid(...)
... := pme.FindBoardsWithVidPid(...)
... := pme.FindBoardsWithID(...)
... := pme.FindBoardWithFQBN(...)
... := pme.ResolveFQBN(...)
... := pme.Package(...)
... := pme.GetInstalledPlatformRelease(...)
... := pme.GetAllInstalledToolsReleases(...)
... := pme.InstalledPlatformReleases(...)
... := pme.InstalledBoards(...)
... := pme.FindToolsRequiredFromPlatformRelease(...)
... := pme.GetTool(...)
... := pme.FindToolsRequiredForBoard(...)
... := pme.FindToolDependency(...)
... := pme.FindDiscoveryDependency(...)
... := pme.FindMonitorDependency(...)
}The Explorer object keeps a read-lock on the underlying PackageManager that must be released once the task is done
by calling the release callback function. This ensures that no other task will change the status of the
PackageManager while the current task is in progress.
The PackageManager.Clean() method has been removed and replaced by the methods:
PackageManager.NewBuilder() (*Builder, commit func())Builder.BuildIntoExistingPackageManager(target *PackageManager)
Previously, to update a PackageManager instance we did:
func Reload(pm *packagemanager.PackageManager) {
pm.Clear()
... = pm.LoadHardware(...)
// ...other pm.Load* calls...
}now we have two options:
func Reload(pm *packagemanager.PackageManager) {
// Create a new builder and build a package manager
pmb := packagemanager.NewBuilder(.../* config params */)
... = pmb.LoadHardware(...)
// ...other pmb.Load* calls...
// apply the changes to the original pm
pmb.BuildIntoExistingPackageManager(pm)
}in this case, we create a new Builder with the given config params and once the package manager is built we apply the
changes atomically with BuildIntoExistingPackageManager. This procedure may be even more simplified with:
func Reload(pm *packagemanager.PackageManager) {
// Create a new builder using the same config params
// as the original package manager
pmb, commit := pm.NewBuilder()
// build the new package manager
... = pmb.LoadHardware(...)
// ...other pmb.Load* calls...
// apply the changes to the original pm
commit()
}In this case, we don't even need to bother to provide the configuration parameters because they are taken from the
previous PackageManager instance.
The following methods in subpackages of github.com/arduino/arduino-cli/commands/*:
func Watch(instanceID int32) (<-chan *rpc.BoardListWatchResponse, func(), error) { ... }
func LibraryUpgradeAll(instanceID int32, downloadCB rpc.DownloadProgressCB, taskCB rpc.TaskProgressCB) error { ... }
func LibraryUpgrade(instanceID int32, libraryNames []string, downloadCB rpc.DownloadProgressCB, taskCB rpc.TaskProgressCB) error { ... }have been changed to:
func Watch(req *rpc.BoardListWatchRequest) (<-chan *rpc.BoardListWatchResponse, func(), error) { ... }
func LibraryUpgradeAll(req *rpc.LibraryUpgradeAllRequest, downloadCB rpc.DownloadProgressCB, taskCB rpc.TaskProgressCB) error { ... }
func LibraryUpgrade(ctx context.Context, req *rpc.LibraryUpgradeRequest, downloadCB rpc.DownloadProgressCB, taskCB rpc.TaskProgressCB) error { ... }The following methods in package github.com/arduino/arduino-cli/commands
func GetInstance(id int32) *CoreInstance { ... }
func GetPackageManager(id int32) *packagemanager.PackageManager { ... }
func GetLibraryManager(instanceID int32) *librariesmanager.LibrariesManager { ... }have been changed to:
func GetPackageManager(instance rpc.InstanceCommand) *packagemanager.PackageManager { ... } // Deprecated
func GetPackageManagerExplorer(req rpc.InstanceCommand) (explorer *packagemanager.Explorer, release func()) { ... }
func GetLibraryManager(req rpc.InstanceCommand) *librariesmanager.LibrariesManager { ... }Old code passing the instanceID inside the gRPC request must be changed to pass directly the whole gRPC request, for
example:
eventsChan, closeWatcher, err := board.Watch(req.Instance.Id)must be changed to:
eventsChan, closeWatcher, err := board.Watch(req)Arduino CLI does not check anymore if it's bundled with the Arduino IDE 1.x. Previously this check allowed the Arduino
CLI to automatically use the libraries and tools bundled in the Arduino IDE, now this is not supported anymore unless
the configuration keys directories.builtin.libraries and directories.builtin.tools are set.
LIBRARY_LOCATION_IDE_BUILTIN has been renamed to LIBRARY_LOCATION_BUILTIN
The following methods:
func (lm *LibrariesManager) InstallPrerequisiteCheck(indexLibrary *librariesindex.Release) (*paths.Path, *libraries.Library, error) { ... }
func (lm *LibrariesManager) Install(indexLibrary *librariesindex.Release, libPath *paths.Path) error { ... ]
func (alts *LibraryAlternatives) FindVersion(version *semver.Version, installLocation libraries.LibraryLocation) *libraries.Library { ... }
func (lm *LibrariesManager) FindByReference(libRef *librariesindex.Reference) *libraries.Library { ... }now requires a new parameter LibraryLocation:
func (lm *LibrariesManager) InstallPrerequisiteCheck(indexLibrary *librariesindex.Release, installLocation libraries.LibraryLocation) (*paths.Path, *libraries.Library, error) { ... }
func (lm *LibrariesManager) Install(indexLibrary *librariesindex.Release, libPath *paths.Path, installLocation libraries.LibraryLocation) error { ... ]
func (alts *LibraryAlternatives) FindVersion(version *semver.Version, installLocation libraries.LibraryLocation) *libraries.Library { ... }
+func (lm *LibrariesManager) FindByReference(libRef *librariesindex.Reference, installLocation libraries.LibraryLocation) *libraries.Library { ... }If you're not interested in specifying the LibraryLocation you can use libraries.User to refer to the user
directory.
github.com/arduino/arduino-cli/configuration.IsBundledInDesktopIDEfunction has been removed.github.com/arduino/arduino-cli/configuration.BundleToolsDirectorieshas been renamed toBuiltinToolsDirectoriesgithub.com/arduino/arduino-cli/configuration.IDEBundledLibrariesDirhas been renamed toIDEBuiltinLibrariesDir
github.com/arduino/arduino-cli/arduino/utils.FeedStreamTo and
github.com/arduino/arduino-cli/arduino/utils.ConsumeStreamFrom are now private. They are mainly used internally for
gRPC stream handling and are not suitable to be public API.
github.com/arduino/arduino-cli/commands.DownloadToolRelease, and InstallToolRelease functions have been removed
This functionality was duplicated and already available via PackageManager methods.
github.com/arduino/arduino-cli/commands.Outdatedis nowgithub.com/arduino/arduino-cli/commands/outdated.Outdatedgithub.com/arduino/arduino-cli/commands.Upgradeis nowgithub.com/arduino/arduino-cli/commands/upgrade.Upgrade
Old code must change the imports accordingly.
-
The
PackageManager.LogandTempDirfields are now private. -
The
PackageManager.DownloadToolReleasemethod has no more thelabelparameter:func (pm *PackageManager) DownloadToolRelease(tool *cores.ToolRelease, config *downloader.Config, label string, progressCB rpc.DownloadProgressCB) error {
has been changed to:
func (pm *PackageManager) DownloadToolRelease(tool *cores.ToolRelease, config *downloader.Config, progressCB rpc.DownloadProgressCB) error {
Old code should remove the
labelparameter. -
The
PackageManager.UninstallPlatform,PackageManager.InstallTool, andPackageManager.UninstallToolmethods now requires agithub.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1.TaskProgressCBfunc (pm *PackageManager) UninstallPlatform(platformRelease *cores.PlatformRelease) error { func (pm *PackageManager) InstallTool(toolRelease *cores.ToolRelease) error { func (pm *PackageManager) UninstallTool(toolRelease *cores.ToolRelease) error {
have been changed to:
func (pm *PackageManager) UninstallPlatform(platformRelease *cores.PlatformRelease, taskCB rpc.TaskProgressCB) error { func (pm *PackageManager) InstallTool(toolRelease *cores.ToolRelease, taskCB rpc.TaskProgressCB) error { func (pm *PackageManager) UninstallTool(toolRelease *cores.ToolRelease, taskCB rpc.TaskProgressCB) error {
If you're not interested in getting the task events you can pass an empty callback function.
The function FeedStreamTo has been changed from:
func FeedStreamTo(writer func(data []byte)) io.Writerto
func FeedStreamTo(writer func(data []byte)) (io.WriteCloser, context.Context)The user must call the Close method on the returned io.WriteClose to correctly dispose the streaming channel. The
context Done() method may be used to wait for the internal subroutines to complete.
The gRPC Monitor service and the gRPC call Monitor.StreamingOpen have been removed in favor of the new Pluggable
Monitor API in the gRPC Commands service:
Commands.Monitor: open a monitor connection to a communication port.Commands.EnumerateMonitorPortSettings: enumerate the possible configurations parameters for a communication port.
Please refer to the official documentation and the reference client implementation for details on how to use the new API.
https://arduino.github.io/arduino-cli/dev/rpc/commands/#monitorrequest https://arduino.github.io/arduino-cli/dev/rpc/commands/#monitorresponse https://arduino.github.io/arduino-cli/dev/rpc/commands/#enumeratemonitorportsettingsrequest https://arduino.github.io/arduino-cli/dev/rpc/commands/#enumeratemonitorportsettingsresponse
Previously the "builtin libraries" in the Arduino IDE 1.8.x were always included in the build process. This wasn't the
intended behaviour, arduino-cli should include them only if run as a daemon from the Arduino IDE. Now this is fixed,
but since it has been the default behaviour from a very long time we decided to report it here as a breaking change.
If a compilation fail for a missing bundled library, you can fix it just by installing the missing library from the library manager as usual.
The gRPC message structure cc.arduino.cli.commands.v1.PlatformReference has been renamed to
cc.arduino.cli.commands.v1.InstalledPlatformReference, and some new fields have been added:
install_diris the installation directory of the platformpackage_urlis the 3rd party platform URL of the platform
It is currently used only in cc.arduino.cli.commands.v1.CompileResponse, so the field type has been changed as well.
Old gRPC clients must only update gRPC bindings. They can safely ignore the new fields if not needed.
golang API: github.com/arduino/arduino-cli/cli/globals.DefaultIndexURL has been moved under github.com/arduino/arduino-cli/arduino/globals
Legacy code should just update the import.
func (pm *PackageManager) DownloadPlatformRelease(platform *cores.PlatformRelease, config *downloader.Config, label string, progressCB rpc.DownloadProgressCB) error {is now:
func (pm *PackageManager) DownloadPlatformRelease(platform *cores.PlatformRelease, config *downloader.Config, progressCB rpc.DownloadProgressCB) error {Just remove the label parameter from legacy code.
Now the Port field of the error is a github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1.Port, usually
imported as rpc.Port. The old discovery.Port can be converted to the new one using the .ToRPC() method.
Use github.com/arduino/arduino-cli/commands/board.List(...) to detect boards.
NOTE: the functions in the arguments package doesn't have much use outside of the arduino-cli so we are considering
to remove them from the public golang API making them internal.
The old function:
func (p *Port) GetDiscoveryPort(instance *rpc.Instance, sk *sketch.Sketch) *discovery.Port { }is now replaced by the more powerful:
func (p *Port) DetectFQBN(inst *rpc.Instance) (string, *rpc.Port) { }
func CalculateFQBNAndPort(portArgs *Port, fqbnArg *Fqbn, instance *rpc.Instance, sk *sketch.Sketch) (string, *rpc.Port) { }The parameter is no more needed. Lagacy code will continue to work without modification (the value of the parameter will be just ignored).
In particular:
UserAgentandNetworkProxyhave been moved togithub.com/arduino/arduino-cli/configuration- the remainder of the package
github.com/arduino/arduino-cli/httpclienthas been moved togithub.com/arduino/arduino-cli/arduino/httpclient
The old imports must be updated according to the list above.
commands.DownloadProgressCB and commands.TaskProgressCB have been moved to package github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1
All references to these types must be updated with the new import.
commands.GetDownloaderConfig has been moved to package github.com/arduino/arduino-cli/arduino/httpclient
All references to this function must be updated with the new import.
commands.Download has been removed and replaced by github.com/arduino/arduino-cli/arduino/httpclient.DownloadFile
The old function must be replaced by the new one that is much more versatile.
packagemanager.PackageManager.DownloadToolRelease, packagemanager.PackageManager.DownloadPlatformRelease, and resources.DownloadResource.Download functions change signature and behaviour
The following functions:
func (pm *PackageManager) DownloadToolRelease(tool *cores.ToolRelease, config *downloader.Config) (*downloader.Downloader, error)
func (pm *PackageManager) DownloadPlatformRelease(platform *cores.PlatformRelease, config *downloader.Config) (*downloader.Downloader, error)
func (r *DownloadResource) Download(downloadDir *paths.Path, config *downloader.Config) (*downloader.Downloader, error)now requires a label and a progress callback parameter, do not return the Downloader object anymore, and they
automatically handles the download internally:
func (pm *PackageManager) DownloadToolRelease(tool *cores.ToolRelease, config *downloader.Config, label string, progressCB rpc.DownloadProgressCB) error
func (pm *PackageManager) DownloadPlatformRelease(platform *cores.PlatformRelease, config *downloader.Config, label string, progressCB rpc.DownloadProgressCB) error
func (r *DownloadResource) Download(downloadDir *paths.Path, config *downloader.Config, label string, downloadCB rpc.DownloadProgressCB) errorThe new progress parameters must be added to legacy code, if progress reports are not needed an empty stub for label
and progressCB must be provided. There is no more need to execute the downloader.Run() or
downloader.RunAndPoll(...) method.
For example, the old legacy code like:
downloader, err := pm.DownloadPlatformRelease(platformToDownload, config)
if err != nil {
...
}
if err := downloader.Run(); err != nil {
...
}may be ported to the new version as:
err := pm.DownloadPlatformRelease(platformToDownload, config, "", func(progress *rpc.DownloadProgress) {})The following functions signature:
func (pm *PackageManager) LoadHardware() []*status.Status { ... }
func (pm *PackageManager) LoadHardwareFromDirectories(hardwarePaths paths.PathList) []*status.Status { ... }
func (pm *PackageManager) LoadHardwareFromDirectory(path *paths.Path) []*status.Status { ... }
func (pm *PackageManager) LoadToolsFromBundleDirectories(dirs paths.PathList) []*status.Status { ... }
func (pm *PackageManager) LoadDiscoveries() []*status.Status { ... }have been changed to:
func (pm *PackageManager) LoadHardware() []error { ... }
func (pm *PackageManager) LoadHardwareFromDirectories(hardwarePaths paths.PathList) []error { ... }
func (pm *PackageManager) LoadHardwareFromDirectory(path *paths.Path) []error { ... }
func (pm *PackageManager) LoadToolsFromBundleDirectories(dirs paths.PathList) []error { ... }
func (pm *PackageManager) LoadDiscoveries() []error { ... }These function no longer returns a gRPC status, so the errors can be handled as any other error.
The discovery.New(...) function never fails, so the error has been removed, the old signature:
func New(id string, args ...string) (*PluggableDiscovery, error) { ... }is now:
func New(id string, args ...string) *PluggableDiscovery { ... }A new argument userAgent has been added to packagemanager.NewPackageManager, the new function signature is:
func NewPackageManager(indexDir, packagesDir, downloadDir, tempDir *paths.Path, userAgent string) *PackageManager {The userAgent string must be in the format "ProgramName/Version", for example "arduino-cli/0.20.1".
A new argument extraUserAgent has been added to commands.Create, the new function signature is:
func Create(req *rpc.CreateRequest, extraUserAgent ...string) (*rpc.CreateResponse, error) {extraUserAgent is an array of strings, so multiple user agent may be provided. Each user agent must be in the format
"ProgramName/Version", for example "arduino-cli/0.20.1".
A new argument progressCB has been added to commands.Compile, the new function signature is:
func Compile(
ctx context.Context,
req *rpc.CompileRequest,
outStream, errStream io.Writer,
progressCB commands.TaskProgressCB,
debug bool
) (r *rpc.CompileResponse, e error) {if a callback function is provided the Compile command will call it periodically with progress reports with the
percentage of compilation completed, otherwise, if the parameter is nil, no progress reports will be performed.
The parseArch parameter was removed since it was unused and was always true. This means that the architecture gets
always parsed by the function.
The parseArch parameter was removed since it was unused and was always true. This means that the architecture gets
always parsed by the function. Furthermore the function now should also correctly interpret packager:arch spelled with
the wrong casing.
github.com/arduino/arduino-cli/executils.NewProcess and executils.NewProcessFromPath function change
A new argument extraEnv has been added to executils.NewProcess and executils.NewProcessFromPath, the new function
signature is:
func NewProcess(extraEnv []string, args ...string) (*Process, error) {func NewProcessFromPath(extraEnv []string, executable *paths.Path, args ...string) (*Process, error) {The extraEnv params allow to pass environment variables (in addition to the default ones) to the spawned process.
github.com/arduino/arduino-cli/i18n.Init(...) now requires an empty string to be passed for autodetection of locale
For automated detection of locale, change the call from:
i18n.Init()to
i18n.Init("")The i18n.Logger is no longer available. It was mainly used in the legacy builder struct field Context.Logger.
The Context.Logger field has been replaced with plain io.Writer fields Contex.Stdout and Context.Stderr. All
existing logger functionality has been dropped, for example the Java-Style formatting with tags like {0} {1}... must
be replaced with one of the equivalent golang printf-based alternatives and logging levels must be replaced with direct
writes to Stdout or Stderr.
The board details command now accepts only the --fqbn or -b flags to specify the FQBN.
The previously deprecated board details <FQBN> syntax is no longer supported.
The board attach command now uses --port and -p flags to set board port and --board and -b flags to select its
FQBN.
The previous syntax board attach <port>|<FQBN> [sketchPath] is no longer supported.
The flag --timeout in the board list command is no longer supported.
The board list command JSON output has been changed quite a bit, from:
$ arduino-cli board list --format json
[
{
"address": "/dev/ttyACM1",
"protocol": "serial",
"protocol_label": "Serial Port (USB)",
"boards": [
{
"name": "Arduino Uno",
"fqbn": "arduino:avr:uno",
"vid": "0x2341",
"pid": "0x0043"
}
],
"serial_number": "954323132383515092E1"
}
]
to:
$ arduino-cli board list --format json
[
{
"matching_boards": [
{
"name": "Arduino Uno",
"fqbn": "arduino:avr:uno"
}
],
"port": {
"address": "/dev/ttyACM1",
"label": "/dev/ttyACM1",
"protocol": "serial",
"protocol_label": "Serial Port (USB)",
"properties": {
"pid": "0x0043",
"serialNumber": "954323132383515092E1",
"vid": "0x2341"
}
}
}
]
The boards array has been renamed matching_boards, each contained object will now contain only name and fqbn.
Properties that can be used to identify a board are now moved to the new properties object, it can contain any key
name. pid and vid have been moved to properties, serial_number has been renamed serialNumber and moved to
properties. The new label field is the name of the port if it should be displayed in a GUI.
gRPC interface DebugConfigRequest, UploadRequest, UploadUsingProgrammerRequest, BurnBootloaderRequest, DetectedPort field changes
DebugConfigRequest, UploadRequest, UploadUsingProgrammerRequest and BurnBootloaderRequest had their port field
change from type string to Port.
Port contains the following information:
// Port represents a board port that may be used to upload or to monitor a board
message Port {
// Address of the port (e.g., `/dev/ttyACM0`).
string address = 1;
// The port label to show on the GUI (e.g. "ttyACM0")
string label = 2;
// Protocol of the port (e.g., `serial`, `network`, ...).
string protocol = 3;
// A human friendly description of the protocol (e.g., "Serial Port (USB)"
string protocol_label = 4;
// A set of properties of the port
map<string, string> properties = 5;
}
The gRPC interface message DetectedPort has been changed from:
message DetectedPort {
// Address of the port (e.g., `serial:///dev/ttyACM0`).
string address = 1;
// Protocol of the port (e.g., `serial`).
string protocol = 2;
// A human friendly description of the protocol (e.g., "Serial Port (USB)").
string protocol_label = 3;
// The boards attached to the port.
repeated BoardListItem boards = 4;
// Serial number of connected board
string serial_number = 5;
}
to:
message DetectedPort {
// The possible boards attached to the port.
repeated BoardListItem matching_boards = 1;
// The port details
Port port = 2;
}
The properties previously contained directly in the message are now stored in the port property.
These changes are necessary for the pluggable discovery.
The vid and pid fields of the BoardListItem message have been removed. They used to only be available when
requesting connected board lists, now that information is stored in the port field of DetectedPort.
The behavior of the Init function has changed. The user specified locale code is no longer read from the
github.com/arduino/arduino-cli/configuration package and now must be passed directly to Init as a string:
i18n.Init("it")Omit the argument for automated locale detection:
i18n.Init()GenBuildPath() function has been moved to github.com/arduino/arduino-cli/arduino/sketch package. The signature is
unchanged.
EnsureBuildPathExists function from has been completely removed, in its place use
github.com/arduino/go-paths-helper.MkDirAll().
SketchSaveItemCpp function signature is changed from path string, contents []byte, destPath string to
path *paths.Path, contents []byte, destPath *paths.Path. paths is github.com/arduino/go-paths-helper.
SketchLoad function has been removed, in its place use New from github.com/arduino/arduino-cli/arduino/sketch
package.
- SketchLoad("/some/path", "")
+ sketch.New(paths.New("some/path))
}If you need to set a custom build path you must instead set it after creating the Sketch.
- SketchLoad("/some/path", "/my/build/path")
+ s, err := sketch.New(paths.New("some/path))
+ s.BuildPath = paths.new("/my/build/path")
}SketchCopyAdditionalFiles function signature is changed from
sketch *sketch.Sketch, destPath string, overrides map[string]string to
sketch *sketch.Sketch, destPath *paths.Path, overrides map[string]string.
Item struct has been removed, use go-paths-helper.Path in its place.
NewItem has been removed too, use go-paths-helper.New in its place.
GetSourceBytes has been removed, in its place use go-paths-helper.Path.ReadFile. GetSourceStr too has been
removed, in its place:
- s, err := item.GetSourceStr()
+ data, err := file.ReadFile()
+ s := string(data)
}ItemByPath type and its member functions have been removed, use go-paths-helper.PathList in its place.
Sketch.LocationPath has been renamed to FullPath and its type changed from string to go-paths-helper.Path.
Sketch.MainFile type has changed from *Item to go-paths-helper.Path. Sketch.OtherSketchFiles,
Sketch.AdditionalFiles and Sketch.RootFolderFiles type has changed from []*Item to go-paths-helper.PathList.
New signature has been changed from sketchFolderPath, mainFilePath, buildPath string, allFilesPaths []string to
path *go-paths-helper.Path.
CheckSketchCasing function is now private, the check is done internally by New.
InvalidSketchFoldernameError has been renamed InvalidSketchFolderNameError.
Sketch struct has been merged with sketch.Sketch struct.
Metadata and BoardMetadata structs have been moved to github.com/arduino/arduino-cli/arduino/sketch package.
NewSketchFromPath has been deleted, use sketch.New in its place.
ImportMetadata is now private called internally by sketch.New.
ExportMetadata has been moved to github.com/arduino/arduino-cli/arduino/sketch package.
BuildPath has been removed, use sketch.Sketch.BuildPath in its place.
CheckForPdeFiles has been moved to github.com/arduino/arduino-cli/arduino/sketch package.
Sketch has been removed, use sketch.Sketch in its place.
SketchToLegacy and SketchFromLegacy have been removed, nothing replaces them.
Context.Sketch types has been changed from Sketch to sketch.Sketch.
The board details output WRT board identification properties has changed, before it was:
$ arduino-cli board details arduino:samd:mkr1000
Board name: Arduino MKR1000
FQBN: arduino:samd:mkr1000
Board version: 1.8.11
Debugging supported: ✔
Official Arduino board: ✔
Identification properties: VID:0x2341 PID:0x824e
VID:0x2341 PID:0x024e
VID:0x2341 PID:0x804e
VID:0x2341 PID:0x004e
[...]
$ arduino-cli board details arduino:samd:mkr1000 --format json
[...]
"identification_prefs": [
{
"usb_id": {
"vid": "0x2341",
"pid": "0x804e"
}
},
{
"usb_id": {
"vid": "0x2341",
"pid": "0x004e"
}
},
{
"usb_id": {
"vid": "0x2341",
"pid": "0x824e"
}
},
{
"usb_id": {
"vid": "0x2341",
"pid": "0x024e"
}
}
],
[...]
now the properties have been renamed from identification_prefs to identification_properties and they are no longer
specific to USB but they can theoretically be any set of key/values:
$ arduino-cli board details arduino:samd:mkr1000
Board name: Arduino MKR1000
FQBN: arduino:samd:mkr1000
Board version: 1.8.11
Debugging supported: ✔
Official Arduino board: ✔
Identification properties: vid=0x2341
pid=0x804e
Identification properties: vid=0x2341
pid=0x004e
Identification properties: vid=0x2341
pid=0x824e
Identification properties: vid=0x2341
pid=0x024e
[...]
$ arduino-cli board details arduino:samd:mkr1000 --format json
[...]
"identification_properties": [
{
"properties": {
"pid": "0x804e",
"vid": "0x2341"
}
},
{
"properties": {
"pid": "0x004e",
"vid": "0x2341"
}
},
{
"properties": {
"pid": "0x824e",
"vid": "0x2341"
}
},
{
"properties": {
"pid": "0x024e",
"vid": "0x2341"
}
}
]
}
Previously the Init function was used to both create a new CoreInstance and initialize it, so that the internal
package and library managers were already populated with all the information available from *_index.json files,
installed platforms and libraries and so on.
Now the initialization phase is split into two, first the client must create a new CoreInstance with the Create
function, that does mainly two things:
- create all folders necessary to correctly run the CLI if not already existing
- create and return a new
CoreInstance
The Create function will only fail if folders creation is not successful.
The returned instance is relatively unusable since no library and no platform is loaded, some functions that don't need that information can still be called though.
The Init function has been greatly overhauled and it doesn't fail completely if one or more platforms or libraries
fail to load now.
Also the option library_manager_only has been removed, the package manager is always initialized and platforms are
loaded.
The Init was already a server-side streaming function but it would always return one and only one response, this has
been modified so that each response is either an error or a notification on the initialization process so that it works
more like an actual stream of information.
Previously a client would call the function like so:
const initReq = new InitRequest()
initReq.setLibraryManagerOnly(false)
const initResp = await new Promise<InitResponse>((resolve, reject) => {
let resp: InitResponse | undefined = undefined
const stream = client.init(initReq)
stream.on("data", (data: InitResponse) => (resp = data))
stream.on("end", () => resolve(resp!))
stream.on("error", (err) => reject(err))
})
const instance = initResp.getInstance()
if (!instance) {
throw new Error("Could not retrieve instance from the initialize response.")
}Now something similar should be done.
const createReq = new CreateRequest()
const instance = client.create(createReq)
if (!instance) {
throw new Error("Could not retrieve instance from the initialize response.")
}
const initReq = new InitRequest()
initReq.setInstance(instance)
const initResp = client.init(initReq)
initResp.on("data", (o: InitResponse) => {
const downloadProgress = o.getDownloadProgress()
if (downloadProgress) {
// Handle download progress
}
const taskProgress = o.getTaskProgress()
if (taskProgress) {
// Handle task progress
}
const err = o.getError()
if (err) {
// Handle error
}
})
await new Promise<void>((resolve, reject) => {
initResp.on("error", (err) => reject(err))
initResp.on("end", resolve)
})Previously if even one platform or library failed to load everything else would fail too, that doesn't happen anymore. Now it's easier for both the CLI and the gRPC clients to handle gracefully platforms or libraries updates that might break the initialization step and make everything unusable.
The Rescan function has been removed, in its place the Init function must be used.
Previously both UpdateIndex and UpdateLibrariesIndex functions implicitly called Rescan so that the internal
CoreInstance was updated with the eventual new information obtained in the update.
This behaviour is now removed and the internal CoreInstance must be explicitly updated by the gRPC client using the
Init function.
The following function from the github.com/arduino/arduino-cli/arduino/libraries module is no longer available:
func (lm *LibrariesManager) UpdateIndex(config *downloader.Config) (*downloader.Downloader, error) {We recommend using the equivalent gRPC API to perform the update of the index.
Starting from this release we applied a more rigorous and stricter naming conventions in gRPC API following the official guidelines: https://developers.google.com/protocol-buffers/docs/style
We also started using a linter to implement checks for gRPC API style errors.
This provides a better consistency and higher quality API but inevitably introduces breaking changes.
Consumers of the gRPC API should regenerate their bindings and update all structures naming where necessary. Most of the changes are trivial and falls into the following categories:
- Service names have been suffixed with
...Service(for exampleArduinoCore->ArduinoCoreService) - Message names suffix has been changed from
...Req/...Respto...Request/...Response(for exampleBoardDetailsReq->BoardDetailsRequest) - Enumerations now have their class name prefixed (for example the enumeration value
FLATinLibraryLayouthas been changed toLIBRARY_LAYOUT_FLAT) - Use of lower-snake case on all fields (for example:
ID->id,FQBN->fqbn,Name->name,ArchiveFilename->archive_filename) - Package names are now versioned (for example
cc.arduino.cli.commands->cc.arduino.cli.commands.v1) - Repeated responses are now in plural form (
identification_pref->identification_prefs,platform->platforms)
Consumers of the JSON output of the CLI must update their clients if they use one of the following commands:
-
in
core searchcommand the following fields have been renamed:Boards->boardsEmail->emailID->idLatest->latestMaintainer->maintainerName->nameWebsite->website
The new output is like:
$ arduino-cli core search Due --format json [ { "id": "arduino:sam", "latest": "1.6.12", "name": "Arduino SAM Boards (32-bits ARM Cortex-M3)", "maintainer": "Arduino", "website": "http://www.arduino.cc/", "email": "packages@arduino.cc", "boards": [ { "name": "Arduino Due (Native USB Port)", "fqbn": "arduino:sam:arduino_due_x" }, { "name": "Arduino Due (Programming Port)", "fqbn": "arduino:sam:arduino_due_x_dbg" } ] } ] -
in
board detailscommand the following fields have been renamed:identification_pref->identification_prefsusbID->usb_idPID->pidVID->vidwebsiteURL->website_urlarchiveFileName->archive_filenamepropertiesId->properties_idtoolsDependencies->tools_dependencies
The new output is like:
$ arduino-cli board details arduino:avr:uno --format json { "fqbn": "arduino:avr:uno", "name": "Arduino Uno", "version": "1.8.3", "properties_id": "uno", "official": true, "package": { "maintainer": "Arduino", "url": "https://downloads.arduino.cc/packages/package_index.json", "website_url": "http://www.arduino.cc/", "email": "packages@arduino.cc", "name": "arduino", "help": { "online": "http://www.arduino.cc/en/Reference/HomePage" } }, "platform": { "architecture": "avr", "category": "Arduino", "url": "http://downloads.arduino.cc/cores/avr-1.8.3.tar.bz2", "archive_filename": "avr-1.8.3.tar.bz2", "checksum": "SHA-256:de8a9b982477762d3d3e52fc2b682cdd8ff194dc3f1d46f4debdea6a01b33c14", "size": 4941548, "name": "Arduino AVR Boards" }, "tools_dependencies": [ { "packager": "arduino", "name": "avr-gcc", "version": "7.3.0-atmel3.6.1-arduino7", "systems": [ { "checksum": "SHA-256:3903553d035da59e33cff9941b857c3cb379cb0638105dfdf69c97f0acc8e7b5", "host": "arm-linux-gnueabihf", "archive_filename": "avr-gcc-7.3.0-atmel3.6.1-arduino7-arm-linux-gnueabihf.tar.bz2", "url": "http://downloads.arduino.cc/tools/avr-gcc-7.3.0-atmel3.6.1-arduino7-arm-linux-gnueabihf.tar.bz2", "size": 34683056 }, { ... } ] }, { ... } ], "identification_prefs": [ { "usb_id": { "vid": "0x2341", "pid": "0x0043" } }, { ... } ], "programmers": [ { "platform": "Arduino AVR Boards", "id": "parallel", "name": "Parallel Programmer" }, { ... } ] } -
in
board listallcommand the following fields have been renamed:FQBN->fqbnEmail->emailID->idInstalled->installedLatest->latestName->nameMaintainer->maintainerWebsite->website
The new output is like:
$ arduino-cli board listall Uno --format json { "boards": [ { "name": "Arduino Uno", "fqbn": "arduino:avr:uno", "platform": { "id": "arduino:avr", "installed": "1.8.3", "latest": "1.8.3", "name": "Arduino AVR Boards", "maintainer": "Arduino", "website": "http://www.arduino.cc/", "email": "packages@arduino.cc" } } ] } -
in
board searchcommand the following fields have been renamed:FQBN->fqbnEmail->emailID->idInstalled->installedLatest->latestName->nameMaintainer->maintainerWebsite->website
The new output is like:
$ arduino-cli board search Uno --format json [ { "name": "Arduino Uno", "fqbn": "arduino:avr:uno", "platform": { "id": "arduino:avr", "installed": "1.8.3", "latest": "1.8.3", "name": "Arduino AVR Boards", "maintainer": "Arduino", "website": "http://www.arduino.cc/", "email": "packages@arduino.cc" } } ] -
in
lib depscommand the following fields have been renamed:versionRequired->version_requiredversionInstalled->version_installed
The new output is like:
$ arduino-cli lib deps Arduino_MKRIoTCarrier --format json { "dependencies": [ { "name": "Adafruit seesaw Library", "version_required": "1.3.1" }, { "name": "SD", "version_required": "1.2.4", "version_installed": "1.2.3" }, { ... } ] } -
in
lib searchcommand the following fields have been renamed:archivefilename->archive_filenamecachepath->cache_path
The new output is like:
$ arduino-cli lib search NTPClient --format json { "libraries": [ { "name": "NTPClient", "releases": { "1.0.0": { "author": "Fabrice Weinberg", "version": "1.0.0", "maintainer": "Fabrice Weinberg \u003cfabrice@weinberg.me\u003e", "sentence": "An NTPClient to connect to a time server", "paragraph": "Get time from a NTP server and keep it in sync.", "website": "https://github.com/FWeinb/NTPClient", "category": "Timing", "architectures": [ "esp8266" ], "types": [ "Arduino" ], "resources": { "url": "https://downloads.arduino.cc/libraries/github.com/arduino-libraries/NTPClient-1.0.0.zip", "archive_filename": "NTPClient-1.0.0.zip", "checksum": "SHA-256:b1f2907c9d51ee253bad23d05e2e9c1087ab1e7ba3eb12ee36881ba018d81678", "size": 6284, "cache_path": "libraries" } }, "2.0.0": { ... }, "3.0.0": { ... }, "3.1.0": { ... }, "3.2.0": { ... } }, "latest": { "author": "Fabrice Weinberg", "version": "3.2.0", "maintainer": "Fabrice Weinberg \u003cfabrice@weinberg.me\u003e", "sentence": "An NTPClient to connect to a time server", "paragraph": "Get time from a NTP server and keep it in sync.", "website": "https://github.com/arduino-libraries/NTPClient", "category": "Timing", "architectures": [ "*" ], "types": [ "Arduino" ], "resources": { "url": "https://downloads.arduino.cc/libraries/github.com/arduino-libraries/NTPClient-3.2.0.zip", "archive_filename": "NTPClient-3.2.0.zip", "checksum": "SHA-256:122d00df276972ba33683aff0f7fe5eb6f9a190ac364f8238a7af25450fd3e31", "size": 7876, "cache_path": "libraries" } } } ], "status": 1 } -
in
board listcommand the following fields have been renamed:FQBN->fqbnVID->vidPID->pid
The new output is like:
$ arduino-cli board list --format json [ { "address": "/dev/ttyACM0", "protocol": "serial", "protocol_label": "Serial Port (USB)", "boards": [ { "name": "Arduino Nano 33 BLE", "fqbn": "arduino:mbed:nano33ble", "vid": "0x2341", "pid": "0x805a" }, { "name": "Arduino Nano 33 BLE", "fqbn": "arduino-dev:mbed:nano33ble", "vid": "0x2341", "pid": "0x805a" }, { "name": "Arduino Nano 33 BLE", "fqbn": "arduino-dev:nrf52:nano33ble", "vid": "0x2341", "pid": "0x805a" }, { "name": "Arduino Nano 33 BLE", "fqbn": "arduino-beta:mbed:nano33ble", "vid": "0x2341", "pid": "0x805a" } ], "serial_number": "BECC45F754185EC9" } ] $ arduino-cli board list -w --format json { "type": "add", "address": "/dev/ttyACM0", "protocol": "serial", "protocol_label": "Serial Port (USB)", "boards": [ { "name": "Arduino Nano 33 BLE", "fqbn": "arduino-dev:nrf52:nano33ble", "vid": "0x2341", "pid": "0x805a" }, { "name": "Arduino Nano 33 BLE", "fqbn": "arduino-dev:mbed:nano33ble", "vid": "0x2341", "pid": "0x805a" }, { "name": "Arduino Nano 33 BLE", "fqbn": "arduino-beta:mbed:nano33ble", "vid": "0x2341", "pid": "0x805a" }, { "name": "Arduino Nano 33 BLE", "fqbn": "arduino:mbed:nano33ble", "vid": "0x2341", "pid": "0x805a" } ], "serial_number": "BECC45F754185EC9" } { "type": "remove", "address": "/dev/ttyACM0" }
This change affects only the gRPC consumers.
In the CompileReq message the export_binaries property type has been changed from bool to
google.protobuf.BoolValue. This has been done to handle settings bindings by gRPC consumers and the CLI in the same
way so that they an identical behaviour.
All instances of the term telemetry in the code and the documentation has been changed to metrics. This has been
done to clarify that no data is currently gathered from users of the CLI.
To handle this change the users must edit their config file, usually arduino-cli.yaml, and change the telemetry key
to metrics. The modification must be done by manually editing the file using a text editor, it can't be done via CLI.
No other action is necessary.
The default folders for the arduino-cli.yaml are:
- Linux:
/home/<your_username>/.arduino15/arduino-cli.yaml - OS X:
/Users/<your_username>/Library/Arduino15/arduino-cli.yaml - Windows:
C:\Users\<your_username>\AppData\Local\Arduino15\arduino-cli.yaml
Previously it was required:
- To provide a debug command line recipe in
platform.txtliketools.reciped-id.debug.pattern=.....that will start agdbsession for the selected board. - To add a
debug.tooldefinition in theboards.txtto recall that recipe, for examplemyboard.debug.tool=recipe-id
Now:
- Only the configuration needs to be supplied, the
arduino-clior the GUI tool will figure out how to call and setup thegdbsession. An example of configuration is the following:
debug.executable={build.path}/{build.project_name}.elf
debug.toolchain=gcc
debug.toolchain.path={runtime.tools.arm-none-eabi-gcc-7-2017q4.path}/bin/
debug.toolchain.prefix=arm-none-eabi
debug.server=openocd
debug.server.openocd.path={runtime.tools.openocd-0.10.0-arduino7.path}/bin/
debug.server.openocd.scripts_dir={runtime.tools.openocd-0.10.0-arduino7.path}/share/openocd/scripts/
debug.server.openocd.script={runtime.platform.path}/variants/{build.variant}/{build.openocdscript}
The debug.executable key must be present and non-empty for debugging to be supported.
The debug.server.XXXX subkeys are optional and also "free text", this means that the configuration may be extended as
needed by the specific server. For now only openocd is supported. Anyway, if this change works, any other kind of
server may be fairly easily added.
The debug.xxx=yyy definitions above may be supplied and overlayed in the usual ways:
- on
platform.txt: definition here will be shared through all boards in the platform - on
boards.txtas part of a board definition: they will override the global platform definitions - on
programmers.txt: they will override the boards and global platform definitions if the programmer is selected
Previously, if the --build-path was not specified, compiling a Sketch would copy the generated binaries in
<sketch_folder>/build/<fqbn>/, uploading to a board required that path to exist and contain the necessary binaries.
The --dry-run flag was removed.
The default, compile does not copy generated binaries to the sketch folder. The --export-binaries (-e) flag was
introduced to copy the binaries from the build folder to the sketch one. --export-binaries is not required when using
the --output-dir flag. A related configuration key and environment variable has been added to avoid the need to always
specify the --export-binaries flag: sketch.always_export_binaries and ARDUINO_SKETCH_ALWAYS_EXPORT_BINARIES.
If --input-dir or --input-file is not set when calling upload the command will search for the deterministically
created build directory in the temp folder and use the binaries found there.
The gRPC interface has been updated accordingly, dryRun is removed.
The -P flag is used to select the programmer used to burn the bootloader on the specified board. Using -P list to
list all the possible programmers for the current board was hackish.
This way has been removed in favour of board details <fqbn> --list-programmers.
With the introduction of the --git-url and --zip-file flags the new config key library.enable_unsafe_install has
been added to enable them.
This changes the ouput of the config dump command.
To create a new config file with config init one must now use --dest-dir or the new --dest-file flags. Previously
the config file would always be overwritten by this command, now it fails if the it already exists, to force the
previous behaviour the user must set the --overwrite flag.