Skip to content

Commit a85053c

Browse files
committed
Add documentation to serial connection handler
1 parent e2789f4 commit a85053c

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

libraries/Camera/extras/WebSerialCamera/serialConnectionHandler.js

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
const ArduinoUSBVendorId = 0x2341;
22
const UserActionAbortError = 8;
33

4+
/**
5+
* Handles the connection between the browser and the Arduino board via Web Serial.
6+
*/
47
class 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

Comments
 (0)