Data I/O Operations
Relevant source files
The following files were used as context for generating this wiki page:
The Data I/O Operations system in the tauri-plugin-serialplugin provides a robust interface for exchanging data between a Tauri application's frontend and physical serial hardware. It supports synchronous request-response patterns for reading and writing data, as well as an asynchronous event-driven model for continuous data monitoring.
This system handles data in both UTF-8 string formats and raw binary byte arrays, ensuring compatibility with a wide range of serial protocols. It abstracts platform-specific complexities across Windows, macOS, Linux, and Android, providing a unified JavaScript API for developers.
Architecture and Data Flow
The Data I/O architecture follows the standard Tauri plugin pattern, where JavaScript calls in the "Guest" layer are proxied through Tauri's IPC mechanism to Rust commands, which then interact with native OS serial drivers or the Android USB host API.
This diagram illustrates the multi-layered path data takes from the frontend to the physical hardware.
Sources: src/lib.rs, guest-js/index.ts, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt
Write Operations
The plugin provides two primary methods for sending data to a serial port: write for text-based communication and writeBinary for raw byte transmission.
Text Write
The write method accepts a string and an optional encoding (defaulting to UTF-8). On the backend, it converts the string to bytes and transmits them through the open port handle. On Android, writes are synchronous as the underlying usb-serial-for-android library does not expose a transmit backlog.
Binary Write
The writeBinary method allows sending raw data as a Uint8Array or a numeric array. This is critical for binary protocols like Modbus or custom firmware updates.
| Feature | write | writeBinary |
|---|---|---|
| Input Type | string | Uint8Array | number[] |
| Backend Endpoint | plugin:serialplugin|write | plugin:serialplugin|write_binary |
| Android Behavior | Synchronous | Synchronous |
Sources: guest-js/index.ts:480-515, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:215-228, android/README.md
Read Operations
Reading data can be performed on-demand using synchronous calls that wait for a specific amount of data or a timeout.
On-Demand Reading
Frontend developers can call read or readBinary to retrieve data currently sitting in the hardware or OS buffer.
read(options): Returns a string decoded from the incoming bytes.readBinary(options): Returns aUint8Array.
Both methods support an options object:
size: The maximum number of bytes to read (default: 1024).timeout: How long to wait for data in milliseconds (default: 1000).
Sequence of a synchronous read operation.
Sources: guest-js/index.ts:530-575, tests/port-operations.test.ts:100-145
Asynchronous Listening
For real-time applications, the system supports a "Listening" mode where the backend continuously monitors the port and pushes data to the frontend via events.
The Listening Lifecycle
startListening(options): Instructs the backend to begin a background polling loop.- On Android, users can specify a
serialDataFlushIntervalMs(10ms to 2000ms) to batch data into single events for better performance.
- On Android, users can specify a
listen(callback): Registers a JavaScript handler for theserialDataevent.stopListening(): Terminates the background polling.
Buffered Emitter (Android)
On Android, data is managed by a BufferedEmitter. It accumulates bytes from the USB bus and flushes them to the JavaScript layer based on the configured interval. This reduces the IPC overhead compared to emitting every single byte as it arrives.
| Parameter | Type | Description |
|---|---|---|
path | string | The port identifier to listen on. |
size | number | The buffer size for each read attempt. |
serialDataFlushIntervalMs | number | (Android only) Time between event flushes. |
Sources: guest-js/index.ts:580-620, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:265-285, android/README.md
Buffer Management
Proper I/O requires managing the state of internal buffers to prevent stale data from interfering with new commands.
Clearing Buffers
The clearBuffer command allows clearing input, output, or both buffers.
- Input: Discards data received but not yet read by the application.
- Output: Discards data written but not yet transmitted by the hardware.
Monitoring Buffer Levels
bytesToRead(): Returns the number of bytes currently available in the input buffer. On Android, this specifically tracks bytes in theBufferedEmitterwaiting for the next flush.bytesToWrite(): Returns the number of bytes waiting to be sent. Note that on Android this always returns0because writes are handled synchronously.
Sources: guest-js/index.ts:780-810, android/src/main/kotlin/app/tauri/serialplugin/SerialPlugin.kt:410-445, android/README.md
Summary of I/O Commands
| Command | Description | Platform Support |
|---|---|---|
read | Read data as string | All |
read_binary | Read data as byte array | All |
write | Write string data | All |
write_binary | Write byte array | All |
start_listening | Start background data monitoring | All |
stop_listening | Stop background data monitoring | All |
clear_buffer | Purge hardware/software buffers | All (Driver dependent) |
Sources: src/lib.rs:160-200, src/commands.rs