Graphical User Interface for Serial Communication

SerialUI provides a graphical interface to send and receive text and data from the serial port or BLE connection (Nordic UART Service).

It includes a serial plotter for displaying numerical data.

It offers features beyond other serial terminals. For example, in addition to features found on Arduino IDE Monitor or Plotter it offers:

• Serial over BLE (NUS)
• Recording of received data
• Extended charting of the data

Throughput is similar to other serial terminal programs.

This program is written in python using PyQt and Bleak as well as PyQtGraph or fastplotlib .

Under development are binary data transmission and indicating data with display elements other than a chart.

The main program is SerialUI.py. It uses files in the assets, docs and helper folders.

Video

Video using ESP32 with testBLESerial program. Data is transmitted using BLE Serial and maximum transfer test shows > 100 kByte/s. Device is initally connected to application with serial USB and then with serial BLE.

Description

The serial monitor interface

The serial charting interface

Serial BLE extension

How to Use This Program

Either use the executable from the release assets or run the program with python3 SerialUI.py

• Usage instructions.
• Supplemental instructions.

Installation

From Executables

Use the executable from the release assets on Github. No packages will need to be installed and no source code needs to be downloaded.

• MacOs supports arm architecture
• Linux supports ubuntu 24 with arm and amd64 architecture as well as ubuntu 22 with amd64 architecture
• Windows supports windows amd64 and arm64 architecture

From Source

Clone this repository into a folder where you store python programs and install the packages described below.

To work of the source code either download the zip or git clone https://github.com/uutzinger/SerialUI.git to that folder.

This program has dependencies. You can install them with scripts/setup.sh on Linux and MacOS and scripts\setup.ps1 on Windows.

There is build script in scripts/release.sh or release.ps1 to activate the C accelerated text parser with ./scripts/release.sh --build-c-accelerated or ./scripts/release.ps1 -build-c-accelerated

This requires a Cpp compiler and the python packages pybind11 and setuptools to be available.

A future version will also need:

• scipy image decompression (FFT)
• cobs serial data encoding (byte stuffing)
• tamp for compression (lightweight for microcontrollers)

Enabling / Disabling Features

The programs configuration is stored in config.py (main folder). Here you can enable/disable features such as:

• USE_FASTPLOTLIB: Plotting with fastplotlib instead of pyqtgraph
• USE_BLE: enable serial communication over BLE
• USE_BLUETOOTHCTL: enable pairing and trusting of BLE devices (available on Unix like systems)

The standalone executable does not provide access to the configuration file.

Modules

The program is organized into modules.

Nordic UART Service - BLE

The NUS provides a serial interface similar to regular USB interface for microcontrollers.

The implementation on a microcontroller requires more programming effort than a simple Serial.print especially if secure connections and automatic reconnection is considered. BLE connections can be optimized for low power, extended distance or high throughput.

A detailed example is the BLE test program which was used to test SerialUI.

With ESP32-S3 a transfer rate of more than 100kByte/s can be expected when BLE connection is optimized for high throughput.

Data Parsing

The data parser extract values and variable names from lines of text. Besides a python version, there is a C accelerated version available. For supported data formats see: Data Parsing Approach

Indicating Data

Indicating data is not implemented yet: Feature not implemented yet.

fastplotlib

Fastplotlib itself is under development. There is a custom legend.py in python libraries folder that is needed when you enable fastplotlib in the config file. The file replaces the legend.py of the creators. It needs more work.

During program startup the library and the chart widget are initialized. This requires building the pipeline for the GPU which takes 5-10 seconds. During that time the program might be sluggish.

fastplotlib is not available in the standalone executable and requires customizations. It is useful if you have GPU and need to display large data sets.

Arduino Test Programs

In the Arduino_programs folder are example programs that simulate data for serial UART and BLE connection.

To create your own application remove all the simulations except one and replace it with your code.

Efficiency

A detailed comparison of SerialUI with other serial IO programs was conducted.

The SerialUI is as performant as other good terminal programs. The maximum text transfer of an ESP32-S3 over USB is about 800k bytes/s and 100k bytes/s over BLE. With a Cortex-M7 (Teensy) we reached about 7M bytes/s over USB.

With both fastplotlib and pyqtgraph we can plot two channels with at least 200k samples per second at 10Hz plotting refresh rate. When large display history is needed fastplotlib with a dedicated GPU is better suited as plotting engine.

Packages utilized in this Project

The following libraries are used:

• asyncio for bleak**
• bleak - BLE**
• cobs - serial binary****
• fastplotlib - GPU based charting*** beta
• datetime
• difflib - device ID comparison
• html - html display
• logging
• markdown - markdown display
• math
• numpy - data buffer and display
• numba - accelerator*
• os
• pathlib
• platform
• pybind11 - text parsing acceleration*
• PyQt5 or 6 - UI
• pyqtgraph - charting
• re - regular expression filter
• scipy - fft ***
• setuptools*
• tamp - compressor ***
• textwrap - logging
• time
• typing
• wmi - USB events or pyudev - USB events
• zlib - compressor ***

[*] not required but will accelerate the program, [**] needed if BLE is enabled, [***] needed if fastplotlib is enabled, [***] future version

Scripts

Setup

A setup script creates a vritual python environment to run the application. It includes all required dependencies.

Release

Use of release scripts from the repository root. The release version is read from VERSION in config.py.

Option style:

• Linux shell convention uses --long-option (for example --build-executable).
• PowerShell convention uses -Parameter (for example -BuildExecutable).
• scripts/release.sh accepts both styles for parity (--build-executable and -build-executable).

Linux examples (scripts/release.sh):

• Show options: ./scripts/release.sh --help
• Update ankerl for C-accelerated parser extension: ./scripts/release.sh --update-ankerl
• Build C- ccelerated parser extension before packaging: ./scripts/release.sh --build-c-accelerated
• Build standalone executable (also creates dist/SerialUI-*.zip): ./scripts/release.sh --build-executable
• Build, commit, tag, and push: ./scripts/release.sh --build-executable --build-c-accelerated --commit --tag --push
• Create GitHub release for an existing version tag without rebuilding: ./scripts/release.sh --release
• Upload existing archives in dist/ (*.tar.gz, *.zip) to an existing release: ./scripts/release.sh --upload-assets

Windows examples (scripts/release.ps1):

• Show options: .\scripts\release.ps1 -Help
• Build standalone executable (also creates dist\SerialUI-*.zip): .\scripts\release.ps1 -BuildExecutable
• Build standalone executable + C-accelerated parser: .\scripts\release.ps1 -BuildExecutable -BuildCAccelerated
• Upload existing archives in dist\ to an existing release: .\scripts\release.ps1 -UploadAssets

Github workflows

There are scripts that create my Github workflows to create executables on different platforms.

build_realease_all.sh creates all of the builds

On Windows amr64 platform, llvmlite is not available and numba acceleration is not activated.

Contributors

Urs Utzinger, 2022-2025 (University of Arizona),

Cameron K Brooks, 2024 (Western University),

GPT-5.3, OpenAI