tauri-plugin-serialplugin v2.0.0-rc.2

Tauri Plugin - SerialPort

This plugin enables Tauri applications to communicate with serial ports, allowing for the reading and writing of data to and from connected serial devices.

Installation

This plugin requires Rust version 1.70 or higher.

There are three recommended methods for installing this plugin:

1. Using crates.io and npm (easiest, requires trust in our publishing pipeline)
2. Directly from GitHub using git tags/revision hashes (most secure)
3. Git submodule in your Tauri project, then using the file protocol for source inclusion (most secure but less convenient)

Core Plugin

Add the following to your Cargo.toml file under src-tauri/Cargo.toml:

[dependencies]
tauri-plugin-serialplugin = "2.0.0-rc.1"

JavaScript Bindings

Install using your preferred package manager:

pnpm add tauri-plugin-serialplugin
# or
npm add tauri-plugin-serialplugin
# or
yarn add tauri-plugin-serialplugin

# For direct GitHub installation:
pnpm add https://github.com/s00d/tauri-plugin-serialplugin#main
# or
npm add https://github.com/s00d/tauri-plugin-serialplugin#main
# or
yarn add https://github.com/s00d/tauri-plugin-serialplugin#main

Usage

First, register the core plugin within your Tauri application's main setup:

src-tauri/src/main.rs

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_serialplugin::init())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Configuring Permissions

To use the plugin, you must define permissions in your capabilities configuration. Add the following to your /src-tauri/capabilities/default.json file:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "serialplugin:default"
  ]
}

The serialplugin:default permission allows basic usage of the plugin. If you need more granular permissions, you can specify them as follows:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "serialplugin:allow-available-ports",
    "serialplugin:allow-cancel-read",
    "serialplugin:allow-close",
    "serialplugin:allow-close-all",
    "serialplugin:allow-force-close",
    "serialplugin:allow-open",
    "serialplugin:allow-read",
    "serialplugin:allow-write",
    "serialplugin:allow-write-binary"
  ]
}

Permission Descriptions

Example Application

An example application can be found in the examples/serialport-test directory of this repository. This example demonstrates basic usage of the plugin, including opening, closing, and listing serial ports.

JavaScript API

After registering the plugin, you can access the plugin's APIs through the provided JavaScript bindings:

import { SerialPort } from "tauri-plugin-serialplugin";

// Example: Listing available serial ports
async function listPorts() {
  const ports = await SerialPort.available_ports();
  console.log(ports);
}

listPorts();

Additional Methods

SerialPort.available_ports()

Lists all available serial ports.

SerialPort.forceClose(path: string)

Forcefully closes the specified serial port.

SerialPort.closeAll()

Closes all open serial ports.

SerialPort.cancelListen()

Cancels serial port monitoring.

SerialPort.cancelRead()

Cancels reading data from the serial port.

SerialPort.change(options: { path?: string; baudRate?: number })

Changes the path and/or baud rate of the serial port.

SerialPort.close()

Closes the currently opened serial port.

SerialPort.disconnected(fn: (...args: any[]) => void)

Sets up a listener for when the serial port is disconnected.

SerialPort.listen(fn: (...args: any[]) => void, isDecode = true)

Monitors serial port information and handles data using the provided callback function.

SerialPort.open()

Opens the serial port with the specified settings.

SerialPort.read(options?: ReadOptions)

Reads data from the serial port with optional settings for timeout and size.

SerialPort.setBaudRate(value: number)

Sets the baud rate of the serial port.

SerialPort.setPath(value: string)

Sets the path of the serial port.

SerialPort.write(value: string)

Writes data to the serial port.

SerialPort.writeBinary(value: Uint8Array | number[])

Writes binary data to the serial port.

Example Code

Below is a small example demonstrating how to use the plugin to open, close, and list available serial ports:

import { SerialPort } from 'tauri-plugin-serialplugin';

let serialport: SerialPort | undefined = undefined;
let name: string;

function openPort() {
  serialport = new SerialPort({ path: name, baudRate: 9600 });
  serialport
    .open()
    .then((res) => {
      console.log('open serialport', res);
    })
    .catch((err) => {
      console.error(err);
    });
}

function closePort() {
  serialport
    .close()
    .then((res) => {
      console.log('close serialport', res);
    })
    .catch((err) => {
      console.error(err);
    });
}

function availablePorts() {
  SerialPort.available_ports()
    .then((res) => {
      console.log('available_ports: ', res);
    })
    .catch((err) => {
      console.error(err);
    });
}

Contributing

We welcome pull requests! Please ensure you read our Contributing Guide before submitting a pull request.

Partners

Support for this plugin is provided by our generous partners. For a complete list, please visit our website and our Open Collective.

License

This code is dual-licensed under MIT or Apache-2.0, where applicable, © 2019-2023 Tauri Programme within The Commons Conservancy.

This README provides an overview, installation instructions, and basic usage examples for integrating serial port communication into a Tauri application. Further details and advanced usage should be documented based on the full capabilities of the plugin and its API.