DEV Community

Cover image for The amazing powers of the web: Web Serial API
Diego Coy
Diego Coy

Posted on • Updated on

The amazing powers of the web: Web Serial API

The Web Serial API

The Web Serial API allows us to interact with serial devices by sending and receiving data from within a web browser.

Using this API we can select and connect to a serial device, and then send and receive messages in just a couple of lines of JavaScript code.

As you can imagine, this is API is only supported by modern Chromium based desktop browsers right now (April 2020) but hopefully support will improve in the near future. At this moment you need to enable your browser's Experimental Web Platform Features, just copy and paste the right URL:

  • chrome://flags/#enable-experimental-web-platform-features
  • opera://flags/#enable-experimental-web-platform-features
  • edge://flags/#enable-experimental-web-platform-features

Why?

Why not? This API brings one more capability to the more widespread platform, the web. Having access to physical devices will make it easier for people with web development knowledge to start diving into the waters of the IoT movement by interfacing with it through the browser, a familiar platform for them.

So dust off that Arduino you may have laying around, connect it to your computer and let's begin connecting the web and the physical world.

How?

Connection

After validating if serial is supported by the browser, we use the requestPort method to prompt the user with a Browser provided UI displaying a list of available serial devices.

list of serial devices

We then open a port to connect with that device. Here the baudRate needs to match the baud rate used by the device. The expected baud rate values are:

115200, 57600, 38400, 19200, 9600, 4800, 2400, 1800, 1200, 600, 300, 200, 150, 134, 110, 75, 50
Enter fullscreen mode Exit fullscreen mode

Using the readable ReadableStream and writable WriteableStream properties that we get from the port we create a reader and a writer.

if ('serial' in navigator) {
  try {
    const port = await navigator.serial.requestPort();
    await port.open({ baudRate: 9600 });
    this.reader = port.readable.getReader();
    this.writer = port.writable.getWriter();
  }
  catch (err) {
    console.error('There was an error opening the serial port:', err);
  }
}
else {
  console.error('The Web serial API doesn\'t seem to be enabled in your browser.');
}
Enter fullscreen mode Exit fullscreen mode

Here we're storing both the reader and the writer objects globally for later use.

Reading and Writing

The data that is transferred between the browser and the device is encoded, so we need to create an encoder to use when sending a message and a decoder to be able to properly read a message.

constructor() {
  this.encoder = new TextEncoder();
  this.decoder = new TextDecoder();
}
Enter fullscreen mode Exit fullscreen mode

Writing

Writing data, or sending a message, is really easy. First we take the message we wish to send and encode it, then using the write method of the global writer object we previously created.

async write(data) {
  const dataArrayBuffer = this.encoder.encode(data);
  return await this.writer.write(dataArrayBuffer);
}
Enter fullscreen mode Exit fullscreen mode

The write method returns a promise that we can use to validate the completion of the write process.

Reading

The reading process is actually similar to the write one, using the reader's read method we get the data that's coming from the device and pass it to the decorder's decode method.

async read() {
  try {
    const readerData = await this.reader.read();
    return this.decoder.decode(readerData.value);
  }
  catch (err) {
    const errorMessage = `error reading data: ${err}`;
    console.error(errorMessage);
    return errorMessage;
  }
}
Enter fullscreen mode Exit fullscreen mode

Here we can catch any reading error and do something with it.

That's it! that's the basic setup of a Web Serial API handler.

Examples

serial-basic

The basic example uses a regular Arduino without any additional hardware. When sending a 1 as a message the Arduino's onboard LED will light up, when sending 0 it'll turn off.


serial and LED Matrix

The "advanced" example keeps the same Web Serial API handler code, it just adds some extra bits to the client side code. It also expects the user to have a MAX7219 controlled 8x8 LED matrix, a really affordable and easy to get LED matrix.

Origin Trial

Update: Web Serial API is promoted to stable from Chrome 89. This means that an Origin Trial token is not required anymore.

Origin trials enable us to ship experimental features without having our users enable flags in their browsers. Check out more here: https://github.com/GoogleChrome/OriginTrials and here https://developers.chrome.com/origintrials/

Browser support

  • Chrome
    • Experimental: 80+
    • Stable: 89+
  • Edge (Chromium based)
  • Opera (you need to enable it's flag in opera://flags/#enable-experimental-web-platform-features)

Further reading

Next steps

Chromium + Web Serial API + Raspberry Pi == Awesomeness 🔥

Top comments (15)

Collapse
 
c00lnerd profile image
c00lnerd

I would like to use this to connect to HC-05, HC-06 devices for controlling arduinos boards.
Your web app doesn't seem to see those when I try to connect,
What do I need to do?

Collapse
 
unjavascripter profile image
Diego Coy

Indeed the example code is quite basic, you would need to update the arduino code to return the sensor readings and handle it on the browser side by catching the messages received by the read function. I'll check if I still have one of those sensors and maybe add it to the example code.

Collapse
 
eliasorggro profile image
eliasorggro

that's great dude !
really made my day
I'm wondering how to use this with a react application ...

Collapse
 
andresgamez profile image
Ændres Gámez

Hello Diego! Thanks for this, it's awesome and easy to implement. I just have one question...
When I run the project locally it works perfect but when I load it into a Elastic Beanstalk app running with ruby it seems like my browser doesn't have enabled "enable-experimental-web-platform-features" but it is enable. Any reason for this? Thanks in advance.

Collapse
 
unjavascripter profile image
Diego Coy

Hi, did you add an Origin Trial token to your app?

The enable-experimental-web-platform-features makes the API available for your browser when developing locally. Once you deploy it you'll need an Origin Trial token to make the browser load the API. Check developers.chrome.com/origintrials...

Collapse
 
andresgamez profile image
Ændres Gámez

It's working fine. Thanks man!
Another thing I had to do in order to use Serial API was adding a SSL certificate to my site.

Thread Thread
 
unjavascripter profile image
Diego Coy

Great to know! Yep, these new APIs require the web app to use HTTPS to be made available because they can be a risk if not loaded securely.

Collapse
 
virtualillie profile image
Lillie Bahrami

Hey Diego, thanks for the great tutorial! I'm running your demo with an Arduino Duemilanove right now and am getting the error "error reading data: TypeError: Cannot read property 'read' of undefined" when I try to send messages. Any idea what could be causing that? Thanks again!

Collapse
 
unjavascripter profile image
Diego Coy

Hi Lillie, It seems like I didn't add a Serial message to be send back in the Arduino code. I just updated the repo and the example. Give it a try and let me know how it goes.

Collapse
 
virtualillie profile image
Lillie Bahrami

Works like a charm! Thank you Diego, excited to use this in my own projects :)

Thread Thread
 
unjavascripter profile image
Diego Coy

Please let me know what you create :D

Collapse
 
mgorbet profile image
Matt Gorbet

I think either the experimental API was changed or your code is broken, because it doesn't run (either from here or gitHub) for me, but if I change 'baudrate' to 'baudRate' in your script it begins to work.

(I posted an issue on your github as well)

Collapse
 
oleksiiivanov profile image
Oleksii Ivanov

I definitely should blow away dust from my arduino xD. Good Job 👍

Collapse
 
unjavascripter profile image
Diego Coy

Thanks! Please do and let me know what you create :)

Collapse
 
alexbaro_pt profile image
alessandro

Great Job, you have saved my life