Protocol Documentation

Table of Contents

Top

commands/board.proto

BoardAttachReq

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.
board_uri string The board's URI (e.g., /dev/ttyACM0).
sketch_path string Path of the sketch to attach the board to. The board attachment metadata will be saved to {sketch_path}/sketch.json.
search_timeout string Duration in seconds to search the given URI for a connected board before timing out. The default value is 5 seconds.

BoardAttachResp

Field Type Label Description
task_progress TaskProgress Description of the current stage of the board attachment.

BoardDetailsReq

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

BoardDetailsResp

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/Genuino Uno).
version string Installed version of the board's platform.
propertiesId 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.
toolsDependencies ToolsDependencies repeated Tool dependencies of the board.
config_options ConfigOption repeated The board's custom configuration options.
identification_pref IdentificationPref repeated Identifying information for the board (e.g., USB VID/PID).

BoardListAllReq

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.

BoardListAllResp

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.

BoardListReq

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

BoardListResp

Field Type Label Description
ports DetectedPort repeated List of ports and the boards detected on those ports.

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

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
address string Address of the port (e.g., serial:///dev/ttyACM0).
protocol string Protocol of the port (e.g., serial).
protocol_label string A human friendly description of the protocol (e.g., "Serial Port (USB)").
boards BoardListItem repeated The boards attached to the port.

Help

Field Type Label Description
online string URL for getting online help.

IdentificationPref

Field Type Label Description
usbID USBID Identifying information for USB-connected boards.

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).
websiteURL 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.
archiveFileName 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.

USBID

Field Type Label Description
VID string USB vendor ID.
PID string USB product ID.

Top

commands/commands.proto

DestroyReq

Field Type Label Description
instance Instance The Arduino Core Service instance to destroy.

DestroyResp

InitReq

Field Type Label Description
library_manager_only bool Start a Arduino Core Service instance that will provide only Library Manager functionality.

InitResp

Field Type Label Description
instance Instance An Arduino Core Service instance.
platforms_index_errors string repeated Error messages related to any problems encountered while parsing the platforms index files.
libraries_index_error string Error message if a problem was encountered while parsing the libraries index file.
download_progress DownloadProgress Progress of the downloads of platforms and libraries index files.
task_progress TaskProgress Describes the current stage of the initialization.

RescanReq

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

RescanResp

Field Type Label Description
platforms_index_errors string repeated Error messages related to any problems encountered while parsing the platforms index file.
libraries_index_error string Error message if a problem was encountered while parsing the libraries index file.

UpdateIndexReq

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

UpdateIndexResp

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

UpdateLibrariesIndexReq

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

UpdateLibrariesIndexResp

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

VersionReq

VersionResp

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

ArduinoCore

The main Arduino Platform Service

BOOTSTRAP COMMANDS

Method Name Request Type Response Type Description
Init InitReq InitResp stream Start a new instance of the Arduino Core Service
Destroy DestroyReq DestroyResp Destroy an instance of the Arduino Core Service
Rescan RescanReq RescanResp Rescan instance of the Arduino Core Service
UpdateIndex UpdateIndexReq UpdateIndexResp stream Update package index of the Arduino Core Service
UpdateLibrariesIndex UpdateLibrariesIndexReq UpdateLibrariesIndexResp stream Update libraries index
Version VersionReq VersionResp Get the version of Arduino CLI in use.
BoardDetails BoardDetailsReq BoardDetailsResp Requests details about a board
BoardAttach BoardAttachReq BoardAttachResp stream Attach a board to a sketch. When the fqbn field of a request is not provided, the FQBN of the attached board will be used.
BoardList BoardListReq BoardListResp List the boards currently connected to the computer.
BoardListAll BoardListAllReq BoardListAllResp List all the boards provided by installed platforms.
Compile CompileReq CompileResp stream Compile an Arduino sketch.
PlatformInstall PlatformInstallReq PlatformInstallResp stream Download and install a platform and its tool dependencies.
PlatformDownload PlatformDownloadReq PlatformDownloadResp stream Download a platform and its tool dependencies to the staging/packages subdirectory of the data directory.
PlatformUninstall PlatformUninstallReq PlatformUninstallResp stream Uninstall a platform as well as its tool dependencies that are not used by other installed platforms.
PlatformUpgrade PlatformUpgradeReq PlatformUpgradeResp stream Upgrade an installed platform to the latest version.
Upload UploadReq UploadResp stream Upload a compiled sketch to an Arduino board.
ListProgrammersAvailableForUpload ListProgrammersAvailableForUploadReq ListProgrammersAvailableForUploadResp
BurnBootloader BurnBootloaderReq BurnBootloaderResp stream Burn bootloader to a board.
PlatformSearch PlatformSearchReq PlatformSearchResp Search for a platform in the platforms indexes.
PlatformList PlatformListReq PlatformListResp List all installed platforms.
LibraryDownload LibraryDownloadReq LibraryDownloadResp stream Download the archive file of an Arduino library in the libraries index to the staging directory.
LibraryInstall LibraryInstallReq LibraryInstallResp stream Download and install an Arduino library from the libraries index.
LibraryUninstall LibraryUninstallReq LibraryUninstallResp stream Uninstall an Arduino library.
LibraryUpgradeAll LibraryUpgradeAllReq LibraryUpgradeAllResp stream Upgrade all installed Arduino libraries to the newest version available.
LibraryResolveDependencies LibraryResolveDependenciesReq LibraryResolveDependenciesResp List the recursive dependencies of a library, as defined by the depends field of the library.properties files.
LibrarySearch LibrarySearchReq LibrarySearchResp Search the Arduino libraries index for libraries.
LibraryList LibraryListReq LibraryListResp List the installed libraries.

