Protocol Documentation

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

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	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	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)