11const ArduinoUSBVendorId = 0x2341 ;
22const UserActionAbortError = 8 ;
33
4+ /**
5+ * Handles the connection between the browser and the Arduino board via Web Serial.
6+ */
47class SerialConnectionHandler {
58 constructor ( baudRate = 115200 , dataBits = 8 , stopBits = 1 , parity = "none" , flowControl = "none" , bufferSize = 4096 , timeout = 2000 ) {
69 this . baudRate = baudRate ;
@@ -15,6 +18,10 @@ class SerialConnectionHandler {
1518 this . registerEvents ( ) ;
1619 }
1720
21+ /**
22+ * Prompts the user to select a serial port.
23+ * @returns {Promise<SerialPort> } The serial port that the user has selected.
24+ */
1825 async requestSerialPort ( ) {
1926 try {
2027 const port = await navigator . serial . requestPort ( { filters : [ { usbVendorId : ArduinoUSBVendorId } ] } ) ;
@@ -28,10 +35,20 @@ class SerialConnectionHandler {
2835 }
2936 }
3037
38+ /**
39+ * Checks if the browser is connected to a serial port.
40+ * @returns {boolean } True if the browser is connected, false otherwise.
41+ */
3142 isConnected ( ) {
3243 return this . currentPort ?. readable != null ;
3344 }
3445
46+ /**
47+ * Opens a connection to the given serial port by using the settings specified in the constructor.
48+ * If the port is already open, it will be closed first.
49+ * This method will call the `onConnect` callback before it returns.
50+ * @returns {boolean } True if the connection was successfully opened, false otherwise.
51+ */
3552 async connectSerial ( ) {
3653 try {
3754 // If the port is already open, close it
@@ -52,6 +69,12 @@ class SerialConnectionHandler {
5269 }
5370 }
5471
72+ /**
73+ * Disconnects from the current serial port.
74+ * If a reading operation is in progress, it will be canceled.
75+ * This function will call the `onDisconnect` callback before it returns.
76+ * @returns {Promise<void> } A promise that resolves when the port has been closed.
77+ */
5578 async disconnectSerial ( ) {
5679 if ( ! this . currentPort ) return ;
5780 try {
@@ -66,6 +89,11 @@ class SerialConnectionHandler {
6689 } ;
6790 }
6891
92+ /**
93+ * Tries to establish a connection to the first available serial port that has the Arduino USB vendor ID.
94+ * This only works if the user has previously granted the website access to that serial port.
95+ * @returns {Promise<boolean> } True if the connection was successfully opened, false otherwise.
96+ */
6997 async autoConnect ( ) {
7098 if ( this . currentPort ) {
7199 console . log ( '🔌 Already connected to a serial port.' ) ;
@@ -85,6 +113,12 @@ class SerialConnectionHandler {
85113 return false ;
86114 }
87115
116+ /**
117+ * Reads the specified number of bytes from the serial port.
118+ * @param {number } numBytes The number of bytes to read.
119+ * @param {number } timeout The timeout in milliseconds.
120+ * If the timeout is reached, the reader will be canceled and the read lock will be released.
121+ */
88122 async readBytes ( numBytes , timeout = null ) {
89123 if ( this . currentPort . readable . locked ) {
90124 console . log ( '🔒 Stream is already locked. Ignoring request...' ) ;
@@ -143,6 +177,10 @@ class SerialConnectionHandler {
143177 return bytesRead ;
144178 }
145179
180+ /**
181+ * Reqests an image frame from the Arduino board by writing a 1 to the serial port.
182+ * @returns {Promise<void> } A promise that resolves when the frame has been requested and the write stream has been closed.
183+ */
146184 async requestFrame ( ) {
147185 if ( ! this . currentPort ?. writable ) {
148186 console . log ( '🚫 Port is not writable. Ignoring request...' ) ;
@@ -155,6 +193,11 @@ class SerialConnectionHandler {
155193 await writer . close ( ) ;
156194 }
157195
196+ /**
197+ * Requests a frame from the Arduino board and reads the specified number of bytes from the serial port afterwards.
198+ * Times out after the timeout in milliseconds specified in the constructor.
199+ * @param {number } totalBytes The number of bytes to read.
200+ */
158201 async getFrame ( totalBytes ) {
159202 if ( ! this . currentPort ) return ;
160203
@@ -164,6 +207,13 @@ class SerialConnectionHandler {
164207 return await this . readBytes ( totalBytes , this . timeout ) ;
165208 }
166209
210+ /**
211+ * Registers event listeners for the `connect` and `disconnect` events of the serial port.
212+ * The `connect` event is fired when a serial port becomes available not when it is opened.
213+ * When the `connect` event is fired, `autoConnect()` is called.
214+ * The `disconnect` event is fired when a serial port is lost.
215+ * When the `disconnect` event is fired, the `onDisconnect` callback is called.
216+ **/
167217 registerEvents ( ) {
168218 navigator . serial . addEventListener ( "connect" , ( e ) => {
169219 // Connect to `e.target` or add it to a list of available ports.
0 commit comments