Category: BleuIO tutorial

Bluetooth Low Energy (BLE) sensors are excellent at collecting environmental data close to where it matters. Many air-quality devices broadcast their readings using BLE advertisements, which keeps power consumption low and avoids the overhead of maintaining a connection. The challenge appears when you want to access that data remotely, share it with a team, or visualize trends over time.

In this tutorial project, we demonstrate a simple and transparent way to bridge that gap. A BleuIO USB dongle scans BLE advertisements from a HibouAir sensor, a lightweight Python script decodes the values, and the data is sent to Thinger.io for storage and visualization. The goal is not to build a product-specific solution, but to show how easily BLE advertisement data can be integrated into a modern cloud platform using readily available tools.

From local BLE data to remote access

BLE advertisement data is, by design, local: a sensor broadcasts data into the surrounding area, and only nearby devices can receive it. This works perfectly for local dashboards, logging, or automation running on a PC or embedded computer. However, as soon as you want to view data remotely, share readings with others, analyze trends over longer periods, or build dashboards that are accessible from anywhere, a cloud layer becomes necessary. A gateway approach solves this neatly by listening to BLE advertisements, decoding them, and forwarding the results to the cloud without requiring changes to the sensor firmware or the addition of complex SDKs. This keeps the BLE side simple while allowing the cloud to handle storage, visualization, and access control.

About Thinger.io

Thinger.io offers a generous free tier that is well suited for prototyping, demos, and proof-of-concept projects. It allows you to create devices that accept data over HTTP, store incoming measurements in data buckets, and build dashboards with charts and widgets in just a few steps.

For this project, Thinger.io acts as a remote endpoint that receives decoded air-quality data and makes it immediately visible through its web dashboard. This makes it easy to demonstrate end-to-end data flow—from BLE advertisements in the air to charts in a browser—without maintaining your own backend.

Project requirements

Hardware

• HibouAir air-quality monitor (broadcasting data via BLE advertisements)
• BleuIO Bluetooth Low Energy USB dongle

Software

• Python 3.9 or later
• pyserial Python library
• requests Python library
• Thinger.io account (free tier)

No embedded firmware development and no BLE SDKs are required.

How the project works

The HibouAir device periodically broadcasts its sensor readings inside BLE advertisement packets. BleuIO, connected to computer via USB, continuously scans for nearby BLE advertisements and filters packets that match the HibouAir identifier.

A Python gateway script reads the scan output from BleuIO, extracts the raw advertisement payload, and decodes the air-quality values such as CO2, temperature, and humidity. These decoded values are then packaged into a simple JSON object and sent to Thinger.io using an authenticated HTTP request.

Thinger.io receives the data, stores it in a bucket, and makes it available for visualization on dashboards. This entire process runs continuously, creating a real-time BLE-to-cloud data pipeline without establishing a persistent BLE connection to the sensor.

Source code

The complete source code for this project is available on GitHub. It includes the Python gateway script, configuration examples, and setup notes.

https://github.com/smart-sensor-devices-ab/bleuio_thinger_cloud/

Setting up the Thinger.io dashboard

On the Thinger.io side, the setup is straightforward. You create an HTTP device that acts as the data entry point, generate an access token for authentication, and configure a data bucket to store incoming measurements. Once the bucket is in place, dashboards can be built by adding widgets such as numeric values, gauges, or time-series charts.

Step 1: Create an HTTP Device

Go to Dashboard → Devices and create a new device.

1. Click Add Device / New Device
2. Choose HTTP Device
3. Set a clear Device ID (example: hibouair_bleuio_gateway)
4. Save

Step 2: Get the Callback URL (endpoint)

Open the device you just created and locate the callback endpoint that will receive your JSON payload.

1. Click your device (example: hibouair_bleuio_gateway)
2. Go to Callback
3. Copy the Callback URL / Endpoint URL

This is the URL your Python gateway will send data to using an HTTP POST.

Step 3: Create a Data Bucket (storage)

Buckets store your incoming time-series data and make charts/dashboard widgets easy.

1. Go to Data Buckets
2. Click Create Bucket
3. Name it something like: hibouair_air_quality
4. Save

Step 4: Link the Device Callback to the Bucket

Now tell Thinger.io to store incoming device payloads into your bucket.

1. Go back to your device: Devices → hibouair_ble_gateway
2. Open Callback settings
3. Enable storing/forwarding incoming data to a bucket
4. Select bucket: hibouair_air_quality
5. Save

Step 5: Create a Dashboard

This is where the live visualization happens.

1. Go to Dashboards
2. Click New Dashboard
3. Name it: HibouAir Live (BleuIO)
4. Save

Step 6: Add widgets to visualize your data

Use the bucket as the data source for widgets.

Suggested widgets (example mapping):

• Numeric / Value widget → co2_ppm
• Gauge widget → temperature_c
• Time-series chart → humidity_rh (and optionally CO2 too)

Steps:

1. Click Add Widget
2. Choose widget type (Value, Gauge, Chart)
3. Select bucket: hibouair_air_quality
4. Choose the field (co2_ppm / temperature_c / humidity_rh)
5. Save widget
6. Arrange widgets on the dashboard

Running the gateway

After configuring the Thinger.io credentials and ensuring BleuIO is connected to the correct serial port, the project is started with a single command:

python3 gateway_thinger.py

Once running, the script scans for BLE advertisements, decodes the sensor data, and pushes updates to Thinger.io at regular intervals. Terminal output confirms successful scans and uploads, while the dashboard updates in near real time.

This project is meant to showcase an integration pattern, not to define a fixed solution. By combining BLE advertisement scanning with a simple Python gateway and a cloud platform like Thinger.io, it becomes clear how flexible this approach can be. Engineers can take this example, replace the sensor, adjust the decoder, or switch the cloud endpoint to suit their own needs.

In this tutorial, we build a simple but practical web application that demonstrates how BleuIO can be integrated with a modern web framework to interact with Bluetooth Low Energy (BLE) devices in real time. The goal of this project is not to create a full-featured product, but to provide a clear example that developers can learn from and extend for their own use cases.

