Update docs and changelog

CHANGELOG.md

@@ -1,27 +1,51 @@
-# 0.2.0
+# [VERSION]
 
 ## Breaking Changes
 
-- [ManufacturerData] `deserialize/1` returns `{:error, bin}` instead of
-  `{:error, {:unhandled_company_id, bin}}`
-- [Event] `deserialize/1` returns `{:error, bin}` instead of
-  `{:error, {:bad_event_code, bin}}`
-- [Apple] when attempting to deserialize a non-binary term, crash
-- [AdvertisingReport] `deserialize/1` always returns
-  `{status, %AdvertisingReport{}}`
-- [Device]
-  - when attempting to deserialize a non-binary term, crash
-  - faults nested within a device discovered during deserialization will no
-    longer be realized through tuples like `{:early_termination, 0}`, instead
-    the violating binary will be returned as-is
+- `Apple`
+  - `deserialize/1` crashes on non-binary terms
+- `ArrayedData`
+  - `deserialize/1` returns `{:error, bin}` instead of crashing on invalid input
+- `Device`
+  - `deserialize/1`
+    - when attempting to deserialize a non-binary term, crash
+    - faults nested within a device discovered during deserialization will no
+      longer be realized through tuples like `{:early_termination, 0}`, instead
+      the violating binary will be returned as-is
+- `ErrorCode`
+  - `name/1` returns `{:ok, String.t()} | :error` instead of
+    `String.t() | no_return()`
+  - `error_code/1` returns `{:ok, non_neg_integer()} | :error` instead of
+    `non_neg_integer() | no_return()`
+- `Event`
+  - `deserialize/1` returns `{:error, bin}` instead of
+    `{:error, {:bad_event_code, bin}}`
+- `HCI`
+  - `deserialize/1` the binary returned in an error tuple like
+    `{:error, binary()}` is now always the binary given to the function instead
+    of a subbinary
+- `InquiryComplete`
+  - `serialize/1` may now return `{:error, InquiryComplete.t()}` instead of
+    crashing when failing to serialize the event's status
+- `ManufacturerData`
+  - namespace changed from `Harald` to `Harald.DataType`, modules previously
+    namespaced under `Harald.ManufacturerData` are impacted
+  - `deserialize/1` returns `{:error, bin}` instead of
+    `{:error, {:unhandled_company_id, bin}}`
 
-## Enhancements
+## Bugfixes
 
-- [Apple] `deserialize/1` returns `{:error, bin}` instead of crashing on invalid
-  input
-- [ArrayedData] `deserialize/1` returns `{:error, bin}` instead of crashing on
-  invalid input
-- [Transport]
-  - `LE` is always included as a handler WRT `Transport`
+- `Transport`
   - errors during deserialization no longer prevent a Bluetooth event from being
     dispatched to handlers
+
+## Enhancements
+
+- `DataType`
+  - add module
+- `Serializable`
+  - add `assert_symmetry/2`
+- `ServiceData`
+  - add module
+- `Transport`
+  - `LE` is always included as a handler WRT `Transport`

docs/faq.md

@@ -0,0 +1,26 @@
+# Frequently Asked Questions
+
+## Can I do X with Harald
+
+A BLE scan is the only high level function implemented so far. Though sending
+and receiving all Bluetooth Commands and Events is within the scope of Harald,
+the spec is vast and it will take some time to implement. As such, it will be
+common to find oneself in a position where you want to do something that isn't
+implemented yet.
+
+## Harald has not implemented X yet, how do I do X
+
+At the end of the day Bluetooth boils down to sending commands and receiving
+events. Those are defined within the
+[Bluetooth Core Specification](https://www.bluetooth.com/specifications/bluetooth-core-specification).
+Find out what commands and events you require, then leverage the plumbing of
+Harald to send and receive binaries you are responsible for creating and
+parsing. Ideally a PR is then opened!
+
+## What if I get stuck
+
+Create an issue or head over to `#nervesbluetooth` in the Elixir Slack
+workspace. Researching what you are trying to do deeper than "send data" or
+"connect to something", along with putting together a list of required commands
+and events, and then asking for help, will go a long way towards creating a
+situation maintainers can be productive with.

docs/getting_started.md

@@ -14,25 +14,24 @@ Start a transport:
 {Harald.Transport,
  namespace: :bt,
  adapter: {Harald.Transport.UART, device: "/dev/ttyAMA0", uart_opts: [speed: 115_200]}}
- ```
+```
 
 The namespace will be used when issuing commands (like scan):
 
 ```elixir
 Harald.LE.scan(:bt)
 ```
 
-## Board Setup
+## Setup with Nerves
 
-### Rpi3
+### Raspberry Pi 0W, 3B
 
 1. add a custom `fwup.conf` based on the Nerves Rpi3's so you may point to a
    custom `config.txt`
 2. add a custom `config.txt` based on the Nerves Rpi3's so you may comment out
    `dtoverlay=pi3-miniuart-bt`
 
-See: [harald_example_rpi3](https://github.com/verypossible/harald_example_rpi3)
-
-## Core Specifications
+See:
 
-https://www.bluetooth.com/specifications/bluetooth-core-specification
+  - [harald_example_rpi3](https://github.com/verypossible/harald_example_rpi3)
+  - [harald_example_rpi0](https://github.com/verypossible/harald_example_rpi0)

mix.exs

@@ -47,7 +47,7 @@ defmodule Harald.MixProject do
 
   defp description do
     """
-    An Elixir Bluetooth library.
+    An Elixir Bluetooth Host library.
     """
   end
 
@@ -56,6 +56,7 @@ defmodule Harald.MixProject do
       main: "readme",
       extras: [
         "README.md",
+        "docs/faq.md",
         "docs/getting_started.md",
         "docs/testing/testing.md"
       ],