RPS Protocol Buffer File (rps.proto)

syntax = "proto3";

package rps_grpc;

service  RpsService {
    ////////////////////
    // Server Methods //
    ////////////////////

    // Gets the status of the server.
    rpc ServerGetStatus (ServerGetStatusRequest) returns (ServerGetStatusResponse);

    //////////////////
    // Core Methods //
    //////////////////

    // Aborts all Tasks and moves to Configuration state.
    rpc Abort (AbortRequest) returns (AbortResponse);

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

    // Commits settings to hardware and moves the session to Committed state. 
    rpc Commit (CommitRequest) returns (CommitResponse);

    // Gets the status of the session.
    rpc GetStatus (GetStatusRequest) returns (GetStatusResponse);

    // Creates a new session in Configuration state.
    // If the same session name of an existing session is used, no new session is created.
    rpc Initialize (InitializeRequest) returns (InitializeResponse);

    // Starts all tasks and moves to Running state.
    rpc Start (StartRequest) returns (StartResponse);

    ///////////////////////////////
    // Acquisition Task Methods  //
    ///////////////////////////////

    // Transfers acquired waveform data from instrument memory. The data transferred was acquired to onboard memory previously by the hardware after the acquisition was initiated.
    //   If Task is part of a Stream Configuration, returns an asynchronous data preview.
    //   If Task is not part of a Stream Configuration or Synchronization Configuration, returns a single asynchronous fetch per Start call.
    //   If Task is not part of a Stream Configuration and is part of a Synchronization Configuration, returns a single synchronous fetch per Start call.
    rpc AcquisitionFetchIQ (AcquisitionFetchIQRequest) returns (AcquisitionFetchIQResponse);

    // Gets the status of the specified acquisition task. Use this method to check for errors and if the task has completed the acquisition operation.
    rpc AcquisitionGetStatus (AcquisitionGetStatusRequest) returns (AcquisitionGetStatusResponse);

    // Sets the same RF bandwidth to each instrument in the specified task. Use this function in place of AcquisitionSetSampleRate.
    rpc AcquisitionSetBandwidth (AcquisitionSetBandwidthRequest) returns (AcquisitionSetBandwidthResponse);

    // Sets the number of samples to fetch by each instrument in the specified task.
    rpc AcquisitionSetFetchSize (AcquisitionSetFetchSizeRequest) returns (AcquisitionSetFetchSizeResponse);

    // Sets the same center frequency for each instrument in the specified task.
    rpc AcquisitionSetFrequency (AcquisitionSetFrequencyRequest) returns (AcquisitionSetFrequencyResponse);

    // Sets a center frequency for each instrument in the specified task.
    rpc AcquisitionSetFrequencies (AcquisitionSetFrequenciesRequest) returns (AcquisitionSetFrequenciesResponse);

    // Sets the LO signal source used to downconvert the RF input signal.
    rpc AcquisitionSetLO (AcquisitionSetLORequest) returns (AcquisitionSetLOResponse);

    // Sets the phase calibration parameters type for the specified task. All adjustments are relative to the reference instrument of the task.
    // The reference instrument is the first instrument listed in the task. To enable phase calibration the reference clocks, LO sharing, and synchronization
    //   all must be the same as when the calibration was performed. 
    rpc AcquisitionSetPhaseCal (AcquisitionSetPhaseCalRequest) returns (AcquisitionSetPhaseCalResponse);

    // Sets the reference clock for each instrument in the specified task.
    rpc AcquisitionSetReferenceClock (AcquisitionSetReferenceClockRequest) returns (AcquisitionSetReferenceClockResponse); 

    // Sets the same reference level for each instrument in the specified task. The reference level represents the maximum expected power of an input RF signal.
    rpc AcquisitionSetReferenceLevel (AcquisitionSetReferenceLevelRequest) returns (AcquisitionSetReferenceLevelResponse);

    // Sets the same IQ sample rate for each instrument in the specified task. Use this function in place of AcquisitionSetBandwidth.
    rpc AcquisitionSetSampleRate (AcquisitionSetSampleRateRequest) returns (AcquisitionSetSampleRateResponse);

    // Creates an Acquisition Task that configures the specified instruments. 
    rpc AcquisitionCreateTask (AcquisitionCreateTaskRequest) returns (AcquisitionCreateTaskResponse);

    ///////////////////////////////////////////
    // Synchronization Configuration Methods //
    ///////////////////////////////////////////

    // Creates a Synchronization Configuration to synchronize all instruments in the specified tasks from SynchronizationSetMasterTask and SynchronizationSetSlaveTask.
    // Only one Synchronization Configuration exists per session.
    rpc SynchronizationCreateConfiguration (SynchronizationCreateConfigurationRequest) returns (SynchronizationCreateConfigurationResponse);

    // Sets the specified task as the master synchronization reference in the Synchronization Configuration.
    rpc SynchronizationSetMasterTask (SynchronizationSetMasterTaskRequest) returns (SynchronizationSetMasterTaskResponse);

    // Sets the specified task(s) as a slave task(s) in the Synchronization Configuration.
    rpc SynchronizationSetSlaveTask (SynchronizationSetSlaveTaskRequest) returns (SynchronizationSetSlaveTaskResponse);

    //////////////////////////////////
    // Stream Configuration Methods //
    //////////////////////////////////

    // Creates a Stream Configuration of the specified type.
    rpc StreamCreateConfiguration (StreamCreateConfigurationRequest) returns (StreamCreateConfigurationResponse);

    // Gets the status of the Stream Configuration.
    rpc StreamGetStatus (StreamGetStatusRequest) returns (StreamGetStatusResponse);

    // Sets the destination endpoint of the specified Stream Configuration.
    rpc StreamSetDestinationEndpoint (StreamSetDestinationEndpointRequest) returns (StreamSetDestinationEndpointResponse);

    // Sets the source endpoint of the specified Stream Configuration.
    rpc StreamSetSourceEndpoint (StreamSetSourceEndpointRequest) returns (StreamSetSourceEndpointResponse);

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

    // Gets detailed error information from the specified status number.
    rpc GetErrorString(GetErrorStringRequest) returns (GetErrorStringResponse);

    // For an echo command and internal use. See messages for further details.
    rpc Message (MessageRequest) returns (MessageResponse);
}

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

