syntax = "proto3";

package icscphasecal_grpc;

service  ICscPhaseCalService {
    //////////////////
    // 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 bandwidth sweep parameters.
    rpc SetBandwidthSweep (SetBandwidthSweepRequest) returns (SetBandwidthSweepResponse);

    // Sets the frequency sweep parameters.
    rpc SetFrequencySweep (SetFrequencySweepRequest) returns (SetFrequencySweepResponse);

    // Sets the level sweep parameters.
    rpc SetLevelSweep (SetLevelSweepRequest) returns (SetLevelSweepResponse); 

    //////////////////////
    // 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 CalVector{
    // Center frequency in Hz.
    double frequency = 1;

    // Reference level in dBm.
    double level = 2;

    // Instantaneous bandwidth centered at "frequency" in Hz.
    double bandwidth = 3;
}

message ComplexWaveformIQ {
    double t0 = 1;
    double dt = 2;
    repeated double i = 3;
    repeated double q = 4;
}

message Session {
    string name = 1;
}

message XYData {
    repeated double x = 1;
    repeated double y = 2;
}

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

    // Number of frequencies times number of levels times the number of bandwidths listed in each sweep. 
    int32 total_cal_points = 3;
    int32 current_cal_point = 4;

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

    // TRUE when the calibration is complete regardless if it passed or failed. 
    bool complete = 6;
    double current_freq = 7;
    double current_level = 8;
    double current_bandwidth = 9;

    // Preview of the relative phase difference at the current calibration point. 
    // X is the offset from the center frequency.
    // Y is the relative phase difference relative to the reference instrument. 
    repeated XYData phase_difference = 10;

    // Preview of the relative magnitude difference at the current calibration point. 
    // X is the offset from the center frequency.
    // Y is the relative magnitude difference relative to the reference instrument. 
    repeated XYData magnitude_difference = 11;
}

message InitializeRequest{
    string session_name = 1;

    CalMode cal_mode = 2;

    // Comma separated string with two or more instruments. The first instrument listed is considered the reference instrument.
    string calibration_instruments = 3;

    // Optional: Defaults to FALSE.
    // Enable if the calibration instruments are in different chassis. 
    // Requires timing and sync hardware, cabled connections, and configuration file are already in place. See user manual for more details.  
    bool enable_multichassis_sync = 4;

    // Name of the instrument providing the signal source for the acquisition calibration.
    string signal_source = 5;
}

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

message StartRequest{
    Session session = 1;
}

message StartResponse{
    int32 status = 1;
}

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

message SetBandwidthSweepRequest{
    Session session = 1;
    double start = 2;
    double end = 3;

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

message SetBandwidthSweepResponse{
    int32 status = 1;
}

message SetFrequencySweepRequest{
    Session session = 1;

    // If lo_type = "star": start = -1 >> use all frequencies from LO power cal file, other parameters ignored
    // If lo_type = "star": start >/= 0 and end >/= start, use all frequencies from file in that range, delta ignored
    // lo_type = any other string: all other parameters are required
    string lo_type = 2;

    double start = 3;
    double end = 4;

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

message SetFrequencySweepResponse{
    int32 status = 1;
} 

message SetLevelSweepRequest{
    Session session = 1;

    // Lowest expected path loss for splitter and cable network for the calibration cabling. 
    double path_loss = 2;

    double start = 3;
    double end = 4;

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

message SetLevelSweepResponse{
    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_mode = 1;
}

message ReadCalFileResponse{
    int32 status = 1;
    string cal_date = 2;

    // Comma separated string.
    string calibration_instruments = 3;

    // List of available calibration vectors.
    repeated CalVector cal_vectors = 4;

    // LO configuration used during calibration.
    string lo_type = 5;
}

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

enum CalMode {
    CAL_MODE_UNSPECIFIED = 0;

    // Creates a file containing the sample clock delay, sub-sample clock delay, and phase offset adjustments relative to the refence instrument. 
    CAL_MODE_ACQUISITION_PHASE_COHERENT = 1;

    // Completes all steps of phase coherent calibration. Creates an additional file containing the sample clock delay, sub-sample clock delay, 
    // phase offset, gain offset, and equalization filter adjustments relative to the refence instrument. 
    CAL_MODE_ACQUISITION_PHASE_ALIGNED = 2;

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

    // Not supported. In place for future implementations.
    CAL_MODE_GENERATION_PHASE_ALIGNED = 12;
}

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