🔌 bbcom

Cross-platform desktop serial-port debug assistant

English · 中文

Download

---

Overview

bbcom is a Tauri desktop tool for embedded developers who need a fast, inspectable serial console. It combines multi-session serial TX/RX, protocol parsing, Modbus master tooling, waveform plotting, export, and an optional Z.ai-powered command/log assistant in one application.

The frontend owns session state and protocol engines so high-volume serial data can stay responsive in the webview. The Rust side stays deliberately small: Tauri commands, filesystem/export work, checksums, updater integration, and AI client calls.

Highlights

• Multi-session serial console with independent connection state, TX/RX counters, pause/resume, search, direction filters, and restored recent captures.
• High-throughput rendering path using an O(1) RX queue, batched requestAnimationFrame flushes, virtual scrolling, and explicit frame reactivity.
• Modbus master for RTU and raw-PDU transports, FC01-FC06/FC10 operations, contiguous read/write batching, periodic read/write loops, replay sources, and register-to-waveform bindings.
• Protocol tools for delimiter, fixed-length, and length-field frame parsing, plus .bbrec raw stream record/replay.
• Waveform plotting for numeric RX streams or Modbus register samples, with channel visibility, statistics, autoscale, pause, clear, and CSV export.
• Automation helpers including macros with control flow, RX-triggered responses, quick commands, send history, highlights, connection presets, DTR/RTS control, and a 250 ms BREAK pulse.
• Export and logging to TXT, CSV, JSONL, and BIN; large exports use a capture-file path so big frame sets do not cross IPC as one giant argument.
• AI assistant for Linux/BusyBox command generation and serial-log analysis, with model validation, request cooldown, risk classification, and streaming response assembly.
• Desktop polish with dark/light themes, English/Chinese UI catalogs, persisted settings, keyboard shortcuts, and optional update checks.

Screenshots

Main Window	AI Assistant
Modbus Registers	Waveform Plot

Core Features

Serial Console

• Display modes: HEX, ASCII, UTF-8, ANSI, and HEX+ASCII split view.
• Port settings: baud rate, data bits, stop bits, parity, flow control, DTR, and RTS.
• Hot-plug port refresh, reconnect attempts, millisecond timestamps, per-frame and merged views.
• Cyclic sending, quick commands, send history, and large-write chunking with retry/backoff.
• Trigger rules that match text or HEX in RX and send a response with cooldown.
• Keyword highlights scoped to All/TX/RX with text or HEX matching.

Protocol And Data Tools

• Parser presets for CRLF, NMEA 0183, AT/modem, SCPI, NUL-delimited binary, and length-prefixed frames.
• .bbrec capture/replay for raw RX/TX byte streams.
• Modbus .bbreg import/export for register tables and replay data sources.
• Export filters by time range and direction.
• Checksum / CRC-8 / CRC-16 / CRC-32 calculations.

AI Workflows

• Standalone always-on-top assistant window.
• Natural-language prompt to terminal command, with safe/caution/dangerous risk classification.
• Serial-log Q&A scoped to the current session context.
• Z.ai model registry shared between frontend validation and Rust dispatch.
• Stream accumulator for incremental SSE responses and abort handling.

Tech Stack

Layer	Technology
Desktop	Tauri v2
Backend	Rust 2024, tokio, serde, thiserror, crc, zai-rs
Frontend	Vue 3 Composition API + TypeScript
UI	Naive UI, lucide-vue-next
State	Pinia
Build	Vite 6, pnpm
Serial	tauri-plugin-serialplugin
Persistence	localStorage snapshots + Tauri Store for local secrets
Test/Quality	node:test, c8, ESLint, Prettier, madge, cargo test, clippy, criterion

Getting Started

Prerequisites

• Rust stable 1.85+ (edition 2024)
• Node.js 22+
• pnpm 11+
• OS permission to access serial ports

On Linux you may need to add your user to the serial group, for example:

sudo usermod -aG dialout "$USER"

Install And Run

pnpm install
pnpm tauri:dev

Frontend-only development:

pnpm dev

Production builds:

pnpm build
pnpm tauri:build

The helper script wraps the same common flows:

chmod +x scripts/dev.sh
./scripts/dev.sh install
./scripts/dev.sh dev
./scripts/dev.sh build

