1// Copyright 2014 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 5// Use the <code>chrome.serial</code> API to read from and write to a device 6// connected to a serial port. 7namespace serial { 8 9 dictionary DeviceInfo { 10 // The device's system path. This should be passed as the <code>path</code> 11 // argument to <code>chrome.serial.connect</code> in order to connect to 12 // this device. 13 DOMString path; 14 15 // A PCI or USB vendor ID if one can be determined for the underlying 16 // device. 17 long? vendorId; 18 19 // A USB product ID if one can be determined for the underlying device. 20 long? productId; 21 22 // A human-readable display name for the underlying device if one can be 23 // queried from the host driver. 24 DOMString? displayName; 25 }; 26 27 callback GetDevicesCallback = void (DeviceInfo[] ports); 28 29 enum DataBits { seven, eight }; 30 enum ParityBit { no, odd, even }; 31 enum StopBits { one, two }; 32 33 dictionary ConnectionOptions { 34 // Flag indicating whether or not the connection should be left open when 35 // the application is suspended (see 36 // <a href="http://developer.chrome.com/apps/app_lifecycle.html">Manage App 37 // Lifecycle</a>). The default value is "false." When the application is 38 // loaded, any serial connections previously opened with persistent=true 39 // can be fetched with <code>getConnections</code>. 40 boolean? persistent; 41 42 // An application-defined string to associate with the connection. 43 DOMString? name; 44 45 // The size of the buffer used to receive data. The default value is 4096. 46 long? bufferSize; 47 48 // The requested bitrate of the connection to be opened. For compatibility 49 // with the widest range of hardware, this number should match one of 50 // commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600, 51 // 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course, 52 // that the device connected to the serial port will support the requested 53 // bitrate, even if the port itself supports that bitrate. <code>9600</code> 54 // will be passed by default. 55 long? bitrate; 56 57 // <code>"eight"</code> will be passed by default. 58 DataBits? dataBits; 59 60 // <code>"no"</code> will be passed by default. 61 ParityBit? parityBit; 62 63 // <code>"one"</code> will be passed by default. 64 StopBits? stopBits; 65 66 // Flag indicating whether or not to enable RTS/CTS hardware flow control. 67 // Defaults to false. 68 boolean? ctsFlowControl; 69 70 // The maximum amount of time (in milliseconds) to wait for new data before 71 // raising an <code>onReceiveError</code> event with a "timeout" error. 72 // If zero, receive timeout errors will not be raised for the connection. 73 // Defaults to 0. 74 long? receiveTimeout; 75 76 // The maximum amount of time (in milliseconds) to wait for a 77 // <code>send</code> operation to complete before calling the callback with 78 // a "timeout" error. If zero, send timeout errors will not be triggered. 79 // Defaults to 0. 80 long? sendTimeout; 81 }; 82 83 // Result of the <code>getInfo</code> method. 84 dictionary ConnectionInfo { 85 // The id of the serial port connection. 86 long connectionId; 87 88 // Flag indicating whether the connection is blocked from firing onReceive 89 // events. 90 boolean paused; 91 92 // See <code>ConnectionOptions.persistent</code> 93 boolean persistent; 94 95 // See <code>ConnectionOptions.name</code> 96 DOMString name; 97 98 // See <code>ConnectionOptions.bufferSize</code> 99 long bufferSize; 100 101 // See <code>ConnectionOptions.receiveTimeout</code> 102 long receiveTimeout; 103 104 // See <code>ConnectionOptions.sendTimeout</code> 105 long sendTimeout; 106 107 // See <code>ConnectionOptions.bitrate</code>. This field may be omitted 108 // or inaccurate if a non-standard bitrate is in use, or if an error 109 // occurred while querying the underlying device. 110 long? bitrate; 111 112 // See <code>ConnectionOptions.dataBits</code>. This field may be omitted 113 // if an error occurred while querying the underlying device. 114 DataBits? dataBits; 115 116 // See <code>ConnectionOptions.parityBit</code>. This field may be omitted 117 // if an error occurred while querying the underlying device. 118 ParityBit? parityBit; 119 120 // See <code>ConnectionOptions.stopBits</code>. This field may be omitted 121 // if an error occurred while querying the underlying device. 122 StopBits? stopBits; 123 124 // See <code>ConnectionOptions.ctsFlowControl</code>. This field may be 125 // omitted if an error occurred while querying the underlying device. 126 boolean? ctsFlowControl; 127 }; 128 129 // Callback from the <code>connect</code> method; 130 callback ConnectCallback = void (ConnectionInfo connectionInfo); 131 132 // Callback from the <code>update</code> method. 133 callback UpdateCallback = void (boolean result); 134 135 // Callback from the <code>disconnect</code> method. Returns true if the 136 // operation was successful. 137 callback DisconnectCallback = void (boolean result); 138 139 // Callback from the <code>setPaused</code> method. 140 callback SetPausedCallback = void (); 141 142 // Callback from the <code>getInfo</code> method. 143 callback GetInfoCallback = void (ConnectionInfo connectionInfo); 144 145 // Callback from the <code>getConnections</code> method. 146 callback GetConnectionsCallback = void (ConnectionInfo[] connectionInfos); 147 148 enum SendError { 149 // The connection was disconnected. 150 disconnected, 151 152 // A send was already pending. 153 pending, 154 155 // The send timed out. 156 timeout, 157 158 // A system error occurred and the connection may be unrecoverable. 159 system_error 160 }; 161 162 dictionary SendInfo { 163 // The number of bytes sent. 164 long bytesSent; 165 166 // An error code if an error occurred. 167 SendError? error; 168 }; 169 170 callback SendCallback = void (SendInfo sendInfo); 171 172 callback FlushCallback = void (boolean result); 173 174 // The set of control signals which may be sent to a connected serial device 175 // using <code>setControlSignals</code>. Note that support for these signals 176 // is device-dependent. 177 dictionary HostControlSignals { 178 // DTR (Data Terminal Ready). 179 boolean? dtr; 180 181 // RTS (Request To Send). 182 boolean? rts; 183 }; 184 185 // The set of control signals which may be set by a connected serial device. 186 // These can be queried using <code>getControlSignals</code>. Note that 187 // support for these signals is device-dependent. 188 dictionary DeviceControlSignals { 189 // DCD (Data Carrier Detect) or RLSD (Receive Line Signal/ Detect). 190 boolean dcd; 191 192 // CTS (Clear To Send). 193 boolean cts; 194 195 // RI (Ring Indicator). 196 boolean ri; 197 198 // DSR (Data Set Ready). 199 boolean dsr; 200 }; 201 202 // Returns a snapshot of current control signals. 203 callback GetControlSignalsCallback = void (DeviceControlSignals signals); 204 205 // Returns true if operation was successful. 206 callback SetControlSignalsCallback = void (boolean result); 207 208 // Data from an <code>onReceive</code> event. 209 dictionary ReceiveInfo { 210 // The connection identifier. 211 long connectionId; 212 213 // The data received. 214 ArrayBuffer data; 215 }; 216 217 enum ReceiveError { 218 // The connection was disconnected. 219 disconnected, 220 221 // No data has been received for <code>receiveTimeout</code> milliseconds. 222 timeout, 223 224 // The device was most likely disconnected from the host. 225 device_lost, 226 227 // A system error occurred and the connection may be unrecoverable. 228 system_error 229 }; 230 231 // Data from an <code>onReceiveError</code> event. 232 dictionary ReceiveErrorInfo { 233 // The connection identifier. 234 long connectionId; 235 236 // An error code indicating what went wrong. 237 ReceiveError error; 238 }; 239 240 interface Functions { 241 // Returns information about available serial devices on the system. 242 // The list is regenerated each time this method is called. 243 // |callback| : Called with the list of <code>DeviceInfo</code> objects. 244 static void getDevices(GetDevicesCallback callback); 245 246 // Connects to a given serial port. 247 // |path| : The system path of the serial port to open. 248 // |options| : Port configuration options. 249 // |callback| : Called when the connection has been opened. 250 static void connect(DOMString path, 251 optional ConnectionOptions options, 252 ConnectCallback callback); 253 254 // Update the option settings on an open serial port connection. 255 // |connectionId| : The id of the opened connection. 256 // |options| : Port configuration options. 257 // |callback| : Called when the configuation has completed. 258 static void update(long connectionId, 259 ConnectionOptions options, 260 UpdateCallback callback); 261 262 // Disconnects from a serial port. 263 // |connectionId| : The id of the opened connection. 264 // |callback| : Called when the connection has been closed. 265 static void disconnect(long connectionId, DisconnectCallback callback); 266 267 // Pauses or unpauses an open connection. 268 // |connectionId| : The id of the opened connection. 269 // |paused| : Flag to indicate whether to pause or unpause. 270 // |callback| : Called when the connection has been successfully paused or 271 // unpaused. 272 static void setPaused(long connectionId, 273 boolean paused, 274 SetPausedCallback callback); 275 276 // Retrieves the state of a given connection. 277 // |connectionId| : The id of the opened connection. 278 // |callback| : Called with connection state information when available. 279 static void getInfo(long connectionId, GetInfoCallback callback); 280 281 // Retrieves the list of currently opened serial port connections owned by 282 // the application. 283 // |callback| : Called with the list of connections when available. 284 static void getConnections(GetConnectionsCallback callback); 285 286 // Writes data to the given connection. 287 // |connectionId| : The id of the connection. 288 // |data| : The data to send. 289 // |callback| : Called when the operation has completed. 290 static void send(long connectionId, 291 ArrayBuffer data, 292 SendCallback callback); 293 294 // Flushes all bytes in the given connection's input and output buffers. 295 static void flush(long connectionId, FlushCallback callback); 296 297 // Retrieves the state of control signals on a given connection. 298 // |connectionId| : The id of the connection. 299 // |callback| : Called when the control signals are available. 300 static void getControlSignals(long connectionId, 301 GetControlSignalsCallback callback); 302 303 // Sets the state of control signals on a given connection. 304 // |connectionId| : The id of the connection. 305 // |signals| : The set of signal changes to send to the device. 306 // |callback| : Called once the control signals have been set. 307 static void setControlSignals(long connectionId, 308 HostControlSignals signals, 309 SetControlSignalsCallback callback); 310 }; 311 312 interface Events { 313 // Event raised when data has been read from the connection. 314 // |info| : Event data. 315 static void onReceive(ReceiveInfo info); 316 317 // Event raised when an error occurred while the runtime was waiting for 318 // data on the serial port. Once this event is raised, the connection may be 319 // set to <code>paused</code>. A <code>"timeout"</code> error does not pause 320 // the connection. 321 static void onReceiveError(ReceiveErrorInfo info); 322 }; 323}; 324