// NOTICE: SEMI makes no warranties or representations as to the suitability of
// the standards set forth herein for any particular application. The
// determination of the suitability of the standard is solely the responsibility
// of the user. Users are cautioned to refer to manufacturer's instructions,
// product labels, product data sheets, and other relevant literature,
// respecting any materials or equipment mentioned herein. These standards
// are subject to change without notice.
//
// By publication of this standard, Semiconductor Equipment and Materials
// International (SEMI) takes no position respecting the validity of any patent
// rights or copyrights asserted in connection with any items mentioned in this
// standard. Users of this standard are expressly advised that determination of
// any such patent rights or copyrights, and the risk of infringement of such
// rights are entirely their own responsibility.

// This proto file will define representations of objects in SEMI E125 in the Protocol Buffer 3 language

syntax = "proto3";

package semi;

// Import statements allow Protocol Buffer messages defined in this .proto file to use
// Protocol Buffer messages defined in other .proto files
// Import statements need to match the filenames of the corresponding .proto files to import for
// this .proto file to compile properly.
//
// This .proto file can import .proto files corresponding to newer revisions of SEMI Standards
// used by this SEMI Standard as long as they are compatible (e.g. the SEMI standard revision corresponding
// to the .proto file to import is the latest revision referenced by the SEMI standard corresponding to this
// .proto file.
// * This allows referenced SEMI Standards to be updated without having to constantly update the import statements
//   used by this .proto file.
// * For example, implementers can update the import statement referencing the .proto file corresponding to a newer
//   revision of SEMI E179.
// * If a specific revision of the referenced SEMI Standard is required, this .proto file will be explicitly updated to
//   import the corresponding .proto file of the referenced SEMI standard as part of updates to this .proto file.

import "semi_e179-1225.proto";
import "semi_e120-02-1225.proto";
import "semi_e132-02-1225.proto";

import "google/protobuf/descriptor.proto";
import "google/protobuf/timestamp.proto";

// ***************************************************************
// Version information
// ***************************************************************

// Protobuf3 doesn't support the concept of constants
// We want a way for the implementor to get the .proto file version
// if they want to log or check this information.
// We workaround the issue by exposing a file attribute with the version information
// Information corresponding to the associated SEMI Standard as a custom file option on the .proto file.
//
// Note - the proto_buf_file_version will uniquely identify the .proto file version.
// * For the .proto file associated with the official standard, the proto_buf_file_version will
//   be the SEMI Standard version (including the publication date in MMYY format)
//   For example,
//     proto_buf_file_version="E134.2-MMYY" will indicate this .proto file is for
//     an official SEMI Version (SEMI E134.2-MMYY)
// * If the .proto file is for an interim release (for example as part of a ballot),
//   suffix information along the lines of "-Ballot<nnnn>-<Date>" can be added.
//   For example,
//     proto_buf_file_version="E134.2-Ballot1234-20180522" will indicate this .proto file is an interim version for
//     SEMI E134.2-XXXX Ballot 1234 and was released on May 22, 2018
//
// Note - semi_standard_information Field is defined once in the SEMI E179 .proto file

option (semi_standard_information) =
{
  semi_standard : "SEMI E125.2",
  proto_buf_file_version : "SEMIE125-02-1225"
};

// ***************************************************************
// Enumerated Type Definitions
// ***************************************************************

// Best Practice is to specify Unknown element as index 0 for future proofing
// Enum elements need to be unique across the namespace, so make sure Unknown element name
// is meaningful to the enum.

// Specifies the parameter's transient nature
enum ParameterTransientNature
{
  PARAMETER_TRANSIENT_NATURE_UNSPECIFIED = 0;   // Value when unspecified enum value is received - per Protocol Buffers best practice
  TRANSIENT = 1;        // Transient parameters are reportable only in association with certain
                        // events and exceptions
  RESTRICTED = 2;       // Restricted parameters are available to report data at any times in
                        // certain conditions
  UNRESTRICTED = 3;     // Unrestricted parameter are available to report data at any time the
                        // equipment communication is available

  reserved 4 to 999;    // Reserved for future use
}

// Specifies the valid type of SECS variables
enum SecsVariableTypeSpecifier
{
  SECS_VARIABLE_TYPE_SPECIFIER_UNSPECIFIED = 0;   // Value when unspecified enum value is received - per Protocol Buffers best practice
  STATUS_VARIABLE = 1;                            // Status Variable (SV)
  EQUIPMENT_CONSTANT_VARIABLE = 2;                // Equipment Constant Variable (ECV)
  DATA_VARIABLE = 3;                              // Data Variable (DV)