Scripts

Command	Description
pnpm dev	Start the Vite dev server
pnpm build	Type-check the Vue app and build the frontend
pnpm preview	Preview the frontend build
pnpm tauri:dev	Run the Tauri desktop app with frontend HMR
pnpm tauri:build	Build the desktop application bundle
pnpm format	Format frontend and Rust code
pnpm format:check	Check frontend and Rust formatting
pnpm lint	Run ESLint on src/
pnpm test:frontend	Run frontend unit tests
pnpm test:rust	Run Rust unit tests
pnpm test	Run frontend and Rust tests
pnpm coverage:frontend	Run frontend tests under the .c8rc.json coverage gate
pnpm coverage:lib	Enforce per-file line coverage for framework-free src/lib/ modules
pnpm bench:frontend	Run frontend hot-path benchmarks
pnpm bench:frontend:write	Refresh the local frontend benchmark baseline
pnpm bench:rust	Run Rust criterion benchmarks
pnpm cycles	Fail on TypeScript import cycles
pnpm check	Run lint, format check, build, and unit tests

Project Map

bbcom/
├── src/                         # Vue frontend
│   ├── components/              # App shell, session view, terminal panels, AI panels
│   ├── composables/             # Serial connection, Modbus orchestration, export, triggers
│   ├── lib/                     # Framework-free domain logic and IPC wrappers
│   │   ├── modbus/              # Request building, batching, transport, loops, replay
│   │   ├── format.ts            # HEX/text/ANSI/HEX+ASCII formatting
│   │   ├── serial-rx-queue.ts   # Bounded RX queue for high-rate captures
│   │   ├── protocol-parser.ts   # Delimiter/fixed/length-field frame parsing
│   │   ├── waveform*.ts         # Parsing, viewport math, and canvas rendering helpers
│   │   ├── session-persistence.ts
│   │   └── ipc.ts
│   ├── stores/                  # Pinia stores for sessions, serial ports, app settings
│   ├── styles/                  # Theme tokens and global CSS
│   ├── types/                   # Domain type barrels
│   ├── App.vue                  # Main window entry
│   └── AiWindow.vue             # Floating AI window entry
├── src-tauri/                   # Rust backend
│   ├── src/commands/            # Tauri commands: ai, checksum, export, log, updater, window
│   ├── src/export/              # TXT/CSV/JSONL/BIN formatters
│   ├── src/models/              # IPC data and app error models
│   ├── src/utils/               # HEX, timestamp, checksum helpers
│   └── benches/hot_paths.rs     # Criterion benchmarks
├── tests/frontend/              # node:test unit tests and frontend benchmarks
├── images/                      # README screenshots
├── .github/workflows/           # CI and release workflows
├── ARCHITECTURE.md              # Maintainer architecture guide
└── scripts/dev.sh               # Development helper

For module ownership, data-flow invariants, upstream constraints, and manual verification guidance, read ARCHITECTURE.md.

Verification

CI runs frontend lint/format/build/test/coverage/benchmark/cycle gates plus Rust format, clippy, and tests. Rust coverage is collected as a best-effort tarpaulin report in CI, while frontend coverage gates are enforced through c8.

Before opening a pull request, run:

pnpm check
pnpm cycles
pnpm coverage:frontend
pnpm coverage:lib

Use pnpm bench:frontend and pnpm bench:rust when changing hot paths such as formatting, RX queue handling, session frame storage, export, checksums, or Modbus batching.

FAQ

Which platforms are supported?

bbcom targets Windows, macOS, and Linux through Tauri v2.

How do I get a Z.ai API key?

Create a key at open.bigmodel.cn and enter it in the AI assistant settings panel.

Why is my serial port missing?

• Confirm the device is connected and the driver is installed.
• On Linux, check group permissions such as dialout.
• On macOS, check ls /dev/cu.*.
• Reopen the port list after plugging in the device.

Contributing

Please use Conventional Commits, keep TypeScript strict, keep Rust warnings clean, and include focused tests for behavior changes. For persisted session shape changes, bump SESSION_STORAGE_VERSION, add a migration step, and cover legacy data with a regression test.

License

This project is licensed under the MIT License.