Skip to main content

Webserial

Webserial is an API for reading and writing serial devices directly from your browser. This tutorial will guide you through the process of connect to them with the Webserial API.

What is Webserial?​

Ok, let's clear something Webserial is an API that allows you to connect to physical devices from your browser. But to simplify things, we will refer to the custom API as Webserial.

Getting Started​

It's important to note that the Webserial API is only available in secure contexts (i.e., HTTPS or localhost). This is because the API allows you to connect to physical devices, and it would be a security risk if it were available on any website.

For that reason, you will need to run your code on a local server or use a secure connection (HTTPS). But not only that, only selected browsers support the Webserial API, so you will need to check if your browser supports it.

Check the table in Can I Use to see if your browser supports the Webserial API.

You can check if your browser supports the Webserial API by running the following code (i.e., in the browser console):

if ('serial' in navigator) {
    console.log('Webserial API is supported');
} else {
    console.log('Webserial API is not supported');
}

If your browser supports the Webserial API, good! You can continue with the tutorial.

Installation​

There many ways to install, but the recomended is the first one

Install by npm​

npm install @danidoble/webserial

Install by URL as module​

import * as webserial from 'https://cdn.jsdelivr.net/npm/@danidoble/webserial@latest/dist/webserial.js';

// OR

// only what you need, here we are importing all the devices, but you can import only one or two, etc.
import {Locker, Jofemar, Devices, Jofemar, Boardroid, Emulator} from 'https://cdn.jsdelivr.net/npm/@danidoble/webserial@latest/dist/webserial.js';

Install by URL Common JS​

You need download file from https://cdn.jsdelivr.net/npm/@danidoble/webserial@latest/dist/webserial.umd.cjs

after that rename it with extension .js in flavor of .cjs


<script src="./webserial.umd.js"></script>

Example​

Note

In this example we use method #1 (npm install @danidoble/webserial)

Import the module in your code:

import {Jofemar} from '@danidoble/webserial';

Let's create a new instance of the Jofemar class (by default, is not needed pass any parameter to the constructor.)

const machine = new Jofemar();

But of course, you can pass the parameters to the constructor, like below:

Note: only include the parameters that you want to change, the rest will be the default values.

const machine = new Jofemar({
    filters: [],
    config_port: {
        baudRate: 9600,
        dataBits: 8,
        stopBits: 1,
        parity: "none",
        bufferSize: 32768,
        flowControl: "none",
    },
    no_device: 1,
    device_listen_on_port: 1,
});

Now, let's connect to the device, since the connect method is asynchronous, we need to use await/async or promise to handle the connection. Or you can use the then method to handle the connection.

Note: When the async function execute, never finish until the connection is closed, i.e: check this.

function tryConnect() {
    jofemar.connect().then(() => {
    }).catch(console.error);
}

Never finish until the connection is closed​

If you run the code below, the console never will print the message Connected, because the connection still open. this is because the connection is still open, and the async function never finish, unless the connection is closed or serial not connected.

But when you disconnect the serial or if you not select a device in the prompt, the console will print the message Connected. So please DON'T do this, it's just an example.

async function tryConnect() {
    await jofemar.connect().catch(console.error);
    console.log('Connected');
}