https://github.com/robsonos/spie
A comprehensiveserial monitor/plotter application using Electron, Node SerialPort and Ionic/Angular
https://github.com/robsonos/spie
angular arduino electronjs ionic serialport uart
Last synced: 6 months ago
JSON representation
A comprehensiveserial monitor/plotter application using Electron, Node SerialPort and Ionic/Angular
- Host: GitHub
- URL: https://github.com/robsonos/spie
- Owner: robsonos
- License: mit
- Created: 2024-11-12T03:44:40.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-01-17T01:31:41.000Z (about 1 year ago)
- Last Synced: 2025-03-25T23:11:54.803Z (about 1 year ago)
- Topics: angular, arduino, electronjs, ionic, serialport, uart
- Language: TypeScript
- Homepage:
- Size: 55.7 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
SPIE
This repository helps you quickly set up and develop your serial port communication project. Built with **ElectronJS** and a modern **Ionic/Angular** front-end, it uses an **NX monorepo** structure for efficient project management.
The repository provides:
- Core functionality of Arduino's Serial Monitor, enhanced with tools to configure, monitor, and communicate with serial devices
- Core functionality of Arduino's Serial Plotter, enhanced with tools to select, zoom, export and visualize data
- Cross-platform desktop application (`windows`, `linux` and `macOS`)
- Hot-reloading to accelerate development and testing cycles
- Enforced code linting and formatting
- Enforced conventional commits
- Streamlined workspace management and remote caching with [NX](https://nx.dev/)
- CI/CD and Release pipelines with local testing
- Angular's signals and RxJS for reactivity and state management
- Unit testing examples
- E2E testing examples
- Automatic updates on new github releases (see [limitations](#limitations) for more details)
- Modern tech stack:
| Package | version |
| ---------- | ------- |
| nodejs | 22.x.x |
| angular | 20.x.x |
| ionic | 8.x.x |
| electron | 34.5.x |
| nx | 21.3.10 |
| typescript | 5.8.x |
For a demo, check the [sample binaries](https://github.com/robsonos/spie/releases).
## Index
- [Features](#features)
- [Getting started](#getting-started)
- [Nx tasks](#nx-tasks)
- [CD/CI/Release workflow](#cdcirelease-workflow)
- [Troubleshooting](#troubleshooting)
## Features
### Connection
### Sending Data
### Terminal
### Plotter
### Auto update
[Back to Index](#index)
## Getting Started
Firstly, ensure the following are installed:
- [Node.js](https://nodejs.org) (preferably using `nvm` for version management)
- [NX CLI](https://nx.dev) (`npm install -g nx`, or you can use `npx nx ...` if you prefer)
### Steps
1. Clone the repository:
```sh
git clone https://github.com/robsonos/spie
cd spie
```
2. Install dependencies:
```sh
npm i
```
3. Run the application:
```sh
npx nx run-many -t serve
```
### Sample Arduino code
If you want a minimalistic two way serial example, use the following:
```cpp
#include
int period = 1000;
unsigned long time_now = 0;
void setup() {
Serial.begin(115200);
}
void loop() {
if (Serial.available() > 0)
Serial.write(Serial.read());
if (millis() > time_now + period) {
time_now = millis();
Serial.print("Hello World ");
Serial.println(millis());
}
}
```
For a example used on the plotter images, check out [spie-firmware](https://github.com/robsonos/spie-firmware).
### Plotter
The Plotter expects a line feed LF (`\n`) to separate records. Ensure that there is a linebreak character after the last variable in each record.
You can use different delimiters to separate variables within a record: space (` `), tab (`\t`), or comma (`,`).
For labeled data, the plotter can interpret variables in the format `:`.
The Plotter supports parsing single and multiple variables in each record, handles duplicates for the same
variable label, and correctly groups the data under their respective labels.
Examples:
Single variable: `1\n`, `2\n`
Multiple variables: `1,2\n`, `3,4\n`
Multiple labeled variables: `temp1:1,temp2:2\n`, `temp1:3,temp2:4\n`
[Back to Index](#index)
## NX tasks
Learn more about NX in this [Angular Monorepo tutorial](https://nx.dev/getting-started/tutorials/angular-monorepo-tutorial?utm_source=nx_project&utm_medium=readme&utm_campaign=nx_projects).
Here are the most commonly used NX tasks:
- Serve the applications:
```sh
npx nx run-many -t serve
```
- Lint the code:
```sh
npx nx run-many -t lint
```
- Run unit tests:
```sh
npx nx run-many -t test
```
- Run e2e tests:
```sh
npx nx run-many -t e2e
```
- Build the applications (development):
```sh
npx nx run-many -t build
```
- Build the applications (production):
```sh
npx nx run-many -t build --prod
```
- Build and generate unpacked executables:
> [!WARNING]
> Build the applications first
```sh
npx nx run spie:package
```
Output files are located in `dist\packages`
- Build and generate the executables:
> [!WARNING]
> Build the applications first
```sh
npx nx run spie:make
```
Output files are located in `dist\executables`
[Back to Index](#index)
## CD/CI/Release workflow
There are many ways CD/CI/Release workflow can be implemented. I chose the most convenient one and here is how it is meant to work:
- `dev`: holds the development code. Pushes to this will trigger the `CI workflow`, test your code, and create a PR to merge it into `main`.
- `main`: holds the code for the latest release. Pushes to this will trigger the `CD workflow` and create a new github release and tag. You should never need to push commits to `main`; use `dev` and create a PR instead. The code on this branch should always come from merges from `dev`.
- Once a new release is done, the `Release` workflow will be triggered to build and add the binaries to the release.
- If you need to maintain more release channels, like `main` is at `v3.x.x` but you need to support `v1.x.x`, I would recommend using a similar approach:
- `main` for `v3.x.x`
- `main/v1` for `v1.x.x`
- `dev` for `v3.x.x` development
- `dev/v1` for `v1.x.x` development
- I may look into exemplifying the above and `pre-releases` in the feature
### act
You can use [act](https://github.com/nektos/act) to test workflows locally. Read more about `act` [here](https://nektosact.com/). Also, check out [.actrc](.actrc)
- CI
```shell
act push -W .github/workflows/ci.yml
```
- CD
```shell
act push -W .github/workflows/cd.yml
```
- Release
```shell
act release -W .github/workflows/release.yml -e event.json
```
Sample `event.json`
```json
{
"action": "created",
"release": {
"name": "v1.0.0",
"tag_name": "1.0.0"
}
}
```
[Back to Index](#index)
## Troubleshooting
- Serial data may be delivered in more than one `.on('data')` event. This means data received by the serialport library might arrive in multiple packets. For details, see [node-serialport/issues/659](https://github.com/serialport/node-serialport/issues/659). This is not a problem in most cases, but unexpected behavior may occur if you are trying to monitor data at a fast rate. A good way to demonstrate the issues is to send data every `5ms`, `115200` baud rate and with `show timestamps`. You will notice that every so often there is a "broken" message. If your data is terminated with a new line (`\n`) you can use `use readline parser` to alleviate that. If you are developing your own application, I would recommend using one of the [parsers](https://serialport.io/docs/api-parsers-overview) available.
- Depending on your operating system, the serial port ingestion may take a while, which could make the `plotter` look off when using `timestamp` instead of `sample count`.
- `macOS` application must be signed in order for auto updating to work. See [electron-builder Auto Update](https://www.electron.build/auto-update) for more details.
[Back to Index](#index)
## Contributors
[Back to Index](#index)