commands.proto

// This file is part of arduino-cli.
//
// Copyright 2020 ARDUINO SA (http://www.arduino.cc/)
//
// This software is released under the GNU General Public License version 3,
// which covers the main part of arduino-cli.
// The terms of this license can be found at:
// https://www.gnu.org/licenses/gpl-3.0.en.html
//
// You can be released from the requirements of the above licenses by purchasing
// a commercial license. Buying such a license is mandatory if you want to
// modify or otherwise use the software for commercial activities involving the
// Arduino software without disclosing the source code of your own applications.
// To purchase a commercial license, send an email to license@arduino.cc.

syntax = "proto3";

package cc.arduino.cli.commands;

option go_package = "github.com/arduino/arduino-cli/rpc/commands";

import "commands/common.proto";
import "commands/board.proto";
import "commands/compile.proto";
import "commands/core.proto";
import "commands/upload.proto";
import "commands/lib.proto";

// The main Arduino Platform Service
service ArduinoCore {
  // BOOTSTRAP COMMANDS
  //-------------------

  // Start a new instance of the Arduino Core Service
  rpc Init(InitReq) returns (stream InitResp) {}

  // Destroy an instance of the Arduino Core Service
  rpc Destroy(DestroyReq) returns (DestroyResp) {}

  // Rescan instance of the Arduino Core Service
  rpc Rescan(RescanReq) returns (RescanResp) {}

  // Update package index of the Arduino Core Service
  rpc UpdateIndex(UpdateIndexReq) returns (stream UpdateIndexResp) {}

  // Update libraries index
  rpc UpdateLibrariesIndex(UpdateLibrariesIndexReq) returns (stream UpdateLibrariesIndexResp) {}

  // Update packages indexes for both Cores and Libraries
  rpc UpdateCoreLibrariesIndex(UpdateCoreLibrariesIndexReq) returns (stream UpdateCoreLibrariesIndexResp) {}

  // Outdated returns a message with a list of outdated Cores and Libraries
  rpc Outdated(OutdatedReq) returns (OutdatedResp) {}

  // Upgrade both Cores and Libraries
  rpc Upgrade(UpgradeReq) returns (stream UpgradeResp) {}

  // Get the version of Arduino CLI in use.
  rpc Version(VersionReq) returns (VersionResp) {}

  // Returns all files composing a Sketch
  rpc LoadSketch(LoadSketchReq) returns (LoadSketchResp) {}

  // Creates a zip file containing all files of specified Sketch
  rpc ArchiveSketch(ArchiveSketchReq) returns (ArchiveSketchResp) {}

  // BOARD COMMANDS
  // --------------

  // Requests details about a board
  rpc BoardDetails(BoardDetailsReq) returns (BoardDetailsResp);

  // 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.
  rpc BoardAttach(BoardAttachReq) returns (stream BoardAttachResp);

  // List the boards currently connected to the computer.
  rpc BoardList(BoardListReq) returns (BoardListResp);

  // List all the boards provided by installed platforms.
  rpc BoardListAll(BoardListAllReq) returns (BoardListAllResp);

  // List boards connection and disconnected events.
  rpc BoardListWatch(stream BoardListWatchReq) returns (stream BoardListWatchResp);

  // Compile an Arduino sketch.
  rpc Compile(CompileReq) returns (stream CompileResp);

  // Download and install a platform and its tool dependencies.
  rpc PlatformInstall(PlatformInstallReq) returns (stream PlatformInstallResp);

  // Download a platform and its tool dependencies to the `staging/packages`
  // subdirectory of the data directory.
  rpc PlatformDownload(PlatformDownloadReq) returns (stream PlatformDownloadResp);

  // Uninstall a platform as well as its tool dependencies that are not used by
  // other installed platforms.
  rpc PlatformUninstall(PlatformUninstallReq) returns (stream PlatformUninstallResp);

  // Upgrade an installed platform to the latest version.
  rpc PlatformUpgrade(PlatformUpgradeReq) returns (stream PlatformUpgradeResp);

  // Upload a compiled sketch to a board.
  rpc Upload(UploadReq) returns (stream UploadResp);

  // Upload a compiled sketch to a board using a programmer.
  rpc UploadUsingProgrammer(UploadUsingProgrammerReq) returns (stream UploadUsingProgrammerResp);

  // List programmers available for a board.
  rpc ListProgrammersAvailableForUpload(ListProgrammersAvailableForUploadReq) returns (ListProgrammersAvailableForUploadResp);

  // Burn bootloader to a board.
  rpc BurnBootloader(BurnBootloaderReq) returns (stream BurnBootloaderResp);

  // Search for a platform in the platforms indexes.
  rpc PlatformSearch(PlatformSearchReq) returns (PlatformSearchResp);

  // List all installed platforms.
  rpc PlatformList(PlatformListReq) returns (PlatformListResp);

  // Download the archive file of an Arduino library in the libraries index to
  // the staging directory.
  rpc LibraryDownload(LibraryDownloadReq) returns (stream LibraryDownloadResp);

  // Download and install an Arduino library from the libraries index.
  rpc LibraryInstall(LibraryInstallReq) returns (stream LibraryInstallResp);

  // Install a library from a Zip File 
  rpc ZipLibraryInstall(ZipLibraryInstallReq) returns (stream ZipLibraryInstallResp);

  // Download and install a library from a git url
  rpc GitLibraryInstall(GitLibraryInstallReq) returns (stream GitLibraryInstallResp);

  // Uninstall an Arduino library.
  rpc LibraryUninstall(LibraryUninstallReq) returns (stream LibraryUninstallResp);

  // Upgrade all installed Arduino libraries to the newest version available.
  rpc LibraryUpgradeAll(LibraryUpgradeAllReq) returns (stream LibraryUpgradeAllResp);

  // List the recursive dependencies of a library, as defined by the `depends`
  // field of the library.properties files.
  rpc LibraryResolveDependencies(LibraryResolveDependenciesReq) returns (LibraryResolveDependenciesResp);

  // Search the Arduino libraries index for libraries.
  rpc LibrarySearch(LibrarySearchReq) returns (LibrarySearchResp);

  // List the installed libraries.
  rpc LibraryList(LibraryListReq) returns (LibraryListResp);
}

