1// Copyright 2022 The Android Open Source Project
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//      http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package netsim.frontend;
18
19import "google/protobuf/empty.proto";
20import "google/protobuf/timestamp.proto";
21import "netsim/model.proto";
22
23/**
24 * The frontend service for the network simulator.
25 *
26 * The network simulator interconnects virtual radio controllers on emulated
27 * android and accessory devices to allows control of the topology, device
28 * positions, and RF characteristics.
29 *
30 * Clients of the frontend service include a Command Line Interface (cli), Mobly
31 * scripts, and a web UI.
32 *
33 */
34service FrontendService {
35  // Get the version of the netsim service.
36  rpc GetVersion(google.protobuf.Empty) returns (VersionResponse);
37
38  // Create a builtin device
39  rpc CreateDevice(CreateDeviceRequest) returns (CreateDeviceResponse);
40
41  // Delete a builtin chip. Implicitly deletes devices which contain no chips.
42  rpc DeleteChip(DeleteChipRequest) returns (google.protobuf.Empty);
43
44  // Patch a device
45  rpc PatchDevice(PatchDeviceRequest) returns (google.protobuf.Empty);
46
47  // Reset all devices.
48  rpc Reset(google.protobuf.Empty) returns (google.protobuf.Empty);
49
50  // Get a list of devices
51  rpc ListDevice(google.protobuf.Empty) returns (ListDeviceResponse);
52
53  // Get a list of devices when a device event is published.
54  // Waits for device event up to 15 seconds and returns Error response if no
55  // event is received
56  rpc SubscribeDevice(SubscribeDeviceRequest) returns (SubscribeDeviceResponse);
57
58  // Patch a Capture source to turn capture on/off.
59  // When turned on the old capture contents are replaced.
60  rpc PatchCapture(PatchCaptureRequest) returns (google.protobuf.Empty);
61
62  // List all Captures currently connected on netsim.
63  rpc ListCapture(google.protobuf.Empty) returns (ListCaptureResponse);
64
65  // Retrieve the contents of the packet capture as streaming bytes
66  rpc GetCapture(GetCaptureRequest) returns (stream GetCaptureResponse);
67}
68
69// Response of GetVersion.
70//
71// Returns the version of the netsim service
72message VersionResponse {
73  // Version of netsim service
74  string version = 1;
75}
76
77// Request of CreateDevice.
78//
79// CreateDevice is only used for built-in devices.
80message CreateDeviceRequest {
81  // DeviceCreate proto for creation. Check DeviceCreate in model.proto for more
82  // detail.
83  netsim.model.DeviceCreate device = 1;
84}
85
86// Response of CreateDevice.
87//
88// Returns the device created in netsim
89message CreateDeviceResponse {
90  // Device proto
91  netsim.model.Device device = 1;
92}
93
94// Request of DeleteDevice.
95//
96// DeleteDevice is only used for built-in device.
97message DeleteChipRequest {
98  // Device Identifier
99  uint32 id = 2;
100}
101
102// Request of PatchDevice.
103//
104// You may patch the device position, orientation, and the radio states.
105// For built-in devices, you may patch the specific configurations.
106message PatchDeviceRequest {
107  // Device proto. You must include either the id or name field to have
108  // a successful patch.
109  netsim.model.Device device = 2;
110}
111
112// Response for ListDevice request.
113//
114// Returns the emulators and accessory devices that are connected to
115// the network simulator.
116message ListDeviceResponse {
117  // List of Device protos
118  repeated netsim.model.Device devices = 1;
119  // Last modified timestamp for device resource.
120  // The timestamp will be updated if devices state has changed (except for
121  // packet counts)
122  google.protobuf.Timestamp last_modified = 2;
123}
124
125// Request for SubscribeDevice.
126message SubscribeDeviceRequest {
127  // The SubscribeDevice will immediately return if the
128  // provided last_modified timestamp is prior to the current last_modified
129  // timestamp in device resource.
130  optional google.protobuf.Timestamp last_modified = 1;
131}
132
133// Response for SubscribeDevice request.
134message SubscribeDeviceResponse {
135  // Will return ListDeviceResponse or an EmptyResponse
136  oneof response {
137    // Response for ListDevice
138    ListDeviceResponse list_device_response = 1;
139    // Empty Response
140    google.protobuf.Empty empty_response = 2;
141  }
142}
143
144// Request of PatchCapture.
145message PatchCaptureRequest {
146  // Capture Identifier
147  uint32 id = 1;
148
149  // Body of PatchCapture that will be channeled into
150  // body for HandleCaptureCxx
151  message PatchCapture {
152    // Capture state
153    optional bool state = 1;
154  }
155  // PatchCapture proto
156  PatchCapture patch = 2;
157}
158
159// Response of ListCapture
160//
161// Returns all capture information of devices connected to netsim.
162message ListCaptureResponse {
163  // List of Capture protos
164  repeated netsim.model.Capture captures = 1;
165}
166
167// Request of GetCapture
168message GetCaptureRequest {
169  // Capture Identifier
170  uint32 id = 1;
171}
172
173// Response of GetCapture
174//
175// Returns a max of 1024 bytes of capture file.
176// GetCapture will be returning a stream of GetCaptureResponse
177message GetCaptureResponse {
178  // Max of 1024 bytes of capture file
179  bytes capture_stream = 1;
180}
181