Skip to content

Protocol Documentation

Table of Contents

Top

api/device/device.proto

AddRequest

AddRequest adds a device to the topology

Field Type Label Description
device Device device is the device to add

AddResponse

AddResponse is sent in response to an AddDeviceRequest

Field Type Label Description
device Device device is the device with a revision number

Credentials

Credentials is the device credentials

Field Type Label Description
user string user is the user with which to connect to the device
password string password is the password for connecting to the device

Device

Device contains information about a device

Field Type Label Description
id string id is a globally unique device identifier
revision uint64 revision is the revision of the device
address string address is the host:port of the device
target string target is the device target
version string version is the device software version
timeout google.protobuf.Duration timeout indicates the device request timeout
credentials Credentials credentials contains the credentials for connecting to the device
tls TlsConfig tls is the device TLS configuration
type string type is the type of the device
role string role is a role for the device
attributes Device.AttributesEntry repeated attributes is an arbitrary mapping of attribute keys/values
protocols ProtocolState repeated
displayname string displayname is a user friendly tag

Device.AttributesEntry

Field Type Label Description
key string
value string

GetRequest

GetRequest gets a device by ID

Field Type Label Description
id string id is the unique device ID with which to lookup the device

GetResponse

GetResponse carries a device

Field Type Label Description
device Device device is the device object

ListRequest

ListRequest requests a stream of devices and changes By default, the request requests a stream of all devices that are present in the topology when the request is received by the service. However, if subscribe is true, the stream will remain open after all devices have been sent and events that occur following the last device will be streamed to the client until the stream is closed.

Field Type Label Description
subscribe bool subscribe indicates whether to subscribe to events (e.g. ADD, UPDATE, and REMOVE) that occur after all devices have been streamed to the client

ListResponse

ListResponse carries a single device event

Field Type Label Description
type ListResponse.Type type is the type of the event
device Device device is the device on which the event occurred

ProtocolState

ProtocolState contains information related to service and connectivity to a device

Field Type Label Description
protocol Protocol The protocol to which state relates
connectivityState ConnectivityState ConnectivityState contains the L3 connectivity information
channelState ChannelState ChannelState relates to the availability of the gRPC channel
serviceState ServiceState ServiceState indicates the availability of the gRPC servic on top of the channel

RemoveRequest

RemoveRequest removes a device by ID

Field Type Label Description
device Device device is the device to remove

RemoveResponse

RemoveResponse is sent in response to a RemoveDeviceRequest

TlsConfig

Device TLS configuration

Field Type Label Description
caCert string caCert is the name of the device's CA certificate
cert string cert is the name of the device's certificate
key string key is the name of the device's TLS key
plain bool plain indicates whether to connect to the device over plaintext
insecure bool insecure indicates whether to connect to the device with insecure communication

UpdateRequest

UpdateRequest updates a device

Field Type Label Description
device Device device is the updated device

UpdateResponse

UpdateResponse is sent in response to an UpdateDeviceRequest

Field Type Label Description
device Device device is the device with updated revision

ChannelState

ConnectivityState represents the state of a gRPC channel to the device from the service container

Name Number Description
UNKNOWN_CHANNEL_STATE 0 UNKNOWN_CHANNEL_STATE constant needed to go around proto3 nullifying the 0 values
CONNECTED 1 CONNECTED indicates the corresponding grpc channel is connected on this device
DISCONNECTED 2 DISCONNECTED indicates the corresponding grpc channel is not connected on this device

ConnectivityState

ConnectivityState represents the L3 reachability of a device from the service container (e.g. enos-config), independently of gRPC or the service itself (e.g. gNMI)

Name Number Description
UNKNOWN_CONNECTIVITY_STATE 0 UNKNOWN_CONNECTIVITY_STATE constant needed to go around proto3 nullifying the 0 values
REACHABLE 1 REACHABLE indicates the the service can reach the device at L3
UNREACHABLE 2 UNREACHABLE indicates the the service can't reach the device at L3

ListResponse.Type

Device event type

Name Number Description
NONE 0 NONE indicates this response does not represent a state change
ADDED 1 ADDED is an event which occurs when a device is added to the topology
UPDATED 2 UPDATED is an event which occurs when a device is updated
REMOVED 3 REMOVED is an event which occurs when a device is removed from the topology

Protocol

Protocol to interact with a device

Name Number Description
UNKNOWN_PROTOCOL 0 UNKNOWN_PROTOCOL constant needed to go around proto3 nullifying the 0 values
GNMI 1 GNMI protocol reference
P4RUNTIME 2 P4RUNTIME protocol reference
GNOI 3 GNOI protocol reference
E2AP 4 E2 Control Plane Protocol

ServiceState

ServiceState represents the state of the gRPC service (e.g. gNMI) to the device from the service container

Name Number Description
UNKNOWN_SERVICE_STATE 0 UNKNOWN_SERVICE_STATE constant needed to go around proto3 nullifying the 0 values
AVAILABLE 1 AVAILABLE indicates the corresponding grpc service is available
UNAVAILABLE 2 UNAVAILABLE indicates the corresponding grpc service is not available
CONNECTING 3 CONNECTING indicates the corresponding protocol is in the connecting phase on this device

DeviceService

DeviceService provides an API for managing devices.

Method Name Request Type Response Type Description
Add AddRequest AddResponse Add adds a device to the topology
Update UpdateRequest UpdateResponse Update updates a device
Get GetRequest GetResponse Get gets a device by ID
List ListRequest ListResponse stream List gets a stream of device add/update/remove events
Remove RemoveRequest RemoveResponse Remove removes a device from the topology

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)