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.

async function tryConnect() {
    try{
    const connected = await jofemar.connect();
    } catch(e){
        console.error('Error connecting to the device:', e);
    }
}

Never finish until the connection is closed

Warning

The following code now is obsolete because the connect method now returns a promise that resolves when the connection is established. So, the code below is just an example of how the connection works, but you should not use it in your code.

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');
}

Info

To connect now is more easy, you just need to call the connect method and it will handle the connection for you. You can also use the connect method with the then method to handle the connection

jofemar.connect().then(() => {
    console.log('Connected');
}).catch(console.error);

Or

async function tryConnect() {
    try {
        await jofemar.connect();
        console.log('Connected');
    } catch (e) {
        console.error('Error connecting to the device:', e);
    }
}