Driver Event API

// ------------------------------------------------------------------
// Connectivity Suite Driver Event Interface
// ------------------------------------------------------------------
//
// Naming convention according:
// https://cloud.google.com/apis/design/naming_convention
//
// ------------------------------------------------------------------

syntax = "proto3";

// Include for using Protobuf-Any
import "google/protobuf/any.proto";

package siemens.connectivitysuite.driverevent.v1;


// ===========================================
// The Services Definition
//
service DriverEventApi
{   
    // Possible return values
    // - OK
    //
    rpc SubscribeEvents( SubscribeEventsRequest ) returns ( stream SubscribeEventsNotification ) {};

}

// ==================================================================
// Subscription 'Driver-Events'
//
message SubscribeEventsRequest {
    //void
}

message SubscribeEventsNotification {
    repeated google.protobuf.Any notifications = 1;
}

// ------------------------------------------------------------------
// possible notifications
// - meta data has changed
// - driver status has changed
//

// Metadata has changed. The client should request the metadata again.
message MetadataChangedNotification {
    fixed64 timestamp = 1; // source timestamp of the notification (filetime in 100ns)
    bool config_added_only = 2; // The configuration of a connector has new connections and/or datapoints only
}

// Driver status has changed
// (respectively underlying connection status) 
//
// The message contains the  status of driver and _ALL_ connections.
// In this way no special handling for 'late subscribers' is needed.
//
// Logical Hierarchy
// - CS Driver (e.g. S7+Connector)
//   - Driver Units (e.g. Modbus-RTU, Modbus-TCP)
//     - Connections (e.g. 'PLC-1', 'PLC-2')
//
// The 'Driver Status Change Notification' represents only the levels 'Driver'
// and 'Connections'. If the specific driver supports multi-driver-units,
// it has to provide unique connections, e.g. 'PLC1-RTU' or 'PLC1-TCP'
// 
message DriverStateNotification {

    // source timestamp of driver state change
    // 64 bit unsigned integer which represents the number 
    // of 100 nano-second [0.1 microsec] intervals since January 1, 1601 (UTC).
    // (see Connectivity Suite type DT_TIMESTAMP)
    fixed64 timestamp = 1;

    // possible values for the driver statue
    enum DriverState {
      // 'undef' might be used as initial value. This is no valid driver state
      DRIVER_UNDEF = 0;
      // Connector is running, connections to underlying device(s) are established. Everything is fine.
      DRIVER_GOOD = 1;
      // Connector is running, but not fully functional.
      DRIVER_BAD = 2;
      // Connector started up and just visible via gRPC. "Birth message"
      DRIVER_AVAILABLE = 3;
      // Device not available. This is the "last will" message.
      DRIVER_UNAVAILABLE = 4;
    }
    // the current driver state
    // valid values are numbers defined with enum 'DriverState'
    uint32 driver_state = 2;

    // list of the underlayed connections
    repeated ConnectionStateInfo connection_states = 3;
}

// When a device is removed due a configuration change send the notifications in this order:
// 1. DriverStateNotification for old configured connections (with CONN_STOPPED)
// 2. MetadataChangedNotification
// 3. DriverStateNotification for new configured connections
message ConnectionStateInfo {
    // source timestamp of connection state change
    // 64 bit unsigned integer which represents the number 
    // of 100 nano-second [0.1 microsec] intervals since January 1, 1601 (UTC).
    // (see Connectivity Suite type DT_TIMESTAMP)
    fixed64 timestamp = 1;

    // Name of the connection
    // This name is unique for all connections of one driver
    // Example: "PLC_1"
    string connection_name = 2;

    // possible values for the 'Connection State'
    enum ConnectionState {
      // 'undef' might be used as initial value. This is no valid connection state
      CONN_UNDEF = 0;
      // Connection to device is up. Device is in running state.
      CONN_GOOD = 1;
      // Connection to device is up. Device is in stopped state. No process data will be available.
      CONN_STOPPED = 2;
      // Connection to device is not working as expected, communication to device will not work.
      CONN_BAD = 3;
    }
    // the current connection state
    // valid values are numbers defined with enum 'ConnectionState'
    uint32 connection_state = 3;

    // Reason/Detail for 'bad' state
    // Values defined by enum siemens.connectivitysuite.code.v1.Code
    //
    // PERMISSION_DENIED   - user credentials are valid, but don't have sufficient permissions
    // UNAUTHENTICATED     - no valid user credentials (wrong or missing)
    // UNAVAILABLE         - e.g. when communication is not possible
    // FAILED_PRECONDITION - e.g. initial browsing of the connected device not finished yet
    //
    uint32 reason_code = 4;
}

conn_suite_drv_event.proto

Message	Field	Type	Label	Description
SubscribeEventsRequest
SubscribeEventsNotification	notifications	google.protobuf.Any	repeated
MetadataChangedNotification	timestamp	fixed64		Source timestamp of the notification (filetime in 100ns)
	config_added_only	bool		The configuration of a connector has new connections and/or datapoints only
DriverStateNotification	timestamp	fixed64		Source timestamp of driver state change
	driver_state	uint32		The current driver state
	connection_states	ConnectionStateInfo	repeated	List of the under layed connections
ConnectionStateInfo	timestamp	fixed64		Source timestamp of connection state change
	connection_name	string		Name of the connection
	connection_state	uint32		The current connection state
	reason_code	uint32		Reason/Detail for 'bad' state