message Session {
    string name = 1;
}

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

////////////////////////////
// Server Method Messages //
////////////////////////////

message ServerGetStatusRequest{}

message ServerGetStatusResponse{
    int32 status = 1;
    bool ready = 2;
    string message = 3;
}

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

message AbortRequest {
    Session session = 1;
}

message AbortResponse {
    int32 status = 1;
}

message CloseRequest {
    Session session = 1;

    // Not supported. In place for future implementations.
    bool session_only = 2;
}

message CloseResponse {
    int32 status = 1;
}

message CommitRequest {
    Session session = 1;
}

message CommitResponse {
    int32 status = 1;
}

message GetStatusRequest {
    Session session = 1;
}

message GetStatusResponse {
    int32 status = 1;
    repeated int32 logged_statuses = 2;
    State state = 3;
    bool ready = 4;
}

message InitializeRequest {
    string session_name = 1;

    // Not supported. In place for future implementations.
    string options = 10;
}

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

message StartRequest {
    Session session = 1;
}

message StartResponse {
    int32 status = 1;
}

/////////////////////////////////
// Acquisition Method Messages //
/////////////////////////////////

message AcquisitionGetStatusRequest{
    Session session = 1;
    string task_name = 2;
} 

message AcquisitionGetStatusResponse{
    int32 status = 1;
    int32 acquisition_status = 2;
    bool done = 3;
}

message AcquisitionSetBandwidthRequest{
    Session session = 1;
    string task_name = 2;

    // Defaults to 1 GHz.
    int64 bandwidth_hz = 3;
}

message AcquisitionSetBandwidthResponse{
    int32 status = 1;
}

message AcquisitionSetFetchSizeRequest{
    Session session = 1;
    string task_name = 2;
    
    // Defaults to 2048.
    int64 fetch_size = 4;
} 

message AcquisitionSetFetchSizeResponse{
    int32 status = 1;
}

