@openble/openble-sdk NPM

OpenBLE SDK

Define your GATT services in YAML with the OpenBLE SDK. This SDK can

Accept and validate raw JSON schema
Generate type safe clients and perepherals

Features

Define your GATT services in YAML.
Say goodbye to searching UUIDs in datasheets. Directly use GATT and Nordic identifiers.
Read and write directly from your browser with Web Bluetooth.
Automatically validate your schema with the connected device.
Generate type safe clients and peripherals using a platform agnostic specification.

Spec summary

openble: 0.1.0

info:
  title: string
  # Description in markdown
  description: string
  version: string

services:
  # Service key can be
  # - 16 bit UUID in capital for GATT services: 181A
  # - Long UUID in capital for GATT or custom services: 0000181A-0000-1000-8000-00805F9B34FB
  # - Long identifier: org.bluetooth.service.environmental_sensing
  # - Short identifier: environmental_sensing
  # Identifiers are read from Nordic's UUID database- https://github.com/NordicSemiconductor/bluetooth-numbers-database/tree/master/v1
  environmental_sensing:
    name: Environmental Sensing Service
    summary: Service to read temperature and humidity
    characteristics:
      # Characteristic key is defined similar to service key
      temperature_celsius:
        name: Temperature
        summary: Read or write temperature in Degree Celsius
        # Currently INT32 is the only supported type. TODO support other types
        dataType: INT32
        # READ, WRITE, NOTIFY, INDICATE
        permissions:
          - READ
          - WRITE
      humidity:
        name: Humidity
        summary: Read humidity in percentage. A value of 50 denotes 50% humidity
        dataType: INT32
        permissions:
          - READ

The spec is defined here.

Motivation

Bluetooth development is frustrating. While building an environment sensor on Arduino, I had to

Look up specifications in PDF sheets
Write services / clients by hand for each platform I wanted to support. Building my climate sensor app involved
1. Writing the arduino perepheral in C++
2. Writing clients and encoders/decoders by hand. Every platform I wished to support had its own language and libraries. Mobile cross platform SDKs in React Native and Flutter do not support desktop, and the desktop implementations don't support mobile. Under the hood every OS (linux, macOS, windows, phones) have their own bluetooth implementation.
Dealing with library sprawl. Android has an official SDK from Google and additionally two more from Nordic. Then the canonical BLE library for NodeJS is abandoned; a community fork is being used.

I scratched my head, realizing that

A Swagger / OpenAPI style specification would make development 10x faster
Web bluetooth supports all platforms except iOS and works out of the box, straight from the browser

The OpenBLE spec benefits from but does not depend on web bluetooth.