Skip to content

Protocol Documentation

Table of Contents

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

Field Type Label Description
properties BoardIdentificationProperties.PropertiesEntry repeated A set of properties that must all be matched to identify the board

BoardIdentificationProperties.PropertiesEntry

Field Type Label Description
key string
value string

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.

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

BoardPlatform

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

Field Type Label Description
maintainer string Maintainer of the package.
url string The URL of the platforms index file (e.g., https://downloads.arduino.cc/packages/package_index.json).
website_url string A URL provided by the package author, intended to point to their website.
email string Email address of the package maintainer.
name string Package vendor name.
help Help Resources for getting help about using the 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.

ToolsDependencies

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/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

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

Field Type Label Description
reason FailedInstanceInitReason specific cause of the error
message string explanation of the error

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

Field Type Label Description
init_progress InitResponse.Progress
error google.rpc.Status
profile Profile Selected profile information

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)

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)

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.

UpdateIndexResponse

Field Type Label Description
download_progress DownloadProgress Progress of the package index download.

UpdateLibrariesIndexRequest

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.

UpdateLibrariesIndexResponse

Field Type Label Description
download_progress DownloadProgress Progress of the libraries index download.

VersionRequest

VersionResponse

Field Type Label Description
version string The version of Arduino CLI in use.

FailedInstanceInitReason

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

ArduinoCoreService

The main Arduino Platform service API

