Protocol Documentation
Table of Contents
Top
cc/arduino/cli/commands/v1/common.proto
Board
Field
Type
Label
Description
name
string
Name used to identify the board to humans.
fqbn
string
Fully qualified board name used to identify the board to machines. The FQBN is only available for installed boards.
DownloadProgress
DownloadProgressEnd
Field
Type
Label
Description
success
bool
True if the download is successful.
message
string
Info or error message, depending on the value of 'success'. Some examples: "File xxx already downloaded" or "Connection timeout".
DownloadProgressStart
Field
Type
Label
Description
url
string
URL of the download.
label
string
The label to display on the progress bar.
DownloadProgressUpdate
Field
Type
Label
Description
downloaded
int64
Size of the downloaded portion of the file.
total_size
int64
Total size of the file being downloaded.
HelpResources
Field
Type
Label
Description
online
string
A URL provided by the author of the platform's package, intended to point to their online help service.
Field
Type
Label
Description
id
string
Platform ID (e.g., arduino:avr
).
version
string
Version of the platform.
install_dir
string
Installation directory of the platform.
package_url
string
3rd party platform URL.
Instance
Field
Type
Label
Description
id
int32
The ID of the instance.
MissingProgrammerError
MissingProgrammerError is a status error detail that is returned when
the operation can not be completed due to a missing programmer argument.
MonitorPortConfiguration
Field
Type
Label
Description
settings
MonitorPortSetting
repeated
The port configuration parameters.
MonitorPortSetting
Field
Type
Label
Description
setting_id
string
The setting identifier.
value
string
The setting value.
Platform is a structure containing all the information about a single
platform release.
Field
Type
Label
Description
metadata
PlatformMetadata
Generic information about a platform.
release
PlatformRelease
Information about a specific release of a platform.
PlatformMetadata contains generic information about a platform (not
correlated to a specific release).
Field
Type
Label
Description
id
string
Platform ID (e.g., arduino:avr
).
maintainer
string
Maintainer of the platform's package.
website
string
A URL provided by the author of the platform's package, intended to point to their website.
email
string
Email of the maintainer of the platform's package.
manually_installed
bool
If true this Platform has been installed manually in the user' sketchbook hardware folder.
deprecated
bool
True if the latest release of this Platform has been deprecated.
indexed
bool
If true the platform is indexed.
PlatformRelease contains information about a specific release of a platform.
Field
Type
Label
Description
name
string
Name used to identify the platform to humans (e.g., "Arduino AVR Boards").
version
string
Version of the platform release.
types
string
repeated
Type of the platform.
installed
bool
True if the platform is installed.
boards
Board
repeated
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.
help
HelpResources
A URL provided by the author of the platform's package, intended to point to their online help service.
missing_metadata
bool
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.
deprecated
bool
True this release is deprecated.
compatible
bool
True if the platform dependencies are available for the current OS/ARCH. This also means that the platform is installable.
PlatformSummary is a structure containing all the information about
a platform and all its available releases.
Field
Type
Label
Description
metadata
PlatformMetadata
Generic information about a platform.
releases
PlatformSummary.ReleasesEntry
repeated
Maps version to the corresponding PlatformRelease.
installed_version
string
The installed version of the platform, or empty string if none installed.
latest_version
string
The latest available version of the platform that can be installable, or empty if none available.
PlatformSummary.ReleasesEntry
Programmer
Field
Type
Label
Description
platform
string
Platform name.
id
string
Programmer ID.
name
string
Programmer name.
Sketch
Field
Type
Label
Description
main_file
string
Absolute path to a main sketch files.
location_path
string
Absolute path to folder that contains main_file.
other_sketch_files
string
repeated
List of absolute paths to other sketch files.
additional_files
string
repeated
List of absolute paths to additional sketch files.
root_folder_files
string
repeated
List of absolute paths to supported files in the sketch root folder, main file excluded.
default_fqbn
string
Default FQBN set in project file (sketch.yaml).
default_port
string
Default Port set in project file (sketch.yaml).
default_protocol
string
Default Protocol set in project file (sketch.yaml).
profiles
SketchProfile
repeated
List of profiles present in the project file (sketch.yaml).
default_profile
SketchProfile
Default profile set in the project file (sketch.yaml).
default_programmer
string
Default Programmer set in project file (sketch.yaml).
default_port_config
MonitorPortConfiguration
Default Port configuration set in project file (sketch.yaml).
SketchProfile
Field
Type
Label
Description
name
string
Name of the profile.
fqbn
string
FQBN used by the profile.
programmer
string
Programmer used by the profile.
port
string
Default Port in this profile.
port_config
MonitorPortConfiguration
Default Port configuration set in project file (sketch.yaml).
protocol
string
Default Protocol in this profile.
TaskProgress
Field
Type
Label
Description
name
string
Description of the task.
message
string
Additional information about the task.
completed
bool
Whether the task is complete.
percent
float
Amount in percent of the task completion (optional).
Top
cc/arduino/cli/commands/v1/port.proto
Port
Port represents a board port that may be used to upload or to monitor a board.
Field
Type
Label
Description
address
string
Address of the port (e.g., /dev/ttyACM0
).
label
string
The port label to show on the GUI (e.g. "ttyACM0").
protocol
string
Protocol of the port (e.g., serial
, network
, ...).
protocol_label
string
A human friendly description of the protocol (e.g., "Serial Port (USB)").
properties
Port.PropertiesEntry
repeated
A set of properties of the port.
hardware_id
string
The hardware ID (serial number) of the board attached to the port.
Port.PropertiesEntry
Top
cc/arduino/cli/commands/v1/board.proto
BoardDetailsRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
The fully qualified board name of the board you want information about (e.g., arduino:avr:uno
).
do_not_expand_build_properties
bool
If set to true the returned build properties will be left unexpanded, with the variables placeholders exactly as defined in the platform.
BoardDetailsResponse
Field
Type
Label
Description
fqbn
string
The fully qualified board name of the board.
name
string
Name used to identify the board to humans (e.g., Arduino Uno).
version
string
Installed version of the board's platform.
properties_id
string
The board ID component of the FQBN (e.g., uno
).
alias
string
Board alias that can be used as a more user friendly alternative to the FQBN.
official
bool
Whether this is an official or 3rd party board.
pinout
string
URL of the board's pinout documentation.
package
Package
Data about the package that contains the board's platform.
platform
BoardPlatform
Data about the board's platform.
tools_dependencies
ToolsDependencies
repeated
Tool dependencies of the board.
config_options
ConfigOption
repeated
The board's custom configuration options.
programmers
Programmer
repeated
List of programmers supported by the board.
identification_properties
BoardIdentificationProperties
repeated
Identifying information for the board (e.g., USB VID/PID).
build_properties
string
repeated
Board build properties used for compiling.
default_programmer_id
string
Default programmer for the board.
BoardIdentificationProperties
BoardIdentificationProperties.PropertiesEntry
BoardListAllRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
search_args
string
repeated
The search query to filter the board list by.
include_hidden_boards
bool
Set to true to get also the boards marked as "hidden" in the platform.
BoardListAllResponse
Field
Type
Label
Description
boards
BoardListItem
repeated
List of installed boards.
BoardListItem
Field
Type
Label
Description
name
string
The name for use when identifying the board to a human.
fqbn
string
The fully qualified board name. Used to identify the board to a machine.
is_hidden
bool
If the board is marked as "hidden" in the platform.
platform
Platform
Platform this board belongs to.
BoardListRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
timeout
int64
Search for boards for the given time (in milliseconds).
fqbn
string
The fully qualified board name of the board you want information about (e.g., arduino:avr:uno
).
BoardListResponse
Field
Type
Label
Description
ports
DetectedPort
repeated
List of ports and the boards detected on those ports.
warnings
string
repeated
Warning messages or errors coming from the discoveries.
BoardListWatchRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
BoardListWatchResponse
Field
Type
Label
Description
event_type
string
Event type as received from the serial discovery tool.
port
DetectedPort
Information about the port.
error
string
Eventual errors when detecting connected boards.
Field
Type
Label
Description
architecture
string
Architecture of the platform (e.g., avr
).
category
string
Category of the platform. Set to Contributed
for 3rd party platforms.
url
string
Download URL of the platform archive file.
archive_filename
string
File name of the platform archive.
checksum
string
Checksum of the platform archive.
size
int64
File size of the platform archive.
name
string
Name used to identify the platform to humans.
BoardSearchRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
search_args
string
The search query to filter the board list by.
include_hidden_boards
bool
Set to true to get also the boards marked as "hidden" in installed platforms.
BoardSearchResponse
Field
Type
Label
Description
boards
BoardListItem
repeated
List of installed and installable boards.
ConfigOption
Field
Type
Label
Description
option
string
ID of the configuration option. For identifying the option to machines.
option_label
string
Name of the configuration option for identifying the option to humans.
values
ConfigValue
repeated
Possible values of the configuration option.
ConfigValue
Field
Type
Label
Description
value
string
The configuration option value.
value_label
string
Label to identify the configuration option to humans.
selected
bool
Whether the configuration option is selected.
DetectedPort
Field
Type
Label
Description
matching_boards
BoardListItem
repeated
The possible boards attached to the port.
port
Port
The port details.
Help
Field
Type
Label
Description
online
string
URL for getting online help.
Package
Systems
Field
Type
Label
Description
checksum
string
Checksum of the tool archive.
host
string
Operating system identifier.
archive_filename
string
File name of the tool archive.
url
string
Download URL of the tool archive.
size
int64
File size of the tool archive.
Field
Type
Label
Description
packager
string
Vendor name of the package containing the tool definition.
name
string
Tool name.
version
string
Tool version.
systems
Systems
repeated
Data for the operating system-specific builds of the tool.
Top
cc/arduino/cli/commands/v1/lib.proto
DownloadResource
Field
Type
Label
Description
url
string
Download URL of the library archive.
archive_filename
string
Filename of the library archive.
checksum
string
Checksum of the library archive.
size
int64
File size of the library archive.
cache_path
string
The directory under the staging subdirectory of the data directory the library archive file will be downloaded to.
GitLibraryInstallRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
url
string
URL to the repository containing the library.
overwrite
bool
Set to true to overwrite an already installed library with the same name. Defaults to false.
GitLibraryInstallResponse
GitLibraryInstallResponse.Result
Empty message, reserved for future expansion.
InstalledLibrary
Field
Type
Label
Description
library
Library
Information about the library.
release
LibraryRelease
When the updatable
field of the LibraryList
request is set to true
, this will contain information on the latest version of the library in the libraries index.
Library
Field
Type
Label
Description
name
string
Library name (value of name
field in library.properties).
author
string
Value of the author
field in library.properties.
maintainer
string
Value of the maintainer
field in library.properties.
sentence
string
Value of the sentence
field in library.properties.
paragraph
string
Value of the paragraph
field in library.properties.
website
string
Value of the url
field in library.properties.
category
string
Value of the category
field in library.properties.
architectures
string
repeated
Value of the architectures
field in library.properties.
types
string
repeated
The type categories of the library. Possible values: Arduino
, Partner
, Recommended
, Contributed
, Retired
.
install_dir
string
The path of the library directory.
source_dir
string
The location of the library's source files.
utility_dir
string
The location of the library's utility
directory.
container_platform
string
If location
is platform_builtin
or referenced_platform_builtin
, the identifying string for the platform containing the library (e.g., arduino:avr@1.8.2
).
dot_a_linkage
bool
Value of the dot_a_linkage
field in library.properties.
precompiled
bool
Value of the precompiled
field in library.properties.
ld_flags
string
Value of the ldflags
field in library.properties.
is_legacy
bool
A library.properties file is not present in the library's root directory.
version
string
Value of the version
field in library.properties.
license
string
Value of the license
field in library.properties.
properties
Library.PropertiesEntry
repeated
The data from the library's library.properties file, including unused fields.
location
LibraryLocation
The location type of the library installation.
layout
LibraryLayout
The library format type.
examples
string
repeated
The example sketches provided by the library.
provides_includes
string
repeated
Value of the includes
field in library.properties or, if missing, the list of include files available on the library source root directory.
compatible_with
Library.CompatibleWithEntry
repeated
Map of FQBNs that specifies if library is compatible with this library.
in_development
bool
This value is set to true if the library is in development and should not be treated as read-only. This status is determined by the presence of a .development
file in the library root directory.
Library.CompatibleWithEntry
Field
Type
Label
Description
key
string
value
bool
Library.PropertiesEntry
LibraryDependency
Field
Type
Label
Description
name
string
Library name of the dependency.
version_constraint
string
Version constraint of the dependency.
LibraryDependencyStatus
Field
Type
Label
Description
name
string
The name of the library dependency.
version_required
string
The required version of the library dependency.
version_installed
string
Version of the library dependency currently installed.
LibraryDownloadRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
name
string
Name of the library.
version
string
The version of the library to download.
LibraryDownloadResponse
LibraryDownloadResponse.Result
Empty message, reserved for future expansion.
LibraryInstallRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
name
string
Name of the library.
version
string
The version of the library to install.
no_deps
bool
Set to true to skip installation of specified library's dependencies, defaults to false.
no_overwrite
bool
Set to true to skip installation if a different version of the library or one of its dependencies is already installed, defaults to false.
install_location
LibraryInstallLocation
Install the library and dependencies in the specified location.
LibraryInstallResponse
LibraryInstallResponse.Result
Empty message, reserved for future expansion.
LibraryListRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
all
bool
Whether to include built-in libraries (from platforms and the Arduino IDE) in the listing.
updatable
bool
Whether to list only libraries for which there is a newer version than the installed version available in the libraries index.
name
string
If set filters out the libraries not matching name.
fqbn
string
By setting this field all duplicate libraries are filtered out leaving only the libraries that will be used to compile for the specified board FQBN.
LibraryListResponse
Field
Type
Label
Description
installed_libraries
InstalledLibrary
repeated
List of installed libraries.
LibraryRelease
Field
Type
Label
Description
author
string
Value of the author
field in library.properties.
version
string
Value of the version
field in library.properties.
maintainer
string
Value of the maintainer
field in library.properties.
sentence
string
Value of the sentence
field in library.properties.
paragraph
string
Value of the paragraph
field in library.properties.
website
string
Value of the url
field in library.properties.
category
string
Value of the category
field in library.properties.
architectures
string
repeated
Value of the architectures
field in library.properties.
types
string
repeated
The type categories of the library, as defined in the libraries index. Possible values: Arduino
, Partner
, Recommended
, Contributed
, Retired
.
resources
DownloadResource
Information about the library archive file.
license
string
Value of the license
field in library.properties.
provides_includes
string
repeated
Value of the includes
field in library.properties.
dependencies
LibraryDependency
repeated
The names of the library's dependencies, as defined by the 'depends' field of library.properties.
LibraryResolveDependenciesRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
name
string
Name of the library.
version
string
The version of the library to check dependencies of. If no version is specified, dependencies of the newest version will be listed.
do_not_update_installed_libraries
bool
If true the computed solution will try to keep exising libraries at their current version.
LibraryResolveDependenciesResponse
LibrarySearchRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
omit_releases_details
bool
Set to true to not populate the releases field in the response (may save a lot of bandwidth/CPU).
search_args
string
Keywords for the search.
LibrarySearchResponse
LibraryUninstallRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
name
string
Name of the library.
version
string
The version of the library to uninstall.
LibraryUninstallResponse
LibraryUninstallResponse.Result
Empty message, reserved for future expansion.
LibraryUpgradeAllRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
LibraryUpgradeAllResponse
LibraryUpgradeAllResponse.Result
Empty message, reserved for future expansion.
LibraryUpgradeRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
name
string
Name of the library.
no_deps
bool
Set to true to skip installation of specified library's dependencies, defaults to false.
LibraryUpgradeResponse
LibraryUpgradeResponse.Result
Empty message, reserved for future expansion.
SearchedLibrary
Field
Type
Label
Description
name
string
Library name.
releases
SearchedLibrary.ReleasesEntry
repeated
The index data for the available versions of the library. The key of the map is the library version.
latest
LibraryRelease
The index data for the latest version of the library.
available_versions
string
repeated
The available versions of this library.
SearchedLibrary.ReleasesEntry
ZipLibraryInstallRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
path
string
Path to the archived library.
overwrite
bool
Set to true to overwrite an already installed library with the same name. Defaults to false.
ZipLibraryInstallResponse
ZipLibraryInstallResponse.Result
Empty message, reserved for future expansion.
LibraryInstallLocation
Represent a library installation location.
Name
Number
Description
LIBRARY_INSTALL_LOCATION_USER
0
In the libraries
subdirectory of the user directory (sketchbook). This is the default if not specified.
LIBRARY_INSTALL_LOCATION_BUILTIN
1
In the configured 'builtin.libraries' directory.
LibraryLayout
Represent the library layout.
Name
Number
Description
LIBRARY_LAYOUT_FLAT
0
Library is in the 1.0 Arduino library format.
LIBRARY_LAYOUT_RECURSIVE
1
Library is in the 1.5 Arduino library format.
LibraryLocation
Represent the location of the library.
Name
Number
Description
LIBRARY_LOCATION_BUILTIN
0
In the configured 'builtin.libraries' directory.
LIBRARY_LOCATION_USER
1
In the libraries
subdirectory of the user directory (sketchbook).
LIBRARY_LOCATION_PLATFORM_BUILTIN
2
In the libraries
subdirectory of a platform.
LIBRARY_LOCATION_REFERENCED_PLATFORM_BUILTIN
3
When LibraryLocation
is used in a context where a board is specified, this indicates the library is in the libraries
subdirectory of a platform referenced by the board's platform.
LIBRARY_LOCATION_UNMANAGED
4
Outside the libraries
folders managed by the CLI.
LibrarySearchStatus
Represent the result of the library search.
Name
Number
Description
LIBRARY_SEARCH_STATUS_FAILED
0
No search results were found.
LIBRARY_SEARCH_STATUS_SUCCESS
1
Search results were found.
Top
cc/arduino/cli/commands/v1/compile.proto
BuilderResult
Field
Type
Label
Description
build_path
string
The compiler build path.
used_libraries
Library
repeated
The libraries used in the build.
executable_sections_size
ExecutableSectionSize
repeated
The size of the executable split by sections.
board_platform
InstalledPlatformReference
The platform where the board is defined.
build_platform
InstalledPlatformReference
The platform used for the build (if referenced from the board platform).
build_properties
string
repeated
Build properties used for compiling.
diagnostics
CompileDiagnostic
repeated
Compiler errors and warnings.
CompileDiagnostic
Field
Type
Label
Description
severity
string
Severity of the diagnostic.
message
string
The explanation of the diagnostic (it may be multiple preformatted lines).
file
string
The file containing the diagnostic.
line
int64
The line of the diagnostic if available (starts from 1).
column
int64
The column of the diagnostic if available (starts from 1).
context
CompileDiagnosticContext
repeated
The context where this diagnostic is found (it may be multiple files that represents a chain of includes, or a text describing where the diagnostic is found).
notes
CompileDiagnosticNote
repeated
Annotations or suggestions to the diagnostic made by the compiler.
CompileDiagnosticContext
Field
Type
Label
Description
message
string
The message describing the context reference.
file
string
The file of the context reference.
line
int64
The line of the context reference.
column
int64
The column of the context reference.
CompileDiagnosticNote
Field
Type
Label
Description
message
string
The message describing the compiler note.
file
string
The file of the compiler note.
line
int64
The line of the compiler note.
column
int64
The column of the compiler note.
CompileRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully Qualified Board Name, e.g.: arduino:avr:uno
. If this field is not defined, the FQBN of the board attached to the sketch via the BoardAttach
method is used.
sketch_path
string
The path where the sketch is stored.
show_properties
bool
Just get the build properties and do not run the full compile.
preprocess
bool
Print preprocessed code to stdout instead of compiling.
build_cache_path
string
Deprecated. Builds of core and sketches are saved into this path to be cached and reused.
build_path
string
Path to use to store the files used for the compilation. If omitted, a directory will be created in the operating system's default temporary path.
build_properties
string
repeated
List of custom build properties.
warnings
string
Used to tell gcc which warning level to use. The level names are: "none", "default", "more" and "all".
verbose
bool
Turns on verbose mode.
quiet
bool
Suppresses almost every output.
jobs
int32
The max number of concurrent compiler instances to run (as make -jx
). If jobs is set to 0, it will use the number of available CPUs as the maximum.
libraries
string
repeated
A list of paths to directories containing a collection of libraries.
optimize_for_debug
bool
Optimize compile output for debug, not for release.
export_dir
string
Optional: save the build artifacts in this directory, the directory must exist.
clean
bool
Optional: cleanup the build folder and do not use any previously cached build.
create_compilation_database_only
bool
When set to true
only the compilation database will be produced and no actual build will be performed.
source_override
CompileRequest.SourceOverrideEntry
repeated
This map (source file -> new content) let the builder use the provided content instead of reading the corresponding file on disk. This is useful for IDE that have unsaved changes in memory. The path must be relative to the sketch directory. Only files from the sketch are allowed.
export_binaries
bool
optional
When set to true
the compiled binary will be copied to the export directory.
library
string
repeated
A list of paths to single libraries root directory.
keys_keychain
string
The path where to search for the custom signing key name and the encrypt key name.
sign_key
string
The name of the custom key to use for signing during the compile process.
encrypt_key
string
The name of the custom key to use for encrypting during the compile process.
skip_libraries_discovery
bool
If set to true the build will skip the library discovery process and will use the same libraries of latest build. Enabling this flag may produce a wrong output and should not be used in regular compiles unless there is a very specific reason to do so. This flag is mainly provided for usage in language servers to optimize the build speed in some particular cases.
do_not_expand_build_properties
bool
If set to true the returned build properties will be left unexpanded, with the variables placeholders exactly as defined in the platform.
build_cache_extra_paths
string
repeated
Search for precompiled cores in the given paths and use them if found. This search is performed after the standard build_cache directory.
CompileRequest.SourceOverrideEntry
CompileResponse
Field
Type
Label
Description
out_stream
bytes
The output of the compilation process (stream).
err_stream
bytes
The error output of the compilation process (stream).
progress
TaskProgress
Completions reports of the compilation process (stream).
result
BuilderResult
The compilation result.
ExecutableSectionSize
Field
Type
Label
Description
name
string
The name of the section.
size
int64
The used size of the section in bytes.
max_size
int64
The maximum size of the section in bytes.
InstanceNeedsReinitializationError
Top
cc/arduino/cli/commands/v1/core.proto
AlreadyAtLatestVersionError
AlreadyAtLatestVersionError is returned when an upgrade is not possible
because already at latest version.
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
platform_package
string
Vendor name of the platform (e.g., arduino
).
architecture
string
Architecture name of the platform (e.g., avr
).
version
string
Platform version to download.
Empty message, reserved for future expansion.
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
platform_package
string
Vendor name of the platform (e.g., arduino
).
architecture
string
Architecture name of the platform (e.g., avr
).
version
string
Platform version to install.
skip_post_install
bool
Set to true to not run (eventual) post install scripts for trusted platforms.
no_overwrite
bool
Set to true to skip installation if a different version of the platform is already installed.
skip_pre_uninstall
bool
Set to true to not run (eventual) pre uninstall scripts for trusted platforms when performing platform upgrades.
Empty message, reserved for future expansion.
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
search_args
string
Keywords for the search.
manually_installed
bool
Whether to show manually installed platforms. false
causes to skip manually installed platforms.
Field
Type
Label
Description
search_output
PlatformSummary
repeated
Results of the search.
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
platform_package
string
Vendor name of the platform (e.g., arduino
).
architecture
string
Architecture name of the platform (e.g., avr
).
skip_pre_uninstall
bool
Set to true to not run (eventual) pre uninstall scripts for trusted platforms.
Empty message, reserved for future expansion.
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
platform_package
string
Vendor name of the platform (e.g., arduino
).
architecture
string
Architecture name of the platform (e.g., avr
).
skip_post_install
bool
Set to true to not run (eventual) post install scripts for trusted platforms.
skip_pre_uninstall
bool
Set to true to not run (eventual) pre uninstall scripts for trusted platforms when performing platform upgrades.
Field
Type
Label
Description
platform
Platform
The upgraded platform.
Top
cc/arduino/cli/commands/v1/debug.proto
Configurations specific for the 'gcc' toolchain.
DebugOpenOCDServerConfiguration
Configuration specific for the 'openocd` server.
Field
Type
Label
Description
path
string
Path to openocd.
scripts_dir
string
Path to openocd scripts.
scripts
string
repeated
List of scripts to execute by openocd.
DebugRequest
The top-level message sent by the client for the Debug
method.
Multiple DebugRequest
messages can be sent but the first message
must contain a GetDebugConfigRequest
message to initialize the debug
session. All subsequent messages must contain bytes to be sent to the debug
session and must not contain a GetDebugConfigRequest
message.
Content must be either a debug session config or data to be sent.
Field
Type
Label
Description
debug_request
GetDebugConfigRequest
Provides information to the debug that specifies which is the target. The first DebugRequest
message must contain a GetDebugConfigRequest
message.
data
bytes
The data to be sent to the target being monitored.
send_interrupt
bool
Set this to true to send and Interrupt signal to the debugger process.
DebugResponse
The streaming response may contain chunks of data from the debugger or an
error.
DebugResponse.Result
Field
Type
Label
Description
error
string
Incoming error output from the debugger tool.
GetDebugConfigRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the board in use (e.g., arduino:samd:mkr1000
). If this is omitted, the FQBN attached to the sketch will be used.
sketch_path
string
Path to the sketch that is running on the board. The compiled executable is expected to be located under this path.
port
Port
Port of the debugger (optional).
interpreter
string
Which GDB command interpreter to use.
import_dir
string
Directory containing the compiled executable. If import_dir
is not specified, the executable is assumed to be in {sketch_path}/build/{fqbn}/
.
programmer
string
The programmer to use for debugging.
debug_properties
string
repeated
List of custom debug properties.
GetDebugConfigResponse
Field
Type
Label
Description
executable
string
The executable binary to debug.
toolchain
string
The toolchain type used for the build (for example "gcc").
toolchain_path
string
The toolchain directory.
toolchain_prefix
string
The toolchain architecture prefix (for example "arm-none-eabi").
server
string
The GDB server type used to connect to the programmer/board (for example "openocd").
server_path
string
The GDB server directory.
toolchain_configuration
google.protobuf.Any
Extra configuration parameters wrt toolchain.
server_configuration
google.protobuf.Any
Extra configuration parameters wrt GDB server.
custom_configs
GetDebugConfigResponse.CustomConfigsEntry
repeated
Custom debugger configurations (not handled directly by Arduino CLI but provided for 3rd party plugins/debuggers). The map keys identifies which 3rd party plugin/debugger is referred, the map string values contains a JSON configuration for it.
svd_file
string
the SVD file to use.
programmer
string
The programmer specified in the request.
GetDebugConfigResponse.CustomConfigsEntry
IsDebugSupportedRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the board in use (e.g., arduino:samd:mkr1000
).
port
Port
Port of the debugger (optional).
interpreter
string
Which GDB command interpreter to use.
programmer
string
The programmer to use for debugging.
debug_properties
string
repeated
List of custom debug properties.
IsDebugSupportedResponse
Field
Type
Label
Description
debugging_supported
bool
True if debugging is supported.
debug_fqbn
string
This is the same FQBN given in the IsDebugSupportedRequest but cleaned up of the board options that do not affect the debugger configuration. It may be used by clients/IDE to group slightly different boards option selections under the same debug configuration.
Top
cc/arduino/cli/commands/v1/monitor.proto
EnumerateMonitorPortSettingsRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
port_protocol
string
The port protocol to enumerate settings.
fqbn
string
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.
EnumerateMonitorPortSettingsResponse
Field
Type
Label
Description
settings
MonitorPortSettingDescriptor
repeated
A list of descriptors of the settings that may be changed for the monitor port.
MonitorPortOpenRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
port
Port
Port to open, must be filled only on the first request.
fqbn
string
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.
port_configuration
MonitorPortConfiguration
Port configuration, optional, contains settings of the port to be applied.
MonitorPortSettingDescriptor
Field
Type
Label
Description
setting_id
string
The setting identifier.
label
string
A human-readable label of the setting (to be displayed on the GUI).
type
string
The setting type (at the moment only "enum" is avaiable).
enum_values
string
repeated
The values allowed on "enum" types.
value
string
The selected or default value.
MonitorRequest
Field
Type
Label
Description
open_request
MonitorPortOpenRequest
Open request, it must be the first incoming message.
tx_data
bytes
Data to send to the port.
updated_configuration
MonitorPortConfiguration
Port configuration, contains settings of the port to be changed.
close
bool
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).
MonitorResponse
Field
Type
Label
Description
error
string
Eventual errors dealing with monitor port.
rx_data
bytes
Data received from the port.
applied_settings
MonitorPortConfiguration
Settings applied to the port, may be returned after a port is opened (to report the default settings) or after a new port_configuration is sent (to report the new settings applied).
success
bool
A message with this field set to true is sent as soon as the port is succesfully opened.
Top
cc/arduino/cli/commands/v1/settings.proto
Configuration
Configuration to apply to the given instance.
Any missing field will be kept at the default value.
Configuration.BoardManager
Field
Type
Label
Description
additional_urls
string
repeated
Additional URLs to be used for the board manager.
Configuration.BuildCache
Field
Type
Label
Description
compilations_before_purge
uint64
The minimum number of compilations before the cache is purged.
ttl_secs
uint64
Time to live of the cache in seconds.
Configuration.Daemon
Field
Type
Label
Description
port
string
The TCP port of the daemon.
Configuration.Directories
Configuration.Directories.Builtin
Field
Type
Label
Description
libraries
string
optional
The directory where the built-in libraries are installed.
Configuration.Library
Field
Type
Label
Description
enable_unsafe_install
bool
Set to true to enable library installation from zip archives or git repositories.
Configuration.Logging
Field
Type
Label
Description
level
string
The logging level.
format
string
The logging format.
file
string
optional
The logging file.
Configuration.Network
Field
Type
Label
Description
extra_user_agent
string
optional
Extra user-agent information to be appended in network requests.
proxy
string
optional
The proxy to use for network requests.
Configuration.Output
Field
Type
Label
Description
no_color
bool
Set to true to disable coloring of the output.
Configuration.Sketch
Field
Type
Label
Description
always_export_binaries
bool
Set to true to always export binaries to the sketch directory.
Configuration.Updater
Field
Type
Label
Description
enable_notification
bool
Set to true to enable notifications for updates.
ConfigurationGetRequest
ConfigurationGetResponse
Field
Type
Label
Description
configuration
Configuration
The current configuration.
ConfigurationOpenRequest
Field
Type
Label
Description
encoded_settings
string
The encoded settings.
settings_format
string
The format of the encoded settings, allowed values are "json" and "yaml".
ConfigurationOpenResponse
Field
Type
Label
Description
warnings
string
repeated
Warnings that occurred while opening the configuration (e.g. unknown keys, or invalid values).
ConfigurationSaveRequest
Field
Type
Label
Description
settings_format
string
The format of the encoded settings, allowed values are "json" and "yaml".
ConfigurationSaveResponse
Field
Type
Label
Description
encoded_settings
string
The encoded settings.
SettingsEnumerateRequest
SettingsEnumerateResponse
SettingsEnumerateResponse.Entry
Field
Type
Label
Description
key
string
The key.
type
string
The key type.
SettingsGetValueRequest
Field
Type
Label
Description
key
string
The key to get.
value_format
string
The format of the encoded_value (default is "json", allowed values are "json" and "yaml).
SettingsGetValueResponse
Field
Type
Label
Description
encoded_value
string
The value of the key (encoded).
SettingsSetValueRequest
Field
Type
Label
Description
key
string
The key to change.
encoded_value
string
The new value (encoded), no objects, only scalar or array of scalars are allowed.
value_format
string
The format of the encoded_value (default is "json", allowed values are "json", "yaml" and "cli").
SettingsSetValueResponse
Top
cc/arduino/cli/commands/v1/upload.proto
BurnBootloaderRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the target board (e.g., arduino:avr:uno
).
port
Port
The port of the programmer used to program the bootloader.
verbose
bool
Whether to turn on verbose output during the programming.
verify
bool
After programming, verify the contents of the memory on the board match the uploaded binary.
programmer
string
The programmer to use for burning bootloader.
dry_run
bool
If set to true, the actual upload will not be performed but a trace output will be printed stdout. This is for debugging purposes.
user_fields
BurnBootloaderRequest.UserFieldsEntry
repeated
User provided fields usually used by upload tools that need authentication or in any case fields that can be customized by the user at upload time and cannot be known previously. For more info: https://arduino.github.io/arduino-cli/latest/platform-specification/#user-provided-fields
upload_properties
string
repeated
List of custom upload properties.
BurnBootloaderRequest.UserFieldsEntry
BurnBootloaderResponse
Field
Type
Label
Description
out_stream
bytes
The output of the burn bootloader process.
err_stream
bytes
The error output of the burn bootloader process.
ListProgrammersAvailableForUploadRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the target board (e.g., arduino:avr:uno
).
ListProgrammersAvailableForUploadResponse
Field
Type
Label
Description
programmers
Programmer
repeated
List of programmers supported by the board.
ProgrammerIsRequiredForUploadError
SupportedUserFieldsRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the target board (e.g., arduino:avr:uno
).
protocol
string
Protocol that will be used to upload, this information is necessary to pick the right upload tool for the board specified with the FQBN.
SupportedUserFieldsResponse
Field
Type
Label
Description
user_fields
UserField
repeated
User fields supported by board specified in SupportedUserFieldsRequest. If board doesn't support any field it will be empty.
UploadRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the target board (e.g., arduino:avr:uno
). If this field is not defined, the FQBN of the board attached to the sketch via the BoardAttach
method is used.
sketch_path
string
Path where the sketch to be uploaded is stored. Unless the import_file
field is defined, the compiled binary is assumed to be at the location and filename under this path where it is saved by the Compile
method.
port
Port
The port of the board.
verbose
bool
Whether to turn on verbose output during the upload.
verify
bool
After upload, verify that the contents of the memory on the board match the uploaded binary.
import_file
string
When import_file
is specified, it overrides the import_dir
and sketch_path
params.
import_dir
string
Custom path to a directory containing compiled files. When import_dir
is not specified, the standard build directory under sketch_path
is used.
programmer
string
The programmer to use for upload. If set an UploadUsingProgrammer is triggered instead of a normal upload. The UploadUsingProgrammer call may also be used for explicit error check.
dry_run
bool
If set to true, the actual upload will not be performed but a trace output will be printed stdout. This is for debugging purposes.
user_fields
UploadRequest.UserFieldsEntry
repeated
User provided fields usually used by upload tools that need authentication or in any case fields that can be customized by the user at upload time and cannot be known previously. For more info: https://arduino.github.io/arduino-cli/latest/platform-specification/#user-provided-fields
upload_properties
string
repeated
List of custom upload properties.
UploadRequest.UserFieldsEntry
UploadResponse
Field
Type
Label
Description
out_stream
bytes
The output of the upload process.
err_stream
bytes
The error output of the upload process.
result
UploadResult
The upload result.
UploadResult
Field
Type
Label
Description
updated_upload_port
Port
When a board requires a port disconnection to perform the upload, this field returns the port where the board reconnects after the upload.
UploadUsingProgrammerRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init
response.
fqbn
string
Fully qualified board name of the target board (e.g., arduino:avr:uno
). If this field is not defined, the FQBN of the board attached to the sketch via the BoardAttach
method is used.
sketch_path
string
Path where the sketch to be uploaded is stored. Unless the import_file
field is defined, the compiled binary is assumed to be at the location and filename under this path where it is saved by the Compile
method.
port
Port
The port of the board.
verbose
bool
Whether to turn on verbose output during the upload.
verify
bool
After upload, verify that the contents of the memory on the board match the uploaded binary.
import_file
string
When import_file
is specified, it overrides the import_dir
and sketch_path
params.
import_dir
string
Custom path to a directory containing compiled files. When import_dir
is not specified, the standard build directory under sketch_path
is used.
programmer
string
The programmer to use for upload.
dry_run
bool
If set to true, the actual upload will not be performed but a trace output will be printed stdout. This is for debugging purposes.
user_fields
UploadUsingProgrammerRequest.UserFieldsEntry
repeated
User provided fields usually used by upload tools that need authentication or in any case fields that can be customized by the user at upload time and cannot be known previously. For more info: https://arduino.github.io/arduino-cli/latest/platform-specification/#user-provided-fields
upload_properties
string
repeated
List of custom upload properties.
UploadUsingProgrammerRequest.UserFieldsEntry
UploadUsingProgrammerResponse
Field
Type
Label
Description
out_stream
bytes
The output of the upload process.
err_stream
bytes
The error output of the upload process.
UserField
Field
Type
Label
Description
tool_id
string
Id of the tool that supports this field.
name
string
Name used internally to store and retrieve this field.
label
string
Label is the text shown to the user when they need to input this field.
secret
bool
True if the value of the field must not be shown when typing, for example when the user inputs a network password.
Top
cc/arduino/cli/commands/v1/commands.proto
ArchiveSketchRequest
Field
Type
Label
Description
sketch_path
string
Absolute path to Sketch file or folder containing Sketch file.
archive_path
string
Absolute path to archive that will be created or folder that will contain it.
include_build_dir
bool
Specifies if build directory should be included in the archive.
overwrite
bool
Allows to override an already existing archive.
ArchiveSketchResponse
CheckForArduinoCLIUpdatesRequest
Field
Type
Label
Description
force_check
bool
Force the check, even if the configuration says not to check for updates.
CheckForArduinoCLIUpdatesResponse
Field
Type
Label
Description
newest_version
string
The latest version of Arduino CLI available, if bigger than the current version.
CleanDownloadCacheDirectoryRequest
Field
Type
Label
Description
instance
Instance
The Arduino Core Service instance.
CleanDownloadCacheDirectoryResponse
CreateRequest
CreateResponse
Field
Type
Label
Description
instance
Instance
An Arduino Core instance.
DestroyRequest
Field
Type
Label
Description
instance
Instance
The Arduino Core Service instance to destroy.
DestroyResponse
FailedInstanceInitError
IndexUpdateReport
InitRequest
Field
Type
Label
Description
instance
Instance
An Arduino Core instance.
profile
string
Profile to use.
sketch_path
string
The path where the sketch is stored.
InitResponse
InitResponse.Progress
Field
Type
Label
Description
download_progress
DownloadProgress
Progress of the downloads of platforms and libraries index files.
task_progress
TaskProgress
Describes the current stage of the initialization.
LoadSketchRequest
Field
Type
Label
Description
sketch_path
string
Absolute path to single sketch file or a sketch folder.
LoadSketchResponse
Field
Type
Label
Description
sketch
Sketch
The loaded sketch.
NewSketchRequest
Field
Type
Label
Description
sketch_name
string
New sketch name.
sketch_dir
string
Optional: create a Sketch in this directory (used as "Sketchbook" directory). Default Sketchbook directory "directories.User" is used if sketch_dir is empty.
overwrite
bool
Specificies if an existing .ino sketch should be overwritten.
NewSketchResponse
Field
Type
Label
Description
main_file
string
Absolute path to a main sketch file.
SetSketchDefaultsRequest
Field
Type
Label
Description
sketch_path
string
Absolute path to Sketch file or folder containing Sketch file.
default_fqbn
string
The desired value for default_fqbn in project file (sketch.yaml).
default_port_address
string
The desired value for default_port in project file (sketch.yaml).
default_port_protocol
string
The desired value for default_protocol in project file (sketch.yaml).
default_programmer
string
The desired value for default_programmer in project file (sketch.yaml).
SetSketchDefaultsResponse
Field
Type
Label
Description
default_fqbn
string
The value of default_fqnn that has been written in project file (sketch.yaml).
default_port_address
string
The value of default_port that has been written in project file (sketch.yaml).
default_port_protocol
string
The value of default_protocol that has been written in project file (sketch.yaml).
default_programmer
string
The value of default_programmer that has been written in project file (sketch.yaml).
UpdateIndexRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init response.
ignore_custom_package_indexes
bool
If set to true user defined package indexes will not be updated.
update_if_older_than_secs
int64
Only perform index update if the index file is older than this value in seconds.
UpdateIndexResponse
UpdateIndexResponse.Result
Field
Type
Label
Description
updated_indexes
IndexUpdateReport
repeated
The result of the packages index update.
UpdateLibrariesIndexRequest
Field
Type
Label
Description
instance
Instance
Arduino Core Service instance from the Init response.
update_if_older_than_secs
int64
Only perform index update if the index file is older than this value in seconds.
UpdateLibrariesIndexResponse
UpdateLibrariesIndexResponse.Result
Field
Type
Label
Description
libraries_index
IndexUpdateReport
The result of the libraries index update.
VersionRequest
VersionResponse
Field
Type
Label
Description
version
string
The version of Arduino CLI in use.
FailedInstanceInitReason
Represent the reason why an instance initialization failed.
Name
Number
Description
FAILED_INSTANCE_INIT_REASON_UNSPECIFIED
0
FAILED_INSTANCE_INIT_REASON_UNSPECIFIED the error reason is not specialized.
FAILED_INSTANCE_INIT_REASON_INVALID_INDEX_URL
1
INVALID_INDEX_URL a package index url is malformed.
FAILED_INSTANCE_INIT_REASON_INDEX_LOAD_ERROR
2
FAILED_INSTANCE_INIT_REASON_INDEX_LOAD_ERROR failure encountered while loading an index.
FAILED_INSTANCE_INIT_REASON_TOOL_LOAD_ERROR
3
FAILED_INSTANCE_INIT_REASON_TOOL_LOAD_ERROR failure encountered while loading a tool.
FAILED_INSTANCE_INIT_REASON_INDEX_DOWNLOAD_ERROR
4
FAILED_INSTANCE_INIT_REASON_INDEX_DOWNLOAD_ERROR failure encountered while downloading an index.
IndexUpdateReport.Status
The status represents the result of the index update.
Name
Number
Description
STATUS_UNSPECIFIED
0
The status of the index update is unspecified.
STATUS_UPDATED
1
The index has been successfully updated.
STATUS_ALREADY_UP_TO_DATE
2
The index was already up to date.
STATUS_FAILED
3
The index update failed.
STATUS_SKIPPED
4
The index update was skipped.
ArduinoCoreService
The main Arduino Platform service API.
Scalar Value Types
.proto Type
Notes
C++
Java
Python
Go
C#
PHP
Ruby
double
double
double
float
float64
double
float
Float
float
float
float
float
float32
float
float
Float
int32
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.
int32
int
int
int32
int
integer
Bignum or Fixnum (as required)
int64
Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.
int64
long
int/long
int64
long
integer/string
Bignum
uint32
Uses variable-length encoding.
uint32
int
int/long
uint32
uint
integer
Bignum or Fixnum (as required)
uint64
Uses variable-length encoding.
uint64
long
int/long
uint64
ulong
integer/string
Bignum or Fixnum (as required)
sint32
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.
int32
int
int
int32
int
integer
Bignum or Fixnum (as required)
sint64
Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.
int64
long
int/long
int64
long
integer/string
Bignum
fixed32
Always four bytes. More efficient than uint32 if values are often greater than 2^28.
uint32
int
int
uint32
uint
integer
Bignum or Fixnum (as required)
fixed64
Always eight bytes. More efficient than uint64 if values are often greater than 2^56.
uint64
long
int/long
uint64
ulong
integer/string
Bignum
sfixed32
Always four bytes.
int32
int
int
int32
int
integer
Bignum or Fixnum (as required)
sfixed64
Always eight bytes.
int64
long
int/long
int64
long
integer/string
Bignum
bool
bool
boolean
boolean
bool
bool
boolean
TrueClass/FalseClass
string
A string must always contain UTF-8 encoded or 7-bit ASCII text.
string
String
str/unicode
string
string
string
String (UTF-8)
bytes
May contain any arbitrary sequence of bytes.
string
ByteString
str
[]byte
ByteString
string
String (ASCII-8BIT)