Category: BleuIO

In this tutorial, we will guide you through creating a BLE real-time macOS menu bar application using the BleuIO USB BLE dongle. BleuIO is an incredibly versatile tool that simplifies the development of BLE (Bluetooth Low Energy) applications, making it ideal for developers looking to build innovative projects with ease.

macOS menu bar applications offer a seamless way to monitor and interact with data in real time without requiring a dedicated application window. By leveraging the power of the BleuIO dongle, we can create a menu bar app that provides live updates on environmental metrics like temperature, humidity, and CO2 levels. This project demonstrates how BleuIO can be integrated into real-time applications, showcasing its potential for BLE-based projects.

Why is This Project Useful?

• Real-Time Updates: The app fetches BLE data at regular intervals and updates the macOS menu bar dynamically.
• Ease of Access: The macOS menu bar provides a non-intrusive interface, allowing users to access live data at a glance.
• Extensibility: This tutorial serves as a starting point for developers to explore more advanced BLE applications with BleuIO.

Requirements

To complete this project, you will need:

1. BleuIO USB BLE Dongle: A powerful and easy-to-use BLE dongle for developing BLE applications.
2. HibouAir – Air Quality Monitor: A BLE-enabled air quality monitor that broadcasts real-time environmental data such as temperature,pressure,voc,light, humidity, and CO2 levels.
3. macOS System: A macOS device with Python 3 installed.
4. Python Libraries:
   • rumps: For creating macOS menu bar applications.
   • bleuio: For communicating with the BleuIO dongle.

How Real-Time Updates Are Handled

The app connects to the BleuIO dongle and scans for BLE advertisements air quality data from HibouAir. Using a timer, the app periodically initiates a scan every 2 minutes. The decoded data is then displayed directly in the macOS menu bar, providing real-time updates without user intervention.

Step-by-Step Guide

Step 1: Set Up the Environment

1. Ensure you have a macOS system with Python 3 installed.
2. Install the necessary dependencies using pip:
   pip install rumps bleuio
3. Plug in your BleuIO USB dongle.

Step 2: Project Overview

Our goal is to:

• Connect to the BleuIO dongle.
• Put the dongle in Central Mode to scan for BLE advertisements.
• Scan for real time air quality data from HibouAir
• Decode the advertisement data to extract temperature, humidity, pressure, and CO2 levels.
• Update the macOS menu bar with the decoded data in real time.

Step 3: Writing the Code

Below is the Python script for the macOS menu bar app. This code handles the dongle initialization, data scanning, decoding, and menu updates.

import rumps
import time
import json
from datetime import datetime
from bleuio_lib.bleuio_funcs import BleuIO
boardID="220069"

# Function to decode advertisement data
def adv_data_decode(adv):
    try:
        pos = adv.find("5B0705")
        if pos == -1:
            raise ValueError("Invalid advertisement data: '5B0705' not found.")

        dt = datetime.now()
        current_ts = dt.strftime("%Y/%m/%d %H:%M:%S")

        # Temperature decoding
        temp_hex = int(adv[pos + 22:pos + 26][::-1], 16)  # Reversed bytes
        if temp_hex > 1000:
            temp_hex = (temp_hex - (65535 + 1)) / 10
        else:
            temp_hex = temp_hex / 10

        # Pressure decoding (convert from little-endian)
        pressure_bytes = bytes.fromhex(adv[pos + 18:pos + 22])
        pressure = int.from_bytes(pressure_bytes, byteorder='little') / 10

        # Humidity decoding (convert from little-endian)
        humidity_bytes = bytes.fromhex(adv[pos + 26:pos + 30])
        humidity = int.from_bytes(humidity_bytes, byteorder='little') / 10

        return {
            "boardID": adv[pos + 8:pos + 14],
            "pressure": pressure,
            "temp": temp_hex,
            "hum": humidity,
            "co2": int(adv[pos + 46:pos + 50], 16),
            "ts": current_ts,
        }
    except Exception as e:
        print(f"Error decoding advertisement data: {e}")
        return {}


# Callback function for scan results
def my_scan_callback(scan_input):
    try:
        scan_result = json.loads(scan_input[0])
        data = scan_result.get("data", "")

        decoded_data = adv_data_decode(data)

        # Update menu with decoded data
        app.update_menu(decoded_data)

    except Exception as e:
        print(f"Error parsing scan result: {e}")

