Author: BleuIO

Bluetooth Low Energy devices are everywhere, from smart sensors and beacons to IoT devices and proximity-based applications. When working with BLE, developers often need a quick way to scan nearby advertising devices and understand their signal strength.

In this project, we build a simple BLE RSSI Heatmap Visualizer using the BleuIO USB dongle. The application runs directly in the browser and connects to BleuIO through the serial port. It performs a BLE scan, reads nearby advertising devices, extracts their RSSI values, and displays them in a visual heatmap.

This is helpful because raw BLE scan output can be difficult to read, especially when many devices are advertising at the same time. With this visualizer, developers can quickly see which devices have strong, medium, or weak signal strength.

BleuIO makes this project simple because it handles the BLE scanning through easy AT commands. Instead of writing low-level Bluetooth code, we can send commands from JavaScript and focus on building the visualization.

Requirements

To try this project, you need:

• A BleuIO USB dongle
• The project source code from GitHub

How It Works

The application connects to the BleuIO dongle using the browser’s Web Serial API. Once connected, it sends BleuIO AT commands to put the dongle into central scanning mode and start a BLE GAP scan.

The main commands used are:

AT+CENTRAL
AT+SHOWRSSI=1
AT+GAPSCAN=5

AT+CENTRAL prepares BleuIO for scanning. AT+SHOWRSSI=1 enables RSSI values in the scan output. AT+GAPSCAN=5 scans nearby BLE devices for 5 seconds.

The browser app then reads the serial output and looks for device information such as MAC address, RSSI value, and device name if available. Each device is grouped based on RSSI strength.

The signal categories are simple:

Strong signal: RSSI >= -50
Medium signal: RSSI between -51 and -70
Weak signal: RSSI <= -71

The heatmap places BleuIO at the center and displays nearby BLE devices around it. Stronger devices appear closer to the center, while weaker devices appear farther away. The device bubbles are also color-coded, making it easier to understand the BLE environment at a glance.

A table below the heatmap shows the detected devices with MAC address, RSSI, name, signal category, and last seen time.

GitHub Project Code

The full source code is available here:

https://github.com/smart-sensor-devices-ab/ble-rss-heatmap-visualizer

You can download or clone the project and open it in a supported browser.

Live Testing

You can also try the live version here:

https://smart-sensor-devices-ab.github.io/ble-rss-heatmap-visualizer/

To test it:

1. Plug in the BleuIO USB dongle.
2. Open the live page in your browser.
3. Click Connect.
4. Select the BleuIO serial port.
5. Click Scan.
6. View the BLE RSSI heatmap and detected device table.

Output Screenshot

Add output screenshot here.

This is an example project showing how BleuIO can be used with the Web Serial API to build a practical BLE scanning and visualization tool. Developers can use the source code as a starting point and modify it for their own use cases.

For example, the project can be extended to scan for a longer period of time, change the RSSI threshold values, filter specific devices, highlight known BLE sensors, or integrate the scan results into a larger web dashboard.

Because BleuIO works with simple AT commands over serial, it is easy to integrate with different programming languages, platforms, and browser-based tools like this one.

Bluetooth Low Energy development is often associated with languages like C, Python, JavaScript, or mobile frameworks. But with BleuIO, BLE communication becomes accessible from almost any programming language that can work with a serial port. In this tutorial, we will build a simple Fortran terminal application that connects to a BleuIO USB dongle, sends AT commands, scans for nearby HibouAir BLE advertisements, decodes the advertising data, and prints the sensor values directly in the terminal.

This project is intentionally small and beginner-friendly. The goal is not to build a full production BLE application, but to demonstrate how Fortran can communicate with BLE devices through BleuIO using simple serial communication.

Why Fortran for a BLE Example?

Fortran is one of the oldest programming languages still actively used today, especially in scientific computing, engineering, numerical modelling, and high-performance applications. While Fortran is not normally the first language people think of for BLE development, this example shows an interesting advantage of using BleuIO.

What We Are Building

The application does the following:

It connects to a BleuIO USB dongle using serial terminal. Then it configures the serial port and sends BleuIO AT commands. After that, it starts a filtered BLE scan for HibouAir advertisements using the command:

AT+FINDSCANDATA=FF5B07

The program then reads the incoming scan data, extracts the advertising payload, decodes the HibouAir manufacturer data, and prints values such as sensor ID, light or noise, pressure, temperature, humidity, CO2, and particulate matter values where available. The README also notes that the program automatically searches for a BleuIO dongle using VID 0x2dcf and PID 0x6002.

Project Requirements

Before running the project, install the required packages on macOS using Homebrew:

brew install gcc libserialport pkg-config

You will also need the following hardware:

1. BleuIO USB dongle
2. HibouAir CO2 Sensor

Getting the Project

The full source code is available on GitHub:

https://github.com/smart-sensor-devices-ab/bleuio-fortran

Building the Project

Build the project with:

make

This creates the executable:

./bleuio_fortran_scanner

The README confirms that the project is built using make and creates the bleuio_fortran_scanner binary.

Running the Project

Run the scanner from the terminal:

./bleuio_fortran_scanner

Once started, the program searches for the connected BleuIO dongle, opens the serial port, prepares the dongle, and starts scanning for HibouAir BLE advertisements.

You can stop the program at any time using:

Ctrl-C

How It Works

The project is split into small Fortran source files to keep the example easy to understand.

The libserialport_bindings.f90 file contains the small ISO_C_BINDING interface required to call libserialport. The serial_utils.f90 file handles finding, opening, configuring, reading from, writing to, and closing the serial port. The bleuio_commands.f90 file contains helper procedures for sending BleuIO AT commands. The simple_json.f90 file extracts the predictable fields needed from the BleuIO scan response. The hibouair_decoder.f90 file decodes HibouAir manufacturer data and prints the sensor values. Finally, main.f90 contains the main scanner flow.

The main idea is simple. BleuIO receives BLE advertising data and returns it through the serial port. The Fortran application reads each line, checks whether it contains valid scan data, extracts the advertisement payload, and decodes the bytes according to the HibouAir data format.

Because BleuIO handles the BLE communication, the Fortran code does not need to manage Bluetooth scanning directly. It only sends AT commands and reads the response.

Example Output

When a HibouAir CO₂ sensor is found, the terminal output looks like this:

BleuIO Fortran HibouAir Scanner
--------------------------------
Searching for BleuIO dongle...
Connected: /dev/tty.usbmodemXXXX

  Sensor ID: 123ABC
      Light: 52 Lux
   Pressure: 1012.4 hPA
Temperature: 23.6 C
   Humidity: 45.1 %rh
        CO2: 612 ppm

For a PM sensor board, the output includes particulate matter values:

  Sensor ID: 456DEF
      Light: 38 Lux
   Pressure: 1011.8 hPA
Temperature: 22.9 C
   Humidity: 47.2 %rh
     PM 1.0: 2.1 ug/m3
     PM 2.5: 4.8 ug/m3
      PM 10: 7.3 ug/m3
        CO2: 0 ppm

These sample outputs are also included in the project README.

Output Screenshot

Add a screenshot here showing the terminal running the Fortran application and printing decoded HibouAir sensor values.

Further Development

This project is a simple example showing how BleuIO can be used with Fortran when building BLE applications. It demonstrates the basic workflow: connect to BleuIO through a serial port, send AT commands, scan for BLE advertisements, read the response, and decode the data.

Developers can use this example as a starting point and expand it for their own projects. For example, the script could be extended to save sensor readings to a file, export data as CSV, monitor multiple HibouAir devices, trigger alerts when CO₂ or PM values are high, or integrate the data with scientific and engineering workflows where Fortran is already used.

In this tutorial, we will build a lightweight command-line application that interacts with Bluetooth Low Energy (BLE) devices using Zig and a BleuIO USB dongle. The application will scan for nearby BLE advertisements and decode sensor data broadcast by a HibouAir device. While HibouAir is used here as a test case, the main goal is to demonstrate how BleuIO simplifies BLE application development and how Zig can be used to build efficient, low-level tools for working with wireless data. By the end of this guide, you will have a working example of a BLE-powered CLI tool that reads, processes, and displays real-time data directly in your terminal.

About ZipLang (Zig)