  reserved 4 to 999;                              // Reserved for future use
}

// Specifies the valid exception severity levels
enum ExceptionSeveritySpecifier
{
  EXCEPTION_SEVERITY_SPECIFIER_UNSPECIFIED = 0;     // Value when unspecified enum value is received - per Protocol Buffers best practice
  FATAL = 1;              // Fatal exception severity
  ERROR = 2;              // Error exception severity
  WARNING = 3;            // Warning exception severity
  INFORMATIONAL = 4;      // Informational exception severity

  reserved 5 to 999;      // Reserved for future use
}

// ***************************************************************
// Message Definitions
// ***************************************************************

// Protobuf message names need to be unique.  There is already a message ParameterReferenceType defined
// in the .proto file corresponding for SEMI E134.
// Use EquipmentParameterReferenceType as the message name for SEMI E125 ParameterReference
message EquipmentParameterReferenceType
{
  string parameter_name = 1;
  string parameter_id = 2;
}

message StateMachineInstanceEventType    
{
  string event_id = 1;      // Identifier for the StateMachine Event for which Parameters
                            // might be available.
                            
  string event_name = 2;    // Name of the StateMachine Event
  oneof scs_information
  {
    uint64 secs_ceid = 3;   // Populated if event corresponds to a SECS event
                            // SECSEventRef only contains the CEID for the SECS event
                            // No need to create a separate Protocol Buffers message for it
                            // Use uint64 data type because largest CEID per SEMI E5 is
                            // 8 byte integer (unsigned).
  }
  repeated EquipmentParameterReferenceType available_parameters = 4;  
}

message StateMachineInstanceType    
{
  string state_machine_id = 1;                                                
  string state_machine_name = 2;
  oneof current_state_model_state
  { 
    EquipmentParameterReferenceType current_state = 3;                          
  }
  oneof previous_state_model_state
  { 
    EquipmentParameterReferenceType previous_state = 4;                         
  }
  repeated StateMachineInstanceEventType state_machine_instance_events = 5;                                                                       
  repeated StateMachineInstanceType nested_state_machines = 6;                
}

message ParameterClassificationType 
{
  ParameterTransientNature is_transient = 1;  
  string description = 2;
}


message ConstraintType      
{
  string name = 1;          
  string description = 2;   
  string definition = 3;    
}

message SECSVarRefType      
{
  uint64 secs_vid = 1;                            // Use uint64 data type because largest VID per SEMI E5 is
                                                  // 8 byte integer (unsigned).

  SecsVariableTypeSpecifier secs_var_class = 2;   // Use enumerated value - calling code can map to text string
                                                  
}

message CachedDataPropertiesType
{
  float min_collection_interval = 1;   // Positive real number
  float max_collection_interval = 2;   // Positive real number
  uint32 min_reporting_interval = 3;    // Positive Integer
  uint32 max_reporting_interval = 4;    // Positive Integer
}

message ParameterType   
{
  string parameter_id = 1;                          
  string type_name = 2;                             
  string description = 3;                           
  repeated ConstraintType constraints = 4;          
  oneof classification
  {
    ParameterClassificationType controls = 5;       
    ParameterClassificationType configurations = 6; 
    ParameterClassificationType data = 7;           
  }
  ParameterUnitType unit = 8;
  oneof secs_information
  {

    SECSVarRefType secs_variable = 9;               // Populated if this is a SECS variable
                                                    
  }
  oneof cached_data_properties 
  {
    CachedDataPropertiesType properties = 10;
  }

}

message ParameterUnitType
{

  oneof parameter_unit
  {
    string unit_id = 1;
    UnitConfigType available_unit = 2;
  }
}

message UnitConfigType
{
  repeated string unit_ids = 1;
  EquipmentParameterReferenceType unit_symbol_parameter = 2;
}

message TransitionType  
{

  string transition_name = 1;   // Human-readable name for this transition
                                
  string transition_id = 2;     // Unique identifier for this transition
                                
  string description = 3;       
  string source_state_id = 4;   // State of origin for this transaction
                                
  string target_state_id = 5;   // Transitioned-to state
                                
}

message StateMachineEventType   
{
  string event_id = 1;                  
  string description = 2;               
  repeated string transition_ids = 3;   
}

message StateType   
{
  string state_name = 1;                    // Human-readable name for this state
                                            
  string state_id = 2;                      // Unique identifier for this state
                                            
  string description = 3;                   
  oneof state                               
  {
    StatesType sub_state = 4;               
    StateMachinesType state_machine = 5;    
  }
}