# Callback function for events
def my_evt_callback(evt_input):
    cbTime = datetime.now()
    currentTime = cbTime.strftime("%H:%M:%S")
    print(f"\n\n[{currentTime}] Event: {evt_input}")

class AirQualityApp(rumps.App):
    def __init__(self):
        super(AirQualityApp, self).__init__("CO2 : 550")
        self.my_dongle = None  # Placeholder for the dongle object
        self.co2_item = rumps.MenuItem(title="CO2 : 550ppm", callback=lambda _: None)
        self.temp_item = rumps.MenuItem(title="Temperature: 25°C", callback=lambda _: None)
        self.hum_item = rumps.MenuItem(title="Humidity: 65 %rh", callback=lambda _: None)
        self.press_item = rumps.MenuItem(title="Pressure: 1000 mbar", callback=lambda _: None)

        self.menu = [
            self.co2_item,
            self.temp_item,
            self.hum_item,
            self.press_item,
            None  # Separator
        ]

        # Establish connection and start scanning on startup
        self.connect_dongle()
        self.start_periodic_scan()

    def connect_dongle(self):
        try:
            self.my_dongle = BleuIO()  # Initialize the dongle
            self.my_dongle.register_evt_cb(my_evt_callback)  # Register event callback
            self.my_dongle.register_scan_cb(my_scan_callback)  # Register scan callback
            print("Dongle connected successfully.")

            # Set the dongle to central mode
            response = self.my_dongle.at_central()
            print("Dongle is now in central mode.")

        except Exception as e:
            print(f"Error connecting to dongle: {e}")

    def scan(self, _=None):  # Added `_` to accept the timer argument
        try:
            # Start scanning for specific data
            response = self.my_dongle.at_findscandata(boardID, 3)
            print(f"Scan initiated. Response: {response.Rsp}")
        except Exception as e:
            print(f"Error during scan: {e}")

    def start_periodic_scan(self):
        try:
            rumps.timer(120)(self.scan)  # Run the scan method every 30 seconds
        except Exception as e:
            print(f"Error setting up periodic scan: {e}")

    def update_menu(self, decoded_data):
        try:
            self.title = f"CO2 : {decoded_data.get('co2', 'N/A')}ppm"  # Update app title
            self.co2_item.title = f"CO2 : {decoded_data.get('co2', 'N/A')}ppm"
            self.temp_item.title = f"Temperature: {decoded_data.get('temp', 'N/A')}°C"
            self.hum_item.title = f"Humidity: {decoded_data.get('hum', 'N/A')} %rh"
            self.press_item.title = f"Pressure: {decoded_data.get('pressure', 'N/A')} mbar"
        except Exception as e:
            print(f"Error updating menu: {e}")

if __name__ == "__main__":
    app = AirQualityApp()
    app.run()

Note : Make sure to change the BoardID to your HibouAir CO2 device on line 6

Step 4: Run the App

1. Save the script as bleuio.py.
2. Run the script using:
   python bleuio.py
3. The app will appear in the macOS menu bar with latest CO2 value. Click the icon to view the live BLE data updates.

Output

Extending the Project

This project is a foundation for exploring the capabilities of BleuIO. You can extend it to:

• Monitor additional BLE devices.
• Implement alert notifications for specific data thresholds.
• Log the data to a file or send it to a cloud service for further analysis.

This tutorial demonstrates how to create a real-time macOS menu bar application using the BleuIO dongle. By following this guide, you’ll not only learn how to handle BLE data but also understand how to integrate it into user-friendly macOS applications. BleuIO opens up endless possibilities for BLE-based projects, and we’re excited to see what you create next!

BleuIO, a versatile BLE USB dongle, simplifies BLE application development with its powerful AT commands and cross-platform compatibility. This tutorial demonstrates how to use BleuIO with Python to build a real-time BLE proximity-based LED control system.

In this example, we focus on monitoring the RSSI (Received Signal Strength Indicator) of a specific BLE device and controlling the LED blinking rate of BleuIO based on proximity. The closer the device, the faster the blinking rate. The script also ensures clean termination, turning off the LED when the program exits.

This tutorial uses the BleuIO Python library to showcase a practical use case. However, the concepts can be implemented in any programming language.

