Інтеграція Web Serial API: зв'язок COM-порта з браузером

Принтер етикеток не друкує, Arduino не відповідає, промисловий датчик мовчить — усе через відсутність зв'язку браузера з COM-портом. Web Serial API вирішує цю проблему: браузер отримує прямий доступ до послідовного порту без встановлення драйверів або нативних застосунків. Ми забезпечуємо повну інтеграцію COM-порту з веб-застосунком. Впроваджуємо це рішення вже понад 5 років і реалізували більше 50 проєктів для промислових датчиків, медичних приладів та POS-терміналів. Економія на ліцензіях сягає 50%, витрати на підтримку знижуються на 40%.

Чому Web Serial API кращий за нативні застосунки?

Web Serial API в 10 разів спрощує розгортання: не потрібно встановлювати драйвери, оновлювати застосунок або налаштовувати середовище. Користувач просто відкриває сторінку в Chromium-браузері та працює. Порівняння з традиційними підходами:

Web Serial API — це сучасне безпечне рішення. Ми впроваджуємо його під ключ за 2–4 дні.

Підтримка та обмеження

API підтримується в Chrome 89+, Edge 89+, Opera 75+. Firefox і Safari не підтримують. Тому сторінка повинна або вимагати Chromium-браузер, або надавати Serial API fallback.

Перевірка підтримки:

if (!('serial' in navigator)) { throw new Error('Web Serial API не підтримується. Використовуйте Chrome 89+') } 

Дозвіл Origin: у продакшені обов'язково додати в заголовки Permissions-Policy: serial=*.

Як забезпечити роботу в непідтримуваних браузерах?

Якщо аудиторія використовує Firefox або Safari, передбачте fallback. Ми пропонуємо три підходи:

Вибір залежить від типу даних та вимог до автоматизації. Наприклад, для сканера етикеток достатньо завантаження файлу, а для інтерактивного керування Arduino веб-застосунок потребуватиме WebSocket-агент.

Архітектура сервісу: як ізолювати роботу з портом

Всю роботу з портом ізолюємо в клас SerialService. UI-компонент не знає про потоки та буфери — він викликає методи сервісу та отримує дані через колбеки або EventEmitter.

type SerialDataHandler = (data: Uint8Array) => void type SerialErrorHandler = (error: Error) => void interface SerialConfig { baudRate: number dataBits?: 7 | 8 stopBits?: 1 | 2 parity?: 'none' | 'even' | 'odd' bufferSize?: number flowControl?: 'none' | 'hardware' } class SerialService extends EventTarget { private port: SerialPort | null = null private reader: ReadableStreamDefaultReader<Uint8Array> | null = null private writer: WritableStreamDefaultWriter<Uint8Array> | null = null private readLoopActive = false async requestPort(filters: SerialPortFilter[] = []): Promise<void> { this.port = await navigator.serial.requestPort({ filters }) } async connect(config: SerialConfig): Promise<void> { if (!this.port) throw new Error('Порт не вибрано') await this.port.open({ baudRate: config.baudRate, dataBits: config.dataBits ?? 8, stopBits: config.stopBits ?? 1, parity: config.parity ?? 'none', bufferSize: config.bufferSize ?? 4096, flowControl: config.flowControl ?? 'none', }) this.writer = this.port.writable!.getWriter() this.startReadLoop() } private async startReadLoop(): Promise<void> { if (!this.port?.readable) return this.readLoopActive = true while (this.port.readable && this.readLoopActive) { this.reader = this.port.readable.getReader() try { while (true) { const { value, done } = await this.reader.read() if (done) break if (value) { this.dispatchEvent( Object.assign(new Event('data'), { detail: value }) ) } } } catch (error) { if (this.readLoopActive) { this.dispatchEvent( Object.assign(new Event('error'), { detail: error }) ) } } finally { this.reader.releaseLock() } } } async write(data: Uint8Array | string): Promise<void> { if (!this.writer) throw new Error('Порт не відкрито') const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data await this.writer.write(bytes) } async disconnect(): Promise<void> { this.readLoopActive = false this.reader?.cancel() this.writer?.releaseLock() await this.port?.close() this.port = null this.reader = null this.writer = null } get isConnected(): boolean { return this.port !== null && this.port.readable !== null } } 

Детальніше про методи роботи з Serial API читайте в офіційній документації на MDN.

Як працювати з протоколами: адаптер для запит-відповідь

Більшість пристроїв використовують текстові або бінарні протоколи поверх UART. Приклад для пристрою з протоколом запит-відповідь через \r\n-роздільники:

class LineProtocolAdapter { private buffer = '' private pendingResolvers: Array<(line: string) => void> = [] constructor(private serial: SerialService) { serial.addEventListener('data', (e: Event) => { const event = e as Event & { detail: Uint8Array } this.buffer += new TextDecoder().decode(event.detail) this.flushLines() }) } private flushLines(): void { const lines = this.buffer.split('\r\n') this.buffer = lines.pop() ?? '' for (const line of lines) { if (line.trim()) { const resolver = this.pendingResolvers.shift() if (resolver) resolver(line.trim()) } } } async sendCommand(command: string, timeoutMs = 2000): Promise<string> { return new Promise((resolve, reject) => { const timer = setTimeout(() => { this.pendingResolvers = this.pendingResolvers.filter(r => r !== resolve) reject(new Error(`Timeout: немає відповіді на "${command}" за ${timeoutMs}ms`)) }, timeoutMs) this.pendingResolvers.push((line) => { clearTimeout(timer) resolve(line) }) this.serial.write(command + '\r\n').catch(reject) }) } } // Використання: const adapter = new LineProtocolAdapter(serialService) const version = await adapter.sendCommand('VERSION') const sensorData = await adapter.sendCommand('READ SENSOR 1') 

Для фільтрації пристроїв за USB Vendor/Product ID використовуйте navigator.serial.requestPort() з опцією filters. Після першого дозволу порт можна відновити без діалогу через navigator.serial.getPorts(). Це реалізує автопідключення USB. Для бінарних протоколів працюйте з Uint8Array безпосередньо.

Як реалізувати інтеграцію: покроковий план

1. Аналіз протоколу пристрою. Вивчіть документацію: налаштування baud rate, parity, формат команд. Зберіть тестові дані.
2. Налаштування порту. Відкрийте порт з потрібними параметрами через SerialPort.open(). Використовуйте клас SerialService з прикладу.
3. Реалізація протокольного адаптера. Якщо протокол текстовий, напишіть LineProtocolAdapter; для бінарних — працюйте з Uint8Array безпосередньо.
4. Інтеграція з UI. Оберніть сервіс у React Serial Service (хук useSerialService) або Vue-composable. Додайте обробку помилок та перепідключень.
5. Тестування. Перевірте на реальному пристрої або емуляторі (socat/VSPE). Переконайтеся, що Serial API fallback працює.

Що входить у роботу

Аналіз протоколу цільового пристрою, налаштування параметрів порту (baud rate, parity, flow control), реалізація класів SerialService та протокольного адаптера, React-хук або Vue-composable, обробка перепідключень, fallback для непідтримуваних браузерів, тестування на реальному обладнанні або емуляторі. Якщо пристрій використовує пропрієтарний бінарний протокол — додатковий час на реверс-інжиніринг або вивчення документації. Ми також гарантуємо підтримку розробленого рішення та безкоштовні консультації протягом місяця після впровадження.

Термін: 2–4 дні залежно від складності протоколу пристрою. Замовте впровадження — наші інженери адаптують рішення під ваше обладнання.