Skip to content

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.
PlatformSearch PlatformSearchReq PlatformSearchResp Search for a platform in the platforms indexes.
PlatformList PlatformListReq PlatformListResp List all installed platforms.
LibraryDownload LibraryDownloadReq LibraryDownloadResp stream
LibraryInstall LibraryInstallReq LibraryInstallResp stream
LibraryUninstall LibraryUninstallReq LibraryUninstallResp stream
LibraryUpgradeAll LibraryUpgradeAllReq LibraryUpgradeAllResp stream
LibraryResolveDependencies LibraryResolveDependenciesReq LibraryResolveDependenciesResp
LibrarySearch LibrarySearchReq LibrarySearchResp
LibraryList LibraryListReq LibraryListResp

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.

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
archivefilename string
checksum string
size int64
cachepath string

InstalledLibrary

Field Type Label Description
library Library
release LibraryRelease

Library

Field Type Label Description
name string
author string
maintainer string
sentence string
paragraph string
website string
category string
architectures string repeated
types string repeated
install_dir string
source_dir string
utility_dir string
container_platform string
real_name string
dot_a_linkage bool
precompiled bool
ld_flags string
is_legacy bool
version string
license string
properties Library.PropertiesEntry repeated
location LibraryLocation
layout LibraryLayout

Library.PropertiesEntry

Field Type Label Description
key string
value string

LibraryDependency

Field Type Label Description
name string
version_constraint string

LibraryDependencyStatus

Field Type Label Description
name string
versionRequired string
versionInstalled string

LibraryDownloadReq

Field Type Label Description
instance Instance
name string
version string

LibraryDownloadResp

Field Type Label Description
progress DownloadProgress

LibraryInstallReq

Field Type Label Description
instance Instance
name string
version string

LibraryInstallResp

Field Type Label Description
progress DownloadProgress
task_progress TaskProgress

LibraryListReq

Field Type Label Description
instance Instance
all bool
updatable bool

LibraryListResp

Field Type Label Description
installed_library InstalledLibrary repeated

LibraryRelease

Field Type Label Description
author string
version string
maintainer string
sentence string
paragraph string
website string
category string
architectures string repeated
types string repeated
resources DownloadResource
license string
provides_includes string repeated
dependencies LibraryDependency repeated

LibraryResolveDependenciesReq

Field Type Label Description
instance Instance
name string
version string

LibraryResolveDependenciesResp

Field Type Label Description
dependencies LibraryDependencyStatus repeated

LibrarySearchReq

Field Type Label Description
instance Instance
query string

LibrarySearchResp

Field Type Label Description
libraries SearchedLibrary repeated
status LibrarySearchStatus

LibraryUninstallReq

Field Type Label Description
instance Instance
name string
version string

LibraryUninstallResp

Field Type Label Description
task_progress TaskProgress

LibraryUpgradeAllReq

Field Type Label Description
instance Instance

LibraryUpgradeAllResp

Field Type Label Description
progress DownloadProgress
task_progress TaskProgress

SearchedLibrary

Field Type Label Description
name string
releases SearchedLibrary.ReleasesEntry repeated
latest LibraryRelease

SearchedLibrary.ReleasesEntry

Field Type Label Description
key string
value LibraryRelease

LibraryLayout

Name Number Description
flat_layout 0
recursive_layout 1

LibraryLocation

Name Number Description
ide_builtin 0
user 1 (sketchbook)
platform_builtin 2
referenced_platform_builtin 3

LibrarySearchStatus

Name Number Description
failed 0
success 1

Top

commands/upload.proto

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.

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)