board.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";

message BoardDetailsReq {
    // 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 BoardDetailsResp {
    // 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 propertiesId = 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 toolsDependencies = 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_pref = 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 usbID = 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 websiteURL = 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 archiveFileName = 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 archiveFileName = 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 BoardAttachReq {
    // 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 BoardAttachResp {
    // Description of the current stage of the board attachment.
    TaskProgress task_progress = 1;
}

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

message BoardListResp {
    // 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;
}

message BoardListAllReq {
    // 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 BoardListAllResp {
    // List of installed boards.
    repeated BoardListItem boards = 1;
}

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

message BoardListWatchResp {
    // 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;
}