Table of contents

• introduction
• Tech Stack
• Features
• Getting started
  • Installation
  • Usage
• Contributing
• License

Introduction

Serialblocks is an open-source project that combines web development with embedded systems
Communicate with a real hardware like an Arduino through an interactive web-based interface.

Built with❤︎by ahmad ghoniem and contributors

see in action

project uses the following stack:

(Back to top)

1. Client-side (Serialblocks-app)

• React
• Zustand
• ShadcnUI
• TailwindCSS
• Socket.IO (Client API)

2. Server-side (Serialblocks-local)

• Node.JS
• Socket.IO (Server API)
• Node SerialPort

Features

(Back to top)

• communicate with serial port connected to your machine , a machine on the same network or even a remote machine!
• list connected serial ports
• visualize live data using zoomable charts and soon more to come!
• simulate live data
• through the Terminal block
  • change serial port settings [baudrate, data bits, stop bits, parity, etc]
  • toggle timestamp
  • simulate live data
  • toggle autoscroll
  • clear terminal output
• easy to work with prebuilt blocks (currently 5)
• across clients notifications
• light/dark theme
• idle indicator

Pending Features

• upload code
• customizable layout
• More advanced blocks

Getting Started

(Back to top)

Serialblocks is using Multi-Repo structure where the frontend is in serialblocks-app while backend is in serialblocks-local
First, in order to use serialblocks you will need to be running Serialblocks-local on your machine.

Installation

Pre-requisites

To be able to start using Serialblocks , make sure that you have the following prerequisites installed:

• Node.js
• NPM
• Git

Running Serialblocks-local

serialblocks-local is a nodejs server that will run on your machine that will interact with the connected serialports
using Node SerialPort package.

1. Clone the repository and install dependencies:

git clone https://github.com/Serialblocks/Serialblocks-local && cd Serialblocks-local && npm install

2. Run the server script which will use port 3003 by default
   could be changed by changing "config": {"port": "3003"} in package.json
   this will run both _server script and _expose script concurrently
   _server will run the Nodejs server
   while _expose will expose your localhost for easy sharing using localtunnel.

npm run server

Note: you can use Vs Code local port forwarding which offers reduced latency when compared to localtunnel

you can then use the hosted solution and use the localtunnel link as the remote url or run Serialblocks-app locally on your machine and enjoy a latency-free experience.

Running Serialblocks-app locally

1. Clone the repository and install dependencies:

git clone https://github.com/Serialblocks/Serialblocks-app && cd Serialblocks-app && npm install

2. Option 1: Running for production

# Build the app
npm run build

# Run the app in production mode
npm run client:prod

2. Option 2: Running for development

# Run the app in development mode
npm run client:dev

Usage

(Back to top)

After you click the get started button and add the remote url provided by localtunnel or Vs Code local port forwarding
you get to communicate with the server through socket connection made easy by Socket.IO
you then get to list and connect to the connected ports on that machine running the Nodejs server.

Note: You will need to have a microcontroller connected for example an Arduino UNO or if you don’t have access to that you could use a Virtual Serial Port.

based on what you send you can programmatically control the connected microcontrollers

for example, once the microcontroller receives LED_TOGGLE on the serial port you can trigger a function that toggles a specific LED
while sending RGB_255_0_255 commands the RGB LED to emit violet light by maximizing its red and blue components

and based on what data you receive you can visualize that data. for example, receiving {LED: 10} from a humidity sensor from a humidity sensor prompts the UI to update the Humidity block
or {processorTemp : { value: 33.38, interval: 1000 }} could be used by the UI to display the processor temperature value in the processor temp block
accompanied by a refresh interval of 1000 milliseconds that the idle indicator could use to indicate if there has been new data sent or not

Note: Data being sent to be visualized needs to be in JSON format

Contributing

(Back to top)

Serialblocks is an open-source project. We are committed to a fully transparent development process and highly appreciate any contributions.
Whether you are helping us fix bugs, proposing new features, improving our documentation.
Please refer to our contribution guidelines.

• Bug Report: If you see an error message or encounter an issue while using Serialblocks, please create a bug report.
• Feature Request: If you have an idea or if there is a capability that is missing and would make development easier and more robust, please submit a feature request.

License

(Back to top)

This project is licensed under the GPL-3.0 license.