readme update

Author: klundberg

README.md

@@ -9,20 +9,60 @@ CombineCoreBluetooth is a library that bridges Apple's `CoreBluetooth` framework
 
 ## Requirements:
 
-* iOS 13, tvOS 13, macOS 10.15, or watchOS 6
-* Xcode 12 or higher
-* Swift 5.3 or higher
+- iOS 13, tvOS 13, macOS 10.15, or watchOS 6
+- Xcode 12 or higher
+- Swift 5.3 or higher
+
+## Installation
+
+### Swift Package Manager
+
+Add this line to your dependencies list in your Package.swift:
+
+```swift
+.package(name: "CombineCoreBluetooth", url: "https://github.com/StarryInternet/CombineCoreBluetooth.git", from: "0.2.0"),
+```
+
+### Cocoapods
+
+Add this line to your Podfile:
+
+```ruby
+pod 'CombineCoreBluetooth'
+```
+
+### Carthage
+
+Add this line to your Cartfile:
+
+```
+github "StarryInternet/CombineCoreBluetooth"
+```
 
 ## Usage
 
-This library is heavily inspired by [pointfree.co's approach](https://www.pointfree.co/collections/dependencies) to designing dependencies, but with some customizations. Many asynchronous operations returns their own `Publisher` or expose their own long-lived publisher you can subscribe to. To do something like fetching a value from a characteristic, for instance, you could call the following methods on the `Peripheral` type and subscribe to the resulting `Publisher`:
+This library is heavily inspired by [pointfree.co's approach](https://www.pointfree.co/collections/dependencies) to designing dependencies, but with some customizations. Many asynchronous operations returns their own `Publisher` or expose their own long-lived publisher you can subscribe to.
+
+This library doesn't maintain any additional state beyond what's needed to enable this library to provide a combine-centric API. This means that you are responsible for maintaining any state necessary, including holding onto any `Peripheral`s returned by discovering and connected to via the `CentralManager` type.
+
+To scan for a peripheral, much like in plain CoreBluetooth, you call the `scanForPeripherals(withServices:options:)` method. However, on this library's `CentralManager` type, this returns a publisher of `PeripheralDiscovery` values. If you want to store a peripheral for later use, you could subscribe to the returned publisher by doing something like this:
 
 ```swift
-// use whatever ids your peripheral advertises here
 let serviceID = CBUUID(string: "0123")
+
+centralManager.scanForPeripherals(withServices: [serviceID])
+  .first()
+  .assign(to: \.peripheralDiscovery, on: self) // property of type PeripheralDiscovery
+  .store(in: &cancellables)
+```
+
+To do something like fetching a value from a characteristic, for instance, you could call the following methods on the `Peripheral` type and subscribe to the resulting `Publisher`:
+
+```swift
+// use whatever ids your peripheral advertises here
 let characteristicID = CBUUID(string: "4567")
 
-peripheral
+peripheralDiscovery.peripheral
   .readValue(forCharacteristic: characteristicID, inService: serviceID)
   .sink(receiveCompletion: { completion in
     // handle any potential errors here
@@ -32,8 +72,10 @@ peripheral
   .store(in: &cancellables)
 ```
 
-The `Peripheral` type (created and given to you by the `CentralManager` type) here will filter the results from the given delegate methods, and only send values that match the service and characteristic IDs down to subscribers or child publishers. 
+The publisher returned in `readValue` will only send values that match the service and characteristic IDs through to any subscribers, so you don't need to worry about any filtering logic yourself. Note that if the `Peripheral` never receives a value from this characteristic over bluetooth, it will never send a value into the publisher, so you may want to add a timeout if your use case requires it.
 
 ## Caveats
 
-All major types from `CoreBluetooth` should be available in this library, wrapped in their own types to provide the `Combine`-centric API. This library has been tested in production for most `CentralManager` related operations. Apps acting as bluetooth peripherals are also supported using the `PeripheralManager` type, but that side hasn't been as rigorously tested.   
+All major types from `CoreBluetooth` should be available in this library, wrapped in their own types to provide the `Combine`-centric API. This library has been tested in production for most `CentralManager` related operations. Apps acting as bluetooth peripherals are also supported using the `PeripheralManager` type, but that side hasn't been as rigorously tested.
+
+As of version 0.2, all write characteristic operations expect a response even if those characteristics are not specified by the peripheral to respond on write completion; this means that the publisher will never complete if you attempt to write to characteristics that don't respond. Until this is changed, you are responsible for managing the lifetime of publishers for writeable characteristics with these properties