diff --git a/README.md b/README.md
index 20b9b4eb..28e7e08a 100644
--- a/README.md
+++ b/README.md
@@ -280,7 +280,7 @@ You may access the [robeaux](https://github.com/hybridgroup/robeaux) React.js in
 
 Gobot uses the Gort [http://gort.io](http://gort.io) Command Line Interface (CLI) so you can access important features right from the command line. We call it "RobotOps", aka "DevOps For Robotics". You can scan, connect, update device firmware, and more!
 
-Gobot also has its own CLI to generate new platforms, adaptors, and drivers. You can check it out at [https://gobot.io/x/gobot/cli](https://gobot.io/x/gobot/cli).
+Gobot also has its own CLI to generate new platforms, adaptors, and drivers. You can check it out in the `/cli` directory.
 
 ## Documentation
 We're busy adding documentation to our web site at http://gobot.io/ please check there as we continue to work on Gobot
diff --git a/platforms/ble/README.md b/platforms/ble/README.md
index b5567566..e4fe700f 100644
--- a/platforms/ble/README.md
+++ b/platforms/ble/README.md
@@ -1,6 +1,6 @@
 # Bluetooth LE
 
-The gobot-ble adaptor makes it easy to interact with Bluetooth LE using Go.
+The Gobot BLE adaptor makes it easy to interact with Bluetooth LE using Go.
 
 It is written using the [gatt](https://github.com/currantlabs/gatt) package fork by Currant Labs of the package from [Paypal](https://github.com/paypal). Thank you!
 
@@ -11,24 +11,75 @@ Learn more about Bluetooth LE [here](http://en.wikipedia.org/wiki/Bluetooth_low_
 go get gobot.io/x/gobot && go install gobot.io/x/gobot/platforms/ble
 ```
 
-## How To Connect
-
 ### OSX
 
-Info here...
+You need to have XCode installed to be able to compile code that uses the Gobot BLE adaptor on OSX. This is because the `gatt` package uses a CGo based implementation.
 
 ### Ubuntu
 
-Info here...
+Everything should already just compile on most Linux systems.
+
+## How To Connect
+
+When using BLE a "peripheral" aka "server" is something you connect to such a a pulse meter. A "central" aka "client" is what does the connecting, such as your computer or mobile phone.
+
+You need to know the BLE ID of the peripheral you want to connect to. The Gobot BLE client adaptor also lets you connect to a peripheral by friendly name.
+
+### OSX
+
+To run any of the Gobot BLE code you must use the `GODEBUG=cgocheck=0` flag in order to get around some of the issues in the CGo-based implementation.
+
+For example:
+
+    GODEBUG=cgocheck=0 go run examples/minidrone.go 8b2f8032290143e18fc7c426619632e8
+
+OSX uses its own Bluetooth ID system which is different from the IDs used on Linux. The code calls thru the XPC interfaces provided by OSX, so as a result does not need to run under sudo.
+
+### Ubuntu
+
+On Linux the BLE code will need to run as a root user account. The easiest way to accomplish this is probably to use `go build` to build your program, and then to run the requesting executable using `sudo`.
+
+For example:
+
+    go build examples/minidrone.go
+    sudo ./minidrone AA:BB:CC:DD:EE
 
 ### Windows
 
-Info here...
+Hopefully coming soon...
 
 ## How to Use
 
-Example of a simple program...
+Here is an example that uses the BLE "Battery" service to retrieve the current change level of the peripheral device:
 
 ```go
-...
+package main
+
+import (
+	"fmt"
+	"os"
+	"time"
+
+	"gobot.io/x/gobot"
+	"gobot.io/x/gobot/platforms/ble"
+)
+
+func main() {
+	bleAdaptor := ble.NewClientAdaptor(os.Args[1])
+	battery := ble.NewBatteryDriver(bleAdaptor)
+
+	work := func() {
+		gobot.Every(5*time.Second, func() {
+			fmt.Println("Battery level:", battery.GetBatteryLevel())
+		})
+	}
+
+	robot := gobot.NewRobot("bleBot",
+		[]gobot.Connection{bleAdaptor},
+		[]gobot.Device{battery},
+		work,
+	)
+
+	robot.Start()
+}
 ```