// Container object of repeated StateType objects

message StatesType
{
  repeated StateType states = 1;
}

message StateMachineType    
{
  string state_machine_id = 1;                
  string description = 2;                     
  StateType top = 3;                          // Top level state for this state machine
                                              
  repeated TransitionType transitions = 4;    
  repeated StateMachineEventType events = 5;  

}

// Container object of repeated StateMachineType objects

message StateMachinesType
{
  repeated StateMachineType state_machines = 1;
}

message StateMachineReferenceType
{
  string state_machine_id = 1;
  EquipmentParameterReferenceType state_machine_instance_parameter = 2;
  oneof current_state_machine_state
  { 
    EquipmentParameterReferenceType current_state = 3; 
  }
  oneof previous_state_machine_state
  { 
    EquipmentParameterReferenceType previous_state = 4; 
  }
  repeated StateMachineReferenceEventType state_machine_reference_events = 5;
  repeated StateMachineReferenceType nested_state_machines = 6;
}

message StateMachineReferenceEventType
{
  string event_id = 1;
  string event_name = 2;
  oneof secs_information
  {
    uint64 secs_ceid = 3;   // Populated if event corresponds to a SECS event
                            // SECSEventRef only contains the CEID for the SECS event
                            // No need to create a separate Protocol Buffers message for it
                            // Use uint64 data type because largest CEID per SEMI E5 is
                            // 8 byte integer (unsigned).
                            
  }
  repeated EquipmentParameterReferenceType available_parameters = 4;
}

message SimpleEventType     
{
  string event_id = 1;      
  string description = 2;   
  oneof secs_information
  {
    uint64 secs_ceid = 3;   // Populated if event corresponds to a SECS event
                            // SECSEventRef only contains the CEID for the SECS event
                            // No need to create a separate Protocol Buffers message for it
                            // Use uint64 data type because largest CEID per SEMI E5 is
                            // 8 byte integer (unsigned).
  }

}

message SimpleEventInstanceType
{
  string event_name = 1;
  string event_id = 2;
  repeated EquipmentParameterReferenceType available_parameters = 3;

}

message SEMIObjType   
{
  string standard_version = 1;            

  string obj_type = 2;                    
  string state_machine_id = 3;
  repeated AttributeType attributes = 4;  
}

message AttributeType
{
  string attribute_id = 1;
  string type_name = 2;
  EquipmentParameterReferenceType associated_parameter = 3;
  string description = 4;
  ParameterUnitType unit = 5;
}

message SEMIObjTypeReferenceType  
{
  string obj_type = 1;            // Maps to type attribute (identifier for unique SEMIObjTypeReference
                                  
}

message ExceptionType   
{
  string exception_id = 1;                    
  string description = 2;                     
  ExceptionSeveritySpecifier severity = 3;    
  oneof secs_information
  {
    SECSExceptionRefType secs_exception = 4;  // Populated if exception corresponds to a SECS alarm
  }
}

// Specifies information about a SECS Alarm
message SECSExceptionRefType
{
  uint64 secs_alid = 1;         // Use uint64 data type because largest ALID per SEMI E5 is
                                // 8 byte integer (unsigned).
  uint64 secs_set_ceid = 2;     // Use uint64 data type because largest CEID per SEMI E5 is
                                // 8 byte integer (unsigned).
  uint64 secs_clear_ceid = 3;   // Use uint64 data type because largest CEID per SEMI E5 is
                                // 8 byte integer (unsigned).
}

message ExceptionInstanceType
{
  string exception_name = 1;
  string exception_id = 2;
  repeated EquipmentParameterReferenceType exception_parameters = 3;
}

message EquipmentNodeDescriptionType  
{
  string equipment_node_id = 1;       // Identifies an Equipment node

  repeated StateMachineReferenceType state_machine_references = 2;
  repeated StateMachineInstanceType state_machine_instances = 3;  
                                      
  repeated SEMIObjTypeReferenceType semi_obj_type_references = 4;

  repeated ExceptionInstanceType exception_instances = 5;

  repeated EquipmentParameterReferenceType parameter_references = 6;

  repeated SimpleEventInstanceType simple_event_instances = 7;
}

// Currently no information to be passed in this message
message GetUnitsRequestType 
{
}