Zig is a modern systems programming language designed with a focus on simplicity, performance, and control over hardware resources. It is particularly well-suited for applications that require direct interaction with devices, such as serial communication and embedded systems. In this project, Zig is used to communicate with the BleuIO dongle over a serial interface, process incoming BLE scan data, and decode raw payloads into meaningful values. Its minimal runtime and explicit design make it a strong choice for building reliable BLE tools without unnecessary abstraction.

Project Requirements

Hardware

• A BleuIO USB dongle
• A HibouAir sensor device

Software

• Zig installed
• libserialport
• pkg-config

How It Works

The application uses BleuIO as a bridge between the computer and BLE devices. When the program starts, it automatically detects the connected BleuIO dongle by matching its vendor and product ID, then opens a serial connection configured for communication. Once the connection is established, the program sends AT commands to initialize the dongle and begin scanning for BLE advertisement data that matches a specific identifier used by HibouAir devices.

As BLE data is received, the Zig application continuously reads the serial output, interprets the incoming JSON responses, and extracts the relevant payload. This payload is then decoded into human-readable sensor values such as temperature, humidity, pressure, particulate matter, and CO2 levels. The decoded information is printed directly in the terminal, allowing real-time monitoring without requiring any additional tools or manual decoding steps. When the program is stopped, it gracefully sends commands to halt scanning and reset the dongle before closing the connection.

Source Code

You can find the complete source code for this project on GitHub:

https://github.com/smart-sensor-devices-ab/bleuio-ziglang

Install and Run the Project

Follow the readme file inside the project to install and run. Once dependencies are installed, follow these steps:

Build the project

zig build

Run the application

zig build run

Make sure your BleuIO dongle is connected before running the program.

Example Output

When the application is running, it prints decoded BLE sensor data directly to the terminal. Each detected broadcast from a matching device is processed and displayed in a readable format, making it easy to observe environmental data in real time.

About BleuIO

BleuIO plays a central role in this project by abstracting the complexity of BLE communication. Instead of implementing a full Bluetooth stack within the application, developers can interact with BLE devices using simple AT commands over a serial interface. This approach allows BLE functionality to be integrated into applications written in virtually any programming language and run on any major operating system. By handling scanning, filtering, and communication at the hardware level, BleuIO enables developers to focus on application logic, making BLE development faster and more accessible.

This tutorial demonstrates how Zig and BleuIO can be combined to build a practical BLE application with minimal overhead. While HibouAir is used here as a sample device for testing, the same approach can be applied to a wide range of BLE-enabled sensors and devices. The combination of a lightweight programming language and a simple BLE interface creates a powerful development workflow that is both efficient and easy to extend for real-world use cases.

Working with Bluetooth Low Energy devices often means dealing with multiple layers—hardware, protocols, and data decoding. In this tutorial, we are going to simplify that process by building a small command-line application using Nim and a BleuIO USB Dongle.

The goal is simple: scan nearby BLE devices, detect HibouAir sensors, decode their broadcast data, and display readable environmental values directly in the terminal.

By the end, you will have a working local tool that reads real-time air quality data without needing cloud connectivity.

What We Are Building

In this project, we build a lightweight desktop utility that connects to a BleuIO dongle and continuously scans for BLE advertisement data. When a compatible HibouAir device is detected, the application decodes the raw hex payload and prints meaningful values such as temperature, humidity, pressure, CO2, and particulate matter levels.

This is not a heavy application or a full dashboard. It is intentionally simple. The idea is to give developers a clean starting point to understand how BLE data flows from a device to a readable format.

Why Nim with BleuIO?

Nim is a compiled programming language that feels lightweight but powerful. It combines the simplicity of scripting languages with the performance of C. For developers who want fast execution, low memory usage, and clean syntax, Nim is a very practical choice.

Using Nim with BleuIO makes the development process even smoother. The BleuIO dongle abstracts away complex BLE stack handling and exposes everything through simple AT commands over a serial interface. Instead of dealing with platform-specific BLE APIs, you can send commands and receive structured data in return.

This combination allows you to focus more on logic and less on low-level Bluetooth complexity.

Requirements

Before running the project, make sure you have the following:

• BleuIO USB Dongle
• A nearby HibouAir sensor device
• Nim installed on your system
• Homebrew packages: libserialport and pkg-config
• The project source code

How the Project Works

When the application starts, it first looks for the connected BleuIO dongle by checking the USB device identifiers. Once the dongle is found, the program opens the serial port and prepares the device for communication.

The setup phase uses a short sequence of AT commands:

ATV0
ATE0
ATV1

These commands are used to configure how the dongle responds over serial so that the application can read and process the output more reliably.

After setup, the application starts scanning for BLE advertisement data using this command:

AT+FINDSCANDATA=FF5B07

This tells BleuIO to scan and report advertisement packets that match the data pattern used by HibouAir devices.

As scan results come in, the program reads the serial output line by line. It looks for valid scan data entries and then extracts the raw advertisement payload. Once a matching payload is found, the Nim code decodes the hex data into readable sensor values such as temperature, humidity, pressure, CO2, and particulate matter values depending on the device type.

When you stop the program with Ctrl + C, it also sends a final reset command to close things down cleanly:

ATR

Example Output

Below is an example of how the data appears in the terminal when a device is detected and decoded.

You will see values like temperature, humidity, pressure, and CO2 being printed in real time as the device broadcasts data.

Source Code

You can access the full project source code here:

[GitHub Repository ]

The code is intentionally kept small and readable so it is easy to follow and modify.

Running the Project

Once the project is downloaded and the BleuIO dongle is plugged into your Mac, you can build and run it directly from Terminal.

First, move into the project folder:

cd ~/Downloads/bleuio-nim

If you have not already installed the required tools, install them with Homebrew:

brew install nim libserialport pkg-config

After that, build the project:

nimble build

Once the build is complete, run it with:

nimble run

If everything is set up correctly, the application will detect the connected BleuIO dongle, initialize it, and begin scanning for HibouAir advertisement data. Within a few seconds, you should start seeing decoded sensor readings appear in the terminal.

When you want to stop the scanner, press:

Ctrl + C

The application will then stop scanning, send its cleanup command, and close the serial connection.

This project is best seen as a foundation rather than a finished product. It shows how to connect to a BLE device, scan for advertisement data, and decode it into something useful.
From here, you can take it in many directions. You might want to store the data locally, send it to a cloud service, build a graphical dashboard, or integrate it into a larger system. Since the core BLE communication is already handled through BleuIO, extending the project becomes much easier.

Bluetooth Low Energy (BLE) has become one of the most widely used wireless technologies for IoT devices, sensors, wearables, and industrial monitoring systems. Developers working with embedded systems, automation platforms, and hardware integration often rely on C++ because of its performance, low-level hardware access, and portability.

In this tutorial, we will create a simple command-line BLE scanning application using C++. The program connects to the BleuIO USB dongle through a serial port and sends AT commands to control Bluetooth operations. After starting the program, the user enters the number of seconds to scan, and the application instructs the BleuIO dongle to perform a BLE scan and print the detected devices directly in the terminal. This example demonstrates the basic workflow of communicating with BleuIO from a C++ application.

Why C++ and Boost Are Commonly Used for Bluetooth Development

C++ is widely used in Bluetooth and embedded development because it provides high performance and direct access to hardware interfaces such as serial communication. Many IoT gateways, embedded systems, and industrial applications rely on C++ to interact with sensors and wireless devices. To simplify development, developers often use the Boost libraries, which extend the C++ standard library with reliable cross-platform tools. In this tutorial we use Boost.Asio, which provides a portable and efficient way to handle serial communication and asynchronous input/output across different operating systems.

Requirements

Before starting this project, you should have the following:

• A computer running macOS, Windows, or Linux
• A BleuIO USB dongle
• A C++ compiler
• Boost libraries installed
• Basic knowledge of C++ and terminal commands

Installing the Required Tools

macOS Setup

First install Xcode Command Line Tools, which provide the C++ compiler.

xcode-select --install

Next install Homebrew if it is not already installed.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then install Boost:

brew install boost

You can verify the installation using:

brew --prefix boost

Windows Setup

On Windows you will need:

• Visual Studio or MSVC compiler
• Boost libraries

Steps:

1. Install Visual Studio Community Edition
2. Enable Desktop development with C++
3. Download Boost from https://www.boost.org
4. Extract Boost and configure it for your project.

Alternatively, Boost can be installed using vcpkg.

Have a look into the getting started guide on boost office page

https://www.boost.org/doc/user-guide/getting-started.html

Understanding How the Script Works

The example script uses Boost.Asio serial communication to interact with the BleuIO dongle.

The application works in several stages.

Serial Connection

The program opens a serial port connected to the BleuIO dongle.

serial_.open(port_name);

The serial port parameters are configured to match BleuIO’s default UART settings.

serial_.set_option(serial_port_base::baud_rate(57600));
serial_.set_option(serial_port_base::character_size(8));
serial_.set_option(serial_port_base::parity(serial_port_base::parity::none));
serial_.set_option(serial_port_base::stop_bits(serial_port_base::stop_bits::one));
serial_.set_option(serial_port_base::flow_control(serial_port_base::flow_control::none));

Asynchronous Serial Reader

The script uses an asynchronous reader to continuously listen for responses from the BleuIO dongle.

serial_.async_read_some(...)

Whenever the dongle sends data, the program prints the received information to the terminal.

This allows us to see scan results in real time.

Sending AT Commands

Commands are sent to BleuIO using the sendCommand() function.

bleuio.sendCommand("AT+CENTRAL");

The command is written to the serial port followed by a carriage return and newline.

Setting Central Role

BLE devices can operate in different roles.
Before scanning, the BleuIO dongle must be set to central mode.

bleuio.sendCommand("AT+CENTRAL");

Starting a BLE Scan

The scan command is then issued.

AT+GAPSCAN=<seconds>

For example:

AT+GAPSCAN=5

This instructs the BleuIO dongle to scan for nearby BLE devices for five seconds.

The dongle returns advertising data for detected devices during the scan.

Full Source Code

You can find the full source code on GitHub.

GitHub repository

https://github.com/smart-sensor-devices-ab/bleuio-cpp-boost

The repository contains the complete C++ script used in this tutorial.

How to Run the Script

First compile the program.

clang++ -std=c++17 main.cpp -I$(brew --prefix boost)/include -o bleuio_scan

After compilation, run the program:

./bleuio_scan

The program will ask for the scan duration.

Example:

Enter scan duration in seconds: 5

The script will then:

Connect to the BleuIO serial port,Put the dongle into central mode,Start scanning for BLE devices,Print scan results in the terminal

Example output may look like this:

Locating the BleuIO Serial Port

Before running the program, you need to identify the serial port where the BleuIO dongle is connected.

On macOS, you can list available serial devices using the terminal command:

ls /dev/cu.*

The BleuIO device will typically appear with a name similar to:

/dev/cu.usbmodemXXXXXXXX

This value can then be used in the script as the serial port path.

On Windows, the serial port can be identified through Device Manager. After plugging in the BleuIO dongle, open Device Manager and expand the Ports (COM & LPT) section. The device will appear as a USB serial device with a COM port number, such as COM17.

Expanding This Example

The script in this tutorial is a basic example showing how to communicate with the BleuIO dongle using C++ and Boost.Asio. Although it only performs BLE scanning, the same approach can be used to send any AT command supported by BleuIO. Developers can extend this example to connect to devices, read GATT characteristics, parse advertisement data, or integrate BLE functionality into larger applications such as IoT gateways, monitoring tools, or automation systems.

In the previous project, we focused on getting Teensy 4.1 working as a USB Host for the BleuIO. The goal was simple: remove the PC from the equation and prove that a microcontroller could directly control BleuIO and communicate over BLE using AT commands.

This project builds on that foundation and does something practical with it. Instead of manually sending commands and observing responses, we now create a complete scanner that automatically detects nearby HibouAir sensors, reads their BLE advertisement data, decodes it, and prints meaningful environmental values in real time.

At this point, the system stops being a connectivity demo and becomes an actual application.

Hardware Requirements

• Teensy 4.1
• BleuIO
• HibouAir Air quality monitoring sensor
• USB cable
• USB TYPE A pcb adaptor
• Arduino IDE 2.x
• ArduinoJson library (v7.x or compatible)

Software Requirements