message AcquisitionSetFrequencyRequest{
    Session session = 1;
    string task_name = 2;

    // Defaults to 5.5 GHz
    double center_frequency_hz = 3;
}

message AcquisitionSetFrequencyResponse{
    int32 status = 1;
}

message AcquisitionSetFrequenciesRequest{
    Session session = 1;
    string task_name = 2;

    // The number of center frequencies provided must match the number of instruments configured in the specified task. 
    repeated double center_frequencies_hz = 3;
}

message AcquisitionSetFrequenciesResponse{
    int32 status = 1;
}

message AcquisitionSetLORequest{
    Session session = 1;
    string task_name = 2;
    LOType lo_type = 3;

    // Not supported. In place for future implementations.
    string data = 4;
}

message AcquisitionSetLOResponse{
    int32 status = 1;
}

message AcquisitionSetPhaseCalRequest{
    Session session = 1;
    string task_name = 2;
    PhaseCalType phase_cal_type = 3;

    // Not supported. In place for future implementations.
    string data = 4;
}

message AcquisitionSetPhaseCalResponse{
    int32 status = 1;
}


message AcquisitionSetReferenceClockRequest{
    Session session = 1;
    string task_name = 2;

    // Defaults to "PXI_Clk".
    // If Task is part of a Synchronization Configuration, "PXI_Clk" is the only valid input. 
    // If Task is not part of a Synchronization Configuration, valid values are "Onboard" and "PXI_Clk".
    string reference_clock = 3;
} 

message AcquisitionSetReferenceClockResponse{
    int32 status = 1;
}

message AcquisitionSetReferenceLevelRequest{
    Session session = 1;
    string task_name = 2;

    // Defaults to 0 dBm.
    double reference_level = 3;
} 

message AcquisitionSetReferenceLevelResponse{
    int32 status = 1;
}

message AcquisitionSetSampleRateRequest{
    Session session = 1;
    string task_name = 2;

    // Defaults to 1.25 giga samples per second.
    int64 sample_rate = 3;
}

message AcquisitionSetSampleRateResponse{
    int32 status = 1;
}

message AcquisitionCreateTaskRequest{
    Session session = 1;
    string task_name = 2;

    // Comma separated string array of instrument names.
    string instrument_names = 4;

    // Not supported. In place for future implementations.
    string options = 10;
} 

message AcquisitionCreateTaskResponse{
    int32 status = 1;
}

message AcquisitionFetchIQRequest{
    Session session = 1;
    string task_name = 2;
} 

message AcquisitionFetchIQResponse{
    int32 status = 1;
    repeated ComplexWaveformIQ waveforms = 2;
}

///////////////////////////////////////////////////
// Synchronization Configuration Method Messages //
///////////////////////////////////////////////////

message SynchronizationCreateConfigurationRequest{
    Session session = 1;
    SynchronizationType sync_type = 2;
}

message SynchronizationCreateConfigurationResponse{
    int32 status = 1;
}

message SynchronizationSetMasterTaskRequest{
    Session session = 1;
    string task_name = 2;
}

message SynchronizationSetMasterTaskResponse{
    int32 status = 1;
}

message SynchronizationSetSlaveTaskRequest{
    Session session = 1;
    string task_name = 2; 
}

message SynchronizationSetSlaveTaskResponse{
    int32 status = 1;
}

//////////////////////////////////////////
// Stream Configuration Method Messages //
//////////////////////////////////////////

message StreamCreateConfigurationRequest{
    Session session = 1;
    string configuration_name = 2;
    StreamType stream_type = 3;

    // Length of stream of unit "length_unit".
    int64 length = 4;
    Unit length_unit = 5;

    // Not supported. In place for future implementations.
    string options = 10;
} 

message StreamCreateConfigurationResponse{
    int32 status = 1;
}

message StreamGetStatusRequest{
    Session session = 1;
    string configuration_name = 2;
}

message StreamGetStatusResponse{
    int32 status = 1;
    int32 stream_status = 2;
    repeated string task_name = 3;
    repeated string instrument_name = 4;
    repeated uint64 samples_to_stream = 5;
    repeated uint64 samples_streamed = 6;
    repeated bool overflow = 7;
    bool any_overflow = 8;
    bool done = 9;
}

