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