Install ArduinoJson

This project uses ArduinoJson to parse scan results from BleuIO.

In Arduino IDE:

1. Open Library Manager
2. Search for arduinojson
3. Install version 7.x or compatible

ArduinoJson is required to deserialize the JSON scan data received from BleuIO.

How it Works

The architecture remains the same as in Part 1, but now it is used with purpose.

Teensy operates in USB Host mode and communicates directly with BleuIO. BleuIO handles all Bluetooth Low Energy scanning internally and outputs scan results as structured JSON strings over USB serial. Teensy receives those strings, parses the JSON content, extracts the manufacturer-specific payload, and decodes it into usable values.

Conceptually, the flow looks like this:

Teensy 4.1 (USB Host + Application Logic)
        ↓
BleuIO (BLE Scanning Engine)
        ↓
BLE Advertisement Data (JSON)
        ↓
HibouAir Decoder
        ↓
Readable Environmental Measurements

The important thing to notice here is that Teensy never deals with BLE packets directly. There is no radio handling, no GAP or GATT management, and no BLE stack integration. Everything related to Bluetooth stays inside BleuIO. The microcontroller simply receives structured scan results and processes them like any other data stream.

Automatic Startup and Scanning

When the firmware starts, it configures BleuIO automatically. It disables command echo, enables verbose mode, and then sends a filtered scan command:

AT+FINDSCANDATA=FF5B07

This tells BleuIO to report only devices containing the HibouAir manufacturer identifier. From that moment, scan results begin arriving continuously as JSON lines.

Each line contains fields such as the device address and a data field containing the manufacturer payload in hex format. That hex string is where the sensor readings are encoded.

Parsing the JSON Data

Since scan data arrives asynchronously, the project includes a small USB serial line reader. It buffers incoming characters until a newline is detected, ensuring that we always attempt to parse complete JSON messages.

The ArduinoJson library is used to deserialize each line into a JsonDocument. Once deserialized, we check that the expected scan fields are present. If so, we extract the hex-encoded manufacturer payload and pass it to the HibouAir decoder.

At this stage, the data is still raw — just a long hex string representing packed bytes from the BLE advertisement.

Decoding the HibouAir Advertisement Payload

The core of this project is the HibouAir structure. Instead of manually extracting bytes in the main loop, the decoding logic is encapsulated in a dedicated class.

The constructor receives the JSON document, extracts the data field, and interprets the hex string as a packed binary structure. Using offsetof() ensures that the correct byte offsets are used, and helper functions convert the hex pairs into integers. Because the BLE advertisement uses little-endian ordering, some fields require byte swapping before they become meaningful.

Once decoded, the class provides clean accessor functions such as:

• getTemp()
• getHum()
• getBar()
• getCo2()
• getPM2_5()

These functions already return properly scaled values. For example, temperature is divided by 10 to convert from raw integer format to degrees Celsius.

This separation keeps the application logic simple. The main loop only needs to create a HibouAir object and call show_sensor() to print the values.

Example Output

When running the project with a nearby HibouAir sensor, the Serial Monitor shows structured environmental readings like this:

Sensor ID: 22008C
Light: 14 Lux
Pressure: 1007.3 hPA
Temperature: 22.9 C
Humidity: 14.1 %rh
CO2: 508 ppm

For particulate matter devices, additional values appear:

PM 1.0: 0.0 ug/m3
PM 2.5: 1.2 ug/m3
PM 10: 2.5 ug/m3

This output is generated directly from BLE advertisements without establishing a connection to the sensor. The sensors simply broadcast their measurements, and the system passively collects and decodes them.

GitHub Repository

The complete source code for this project is available here:

https://github.com/smart-sensor-devices-ab/bleuio-teensy-hibouair-scanner

You can clone the repository, install the ArduinoJson library through the Arduino IDE Library Manager, upload the sketch to Teensy 4.1, and run it immediately. The code is modular and organized so you can reuse the USB line reader, the HibouAir decoder, or the scanning logic in your own applications.

With this foundation in place, several natural extensions become possible. You could store measurements on an SD card, publish them via MQTT, expose them through a REST interface, or even build a complete air-quality gateway. The BLE side does not need to change.