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

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

message UploadRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // 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 the `BoardAttach` method is used.
  string fqbn = 2;
  // Path where the sketch to be uploaded is stored. Unless the `import_file`
  // field is defined, the compiled binary is assumed to be at the location and
  // filename under this path where it is saved by the `Compile` method.
  string sketch_path = 3;
  // The port of the board.
  Port port = 4;
  // Whether to turn on verbose output during the upload.
  bool verbose = 5;
  // After upload, verify that the contents of the memory on the board match the
  // uploaded binary.
  bool verify = 6;
  // When `import_file` is specified, it overrides the `import_dir` and
  // `sketch_path` params.
  string import_file = 7;
  // Custom path to a directory containing compiled files. When `import_dir` is
  // not specified, the standard build directory under `sketch_path` is used.
  string import_dir = 8;
  // 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.
  string programmer = 9;
  // If set to true, the actual upload will not be performed but a trace output
  // will be printed stdout. This is for debugging purposes.
  bool dry_run = 10;
  // 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
  map<string, string> user_fields = 11;
}

message UploadResponse {
  // The output of the upload process.
  bytes out_stream = 1;
  // The error output of the upload process.
  bytes err_stream = 2;
}

message ProgrammerIsRequiredForUploadError {}

message UploadUsingProgrammerRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // 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 the `BoardAttach` method is used.
  string fqbn = 2;
  // Path where the sketch to be uploaded is stored. Unless the `import_file`
  // field is defined, the compiled binary is assumed to be at the location and
  // filename under this path where it is saved by the `Compile` method.
  string sketch_path = 3;
  // The port of the board.
  Port port = 4;
  // Whether to turn on verbose output during the upload.
  bool verbose = 5;
  // After upload, verify that the contents of the memory on the board match the
  // uploaded binary.
  bool verify = 6;
  // When `import_file` is specified, it overrides the `import_dir` and
  // `sketch_path` params.
  string import_file = 7;
  // Custom path to a directory containing compiled files. When `import_dir` is
  // not specified, the standard build directory under `sketch_path` is used.
  string import_dir = 8;
  // The programmer to use for upload.
  string programmer = 9;
  // If set to true, the actual upload will not be performed but a trace output
  // will be printed stdout. This is for debugging purposes.
  bool dry_run = 10;
  // 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
  map<string, string> user_fields = 11;
}

message UploadUsingProgrammerResponse {
  // The output of the upload process.
  bytes out_stream = 1;
  // The error output of the upload process.
  bytes err_stream = 2;
}

message BurnBootloaderRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // Fully qualified board name of the target board (e.g., `arduino:avr:uno`).
  string fqbn = 2;
  // The port of the programmer used to program the bootloader.
  Port port = 3;
  // Whether to turn on verbose output during the programming.
  bool verbose = 4;
  // After programming, verify the contents of the memory on the board match the
  // uploaded binary.
  bool verify = 5;
  // The programmer to use for burning bootloader.
  string programmer = 6;
  // If set to true, the actual upload will not be performed but a trace output
  // will be printed stdout. This is for debugging purposes.
  bool dry_run = 7;
  // 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
  map<string, string> user_fields = 11;
}

message BurnBootloaderResponse {
  // The output of the burn bootloader process.
  bytes out_stream = 1;
  // The error output of the burn bootloader process.
  bytes err_stream = 2;
}

message ListProgrammersAvailableForUploadRequest {
  Instance instance = 1;
  string fqbn = 2;
}

message ListProgrammersAvailableForUploadResponse {
  repeated Programmer programmers = 1;
}

message SupportedUserFieldsRequest {
  Instance instance = 1;
  string fqbn = 2;
  // Protocol that will be used to upload, this information is
  // necessary to pick the right upload tool for the board specified
  // with the FQBN.
  string protocol = 3;
}

message UserField {
  // Id of the tool that supports this field
  string tool_id = 1;
  // Name used internally to store and retrieve this field
  string name = 2;
  // Label is the text shown to the user when they need to input this field
  string label = 3;
  // True if the value of the field must not be shown when typing, for example
  // when the user inputs a network password
  bool secret = 4;
}

message SupportedUserFieldsResponse {
  // User fields supported by board specified in SupportedUserFieldsRequest.
  // If board doesn't support any field it will be empty.
  repeated UserField user_fields = 1;
}