Method Name Request Type Response Type Description
Create CreateRequest CreateResponse Create a new Arduino Core instance
Init InitRequest InitResponse stream Initializes an existing Arduino Core instance by loading platforms and libraries
Destroy DestroyRequest DestroyResponse Destroy an instance of the Arduino Core Service
UpdateIndex UpdateIndexRequest UpdateIndexResponse stream Update package index of the Arduino Core Service
UpdateLibrariesIndex UpdateLibrariesIndexRequest UpdateLibrariesIndexResponse stream Update libraries index
Version VersionRequest VersionResponse Get the version of Arduino CLI in use.
NewSketch NewSketchRequest NewSketchResponse Create a new Sketch
LoadSketch LoadSketchRequest LoadSketchResponse Returns all files composing a Sketch
ArchiveSketch ArchiveSketchRequest ArchiveSketchResponse Creates a zip file containing all files of specified Sketch
SetSketchDefaults SetSketchDefaultsRequest SetSketchDefaultsResponse Sets the sketch default FQBN and Port Address/Protocol in the sketch project file (sketch.yaml). These metadata can be retrieved using LoadSketch.
BoardDetails BoardDetailsRequest BoardDetailsResponse Requests details about a board
BoardList BoardListRequest BoardListResponse List the boards currently connected to the computer.
BoardListAll BoardListAllRequest BoardListAllResponse List all the boards provided by installed platforms.
BoardSearch BoardSearchRequest BoardSearchResponse Search boards in installed and not installed Platforms.
BoardListWatch BoardListWatchRequest BoardListWatchResponse stream List boards connection and disconnected events.
Compile CompileRequest CompileResponse stream Compile an Arduino sketch.
PlatformInstall PlatformInstallRequest PlatformInstallResponse stream Download and install a platform and its tool dependencies.
PlatformDownload PlatformDownloadRequest PlatformDownloadResponse stream Download a platform and its tool dependencies to the staging/packages subdirectory of the data directory.
PlatformUninstall PlatformUninstallRequest PlatformUninstallResponse stream Uninstall a platform as well as its tool dependencies that are not used by other installed platforms.
PlatformUpgrade PlatformUpgradeRequest PlatformUpgradeResponse stream Upgrade an installed platform to the latest version.
Upload UploadRequest UploadResponse stream Upload a compiled sketch to a board.
UploadUsingProgrammer UploadUsingProgrammerRequest UploadUsingProgrammerResponse stream Upload a compiled sketch to a board using a programmer.
SupportedUserFields SupportedUserFieldsRequest SupportedUserFieldsResponse Returns the list of users fields necessary to upload to that board using the specified protocol.
ListProgrammersAvailableForUpload ListProgrammersAvailableForUploadRequest ListProgrammersAvailableForUploadResponse List programmers available for a board.
BurnBootloader BurnBootloaderRequest BurnBootloaderResponse stream Burn bootloader to a board.
PlatformSearch PlatformSearchRequest PlatformSearchResponse Search for a platform in the platforms indexes.
LibraryDownload LibraryDownloadRequest LibraryDownloadResponse stream Download the archive file of an Arduino library in the libraries index to the staging directory.
LibraryInstall LibraryInstallRequest LibraryInstallResponse stream Download and install an Arduino library from the libraries index.
LibraryUpgrade LibraryUpgradeRequest LibraryUpgradeResponse stream Upgrade a library to the newest version available.
ZipLibraryInstall ZipLibraryInstallRequest ZipLibraryInstallResponse stream Install a library from a Zip File
GitLibraryInstall GitLibraryInstallRequest GitLibraryInstallResponse stream Download and install a library from a git url
LibraryUninstall LibraryUninstallRequest LibraryUninstallResponse stream Uninstall an Arduino library.
LibraryUpgradeAll LibraryUpgradeAllRequest LibraryUpgradeAllResponse stream Upgrade all installed Arduino libraries to the newest version available.
LibraryResolveDependencies LibraryResolveDependenciesRequest LibraryResolveDependenciesResponse List the recursive dependencies of a library, as defined by the depends field of the library.properties files.
LibrarySearch LibrarySearchRequest LibrarySearchResponse Search the Arduino libraries index for libraries.
LibraryList LibraryListRequest LibraryListResponse List the installed libraries.
Monitor MonitorRequest stream MonitorResponse stream Open a monitor connection to a board port
EnumerateMonitorPortSettings EnumerateMonitorPortSettingsRequest EnumerateMonitorPortSettingsResponse Returns the parameters that can be set in the MonitorRequest calls
Debug DebugRequest stream DebugResponse stream Start a debug session and communicate with the debugger tool.
IsDebugSupported IsDebugSupportedRequest IsDebugSupportedResponse Determine if debugging is suported given a specific configuration.
GetDebugConfig GetDebugConfigRequest GetDebugConfigResponse Query the debugger information given a specific configuration.
SettingsGetAll SettingsGetAllRequest SettingsGetAllResponse List all the settings.
SettingsMerge SettingsMergeRequest SettingsMergeResponse Set multiple settings values at once.
SettingsGetValue SettingsGetValueRequest SettingsGetValueResponse Get the value of a specific setting.
SettingsSetValue SettingsSetValueRequest SettingsSetValueResponse Set the value of a specific setting.
SettingsWrite SettingsWriteRequest SettingsWriteResponse Writes to file settings currently stored in memory
SettingsDelete SettingsDeleteRequest SettingsDeleteResponse Deletes an entry and rewrites the file settings

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

Field Type Label Description
start DownloadProgressStart
update DownloadProgressUpdate
end DownloadProgressEnd

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.

InstalledPlatformReference

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.

Platform

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

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

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
type 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

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

Field Type Label Description
key string
value PlatformRelease

Profile

Field Type Label Description
name string Name used to identify the profile within the sketch.
fqbn string FQBN specified in the profile.

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)

SketchProfile

Field Type Label Description
name string Name of the profile
fqbn string FQBN used by the 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/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 Builds of 'core.a' 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 separated by commas.
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 google.protobuf.BoolValue 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.

CompileRequest.SourceOverrideEntry

Field Type Label Description
key string
value string

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
size int64
max_size int64

Top

cc/arduino/cli/commands/v1/core.proto

AlreadyAtLatestVersionError

AlreadyAtLatestVersionError is returned when an upgrade is not possible because already at latest version.

PlatformDownloadRequest

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.
platform_package string
architecture string Architecture name of the platform (e.g., avr).
version string Platform version to download.

PlatformDownloadResponse

Field Type Label Description
progress DownloadProgress Progress of the downloads of platform and tool files.