The application connects to a BleuIO USB dongle via a serial port, enables verbose mode, performs a BLE scan, and detects whether a specific nearby BLE device is present. If the target device is found, the application displays its MAC address. This approach is particularly useful for scenarios such as proximity detection, presence monitoring, or gateway-style BLE integrations.

The complete source code for this project is provided separately so developers can easily clone, modify, and build upon it.

Why Phoenix Framework?

Phoenix is a web framework written in Elixir and built on top of the Erlang/OTP ecosystem. It is designed for applications that require high concurrency, real-time updates, and long-running background processes. These characteristics make Phoenix particularly suitable for hardware-integrated applications where continuous communication with external devices is required.

In this project, Phoenix allows the BleuIO serial connection to remain open while BLE scan results are streamed to the web interface. The framework handles process supervision, message passing, and real-time UI updates in a clean and reliable way, without the need for complex front-end JavaScript logic.

How This Differs from a JavaScript-Based Web App

This project does not use the Web Serial API. Web Serial allows browser-based JavaScript applications to access serial devices, but it is primarily intended for interactive, user-driven scenarios. It requires explicit user permission, depends on browser support, and is not suitable for unattended or always-on systems.

By contrast, this Phoenix-based approach keeps all BLE logic on the backend. The web interface simply reflects the current state of the system and allows the user to trigger actions such as connecting or rescanning. This separation makes the application easier to extend, easier to deploy, and more suitable for real-world integrations where reliability and continuous operation are important.

Requirements

To follow this tutorial, you will need:

• A computer
• A BleuIO USB dongle
• A Close beacon
• Elixir and Phoenix installed on your system

How the Application Works

The application follows a straightforward process. The user enters the serial port name where the BleuIO dongle is connected and initiates the connection from the web interface. Once connected, the application sends an AT command to enable verbose mode, making the responses easier to read and parse.

After verbose mode is enabled, the application starts a timed BLE scan. As scan results arrive from BleuIO, they are analyzed in real time. If a BLE device advertising the configured target name is detected, the application extracts its MAC address and updates the interface accordingly. The user can repeat the scan at any time using the rescan option.

All serial communication and BLE processing run in the background, while the web interface updates automatically based on events generated by the backend.

Running the Application

Installing Phoenix

Phoenix can be installed on macOS using standard tooling for Elixir. Once Elixir is installed, Phoenix can be added using the official project generator. Detailed installation steps are included in the project documentation.

Running the App

Download the source code from https://github.com/smart-sensor-devices-ab/bleuio-phoenix-erlang

After downloading the source code:

1. Install dependencies
2. Start the Phoenix server
3. Open the application in a browser
4. Enter the BleuIO serial port
5. Click Connect
6. View scan results and detected devices

Follow README.md for more details

The application runs locally and does not require any cloud services.

Configuring the Serial Port and Target Device

Two key parameters are intentionally easy to modify:

Serial Port

The serial port used by BleuIO can be updated either through the web interface or in the configuration file (config>runtime.exs). This allows the project to run on different machines without code changes.

The serial port name depends on the operating system being used. On macOS, BleuIO typically appears as a device starting with /dev/cu.usbmodem. On Linux systems, the dongle is commonly available as /dev/ttyUSB0 or /dev/ttyACM0, depending on the system configuration. On Windows, BleuIO appears as a COM port, such as COM3 or COM5.

Target BLE Device

The application looks for a specific BLE device name during scanning. This name is defined as a constant in the backend code on lib>bleuio_phx>bleuio_worker.ex and is matched case-insensitively.

Proximity Detection and CloseBeacon Use Case

In the example implementation, the application detects a device advertising the name closebeacon.com. This makes the project suitable for proximity detection use cases, such as presence awareness, zone monitoring, or asset tracking.

BLE beacons like CloseBeacon are commonly used in proximity-based systems, and this project demonstrates how BleuIO can serve as a reliable BLE scanning interface for such applications. More information about CloseBeacon can be found at https://www.closebeacon.com/.

How This Project Helps Developers

This tutorial is intended as an example project rather than a finished solution. It shows how BleuIO can be integrated with a backend web framework to handle BLE scanning in a clean and scalable way. Developers can use this project as a reference to understand the overall architecture and then build their own custom logic on top of it.

The complete source code is provided so that anyone interested can explore the implementation details, experiment with different configurations, and adapt the project for their own BLE-enabled applications.

By combining BleuIO with Phoenix, developers can build BLE-enabled web applications that are not limited by browser APIs or client-side constraints. This example demonstrates a backend-first approach to BLE scanning that is well suited for gateways, monitoring tools, and proximity detection systems.

Bluetooth Low Energy (BLE) devices are widely used for environmental monitoring, but getting their data into the cloud often requires complex SDKs, gateways, or proprietary platforms. In this tutorial, we demonstrate a simple and flexible alternative: sending BLE advertisement data directly to Arduino Cloud using BleuIO as a USB BLE gateway.

In this project, we build a lightweight data pipeline where a HibouAir air quality sensor broadcasts environmental data over BLE advertisements, BleuIO scans and captures that data, a Python script decodes the values, and the results are sent straight to Arduino Cloud for storage and visualization — all using free tools.

This project is designed as a showcase example to illustrate how BLE development and cloud integration can be done quickly and transparently, without BLE SDKs or embedded firmware development.

Why Arduino Cloud?

Arduino Cloud offers a convenient and reliable platform for storing and visualizing IoT data without the need to build and maintain a custom backend. Although it is often associated with Arduino hardware, the platform supports Manual Devices, which makes it suitable for gateway-based solutions where data originates from external devices such as BLE sensors. In this project, Arduino Cloud serves as a secure endpoint where decoded air quality data can be published using standard MQTT communication. Its integrated dashboards allow developers to quickly visualize sensor data, making it especially useful for prototyping, demonstrations, and proof-of-concept projects that require minimal setup.

Hardware and Software Requirements

Hardware

• HibouAir CO2 air quality monitor
• BleuIO Bluetooth Low Energy USB dongle

Software

• Python 3.9 or later
• pyserial Python library
• arduino-iot-cloud Python library
• Arduino Cloud

