common.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.v1;

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

message Instance {
  // The ID of the instance.
  int32 id = 1;
}

message DownloadProgress {
  oneof message {
    DownloadProgressStart start = 1;
    DownloadProgressUpdate update = 2;
    DownloadProgressEnd end = 3;
  }
}

message DownloadProgressStart {
  // URL of the download.
  string url = 1;
  // The label to display on the progress bar.
  string label = 2;
}

message DownloadProgressUpdate {
  // Size of the downloaded portion of the file.
  int64 downloaded = 1;
  // Total size of the file being downloaded.
  int64 total_size = 2;
}

message DownloadProgressEnd {
  // True if the download is successful
  bool success = 1;
  // Info or error message, depending on the value of 'success'. Some examples:
  // "File xxx already downloaded" or "Connection timeout"
  string message = 2;
}

message TaskProgress {
  // Description of the task.
  string name = 1;
  // Additional information about the task.
  string message = 2;
  // Whether the task is complete.
  bool completed = 3;
  // Amount in percent of the task completion (optional)
  float percent = 4;
}

message Programmer {
  // Platform name
  string platform = 1;
  // Programmer ID
  string id = 2;
  // Programmer name
  string name = 3;
}

// MissingProgrammerError is a status error detail that is returned when
// the operation can not be completed due to a missing programmer argument.
message MissingProgrammerError {}

// Platform is a structure containing all the information about a single
// platform release.
message Platform {
  // Generic information about a platform
  PlatformMetadata metadata = 1;
  // Information about a specific release of a platform
  PlatformRelease release = 2;
}

// PlatformSummary is a structure containing all the information about
// a platform and all its available releases.
message PlatformSummary {
  // Generic information about a platform
  PlatformMetadata metadata = 1;
  // Maps version to the corresponding PlatformRelease
  map<string, PlatformRelease> releases = 2;
  // The installed version of the platform, or empty string if none installed
  string installed_version = 3;
  // The latest available version of the platform that can be installable, or
  // empty if none available.
  string latest_version = 4;
}

// PlatformMetadata contains generic information about a platform (not
// correlated to a specific release).
message PlatformMetadata {
  // Platform ID (e.g., `arduino:avr`).
  string id = 1;
  // Maintainer of the platform's package.
  string maintainer = 2;
  // A URL provided by the author of the platform's package, intended to point
  // to their website.
  string website = 3;
  // Email of the maintainer of the platform's package.
  string email = 4;
  // If true this Platform has been installed manually in the user' sketchbook
  // hardware folder
  bool manually_installed = 5;
  // True if the latest release of this Platform has been deprecated
  bool deprecated = 6;
  // If true the platform is indexed
  bool indexed = 7;
}

// PlatformRelease contains information about a specific release of a platform.
message PlatformRelease {
  // Name used to identify the platform to humans (e.g., "Arduino AVR Boards").
  string name = 1;
  // Version of the platform release
  string version = 2;
  // Type of the platform.
  repeated string type = 3;
  // True if the platform is installed
  bool installed = 4;
  // 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.
  repeated Board boards = 5;
  // A URL provided by the author of the platform's package, intended to point
  // to their online help service.
  HelpResources help = 6;
  // This field is true if the platform is missing installation metadata (this
  // happens if the platform has been installed with the legacy Arduino IDE
  // <=1.8.x). If the platform miss metadata and it's not indexed through a
  // package index, it may fail to work correctly in some circumstances, and it
  // may need to be reinstalled. This should be evaluated only when the
  // PlatformRelease is `Installed` otherwise is an undefined behaviour.
  bool missing_metadata = 7;
  // True this release is deprecated
  bool deprecated = 8;
  // True if the platform dependencies are available for the current OS/ARCH.
  // This also means that the platform is installable.
  bool compatible = 9;
}

message InstalledPlatformReference {
  // Platform ID (e.g., `arduino:avr`).
  string id = 1;
  // Version of the platform.
  string version = 2;
  // Installation directory of the platform
  string install_dir = 3;
  // 3rd party platform URL
  string package_url = 4;
}

message Board {
  // Name used to identify the board to humans.
  string name = 1;
  // Fully qualified board name used to identify the board to machines. The FQBN
  // is only available for installed boards.
  string fqbn = 2;
}

message HelpResources {
  // A URL provided by the author of the platform's package, intended to point
  // to their online help service.
  string online = 1;
}

message Sketch {
  // 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;
  // List of absolute paths to supported files in the sketch root folder, main
  // file excluded
  repeated string root_folder_files = 5;
  // Default FQBN set in project file (sketch.yaml)
  string default_fqbn = 6;
  // Default Port set in project file (sketch.yaml)
  string default_port = 7;
  // Default Protocol set in project file (sketch.yaml)
  string default_protocol = 8;
  // List of profiles present in the project file (sketch.yaml)
  repeated SketchProfile profiles = 9;
  // Default profile set in the project file (sketch.yaml)
  SketchProfile default_profile = 10;
}

message SketchProfile {
  // Name of the profile
  string name = 1;
  // FQBN used by the profile
  string fqbn = 2;
}