// 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";

import "cc/arduino/cli/commands/v1/common.proto";

message BoardDetailsRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // The fully qualified board name of the board you want information about
  // (e.g., `arduino:avr:uno`).
  string fqbn = 2;
}

message BoardDetailsResponse {
  // The fully qualified board name of the board.
  string fqbn = 1;
  // Name used to identify the board to humans (e.g., Arduino Uno).
  string name = 2;
  // Installed version of the board's platform.
  string version = 3;
  // The board ID component of the FQBN (e.g., `uno`).
  string properties_id = 4;
  // Board alias that can be used as a more user friendly alternative to the
  // FQBN.
  string alias = 5;
  // Whether this is an official or 3rd party board.
  bool official = 6;
  // URL of the board's pinout documentation.
  string pinout = 7;
  // Data about the package that contains the board's platform.
  Package package = 8;
  // Data about the board's platform.
  BoardPlatform platform = 9;
  // Tool dependencies of the board.
  repeated ToolsDependencies tools_dependencies = 10;
  // The board's custom configuration options.
  repeated ConfigOption config_options = 11;
  // Identifying information for the board (e.g., USB VID/PID).
  repeated IdentificationPref identification_prefs = 12;
  // List of programmers supported by the board
  repeated Programmer programmers = 13;
  // Set to true if the board supports debugging
  bool debugging_supported = 14;
}

message IdentificationPref {
  // Identifying information for USB-connected boards.
  USBID usb_id = 1;
}

message USBID {
  // USB vendor ID.
  string vid = 1;
  // USB product ID.
  string pid = 2;
}

message Package {
  // Maintainer of the package.
  string maintainer = 1;
  // The URL of the platforms index file
  // (e.g., https://downloads.arduino.cc/packages/package_index.json).
  string url = 2;
  // A URL provided by the package author, intended to point to their website.
  string website_url = 3;
  // Email address of the package maintainer.
  string email = 4;
  // Package vendor name.
  string name = 5;
  // Resources for getting help about using the package.
  Help help = 6;
}

message Help {
  // URL for getting online help.
  string online = 1;
}

message BoardPlatform {
  // Architecture of the platform (e.g., `avr`).
  string architecture = 1;
  // Category of the platform. Set to `Contributed` for 3rd party platforms.
  string category = 2;
  // Download URL of the platform archive file.
  string url = 3;
  // File name of the platform archive.
  string archive_filename = 4;
  // Checksum of the platform archive.
  string checksum = 5;
  // File size of the platform archive.
  int64 size = 6;
  // Name used to identify the platform to humans.
  string name = 7;
}

message ToolsDependencies {
  // Vendor name of the package containing the tool definition.
  string packager = 1;
  // Tool name.
  string name = 2;
  // Tool version.
  string version = 3;
  // Data for the operating system-specific builds of the tool.
  repeated Systems systems = 4;
}

message Systems {
  // Checksum of the tool archive.
  string checksum = 1;
  // Operating system identifier.
  string host = 2;
  // File name of the tool archive.
  string archive_filename = 3;
  // Download URL of the tool archive.
  string url = 4;
  // File size of the tool archive.
  int64 size = 5;
}

message ConfigOption {
  // ID of the configuration option. For identifying the option to machines.
  string option = 1;
  // Name of the configuration option for identifying the option to humans.
  string option_label = 2;
  // Possible values of the configuration option.
  repeated ConfigValue values = 3;
}

message ConfigValue {
  // The configuration option value.
  string value = 1;
  // Label to identify the configuration option to humans.
  string value_label = 2;
  // Whether the configuration option is selected.
  bool selected = 3;
}

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

message BoardAttachResponse {
  // Description of the current stage of the board attachment.
  TaskProgress task_progress = 1;
}

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

message BoardListResponse {
  // List of ports and the boards detected on those ports.
  repeated DetectedPort ports = 1;
}

message DetectedPort {
  // Address of the port (e.g., `serial:///dev/ttyACM0`).
  string address = 1;
  // Protocol of the port (e.g., `serial`).
  string protocol = 2;
  // A human friendly description of the protocol (e.g., "Serial Port (USB)").
  string protocol_label = 3;
  // The boards attached to the port.
  repeated BoardListItem boards = 4;
  // Serial number of connected board
  string serial_number = 5;
}

message BoardListAllRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // The search query to filter the board list by.
  repeated string search_args = 2;
  // Set to true to get also the boards marked as "hidden" in the platform
  bool include_hidden_boards = 3;
}

message BoardListAllResponse {
  // List of installed boards.
  repeated BoardListItem boards = 1;
}

message BoardListWatchRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // Set this to true to stop the discovery process
  bool interrupt = 2;
}

message BoardListWatchResponse {
  // Event type as received from the serial discovery tool
  string event_type = 1;
  // Information about the port
  DetectedPort port = 2;
  // Eventual errors when detecting connected boards
  string error = 3;
}

message BoardListItem {
  // The name for use when identifying the board to a human.
  string name = 1;
  // The fully qualified board name. Used to identify the board to a machine.
  string fqbn = 2;
  // If the board is marked as "hidden" in the platform
  bool is_hidden = 3;
  // Vendor ID
  string vid = 4;
  // Product ID
  string pid = 5;
  // Platform this board belongs to
  Platform platform = 6;
}

message BoardSearchRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // The search query to filter the board list by.
  string search_args = 2;
  // Set to true to get also the boards marked as "hidden" in installed
  // platforms
  bool include_hidden_boards = 3;
}

message BoardSearchResponse {
  // List of installed and installable boards.
  repeated BoardListItem boards = 1;
}