message StreamSetDestinationEndpointRequest{
    Session session = 1;
    string configuration_name = 2;
    StreamDestinationEndpoint endpoint = 3;

    // Number of destinations specified must match the number of configured instruments.
    // Local Storage: comma-separated array of TDMS file locations.
    //   i.e. "F:\recording\file0.tdms,H:\recording\file1.tdms
    // Remote Storage: comma-separated array of folder names. 
    //   Folder names are created in locations specified by each data storage computer's configuration file. 
    //   File names are autogenerated with time stamps in each folder location for each instrument.
    //   i.e. "ch0,ch1"
    string data = 4;
} 

message StreamSetDestinationEndpointResponse{
    int32 status = 1;
}

message StreamSetSourceEndpointRequest{
    Session session = 1;
    string configuration_name = 2;
    StreamSourceEndpoint endpoint = 3;

    // Task name sourcing data to be recorded.
    string data = 4;
} 

message StreamSetSourceEndpointResponse{
    int32 status = 1;
}

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

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

// To use as an echo command, send an empty string for "name"
//   and "data" from MessageResponse will echo "data" from MessageRequest.
message MessageRequest{
    string name = 1;
    string data = 2;
}

message MessageResponse{
    string data = 1;
}

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

enum LOType {
    LO_TYPE_UNSPECIFIED = 0;
    LO_TYPE_NONE = 1;

    // Not supported. In place for future implementations.
    LO_TYPE_CUSTOM = 2;

    // LO daisy chain order expected in order instruments are listed in a task.
    LO_TYPE_DAISY_CHAIN = 10;

    // Not supported. In place for future implementations.
    LO_TYPE_STAR = 20;

    // Requires a valid, existing LO calibration file at the specified center frequency.
    LO_TYPE_STAR_CALIBRATED = 21;
}

enum PhaseCalType {
    PHASE_CAL_TYPE_UNSPECIFIED = 0;
    PHASE_CAL_TYPE_NONE = 1;

    // Calibration parameters to adjust sample clock delay, sub-sample clock delay,
    //   and phase offsets of each instrument relative to the reference instrument. 
    PHASE_CAL_TYPE_COHERENT = 10;

    // Calibration parameters to adjust all phase coherent parameters, equalization
    //   filters, and gain offsets of each instrument relative to the reference instrument.
    PHASE_CAL_TYPE_ALIGNED = 20;
}

enum State {
    STATE_UNSPECIFIED = 0;
    STATE_CONFIGURATION = 1;
    STATE_COMMITTED = 2;
    STATE_RUNNING = 3;
}

enum SynchronizationType {
    // Default, proper mode will be automatically selected
    SYNCHRONIZATION_TYPE_UNSPECIFIED = 0;

    // SCSCh = Single-Controller, Single-Chassis.
    // Synchronization signals are routed automatically.
    SYNCHRONIZATION_TYPE_SCSCH = 1; 

    // SCSMh = Single-Controller, Multi-Chassis.
    // Requires the synchronization routing file is configured properly.
    // Custom routing files are not supported. 
    SYNCHRONIZATION_TYPE_SCMCH = 2;  
}

enum StreamType {
    STREAM_TYPE_UNSPECIFIED = 0;

    // Streams data to TDMS files to RAIDs local to the same controller domain as the instruments.
    STREAM_TYPE_LOCAL_STORAGE = 10;

    // Streams data to binary files on external data storage computer(s).
    STREAM_TYPE_REMOTE_STORAGE = 20;
}

enum StreamSourceEndpoint {
    STREAM_SOURCE_ENDPOINT_UNSPECIFIED = 0;
    STREAM_SOURCE_ENDPOINT_TASK_NAME = 1;
}

enum StreamDestinationEndpoint {
    STREAM_DESTINATION_ENDPOINT_UNSPECIFIED = 0;
    STREAM_DESTINATION_ENDPOINT_FILE = 2;
}

enum Unit {
    UNIT_UNSPECIFIED = 0;
    UNIT_SAMPLE = 1;
    UNIT_SECOND = 2;
    UNIT_BYTE = 3;
}