message InitReq {
  // Start a Arduino Core Service instance that will provide only Library
  // Manager functionality.
  bool library_manager_only = 2;
}

message InitResp {
  // An Arduino Core Service instance.
  Instance instance = 1;
  // Error messages related to any problems encountered while parsing the
  // platforms index files.
  repeated string platforms_index_errors = 2;
  // Error message if a problem was encountered while parsing the libraries
  // index file.
  string libraries_index_error = 3;
  // Progress of the downloads of platforms and libraries index files.
  DownloadProgress download_progress = 4;
  // Describes the current stage of the initialization.
  TaskProgress task_progress = 5;
}

message DestroyReq {
  // The Arduino Core Service instance to destroy.
  Instance instance = 1;
}
message DestroyResp {}

message RescanReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;
}

message RescanResp {
  // Error messages related to any problems encountered while parsing the
  // platforms index file.
  repeated string platforms_index_errors = 1;
  // Error message if a problem was encountered while parsing the libraries
  // index file.
  string libraries_index_error = 2;
}

message UpdateIndexReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;
}

message UpdateIndexResp {
  // Progress of the platforms index download.
  DownloadProgress download_progress = 1;
}

message UpdateLibrariesIndexReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;
}

message UpdateLibrariesIndexResp {
  // Progress of the libraries index download.
  DownloadProgress download_progress = 1;
}

message UpdateCoreLibrariesIndexReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;
}

message UpdateCoreLibrariesIndexResp {
  // Progress of the index download.
  DownloadProgress download_progress = 1;
}

message OutdatedReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;
}

message OutdatedResp {
  // List of installed libraries that can be updated.
  repeated InstalledLibrary outdated_library = 1;
  // List of installed cores that can be updated.
  repeated Platform outdated_platform = 2;
}

message UpgradeReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;

  // Set to true to not run (eventual) post install scripts
  bool skipPostInstall = 2;
}

message UpgradeResp {
  // Progress of the downloads of the platforms and libraries files.
  DownloadProgress progress = 1;
  // Description of the current stage of the upgrade.
  TaskProgress task_progress = 2;
}

message VersionReq {}

message VersionResp {
  // The version of Arduino CLI in use.
  string version = 1;
}

message LoadSketchReq {
  // Arduino Core Service instance from the Init response.
  Instance instance = 1;
  // Absolute path to single sketch file or a sketch folder
  string sketch_path = 2;
}

message LoadSketchResp {
  // Absolute path to a main sketch files
  string main_file = 1;
  // Absolute path to folder that contains main_file
  string location_path = 2;
  // List of absolute paths to other sketch files
  repeated string other_sketch_files = 3;
  // List of absolute paths to additional sketch files
  repeated string additional_files = 4;
}

message ArchiveSketchReq{
  // Absolute path to Sketch file or folder containing Sketch file
  string sketch_path = 1;
  // Absolute path to archive that will be created or folder that will contain it
  string archive_path = 2;
  // Specifies if build directory should be included in the archive
  bool include_build_dir = 3;
}

message ArchiveSketchResp { }