No embedded programming or BLE SDKs are required.

How the System Works

The HibouAir device periodically broadcasts air quality data within its BLE advertisement payload. BleuIO continuously scans for nearby BLE advertisements and filters packets that match a specific device identifier. When a matching advertisement is detected, the Python gateway script extracts the raw data and applies decoding logic to convert the hexadecimal values into human-readable measurements. These decoded values are then published to Arduino Cloud using authenticated MQTT communication. The entire process runs continuously, enabling real-time data updates without establishing a persistent BLE connection to the sensor.

Arduino Cloud Setup (Step by Step)

Step 1: Create or Log In to Arduino Cloud

Go to:
https://app.arduino.cc/dashboards

Create a free account or log in to your existing one. After login Arduino Cloud will generate

• Device ID
• Secret Key

Save these securely — they will be used in the Python script.

Step 2: Create a Device

Navigate to:
https://app.arduino.cc/devices

• Click Add Device from left menu
• Choose Manual Device
• Name the device HibouAir

Step 3: Create a Thing

When prompted after creating device, create a new Thing and name it HibouAir Thing.

Step 4: Add Cloud Variables

Add the following variables to the Thing:

Variable Name	Type	Description
co2_ppm	int	CO₂ concentration (ppm)
temperature_c	float	Temperature in °C
humidity_rh	float	Relative humidity (%)

Step 5: Create a Dashboard

Go back to Dashboards and create a new dashboard.

Add widgets such as:

• Value widget for CO2
• Gauge widget for temperature
• Chart widget for humidity over time

Your cloud setup is now complete.

Project Source Code

Clone or download the project from GitHub:

https://github.com/smart-sensor-devices-ab/bleuio-to-arduino-cloud

Configure secrets.py

Update the following values:

DEVICE_ID = "YOUR_DEVICE_ID"
SECRET_KEY = "YOUR_SECRET_KEY"
SERIAL_PORT = "/dev/tty.usbmodemXXXX"

Make sure the serial port matches where BleuIO is connected.

Configure gateway.py

In gateway.py, update the scan command:

SCAN_CMD = "AT+FINDSCANDATA=220069=3"

In this example, 220069 is the HibouAir board ID used in the BLE advertisement.
If your HibouAir device uses a different ID, update this value accordingly.

Running the Project

Once the Arduino Cloud configuration and local script setup are complete, running the project requires only a single command.

python3 gateway.py

When the gateway script is executed, BleuIO is placed into dual-role mode and begins scanning for BLE advertisements that match the specified HibouAir board identifier. As advertisement packets are received, the script decodes the sensor values and immediately publishes them to Arduino Cloud. Within moments, the dashboard begins displaying live air quality data. This continuous loop allows the system to operate as a real-time BLE-to-cloud gateway with minimal overhead.

Customizing the Dashboard

Arduino Cloud dashboards can be customized to present air quality data in a way that best fits the user’s needs. Live values can be displayed using numeric widgets, gauges can be used to visualize ranges such as CO2 concentration or temperature, and chart widgets can be added to show trends over time. By arranging and configuring these widgets, users can create a clear and informative interface for monitoring indoor air quality. This flexibility makes the dashboard suitable not only for development and testing, but also for presentations and live demonstrations.

This project demonstrates how BLE advertisement data can be efficiently captured and delivered to the cloud using a minimal and transparent approach. By combining HibouAir sensors, BleuIO, a simple Python gateway, and Arduino Cloud, it is possible to create a complete end-to-end monitoring solution without relying on complex SDKs or embedded firmware development. While this tutorial focuses on air quality data, the same method can be extended to other BLE-based sensors and cloud platforms. As a showcase example, it highlights the flexibility of BleuIO as a BLE development tool and provides a solid foundation for developers who want to build and expand their own BLE-enabled cloud solutions.

In the earlier parts of this series, we combined the Adafruit Feather RP2040 with the BleuIO USB dongle to build different BLE applications: setting up the RP2040 as a USB host, reading sensor data, advertising measurements and handling secure connections.

In this Part 5, we take the next step and create a simple two-way communication setup. Instead of only broadcasting data, we let a Python script running on your computer talk to the BleuIO dongle connected to the Feather RP2040 and control its LED in real time. At the same time, the Feather responds over the Serial Port Service (SPS), echoing messages back so you can see exactly what was sent on both sides.

This project is a good starting point if you want to remotely control devices, test custom BLE command protocols or build interactive demos using BleuIO and RP2040.

What This Project Does

Arduino project on Adafruit Feather RP2040

On the hardware side, the Adafruit Feather RP2040 is configured as a USB host for the BleuIO dongle, using the same TinyUSB and Pico PIO USB approach as in Part 1 of the series. When the board starts, it initializes the USB host stack, detects the BleuIO dongle and sends a short sequence of AT commands. These commands disable echo, ask the dongle for its own MAC address, set a friendly advertising name (BleuIO Arduino Example) and start BLE advertising. After that, the sketch simply listens for BLE connection events and SPS messages. Depending on what text message it receives over SPS, it either echoes the message back or sends a command to change the LED behaviour on the dongle.

Python script on the computer

On the computer, a Python script acts as the BLE central. It uses the MAC address printed by the Feather’s serial output to connect to the advertising BleuIO dongle. Once connected, it sends text commands over SPS such as ALERT, NORMAL or OFF, and reads back whatever the Feather sends in response. When the Python script sends one of these special words, the Feather generates BLEU AT commands to control the dongle’s LED; for any other text, it just echoes the message. This creates a complete round-trip: you type in Python, the message travels over BLE to the RP2040 and BleuIO, and a response comes back the same way.

Requirements

Hardware

• Adafruit Feather RP2040 board
• BleuIO Pro – Bluetooth Low Energy USB dongle
• USB cable for the Feather
• USB-A port or hub for the BleuIO dongle
• Computer running Windows, macOS or Linux

Software

• Arduino IDE with RP2040 board support installed
• Adafruit TinyUSB Library
• Pico PIO USB Library
• ArduinoJson library
• Python 3.x and the Python project that connects to BleuIO over SPS