message GetUnitsResponseType    
{
  
  repeated UnitType units = 1;    

  oneof error_information          
  {
    ErrorType error = 2;          // Use this for regular errors that use ErrorType content
                                  // for example UnrecognizedSession
                                  
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

// Currently no information to be passed in this message
message GetTypeDefinitionsRequestType   
{
}

message GetTypeDefinitionsResponseType  
{
  repeated TypeDefinitionType type_definitions = 1;   

  oneof error_information                              
  {
    ErrorType error = 2;                              // Use this for regular errors that use ErrorType content
                                                      // for example UnrecognizedSession
                                                      
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

// Currently no information to be passed in this message
message GetStateMachinesRequestType 
{
}

message GetStateMachinesResponseType    
{
  repeated StateMachineType state_machines = 1;   

  oneof error_information    
  {
    ErrorType error = 2;    // Use this for regular errors that use ErrorType content
                            // for example UnrecognizedSession
                            
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

// Currently no information to be passed in this message
message GetSEMIObjTypesRequestType  
{
}

message GetSEMIObjTypesResponseType   
{
  repeated SEMIObjType obj_types = 1; 

  oneof error_information              
  {
    ErrorType error = 2;              // Use this for regular errors that use ErrorType content
                                      // for example UnrecognizedSession
                                      
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

// Currently no information to be passed in this message
message GetExceptionsRequestType    
{
  repeated string equipment_node_ids = 1;
}

message GetExceptionsResponseType   
{
  repeated ExceptionType exceptions = 1;  
  repeated string unrecognized_ids = 2;

  oneof error_information                  
  {
    ErrorType error = 3;                  // Use this for regular errors that use ErrorType content
                                          // for example UnrecognizedSession
                                          
    UnauthorizedOperationType unauthorized_operation_error = 4;
  }
}

// Currently no information to be passed in this message
message GetParametersRequestType
{
  repeated string equipment_node_ids = 1;
}

message GetParametersResponseType
{
  repeated ParameterType parameters = 1;    // Unordered list of Parameters
  repeated string unrecognized_ids = 2;
  
  oneof error_information                   
  {
    ErrorType error = 3;                    // Use this for regular errors that use ErrorType content
                                            // for example UnrecognizedSession
                                            
    UnauthorizedOperationType unauthorized_operation_error = 4;
  }
}

message GetSimpleEventsRequestType
{
  repeated string equipment_node_ids = 1;
}

message GetSimpleEventsResponseType
{
  repeated SimpleEventType simple_events = 1; // Unordered list of SimpleEvent
  repeated string unrecognized_ids = 2;
  
  oneof error_information                      
  {
    ErrorType error = 3;                      // Use this for regular errors that use ErrorType content
                                              // for example UnrecognizedSession
                                              
    UnauthorizedOperationType unauthorized_operation_error = 4;
  }
}

// Currently no information to be passed in this message
message GetEquipmentStructureRequestType 
{
}

message GetEquipmentStructureResponseType   
{
  EquipmentElementType equipment_structure = 1;   // Structured data that represents the equipment as a whole
                                                  // Type deriving from SEMI E120 EquipmentElement

  oneof error_information                          
  {
    ErrorType error = 2;                          // Use this for regular errors that use ErrorType content
                                                  // for example UnrecognizedSession
                                                  
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

message GetEquipmentNodeDescriptionsRequestType 
{
  repeated string equipment_node_ids = 1;   

  uint32 filter = 2;
}

message NodeDescriptionResultType   
{
  repeated EquipmentNodeDescriptionType node_descriptions = 1;    

  repeated string unrecognized_ids = 2;                           

}

message GetEquipmentNodeDescriptionsResponseType     
{
  NodeDescriptionResultType equipment_node_description = 1;       
 
  oneof error_information                                         
  {
    ErrorType error = 2;                                          // Use this for regular errors that use ErrorType content
                                                                  // for example UnrecognizedSession
                                                                  
    UnauthorizedOperationType unauthorized_operation_error = 3;
  }
}

// Currently no information to be passed in this message
message GetLatestRevisionRequestType    
{
}

message GetLatestRevisionResponseType   
{
  google.protobuf.Timestamp revision_date_time = 1;   
                                                      
  string metadata_fingerprint = 2;
  
  oneof error_information                     
  {
    ErrorType error = 3;                              // Use this for regular errors that use ErrorType content
                                                      // for example UnrecognizedSession
                                                      
    UnauthorizedOperationType unauthorized_operation_error = 4;
  }
}

message NotifyOnRevisionsRequestType    
{
  bool enable = 1;    
}

message NotifyOnRevisionsResponseType   
{

  oneof error_information        
  {
    ErrorType error = 1;        // Use this for regular errors that use ErrorType content
                                // for example UnrecognizedSession
                                
    UnauthorizedOperationType unauthorized_operation_error = 2;
  }
}

message MetadataRevisedNotificationType 
{
  google.protobuf.Timestamp  revision_date_time = 1;  
                                                      
  string metadata_fingerprint = 2;
}

// Container message for all the items that could be sent on the stream to the server related to Equipment Metadata
// Note - Define the message as empty to accommodate future changes
// (if adding input parameters, don't need to change the method interface)
message EquipmentMetadataNotificationUsageStreamRequest
{

}

// Container message for all the items that could be sent on the stream from the server
// related to equipment metadata (unprompted information from the Server)
message EquipmentMetadataNotificationUsageStreamResponse
{
  oneof result
  {
    MetadataRevisedNotificationType metadata_revised_notification = 1;  
  }

}

// Container message for all the items that could be sent on the stream from the server related to Status Data
message ConsumerEquipmentMetadataNotificationUsageStreamRequest
{
  oneof request
  {
    MetadataRevisedNotificationType metadata_revised_notification = 1;  
  }
}

// Container message for all the items that could be sent on the stream to the server
// Note - Define the message as empty to accommodate future changes
// (if adding input parameters, don't need to change the method interface)
message ConsumerEquipmentMetadataNotificationUsageStreamResponse
{

}

// ***************************************************************
// Service Definitions
// ***************************************************************

// This gRPC service looks after equipment metadata functionality defined in SEMI E125 that is handled by a Client (management and receiving messages)
service E125EquipmentMetadataManagement
{
  // *********************************************************************
  // Unary Request/Response methods to manage equipment metadata
  // *********************************************************************

  rpc GetUnits (GetUnitsRequestType) returns (GetUnitsResponseType){};

  rpc GetTypeDefinitions (GetTypeDefinitionsRequestType) returns (GetTypeDefinitionsResponseType){};

  rpc GetStateMachines (GetStateMachinesRequestType) returns (GetStateMachinesResponseType){};

  // <!-- Web Services -->

  rpc GetSEMIObjTypes (GetSEMIObjTypesRequestType) returns (GetSEMIObjTypesResponseType){};

  rpc GetExceptions (GetExceptionsRequestType) returns (GetExceptionsResponseType){};

  rpc GetParameters (GetParametersRequestType) returns (GetParametersResponseType){};

  rpc GetSimpleEvents (GetSimpleEventsRequestType) returns (GetSimpleEventsResponseType){};

  rpc GetEquipmentStructure (GetEquipmentStructureRequestType) returns (GetEquipmentStructureResponseType){};

  rpc GetEquipmentNodeDescriptions (GetEquipmentNodeDescriptionsRequestType) returns (GetEquipmentNodeDescriptionsResponseType){};

  rpc GetLatestRevision (GetLatestRevisionRequestType) returns (GetLatestRevisionResponseType){};

  rpc NotifyOnRevisions (NotifyOnRevisionsRequestType) returns (NotifyOnRevisionsResponseType){};

  // *********************************************************************
  // Streaming methods
  // *********************************************************************

  // Note - there is no streaming gRPC method in this service for operational messages
  // from the Equipment Server since SEMI E125 does not support operational messages.

  // Establish stream to and from the Equipment Server for notification messages
  // Separate RPC method because not all Consumers are interested in these messages

  rpc EquipmentMetadataNotificationUsageStream (stream EquipmentMetadataNotificationUsageStreamRequest) returns (stream EquipmentMetadataNotificationUsageStreamResponse) {}
}

// This gRPC service looks after equipment metadata functionality defined in SEMI E125 that is handled by a Consumer
// It is in a separate service because the Equipment Server opens the connection to the Consumer.
service E125EquipmentMetadataConsumer
{
  //   *********************************************************************
  // Unary Request/Response methods related tzo data collection
  // *********************************************************************
  // None

  // *********************************************************************
  // Streaming  methods
  // *********************************************************************

  // Note - there is no streaming gRPC method in this service for operational messages
  // from the Equipment Server since SEMI E125 does not support operational messages.

  // Establish stream to and from the Consumer for notification messages
  // Separate RPC method because not all Consumers are interested in these messages

  rpc ConsumerEquipmentMetadataNotificationUsageStream (stream ConsumerEquipmentMetadataNotificationUsageStreamRequest) returns (stream ConsumerEquipmentMetadataNotificationUsageStreamResponse) {}
}