1// Copyright 2017 The Chromium Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5module device.mojom;
6
7import "mojo/public/mojom/base/file_path.mojom";
8import "mojo/public/mojom/base/unguessable_token.mojom";
9
10struct SerialPortInfo {
11  mojo_base.mojom.UnguessableToken token;
12  mojo_base.mojom.FilePath path;
13
14  // This member is used to identify whether the SerialPortInfo object is
15  // converted from a Bluetooth serial device.
16  DeviceType type = PLATFORM_SERIAL;
17
18  // On macOS a serial device may have two paths, one for the call-out device
19  // and one for the dial-in device. The call-out device is preferred. If
20  // there is also an associated dial-in device its path is provided here. If
21  // the dial-in device is the only option its path will be in |path|.
22  [EnableIf=is_mac] mojo_base.mojom.FilePath? alternate_path;
23
24  // On macOS a single serial port can be enumerated by multiple drivers. This
25  // field permits disambiguation.
26  [EnableIf=is_mac] string? usb_driver_name;
27
28  // On Windows the "device instance ID" provides a stable identifier that can
29  // be used for device permissions.
30  [EnableIf=is_win] string device_instance_id;
31
32  // The USB device vendor and product IDs.
33  uint16 vendor_id;
34  bool has_vendor_id = false;
35  uint16 product_id;
36  bool has_product_id = false;
37
38  // A string suitable for display to the user for describing this device. May
39  // be, for example, the USB device product name string.
40  string? display_name;
41
42  // The USB device serial number.
43  // Note: This field is not populated on Windows nor for non-USB devices.
44  string? serial_number;
45};
46
47enum SerialSendError {
48  NONE,
49  DISCONNECTED,
50  SYSTEM_ERROR,
51};
52
53enum SerialReceiveError {
54  NONE,
55  DISCONNECTED,
56  DEVICE_LOST,
57  BREAK,
58  FRAME_ERROR,
59  OVERRUN,
60  BUFFER_OVERFLOW,
61  PARITY_ERROR,
62  SYSTEM_ERROR,
63};
64
65enum SerialDataBits {
66  NONE,
67  SEVEN,
68  EIGHT,
69};
70
71enum SerialParityBit {
72  NONE,
73  NO_PARITY,
74  ODD,
75  EVEN,
76};
77
78enum SerialStopBits {
79  NONE,
80  ONE,
81  TWO,
82};
83
84enum SerialPortFlushMode {
85  // Flushes both receive and transmit buffers without discarding any bytes in
86  // the data pipes. This is for compatibility with chrome.serial.flush().
87  kReceiveAndTransmit,
88
89  // Flushes the receive buffers and discards data in the data_pipe_producer by
90  // closing it.
91  kReceive,
92
93  // Flushes the send buffers and discards data in the data_pipe_consumer by
94  // closing it.
95  kTransmit,
96};
97
98enum DeviceType {
99  // The SerialPortInfo object is created from a serial device.
100  PLATFORM_SERIAL,
101  // The SerialPortInfo object is created from a Bluetooth SPP device.
102  SPP_DEVICE,
103};
104
105struct SerialConnectionOptions {
106  uint32 bitrate = 0;
107  SerialDataBits data_bits = NONE;
108  SerialParityBit parity_bit = NONE;
109  SerialStopBits stop_bits = NONE;
110  bool cts_flow_control;
111  bool has_cts_flow_control = false;
112};
113
114struct SerialConnectionInfo {
115  uint32 bitrate = 0;
116  SerialDataBits data_bits = NONE;
117  SerialParityBit parity_bit = NONE;
118  SerialStopBits stop_bits = NONE;
119  bool cts_flow_control;
120};
121
122struct SerialHostControlSignals {
123  // DTR (Data Terminal Ready)
124  bool dtr;
125  bool has_dtr = false;
126  // RTS (Request to Send)
127  bool rts;
128  bool has_rts = false;
129  // BRK (Break)
130  bool brk;
131  bool has_brk = false;
132};
133
134struct SerialPortControlSignals {
135  bool dcd;
136  bool cts;
137  bool ri;
138  bool dsr;
139};
140
141// Discovers and enumerates serial devices available to the host.
142interface SerialPortManager {
143  // Associates an interface the port manager can used to notify the client of
144  // events such as the addition or removal of serial ports from the host.
145  SetClient(pending_remote<SerialPortManagerClient> client);
146
147  // Returns the list of serial ports currently available on the host.
148  GetDevices() => (array<SerialPortInfo> devices);
149
150  // Opens the port represented by |token| using |options| and returns a
151  // connection to it as |port|. If |use_alternate_path| is specified then the
152  // |alternate_path| for the port will be used instead. When the pipe returned
153  // in |port| is closed the optional pipe passed in |watcher| will also be
154  // closed and vice a versa.
155  OpenPort(mojo_base.mojom.UnguessableToken token,
156           bool use_alternate_path,
157           SerialConnectionOptions options,
158           pending_remote<SerialPortClient> client,
159           pending_remote<SerialPortConnectionWatcher>? watcher)
160      => (pending_remote<SerialPort>? port);
161};
162
163// Client interface for SerialPortManager.
164interface SerialPortManagerClient {
165  // This message indicates that a port has been added to the host.
166  OnPortAdded(SerialPortInfo port_info);
167
168  // This message indicates that a port has been removed from the host.
169  OnPortRemoved(SerialPortInfo port_info);
170};
171
172// Performs asynchronous I/O on serial devices.
173interface SerialPort {
174  // Start writing data from |consumer| to the port. This should be called after
175  // Open() or to restart data flow after when SerialPortClient#OnSendError is
176  // called on |client| to indicate an error.
177  StartWriting(handle<data_pipe_consumer> consumer);
178
179  // Start reading data from the port into |producer|. This should be called
180  // after Open() or to restart data flow when SerialPortClient#OnReadError is
181  // called on |client| to indicate an error.
182  StartReading(handle<data_pipe_producer> producer);
183
184  // Flushes buffers according to the selected |mode|.
185  Flush(SerialPortFlushMode mode) => ();
186
187  // Waits for the data_pipe_consumer passed to StartWriting() to be closed and
188  // all buffered data to be transmitted by the port.
189  Drain() => ();
190
191  // Reads current control signals (DCD, CTS, etc.).
192  GetControlSignals() => (SerialPortControlSignals signals);
193
194  // Sets one or more control signals and returns result.
195  SetControlSignals(SerialHostControlSignals signals) => (bool success);
196
197  // Performs platform-specific port configuration and returns result.
198  ConfigurePort(SerialConnectionOptions options) => (bool success);
199
200  // Performs a platform-specific port configuration query and returns got info.
201  GetPortInfo() => (SerialConnectionInfo info);
202
203  // Closes the port and this pipe. Once this returns no more data will be sent
204  // or received on |in_stream| or |out_stream|.
205  Close() => ();
206};
207
208interface SerialPortClient {
209  OnReadError(SerialReceiveError error);
210  OnSendError(SerialSendError error);
211};
212
213interface SerialPortConnectionWatcher {
214};
215