Documentation

README.md

@@ -0,0 +1,54 @@
+# BLE
+
+A modern, cross-platform Go library for Bluetooth Low Energy
+
+This package is a working but incomplete interface for access to Bluetooth
+Low Energy. It is intended to support multiple operating systems with a
+uniform API. Currently, MacOS and Android are supported. Android support
+requires the use of [Gio](https://gioui.org).
+
+The API is asyncrhonous and event driven. To access Bluetooth hardware,
+first create a `BLE` variable with `NewBLE()`. On Android, you must also
+call `Enable` with a pointer to your Gio Window.
+
+```go
+import (
+	...
+	"git.wow.st/gmp/ble"
+	"gioui.org/app"
+)
+
+func runloop() {
+	b := ble.NewBle()
+	w := app.NewWindow()
+	b.Enable(w)
+	...
+```
+
+Once enabled, you can call the primary API functions, `Scan`, `StopScan`,
+`Connect`, and `CancelConnection`. You can also query the state of the
+Bluetooth hardware by calling `State`.
+
+Calling `Events` on your `BLE` object returns a channel on which API events 
+are be delivered. These events notify your program when the state of the
+BLE hardware changes (e.g. powered on or off), peripherals are connected,
+services or characteristics are discovered, or values for characteristics
+are updated.
+
+Using Gio, your main event loop will look something like this:
+
+```
+	for {
+		select {
+		case e := <-b.Events():
+			switch e := e.(type) {
+				// Handle BLE Events
+			}
+		}
+		case e := <-w.Events():
+			switch e := e.(type) {
+				// Handle Gio events
+			}
+		}
+	}
+```