PlatformInstallRequest

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

PlatformInstallResponse

Field Type Label Description
progress DownloadProgress Progress of the downloads of the platform and tool files.
task_progress TaskProgress Description of the current stage of the installation.

PlatformLoadingError

PlatformSearchRequest

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.

PlatformSearchResponse

Field Type Label Description
search_output PlatformSummary repeated Results of the search.

PlatformUninstallRequest

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

PlatformUninstallResponse

Field Type Label Description
task_progress TaskProgress Description of the current stage of the uninstall.

PlatformUpgradeRequest

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

PlatformUpgradeResponse

Field Type Label Description
progress DownloadProgress Progress of the downloads of the platform and tool files.
task_progress TaskProgress Description of the current stage of the upgrade.
platform Platform The upgraded platform.

Top

cc/arduino/cli/commands/v1/debug.proto

DebugGCCToolchainConfiguration

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.

Field Type Label Description
data bytes Incoming data from the debugger tool.
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.

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

Field Type Label Description
key string
value string

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.

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/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

Field Type Label Description
task_progress TaskProgress Description of the current stage of the installation.

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

Field Type Label Description
key string
value string

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

Field Type Label Description
progress DownloadProgress Progress of the library download.

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

Field Type Label Description
progress DownloadProgress Progress of the library download.
task_progress TaskProgress Description of the current stage of the installation.

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

Field Type Label Description
dependencies LibraryDependencyStatus repeated Dependencies of the library.

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

Field Type Label Description
libraries SearchedLibrary repeated The results of the search.
status LibrarySearchStatus Whether the search yielded results.

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

Field Type Label Description
task_progress TaskProgress Description of the current stage of the uninstallation.

LibraryUpgradeAllRequest

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.

LibraryUpgradeAllResponse

Field Type Label Description
progress DownloadProgress Progress of the downloads of files needed for the upgrades.
task_progress TaskProgress Description of the current stage of the upgrade.

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

Field Type Label Description
progress DownloadProgress Progress of the library download.
task_progress TaskProgress Description of the current stage of the installation.

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

Field Type Label Description
key string
value LibraryRelease

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

Field Type Label Description
task_progress TaskProgress Description of the current stage of the installation.

LibraryInstallLocation

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

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

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

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/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.

MonitorPortConfiguration

Field Type Label Description
settings MonitorPortSetting repeated The port configuration parameters to configure

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

MonitorPortSetting

Field Type Label Description
setting_id string
value string

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 MonitorPortSetting repeated 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/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

Field Type Label Description
key string
value string

Top

cc/arduino/cli/commands/v1/settings.proto

SettingsDeleteRequest

Field Type Label Description
key string The key of the setting to delete.

SettingsDeleteResponse

SettingsGetAllRequest

SettingsGetAllResponse

Field Type Label Description
json_data string The settings, in JSON format.

SettingsGetValueRequest

Field Type Label Description
key string The key of the setting.

SettingsGetValueResponse

Field Type Label Description
key string The key of the setting.
json_data string The setting, in JSON format.

SettingsMergeRequest

Field Type Label Description
json_data string The settings, in JSON format.

SettingsMergeResponse

SettingsSetValueRequest

Field Type Label Description
key string The key of the setting.
json_data string The setting, in JSON format.

SettingsSetValueResponse

SettingsWriteRequest

Field Type Label Description
file_path string Path to settings file (e.g. /path/to/arduino-cli.yaml)

SettingsWriteResponse

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

BurnBootloaderRequest.UserFieldsEntry

Field Type Label Description
key string
value string

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
fqbn string

ListProgrammersAvailableForUploadResponse

Field Type Label Description
programmers Programmer repeated

ProgrammerIsRequiredForUploadError

SupportedUserFieldsRequest

Field Type Label Description
instance Instance
fqbn string
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

UploadRequest.UserFieldsEntry

Field Type Label Description
key string
value string

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

UploadUsingProgrammerRequest.UserFieldsEntry

Field Type Label Description
key string
value string

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

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)