syntax = "proto3";

package icsclocal_grpc;

service  ICscLOCalService {
    //////////////////
    // Core Methods //
    //////////////////

    // Aborts a calibration and moves to Idle state.
    rpc Abort (AbortRequest) returns (AbortResponse);

    // Closes the session.
    rpc Close (CloseRequest) returns (CloseResponse);

    // Returns the current status of the calibration.
    rpc GetStatus (GetStatusRequest) returns (GetStatusResponse);

    // Initializes a session in the Idle state.
    rpc Initialize (InitializeRequest) returns (InitializeResponse);

    // Starts the calibration and moves to the Active state.
    rpc Start (StartRequest) returns (StartResponse);

    /////////////////////////////
    // Sweep Parameter Methods //
    /////////////////////////////

    //Sets the calibration measurement parameters.
    rpc SetMeasurementParameters (SetMeasurementParametersRequest) returns (SetMeasurementParametersResponse);
    
    // Sets the frequency sweep parameters.
    rpc SetFrequencySweep (SetFrequencySweepRequest) returns (SetFrequencySweepResponse);

    //////////////////////
    // Advanced Methods //
    //////////////////////

    // Clears the stored errors in the session.
    rpc ClearError (ClearErrorRequest) returns (ClearErrorResponse);

    // Returns detailed error information associated with the specified error code.
    rpc GetErrorString (GetErrorStringRequest) returns (GetErrorStringResponse);

    // Internal use.
    rpc Message (MessageRequest) returns (MessageResponse);

    //////////////////////
    // Calibration File //
    //////////////////////

    // Clears the calibration file associated with the specified calibration mode.
    rpc ClearCalFile (ClearCalFileRequest) returns (ClearCalFileResponse);

    // Returns the contents of the calibration file associated with the specified calibration mode.
    rpc ReadCalFile (ReadCalFileRequest) returns (ReadCalFileResponse);
  }

//////////////////////
// Commons Messages //
//////////////////////

message Session {
    string name = 1;
}

//////////////////////////
// Core Method Messages //
//////////////////////////

message AbortRequest{
    Session session = 1;
}

message AbortResponse{
    int32 status = 1;
}

message CloseRequest{
    Session session = 1;
}

message CloseResponse{
    int32 status = 1;
}

message GetStatusRequest{
    Session session = 1;
}

message GetStatusResponse{
    int32 status = 1;
    CalState cal_state = 2;

    // TRUE only if the calibration was successful.
    bool pass = 3; 

    // TRUE when the calibration is complete regardless if it passed or failed. 
    bool complete = 4;
}

message InitializeRequest{
    string session_name = 1;

    CalMode cal_mode = 2;

    // Names of the instruments performing the power measurements. 
    // Comma separated string with two or more instruments.
    string acquisition_instruments = 3;

    // Name of LO source instrument.
    string lo_source = 4;

    // Valid inputs are "0" or "1".
    string lo_source_port = 5;

    // Name of amplifier instrument.
    string amplifier = 6;

    // Valid inputs are "0" or "1".
    string amplifier_port = 7;
}

message InitializeResponse{
    int32 status = 1;
    Session session = 2;
}

message StartRequest{
    Session session = 1;
}

message StartResponse{
    int32 status = 1;
}

/////////////////////////////////////
// Sweep Parameter Method Messages //
/////////////////////////////////////

message SetMeasurementParametersRequest{
    Session session = 1;

    // Lowest expected path loss for splitter and cable network for the calibration cabling. 
    // Used to calculate the reference level of the acquisition instruments. 
    // Defaults to 0 dB.
    double path_loss = 2;

    // Measurement headroom in dB. 
    // Used to calculate the reference level of the acquisition instruments. 
    // Defaults to 0 dB.
    double headroom = 3;

    // Desired power level for the calibration to achieve. 
    // Vaid values are -4 dBm to 0 dBm. Defaults to -1 dBm.
    double power_target = 4;
}

message SetMeasurementParametersResponse{
    int32 status = 1;
}

message SetFrequencySweepRequest{
    Session session = 1;

    double start = 3;
    double end = 4;

    // If start equals end, delta is ignored
    double delta = 5;
} 

message SetFrequencySweepResponse{
    int32 status = 1;
} 

//////////////////////////////
// Advanced Method Messages //
//////////////////////////////

message ClearErrorRequest {
    Session session = 1;
}
  
message ClearErrorResponse {
    int32 status = 1;
}

message GetErrorStringRequest {
    Session session = 1;
    int32 error_code = 2;
}
  
message GetErrorStringResponse {
    int32 status = 1;
    string error_string = 2;
}


message MessageRequest{
    string name = 1;
    string data = 2;
}

message MessageResponse{
    string data = 1;
}

///////////////////////////////
// Calibration File Messages //
///////////////////////////////

message ClearCalFileRequest{
    CalMode cal_mode = 1;
}

message ClearCalFileResponse{
    int32 status =1;
}

message ReadCalFileRequest{
    CalMode cal_type = 1;
}

message ReadCalFileResponse{
    int32 status = 1;
    string cal_date = 2;
    string lo_source = 3;
    string lo_source_port = 4;
    string amplifier = 5;
    string amplifier_port = 6;

    // List of calibrated frequencies. 
    repeated double frequencies = 7;
}

///////////
// Enums //
///////////

enum CalMode {
    CAL_MODE_UNSPECIFIED = 0;

    // Creates a file containing the parameters for the LO source and amplifier to achieve the target power. 
    CAL_MODE_ACQUISITION_LO_STAR = 1;

    // Not supported. In place for future implementations. 
    CAL_MODE_GENERATION_LO_STAR = 11;
}

enum CalState { 
    CAL_STATE_UNSPECIFIED = 0;
    CAL_STATE_ACTIVE = 1;
    CAL_STATE_INACTIVE = 2;
}