ble

Documentation

Overview

Package ble implements a ble protocol to support the Vanadium discovery api. The package exports a discovery.Plugin that can be used to use ble for discovery. The advertising packet of Vanadium device should contain a manufacturer data field with the manufacturer id of 1001. The first 8 bytes of the data is the stamp of the services exported. If the stamp has not changed, then it is expected that the services and the properties they contain has not changed either.

Index

• Constants
• func New(_ *context.T, name string) (idiscovery.Plugin, error)
• type Driver
• type ScanHandler

Constants

const AddressesUuid = "fe3fa941-1eda-5265-806f-d5127794a9a9" // NewAttributeUUID("_addresses")

const AttachmentNamePrefix = "__"

The prefix for encoded attachment names.

const DirAddrsUuid = "7d8b5c56-0d05-5a7a-a21e-6c0c3c31245e" // NewAttributeUUID("_diraddrs")

const EncryptionUuid = "6286d80a-adaa-519a-8a06-281a4645a607" // NewAttributeUUID("_encryption")

const HashUuid = "9c6286f5-aab0-5009-b81b-704d57ed6035" // NewAttributeUUID("_hash")

const IdUuid = "bf0a3657-37cb-5aad-8c13-00c1d69a141c" // NewAttributeUUID("_id")

This uuids are v5 uuid generated out of band. These constants need to be accessible in all the languages that have a ble implementation

const InterfaceNameUuid = "b2cadfd4-d003-576c-acad-58b8e3a9cbc8" // NewAttributeUUID("_interfacename")

const VanadiumUuidBase = "3dd1d5a8-0000-5000-0000-000000000000"

The Vanadium service base uuid and mask.

const VanadiumUuidMask = "ffffffff-0000-f000-0000-000000000000"

const VanadiumUuidPrefix = "3dd1d5a8"

All the Vanadium service start with this prefix.

Functions

func New

func New(_ *context.T, name string) (idiscovery.Plugin, error)

Types

type Driver

type Driver interface {
	// AddService adds a new service to the GATT server with the given service uuid
	// and characteristics and starts advertising the service uuid.
	//
	// The characteristics will not be changed while it is being advertised.
	//
	// There can be multiple services at any given time and it is the driver's
	// responsibility to handle multiple advertisements in a compatible way.
	//
	// Unlike other discovery plugins, the ble plugin does not allow multiple instances
	// of the same service - i.e., the same interface name for now. If we ever need to
	// allow it, we also have to pass the instance id for a driver to handle it.
	AddService(uuid string, characteristics map[string][]byte) error

	// RemoveService removes the service from the GATT server and stops advertising
	// the service uuid.
	RemoveService(uuid string)

	// StartScan starts BLE scanning for the specified uuids and the scan results will be
	// delivered through the scan handler.
	//
	// An empty uuids means all Vanadium services. The driver may use baseUuid and maskUuid
	// to filter Vanadium services.
	//
	// It is guarantted that there is at most one active scan at any given time. That is,
	// StopScan() will be called before starting a new scan.
	StartScan(uuids []string, baseUuid, maskUUid string, handler ScanHandler) error

	// StopScan stops BLE scanning.
	StopScan()
}

Driver provides an abstraction for an underlying mechanism to discover near-by Vanadium services through Bluetooth Low Energy (BLE).

We publish a Vanadium service as a Gatt service with characteristics that contains the encoded service informations. Each characteristics value is up to 512 bytes as the Bluetooth specification limited. Every service is advertised with 128-bit service uuid that are generated from the interface name and are toggled on every update.

The driver should ignore all operations while BLE is not available, but the operations should be automatically resumed when BLE become available.

type ScanHandler

type ScanHandler interface {
	// OnDiscovered is called when a target Vanadium service has been discovered.
	//
	// Optionally the received signal strength in dBm can be passed to rssi.
	// The valid range is [-127, 0).
	OnDiscovered(uuid string, characteristics map[string][]byte, rssi int)
}

A ScanHandler is used to deliver scan results.