If you already followed Part 1, your RP2040 USB host environment and board configuration should be ready to use.

Source Code on GitHub

You can find the complete source code for this project — both the Arduino sketch and the Python script — in our public GitHub repository: bleuio_arduino_message_transfer_example. Visit the repository at:

https://github.com/smart-sensor-devices-ab/bleuio_arduino_message_transfer_example

Feel free to clone or download the repo to get started quickly. All necessary files — including the .ino, helper headers, and the Python script — are included, so you can replicate the example or adapt it for your own project.

Recap: Preparing the Feather RP2040 as a USB Host

To quickly recap the setup from the earlier article: you install the Raspberry Pi RP2040 board package in the Arduino IDE, select the Feather RP2040 board, and install the Adafruit TinyUSB and Pico PIO USB libraries. You then make sure the CPU speed is set to 120 MHz or 240 MHz, since Pico PIO USB requires a clock that is a multiple of 120 MHz.

Uploading the Arduino Sketch

1. Open the bleuio_arduino_connect_example.ino and usbh_helper.h in the same Arduino sketch folder.
2. Select Adafruit Feather RP2040 (or your RP2040 board) under Tools → Board.

1. Choose the correct COM port for the Feather.
2. Click Upload.

After upload:

1. Open Serial Monitor at 9600 baud.
2. You should see something like:

Connect test v1.0
Core1 setup to run TinyUSB host with pio-usb
SerialHost is connected to a new CDC device. Idx: 0

BleuIO response:
{"own_mac_addr":"xx:xx:xx:xx:xx:xx"}
----

3. Every 10 seconds (based on ALIVE_TIME) you’ll see an update:

H:M:S - 0:0:10
own_mac_addr: xx:xx:xx:xx:xx:xx
Not connected!

Initially it will say Not connected! because no BLE central is connected yet.

The Python Script (BLE Central)

The Python script acts as a BLE central that connects to the advertising BleuIO dongle and uses the Serial Port Service (SPS).

A typical flow in the Python script is:

1. Read the MAC address printed by the Arduino Serial Monitor (own_mac_addr).
2. Use the BleuIO Python library (or BLE stack) to connect to that address.
3. Once connected, send plain text messages over SPS:
   • "ALERT"
   • "NORMAL"
   • "OFF"
   • Or any other text.

On the Python side you’ll see:

• Connection success message.
• Any SPS response sent from the RP2040 (e.g. [RP2040] Alert command Received: [...] or [RP2040] Echo: ...).

On the Arduino Serial Monitor you’ll see:

Connected!
SPS Received!
BleuIO response:
{"type":"SPS","evt":{"len":5,"ascii":"ALERT"}}
----
Sending command: AT+SPSSEND=[RP2040] Alert command Received: [ALERT]

And the LED on the BleuIO dongle will react according to the command:

• ALERT → Blink pattern (AT+LED=T=100=100).
• NORMAL → Toggle LED (AT+LED=T).
• OFF → Turn LED off (AT+LED=0).
• Any other message → Just an echo, no LED change.

Where to Go Next

This example completes the journey from simple advertising to full two-way communication between a computer application and a BleuIO dongle hosted by an Adafruit Feather RP2040. With this pattern in place, you can replace the LED commands with your own device protocol, combine it with the sensor examples from Part 2 and Part 4, or feed the exchanged messages into larger systems for logging, dashboards or control logic. Because the communication relies on the standard Serial Port Service and BleuIO AT commands, the same structure can be reused for many other projects where a PC, an embedded board and a BLE device need to work together.

Bluetooth Low Energy (BLE) has become a key technology in modern wireless applications—from IoT devices and sensors to wearables, smart tools, and more. While BLE development can traditionally require time, experience, and familiarity with complex protocols, BleuIO dramatically simplifies the process.

BleuIO is a powerful USB BLE dongle designed to help developers of all levels build BLE applications quickly and efficiently. With straightforward AT commands, intuitive documentation, and cross-platform flexibility, it allows users to prototype and develop BLE solutions without the usual learning curve.

But now, with the rapid growth of AI tools such as ChatGPT and Gemini, the development workflow becomes even smoother. AI can help generate ready-to-run scripts, automate coding tasks, and speed up BLE experiments—making the combination of BleuIO + AI incredibly valuable for developers.

Common Challenges in BLE Development

Developing Bluetooth Low Energy applications often requires a solid understanding of BLE protocols and command structures, which can be intimidating for beginners. Developers must also write code that interfaces correctly with hardware such as dongles or embedded devices, and this process can involve repetitive boilerplate code—especially when handling tasks like scanning, connecting, and transferring data. Another common challenge is ensuring that code works consistently across different languages and platforms. These factors can slow down development and create barriers for those who simply want to prototype or test BLE functionality quickly.

How BleuIO and AI Solve These Problems

BleuIO addresses many of these challenges by offering straightforward AT commands that simplify common BLE operations. When paired with modern AI tools, the development process becomes even more efficient. AI systems can read the BleuIO AT Command List and instantly generate complete scripts that integrate these commands correctly, significantly speeding up prototyping. This eliminates the need for manually writing repetitive code, allowing developers to focus on their application rather than the setup. Because BleuIO works seamlessly with Python, JavaScript, C#, Node.js, and many other environments, developers can choose the language they prefer. Even newcomers can get started easily, as AI-generated scripts help bridge any knowledge gaps and provide a smooth entry point into BLE development.

Example: Using ChatGPT and Gemini to Generate a BLE Scan Script

To demonstrate how effectively BleuIO and AI work together, we created a simple test scenario. We began by downloading the BleuIO AT Command List PDF from the Getting Started guide and then asked both ChatGPT and Gemini to generate a Python script that communicates with the BleuIO BLE USB dongle. The script needed to use the correct AT commands, include the appropriate COM port, and perform a scan for nearby BLE devices lasting five seconds. After generating the scripts, we ran them to compare the output produced by the two AI tools.

Video Demonstration

You can watch the full demonstration below, where we walk through the entire process—from downloading the command list to generating and testing the scripts:

This example demonstrates just how powerful the combination of BleuIO and modern AI tools can be. By letting AI generate boilerplate code and BLE scripts, you can focus on building features, testing ideas, or integrating wireless communication into your products.

BleuIO already makes BLE development easy—but with AI, it becomes even more efficient, accessible, and developer-friendly.

Outdoor air quality is a major focus in Europe in 2025, with tighter standards placing greater emphasis on fine particulate matter—especially PM2.5. Elevated PM levels are linked to asthma, reduced cognitive performance, and increased cardiovascular risk, making reliable monitoring essential. This project demonstrates a simple, browser-based way to visualize PM1.0, PM2.5, and PM10 in real time—supporting better ventilation decisions and aligning with evolving EU air-quality expectations.

What you’ll build

A single HTML file styled with Tailwind CSS that:

• Puts BleuIO in a central scanning role
• Periodically runs a targeted scan for your HibouAir Board ID
• Decodes PM1.0 / PM2.5 / PM10 from the manufacturer data inside BLE advertisements
• Maps the values to three horizontal bars (default display windows: PM1.0/PM2.5 → 0–150 µg/m³, PM10 → 0–200 µg/m³)
• Shows a high particulate banner when any value exceeds your thresholds

Source code: https://github.com/smart-sensor-devices-ab/pm-monitor-bleuio
Live demo: https://smart-sensor-devices-ab.github.io/pm-monitor-bleuio/

Hardware & software

• BleuIO USB BLE dongle
• HibouAir air quality monitor with particle sensor

How it works

HibouAir broadcast short advertisement packets that includes real-time air quality data. We can read them without pairing.

Scan cadence. The dongle sends:

• AT+CENTRAL once to enter scanning mode
• AT+FINDSCANDATA=<BOARD_ID>=3 every cycle to run a 3-second targeted scan
• It reads lines until BleuIO prints SCAN COMPLETE, then waits and repeats

Decoding. HibouAir advertises a compact environmental frame beginning with the marker 5B 07 05. PM values are 16-bit little-endian fields. In this build we anchor to the marker and read:

• PM1.0 (raw ÷ 10 → µg/m³)
• PM2.5 (raw ÷ 10 → µg/m³)
• PM10 (raw ÷ 10 → µg/m³)

UI behavior. Each metric drives a bar that fills left-to-right as the value rises within its display window. Thresholds are configurable (defaults: PM1.0 1, PM2.5 2, PM10 5 µg/m³). If any metric is at or above its threshold, the page shows “High particulate levels detected.”

Customize & extend

You can tailor this monitor to your space and workflow in several practical ways. If you anticipate larger spikes, widen the display windows—for example, expand PM2.5 to 0–200 µg/m³—to keep the bar responsive at higher ranges. For lightweight analytics, append readings to a CSV file or store them in IndexedDB to explore trends over hours or days. If you’re tracking multiple HibouAir units, build a wallboard that scans a list of Board IDs and renders compact tiles for each sensor in a single view. To act on thresholds, add automation hooks that trigger a webhook or drive a fan/relay from a companion script when levels rise. Finally, pair this particulate display with your existing CO₂ or Noise monitors to create a more complete picture of indoor conditions and ventilation effectiveness.

Output

In the video , the session starts at 0.0 µg/m³ across PM1.0/PM2.5/PM10. To demonstrate responsiveness, we briefly spray aerosol near the HibouAir device. Within seconds, the bars respond and the page displays “High particulate levels detected.” After stopping the aerosol and allowing air to clear, values decay back down, the bars recede, and the banner disappears. This sequence illustrates typical behavior you’ll see during quick particulate events (e.g., cleaning sprays, dust disturbances, smoke from cooking) and their recovery.

This project turns HibouAir’s BLE adverts into a clear view of PM1.0, PM2.5, and PM10 using a BleuIO dongle. In minutes, you get live bars, thresholds, and a simple alert that makes particulate spikes obvious. It’s easy to tune—adjust display windows, tweak thresholds, and adapt the layout for different rooms. As EU air-quality expectations tighten, this lightweight monitor helps you spot issues and validate ventilation quickly. From here, you can add data export, multi-device dashboards, or pair it with your CO2 monitor for a fuller picture.

Have you ever wanted to stream real-time air quality data from a Bluetooth sensor straight into the cloud — without any expensive gateway or IoT server?
In this tutorial, we’ll show you how to use the BleuIO USB dongle and a HibouAir sensor to capture CO2, temperature, and humidity readings over Bluetooth Low Energy (BLE), then automatically log them into Google Sheets for easy tracking and visualization.

By the end, you’ll have a live data logger that updates your Google Sheet every few seconds with real environmental readings — and you’ll even learn how to create charts directly inside Google Sheets.

What is Google Sheets?

Google Sheets is a free, cloud-based spreadsheet application that lets you create, edit, and share data online in real time. It’s part of Google’s Workspace tools and is accessible from any device with an internet connection. Because it stores data in the cloud, it’s ideal for data logging, quick testing, and lightweight analysis — especially for IoT projects. You can capture sensor readings, visualize trends with charts, and even connect Sheets to other platforms like Google Looker Studio or BigQuery for deeper analytics. For developers and makers, Google Sheets serves as an excellent starting point for collecting and analyzing data without needing a dedicated server or database.

What You’ll Need

• A BleuIO USB dongle
• A HibouAir CO2 sensor
• A Google account (for Sheets and Apps Script)

You’ll also need a few Python libraries, which we’ll install below.

Step 1 — Set Up Your Google Sheet

We’ll use Google Sheets as our cloud storage for the data.

1. Go to Google Sheets and create a new spreadsheet.
2. Name it something like BleuIO_HibouAir_Data.
3. Rename the first tab to data.
4. In the first row, add the following headers: timestamp, CO2, temperature, humidity

Step 2 — Create a Google Apps Script Webhook

Next, we’ll build a small Google Apps Script that accepts POST requests and appends data to your sheet.

1. Open https://script.google.com/home and click New Project.
2. Paste this code into the editor:

// ===== CONFIG =====
const SPREADSHEET_ID = 'YOUR_SHEET_ID_HERE'; // from your sheet URL
const SHEET_NAME = 'data'; // tab name
// ==================

function doPost(e) {
  const sheet = SpreadsheetApp.openById(SPREADSHEET_ID).getSheetByName(SHEET_NAME);
  if (!e || !e.postData || !e.postData.contents) {
    return ContentService.createTextOutput('NO_BODY');
  }
  let payload = JSON.parse(e.postData.contents);
  const rows = Array.isArray(payload) ? payload : [payload];
  const toRow = o => [
    o.timestamp || new Date().toISOString(),
    Number(o.CO2),
    Number(o.temperature),
    Number(o.humidity)
  ];
  const values = rows.map(toRow);
  sheet.getRange(sheet.getLastRow() + 1, 1, values.length, values[0].length).setValues(values);
  return ContentService.createTextOutput('OK');
}

3. Replace YOUR_SHEET_ID_HERE with your sheet’s ID — it’s the long string between /d/ and /edit in your Sheet URL.
4. Click Deploy → New Deployment → choose Web app.
5. Under settings:
   • Execute as: Me
   • Who has access: Anyone with the link
6. Click Deploy, then copy the Web app URL.
   This will be your WEBHOOK_URL.

Step 3 — Install Python Libraries

Open your terminal (or PowerShell) and install the required dependencies:

pip install pyserial requests

These will let Python talk to the BleuIO dongle and send HTTPS requests to Google Sheets.

Step 4 — Connect and Configure the BleuIO Dongle

Plug in your BleuIO USB dongle.

• On macOS, it will appear as something like /dev/cu.usbmodemXXXX.
• On Windows, it will show up as COMX.

You can list serial ports to confirm:

ls /dev/cu.usbmodem*    # macOS

or

Get-WMIObject Win32_SerialPort | Select-Object DeviceID,Name  # Windows

Step 5 — Run the Python Script

Now we’ll use a Python script that handles the entire process automatically. The script first connects to the BleuIO dongle and sets it to central mode using the AT+CENTRAL command, which allows it to scan for nearby BLE devices. It then searches for HibouAir BLE advertisements using the AT+FINDSCANDATA=220069=3 command, which filters packets matching the HibouAir sensor’s unique identifier. Once it receives a valid advertisement, the script decodes the CO2, temperature, and humidity values from the data packet. Finally, it packages these readings along with a timestamp and pushes them to your Google Apps Script webhook, which automatically logs them into your Google Sheet.

📂 GitHub Repository: View Source Code on GitHub

Before running, update:

• SERIAL_PORT → your BleuIO port
• WEBHOOK_URL → your Google Apps Script Web App URL

Step 6 — Watch Your Data Flow!

Open your Google Sheet. You’ll see new rows appear every few seconds:

timestamp	CO2	temperature	humidity
2025-10-10T14:48:07.849Z	514	23.8	46.1

Step 7 — Create Charts in Google Sheets

Once your data is flowing into Google Sheets, you can easily visualize it without using any external tools. Start by highlighting the range of data you want to analyze, then go to Insert → Chart in the menu. Google Sheets will automatically suggest a chart type, but you can switch to a Line Chart or Combo Chart to better visualize trends over time. For a more dashboard-like view, you can also add a Gauge Chart to display real-time values for CO₂ or temperature. Customize the chart’s colors, titles, and formatting to match your preferences, and adjust refresh settings so your visuals update automatically as new data arrives.

And that’s it! You’ve built a real-time BLE air-quality logger with BleuIO and Google Sheets — no servers, no databases, no fuss.
This setup is perfect for classrooms, offices, or research labs that need quick, visual environmental monitoring.

Use Cases

This project demonstrates how you can use BleuIO and Google Sheets to quickly prototype and test IoT ideas. For example, it’s perfect for indoor air-quality monitoring in offices, classrooms, or labs, allowing you to observe changes in CO₂ levels, temperature, and humidity over time. Researchers can use it to log environmental data during experiments or field studies. It’s also useful for IoT developers who want to validate BLE sensors or test new device firmware without setting up a backend system. Teachers can turn this setup into an educational project, helping students understand Bluetooth communication, data logging, and visualization. Overall, pairing BleuIO with Google Sheets offers a fast, free, and flexible way to monitor and analyze real-world sensor data.

Whether you’re analyzing indoor air quality, tracking sensor performance, or just exploring IoT data pipelines, BleuIO makes BLE integration simple and powerful.

In this project, we’ll show how to build a real-time air quality monitoring system using the BleuIO USB dongle and Ubidots. The setup listens for Bluetooth Low Energy (BLE) advertising packets from a HibouAir sensor, decodes the CO2, temperature, and humidity data, and sends them directly to Ubidots, where you can visualize and analyze the readings on a live dashboard.

The result is a seamless pipeline from BLE sensor to Ubidots’ cloud platform. This makes it easy to track air quality in real time and share the results with colleagues, clients, or your own IoT applications.

What is Ubidots?

Ubidots is a powerful industrial IoT platform designed to help developers, researchers, and businesses transform raw sensor readings into meaningful insights. More than just a place to store data, Ubidots provides tools to build custom dashboards, alerts, and reports that can be shared across teams or even embedded into products. It is widely used in industries such as smart cities, agriculture, energy, logistics, and healthcare, where real-time monitoring and automation are critical.

By integrating BleuIO with Ubidots, you gain the ability to collect real-time BLE sensor data without the need for complex gateways. The values captured from your sensors can be pushed directly to Ubidots variables through simple HTTPS POST requests, making the process both fast and reliable. Once the data is in Ubidots, you can take advantage of its powerful dashboard features to create professional visualizations with gauges, charts, and triggers, giving you an intuitive way to monitor and analyze your environment.

In short, BleuIO acts as the BLE gateway, and Ubidots becomes the visualization and analytics layer.

Requirements

To complete this project, you’ll need:

• BleuIO USB Dongle – to capture BLE advertising packets.
• HibouAir Sensor – broadcasts CO2, temperature, and humidity.
• Python libraries: pip install pyserial requests
• Ubidots account (a free version is available).
• Ubidots API Token – used to authenticate when posting data to your account.