Devices and Tools Needed

1. BleuIO Pro BLE USB Dongle
2. Python Installed (Python 3.6 or newer recommended)
3. BleuIO Python Library
   Install the library using
   pip install bleuio
   • BleuIO Python Library on PyPI
4. Source Code
   Get the complete source code from GitHub:
   GitHub Repository

Use Case: Real-Time LED Blinking Based on Proximity

Objective:

1. Continuously monitor the RSSI value of a specific BLE device.
2. Adjust the LED blinking rate of the BleuIO dongle based on the device’s proximity.
3. Ensure the LED turns off when the script is terminated.

Workflow:

1. Scan for BLE devices: Identify the target device using its MAC address.
2. Read RSSI values: Fetch real-time signal strength data.
3. Control LED: Adjust the blinking rate based on proximity:
   • Very Close: Fast blinking.
   • Close: Moderate blinking.
   • Far: Slow blinking.
   • Very Far: Very slow blinking.
4. Graceful Exit: Turn off the LED when the script ends.

The Python Script

Below is the complete script for this project:

import time
import json
import atexit
from bleuio_lib.bleuio_funcs import BleuIO

rssi_value = None
dongle = None  

def scan_callback(scan_input):
    global rssi_value  
    try:
        device_data = json.loads(scan_input[0])  
        if device_data.get("addr") == "[1]6B:C0:5C:BD:CF:14":
            rssi_value = device_data["rssi"]  
            print(f"\nDevice Found! Address: {device_data['addr']}, RSSI: {rssi_value}")
    except json.JSONDecodeError as e:
        print(f"Error decoding JSON: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")

def send_led_command(dongle, rssi):
    if rssi is not None:  
        if rssi > -40:
            print(f"RSSI: {rssi} | Sending LED Command: 50/50")
            dongle.at_led(toggle="T", on_period="50", off_period="50")
        elif -60 <= rssi <= -40:
            print(f"RSSI: {rssi} | Sending LED Command: 100/100")
            dongle.at_led(toggle="T", on_period="100", off_period="100")
        elif -90 <= rssi < -60:
            print(f"RSSI: {rssi} | Sending LED Command: 200/200")
            dongle.at_led(toggle="T", on_period="200", off_period="200")
        else:
            print(f"RSSI: {rssi} | Sending LED Command: 300/300")
            dongle.at_led(toggle="T", on_period="300", off_period="300")
    else:
        print("No RSSI value available for LED command.")


def cleanup():
    if dongle:
        print("\n--- Turning off LED and cleaning up ---")
        dongle.at_led(0)

# Main logic
def main():
    global rssi_value, dongle  
    dongle = BleuIO()

    atexit.register(cleanup)

    dongle.register_scan_cb(scan_callback)

    print("\n--- Starting BLE Task ---\n")

    print("Setting device role to Central...")
    central_response = dongle.at_central()

    try:
        while True:
            print("\nStarting scan for 2 seconds...")
            dongle.at_gapscan(2)  
            time.sleep(3)  

            send_led_command(dongle, rssi_value)

            print("\nScan cycle completed. Restarting...\n")
            time.sleep(1)
    except KeyboardInterrupt:
        print("\n--- Script Terminated by User ---")

# Run the main function
if __name__ == "__main__":
    main()

How It Works

1. Initialization: The script initializes the BleuIO dongle and sets it to Central role for scanning.
2. Scan Callback: The scan_callback function extracts the RSSI value of the target device in real-time.
3. LED Control: Based on the RSSI value:
   • RSSI > -40: Fast blinking (50ms on/off).
   • -60 <= RSSI <= -40: Moderate blinking (100ms on/off).
   • -90 <= RSSI < -60: Slow blinking (200ms on/off).
   • RSSI < -90: Very slow blinking (300ms on/off).
4. Graceful Termination: The script turns off the LED when terminated with Ctrl + C.

Output

This example demonstrates how easy it is to use BleuIO for BLE applications. Whether you’re building proximity-based solutions or exploring BLE capabilities, BleuIO’s AT commands and Python library make it simple to get started.

Take this script, adapt it to your needs, and unlock the potential of BLE with BleuIO!