Top

commands/common.proto

DownloadProgress

Field Type Label Description
url string URL of the download.
file string The file being downloaded.
total_size int64 Total size of the file being downloaded.
downloaded int64 Size of the downloaded portion of the file.
completed bool Whether the download is complete.

Instance

Field Type Label Description
id int32 The ID of the instance.

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.

Top

commands/compile.proto

CompileReq

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.
sketchPath string The path where the sketch is stored.
showProperties bool Show all build preferences used instead of compiling.
preprocess bool Print preprocessed code to stdout instead of compiling.
buildCachePath string Builds of 'core.a' are saved into this path to be cached and reused.
buildPath 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.
buildProperties 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.
vidPid string VID/PID specific build properties.
exportFile string DEPRECATED: use exportDir instead
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 List of custom libraries paths separated by commas.
optimizeForDebug bool Optimize compile output for debug, not for release.
dryRun bool When set to true the compiled binary will not be copied to the export directory.
export_dir string Optional: save the build artifacts in this directory, the directory must exist.
programmer string External programmer for upload

CompileResp

Field Type Label Description
out_stream bytes The output of the compilation process.
err_stream bytes The error output of the compilation process.

Top

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

Platform

Field Type Label Description
ID string Platform ID (e.g., arduino:avr).
Installed string Version of the platform.
Latest string Newest available version of the platform.
Name string Name used to identify the platform to humans (e.g., "Arduino AVR Boards").
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.
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.

PlatformDownloadReq

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.

PlatformDownloadResp

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

PlatformInstallReq

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.

PlatformInstallResp

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.

PlatformListReq

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.
updatable_only bool Set to true to only list platforms which have a newer version available than the one currently installed.

PlatformListResp

Field Type Label Description
installed_platform Platform repeated The installed platforms.

PlatformSearchReq

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.
search_args string Keywords for the search.
all_versions bool Whether to show all available versions. false causes only the newest versions of the cores to be listed in the search results.

PlatformSearchResp

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

PlatformUninstallReq

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

PlatformUninstallResp

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

PlatformUpgradeReq

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

PlatformUpgradeResp

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.

Top

commands/lib.proto

DownloadResource

Field Type Label Description
url string Download URL of the library archive.
archivefilename string Filename of the library archive.
checksum string Checksum of the library archive.
size int64 File size of the library archive.
cachepath string The directory under the staging subdirectory of the data directory the library archive file will be downloaded to.

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 The library's directory name.
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).
real_name string Value of the name field in library.properties.
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.

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.
versionRequired string The required version of the library dependency.
versionInstalled string Version of the library dependency currently installed.

LibraryDownloadReq

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.

LibraryDownloadResp

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

LibraryInstallReq

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.

LibraryInstallResp

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

LibraryListReq

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.

LibraryListResp

Field Type Label Description
installed_library 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.

LibraryResolveDependenciesReq

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.

LibraryResolveDependenciesResp

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

LibrarySearchReq

Field Type Label Description
instance Instance Arduino Core Service instance from the Init response.
query string The search query.

LibrarySearchResp

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

LibraryUninstallReq

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.

LibraryUninstallResp

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

LibraryUpgradeAllReq

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

LibraryUpgradeAllResp

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.

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.

SearchedLibrary.ReleasesEntry

Field Type Label Description
key string
value LibraryRelease

LibraryLayout

Name Number Description
flat_layout 0 Library is in the 1.0 Arduino library format.
recursive_layout 1 Library is in the 1.5 Arduino library format.

LibraryLocation

Name Number Description
ide_builtin 0 In the libraries subdirectory of the Arduino IDE installation.
user 1 In the libraries subdirectory of the user directory (sketchbook).
platform_builtin 2 In the libraries subdirectory of a platform.
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.

LibrarySearchStatus

Name Number Description
failed 0 No search results were found.
success 1 Search results were found.

Top

commands/upload.proto

BurnBootloaderReq

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

BurnBootloaderResp

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.

ListProgrammersAvailableForUploadReq

Field Type Label Description
instance Instance
fqbn string

ListProgrammersAvailableForUploadResp

Field Type Label Description
programmers Programmer repeated

Programmer

Field Type Label Description
platform string
id string
name string

UploadReq

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 string 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 DEPRECATED: Use import_dir instead
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

UploadResp

Field Type Label Description
out_stream bytes The output of the upload process.
err_stream bytes The error output of the upload process.

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)