The Script and How It Works

We’ve written a Python script that automates the whole process from BLE scan to Ubidots push. You can find the full code on GitHub:
GitHub Link for Script

Here’s how the script works step by step:

1. Connects to the BleuIO dongle over the serial port you specify (e.g., /dev/cu.usbmodemXXXX on macOS or COMX on Windows).
2. Switches the dongle into central mode with the AT+CENTRAL command (done only once).
3. Scans for HibouAir packets using AT+FINDSCANDATA=220069=3, which looks for advertising data that matches HibouAir’s manufacturer ID.
4. Selects the last valid packet that contains the expected pattern (5B070504). This ensures we work with the freshest data.
5. Decodes the advertising data into usable values:
   • CO in parts per million (ppm).
   • Temperature in Celsius (°C).
   • Humidity in relative percent (%RH).
     The script also applies sanity checks to ignore invalid readings.
6. Pushes the values to Ubidots via HTTPS POST requests. The request format looks like this:
   { "co2": { "value": 415 }, "temperature": { "value": 23.4 }, "humidity": { "value": 52.1 } }
   Each key (co2, temperature, humidity) becomes a variable in Ubidots.
7. The script repeats this process every 10 seconds, so your dashboard stays updated in real time.

This approach keeps everything lightweight and avoids any need for complex backend servers or brokers.

Output

Once the script is running, your Ubidots device (e.g., bleuio-hibouair) will automatically appear in the Devices section. It will have variables for CO2, temperature, and humidity.

Use Cases

This project can be applied in many real-world scenarios where air quality and environmental monitoring are essential. For example, it can be used for indoor air quality monitoring in offices, classrooms, or laboratories to ensure a healthy environment for occupants. In smart building management, the integration of CO₂ and temperature readings into HVAC systems can help optimize ventilation and energy use. The approach also fits perfectly into cold chain logistics, where continuous temperature and humidity tracking is critical for maintaining the safety and quality of sensitive shipments. In the field of environmental research, this setup provides a quick and reliable way to capture and visualize field data without the need for heavy infrastructure. Finally, it is also ideal for IoT prototyping, as Ubidots makes it easy to build dashboards and visualize sensor data quickly without writing or maintaining a backend system.

With just a BleuIO dongle, a BLE sensor, and a few lines of Python, you can build a real-time IoT dashboard in Ubidots. This project demonstrates how easy it is to collect, decode, and visualize BLE data without needing extra hardware or complicated setups.

This project shows how to turn a BleuIO USB dongle into a tiny gateway that streams live air-quality data from a HibouAir sensor straight to Adafruit IO. The script listens for Bluetooth Low Energy (BLE) advertising packets, decodes CO2, temperature, and humidity, and posts fresh readings to your Adafruit IO feeds every few seconds. The result is a clean, shareable dashboard that updates in real time—perfect for demos, labs, offices, classrooms, and proofs of concept.

What is Adafruit IO—and why pair it with BleuIO?

Adafruit IO is a cloud platform for makers and developers that lets you collect, visualize, and route device data using a simple REST API or MQTT. You don’t need any Adafruit hardware; if you can make an HTTPS request, you can send data. BleuIO fits in beautifully here: the dongle handles the BLE side—scanning and parsing sensor frames—while a short Python script formats those values and pushes them to Adafruit IO. In practice that means you can take any BLE-advertising sensor, translate its packets into numbers, and land them on an IoT-friendly dashboard without servers or containers.

Requirements

To complete this project, you will need:

• BleuIO BLE USB Dongle – acts as the BLE central device to capture advertising packets.
• HibouAir Air quality monitor – broadcasts environmental data such as CO2, temperature, and humidity.
• Python libraries – install them with: pip install pyserial requests
• Adafruit IO account – free to sign up at io.adafruit.com.
• Adafruit IO Key – available under your account’s “My Key” page for authentication.

How it works

When you start the script, it opens the BleuIO serial port and switches the dongle into central role the very first time the program runs. From then on it repeatedly performs a short BLE scan that filters for HibouAir advertising frames. The scanner always picks the latest matching packet and decodes the fields we care about: CO2 (ppm), temperature (°C), and humidity (%rH). The script then posts each value to its own Adafruit IO feed over HTTPS. Because Adafruit IO is designed for live IoT data, your dashboard widgets update as soon as new points arrive. The loop cadence is configurable (10 seconds by default), which keeps you comfortably under Adafruit IO’s free-tier request limits.

The code (key points)

The script is intentionally small and readable. It opens the serial device (for example /dev/cu.usbmodemXXXX on macOS or COM7 on Windows), sends the BleuIO commands to scan for a few seconds, and parses the returned “Device Data [ADV]” lines.

A compact decoder extracts CO2, temperature, and humidity from the HibouAir manufacturer data, including the byte order and scaling.

To make the setup painless, credentials are read from variables (AIO_USER, AIO_KEY) and feed names default to co2, temperature, and humidity. Each value is sent to the REST endpoint /api/v2/{username}/feeds/{feed_key}/data with a simple JSON body {"value": <number>}.

The script includes gentle sanity checks (for example, temperature range and humidity bounds) to ignore any malformed frames, and it prints a concise log line each time it pushes fresh data.

Here is the GitHub link with the full source so you can clone and run it as-is or adapt it to other sensors.

How to run the code

Before running, set your serial port and Adafruit IO credentials.

On macOS you can list ports with ls /dev/cu.usbmodem*;

on Windows use Device Manager to find the COM number. Update username and AIO key information, then run the script.
The program will put BleuIO into central mode on first launch and, every cycle, will scan, decode, and push CO2, temperature, and humidity to the three feeds.
If you see an HTTP 401 error, double-check the AIO key; a 404 usually means a feed name typo. If the script can’t open the serial port, confirm the path and that no other program is holding it open.

Creating Adafruit IO feeds, key, and dashboard