Bluetooth Low Energy (BLE) has become a core technology in the modern world, enabling secure and efficient communication for IoT devices, wearables, healthcare gadgets, and more. One of the fascinating applications of BLE is in creating private communication systems. In this tutorial, we will explore how to create a BLE chat application using the BleuIO USB dongle, a powerful yet simple device for BLE application development.

Why This Project?

With increasing concerns about privacy, BLE chat offers a solution that keeps communication entirely local. Unlike internet-based messaging systems, BLE chat does not rely on servers or cloud storage, ensuring that no data leaves your devices. This project demonstrates a simple prototype of such a BLE-based communication system.

How It Works

The project involves two laptops, each connected to a BleuIO USB dongle. For simplicity, we designate one laptop as User 1 (Central role) and the other as User 2 (Peripheral role). Here’s a high-level breakdown of the workflow:

1. Setup:
   Each laptop runs a script to initialize its BleuIO dongle. User 1 starts in a dual role and acts as the central device. User 2 also sets its dongle in a dual role but begins advertising itself.
2. Connection:
   Once User 2 starts advertising, it displays its MAC address. User 1 uses this MAC address to connect to User 2.
3. Messaging:
   After establishing a connection, the users can send and receive messages in real time. The communication is direct and local, with no reliance on external servers.

---

Setting Up the Project

The source code for this project is available on GitHub: BLE Chat Source Code. You can explore, experiment, and build on it to fit your needs.

Steps to Set Up the Project:

1. Clone the Repository
   Open a terminal on both computers and run
   git clone https://github.com/smart-sensor-devices-ab/ble-chat.git
2. Install Dependencies
   Navigate to the project directory and install the required Node.js dependencies
   cd ble-chat
npm install
3. Run the Server
   Start the server by running
   node server.js
   Ensure the server is running on both computers. The terminal should display messages confirming the dongle is detected.

Running the Scripts

Once the servers are running on both computers, follow these steps to use the BLE chat application:

1. User 1 Setup:
   • Open the browser and navigate to http://localhost:3000.
   • Click “Chat as User 1.” This will initialize the BleuIO dongle in dual role mode.
2. User 2 Setup:
   • On the second computer, open the browser and navigate to http://localhost:3000.
   • Click “Chat as User 2.” This will initialize the BleuIO dongle in dual role mode and start advertising. You’ll also see the MAC address of the dongle displayed on the screen.
3. Connecting the Devices:
   • Copy the MAC address from User 2’s screen and enter it on User 1’s screen in the provided input field.
   • Click “Connect” on User 1. Once the connection is established, you’ll see a confirmation message.
     
4. Start Chatting:
   • Use the chat interface on both devices to send messages back and forth. Messages sent from one device will instantly appear on the other device’s screen.
     

Output

In the video below, we demonstrate how this project works with two BleuIO dongles connected to two different computers. To provide a complete view, we are sharing the screen of the second computer to showcase how the chat functions in real-time.

Use Cases for BLE Chat

The BLE chat prototype we’ve created can inspire real-world applications. Here are some potential use cases:

Secure Local Communication:
BLE chat can be used for private messaging within offices, factories, or homes without the need for internet connectivity.

Education Projects:
BLE chat can be a great project for students learning about BLE technology and its applications.

Why Choose BleuIO for Your BLE Projects?

The BleuIO USB dongle makes BLE application development accessible for everyone, from beginners to advanced developers. Its built-in AT commands allow you to quickly prototype applications without diving into complex BLE stacks or SDKs. Whether you’re working on a small hobby project or an enterprise-level IoT solution, BleuIO provides the tools you need.

Here are some standout features of BleuIO:

• Cross-Platform Compatibility: Works seamlessly on Windows, macOS, and Linux.
• Simple AT Commands: No need for extensive coding; just use the built-in commands to control the dongle.
• Lightweight and Portable: Easy to carry and set up for on-the-go development.

This BLE chat application demonstrates the power and simplicity of BLE communication using the BleuIO USB dongle. While it’s a prototype, it showcases how BLE can enable private, secure, and efficient messaging without relying on external networks.

If you’re interested in exploring this further, the source code for the project is available. You can modify and extend it to fit your specific needs. With BleuIO, the possibilities are endless.

Order Your BleuIO USB Dongle Today!
Ready to create your own BLE applications? Visit BleuIO’s to learn more and order your dongle today.