Log in to Adafruit IO and create three feeds named co2, temperature, and humidity. Your AIO Key is available under your account’s “My Key” page; copy it and keep it private. With feeds in place, open the Dashboards section and create a new dashboard for this project (for example, “HibouAir Live”). Add a few blocks: a gauge or line chart for CO₂ (with a range that makes sense for your space), another gauge or slide for temperature, and a slide or line chart for humidity so you can see the trend over time. Each block points to its corresponding feed. As the script posts to those feeds, the blocks will animate and refresh automatically. You can reorder blocks, tweak colors and ranges, and share a read-only link if you want others to watch along.

Output

Once everything is connected, the dashboard shows a live CO2 number in gauge an line chart, an updating temperature value, and a humidity box that advances with each new reading. The values move in near real time as the script cycles, and any spikes or changes in air quality appear immediately.

Use cases

Real-time air-quality dashboards are useful in far more places than a lab bench. Facility manager can watch CO2 levels across meeting rooms to optimize ventilation; schools and libraries can surface temperature and humidity alongside occupancy schedules; small manufacturers can keep an eye on comfort and safety in production spaces; and hobbyists can monitor their home offices or studios. Because the pipeline is “BLE sensor → BleuIO → HTTPS → Adafruit IO,” you can swap HibouAir for other BLE advertisers and reuse the same approach to visualize anything from soil moisture to ambient light.

This project highlights how quickly you can go from BLE broadcast to live cloud dashboard with BleuIO and Adafruit IO. There’s no server to maintain, no container to deploy—just a tiny USB dongle, an air quality monitoring device like HibouAir, a short Python script, and a few clicks on the Adafruit IO site. The result is a shareable, real-time view of your environment that’s easy to extend, brand, and automate.

In this project, we demonstrate how to stream Bluetooth Low Energy (BLE) sensor data directly into Microsoft Power BI using the BleuIO USB dongle. By combining a HibouAir environmental sensor with BleuIO and a simple Python script, we can capture live readings of CO2, temperature, and humidity and display them in real time on a Power BI dashboard.

The goal of this project is to make BLE data visualization simple and accessible. Instead of dealing with complex server setups or containers, BleuIO provides an easy way to turn raw BLE advertising packets into meaningful insights that anyone can understand at a glance.

Why Power BI?

Microsoft Power BI is a business analytics platform designed to turn raw data into interactive dashboards and reports. One of its most powerful features is the ability to handle real-time streaming datasets, allowing live updates from sensors or IoT devices.

For IoT developers and organizations, this is a game-changer. Imagine watching air quality readings from your office appear in real time, or combining BLE sensor data with other business metrics to get a fuller picture of your environment. By using BleuIO as a BLE-to-cloud bridge, developers can integrate IoT data into Power BI dashboards quickly, without heavy infrastructure.

Requirements

To follow this tutorial, you will need:

• A BleuIO USB dongle.
• A HibouAir air quality monitor (for CO2, temperature, and humidity).
• A free or paid Microsoft Power BI account.
• The Python libraries pyserial and requests, which can be installed with: pip install pyserial requests

Setup: Power BI Streaming Dataset

Before writing any code, we need to set up a streaming dataset in Power BI.

1. Log in to Power BI Service and go to My workspace.
2. Select New → Streaming dataset → API.
3. Define the fields you’ll collect from the sensor:
   • CO2 (Number)
   • temperature (Number)
   • humidity (Number)
   • timestamp (DateTime or Text)
4. Toggle Historic data analysis ON if you want Power BI to store rows for reporting.
5. Save the dataset and copy the Push URL that Power BI generates. This will look something like: https://api.powerbi.com/beta/.../datasets/{id}/rows?key=...

This Push URL is what the Python script will use to send live sensor data to your dashboard.

The Script

We wrote a Python script that takes care of the entire process. Once it starts, the script connects to the BleuIO dongle through the serial port and switches it into central mode (this is done only the first time it runs). From then on, it performs a BLE scan every 10 seconds, specifically looking for HibouAir sensor advertising data. When the sensor is found, the script decodes the broadcast payload into CO2, temperature, and humidity values. These values are then packaged into the required JSON format and pushed directly to Power BI, where they appear instantly on your dashboard.

Before running the script, make sure to update two important details:

• Dongle port location: On macOS it will look like /dev/cu.usbmodemXXXX, while on Windows it will appear as COMX.
• Power BI Push URL: Use the one you generated earlier during the dataset setup.

We’ve published the full script on GitHub here:
GitHub Link for Script

To run it:

python script.py

Setup Dashboard

With the script running and sending live data, the next step is to build your Power BI dashboard.

1. Go to My workspace in Power BI and click New → Dashboard.
2. Give the dashboard a descriptive name, for example HibouAir Live Data.
3. Select + Add a tile → Custom streaming data, then choose the dataset you created earlier.
4. Pick a visualization type that suits your needs:
   • A Card to display the current CO₂ value.
   • A Gauge to track temperature within a target range.
   • A Line chart to watch humidity changes over time.
5. Map the fields (CO2, temperature, humidity, timestamp) to each visual and pin them to your dashboard.

Within seconds of running the script, you’ll see live sensor readings begin to appear in your Power BI dashboard — updating automatically with every scan.

Output

Here’s what the final result looks like when the dashboard starts receiving data from the HibouAir sensor.

Use Cases

This project shows just one way to use BLE and Power BI together, but the possibilities are broad. For example, you could build air quality monitoring dashboards in offices, schools, or factories to help maintain healthier environments. In agriculture, farmers could create smart dashboards that combine soil and environmental sensors to optimize crop conditions. The same method can be applied to cold chain logistics, where monitoring temperature and humidity is essential for transporting food or medicine. Fitness and health enthusiasts could stream real-time data from BLE wearables into personal dashboards, making progress more visible and motivating. And for developers, Power BI is an excellent tool for rapid IoT prototyping, offering instant visualization of new sensor data without building a complex backend system.

With BleuIO and Microsoft Power BI, it’s easy to transform BLE sensor broadcasts into live dashboards. This integration makes it possible to visualize environmental data in real time, share insights instantly, and build prototypes faster than ever before. Whether you’re a developer, researcher, or business professional, combining BLE sensors with Power BI opens the door to smarter, data-driven decisions.