README: overhaul for uniformity

- add overview of functionality
- add a supported hardware overview
- move Golioth Features above Local set up
- Separate Stream from State
- Add Stream example JSON
- Add LightDB State Example JSON
- Clarify LightDB State functionality
- update OTA instructions for Packages/Cohorts/Deployments
- Move pipelines higher in the document
- Reverence the pipelines section from the Stream section
- Move hardware variants lower in the document
- Simplify the hardware variants section
- rename opening section
- make all headings after the first subheadings
- fix mention of LightDB Stream
- properly style admonitions for GitHub
- add section for additional sensors/components
- remove hardware variations sections
- add mention of use cases and link to projects site
- add section for asking questions

Signed-off-by: Mike Szczys <[email protected]>

Author: szczys

README.md

@@ -3,107 +3,43 @@
 This repository highlights various aspects of the Golioth platform on
 the Nordic Thingy91 and Thingy91x devices.
 
-This repo is based on the Golioth [Reference Design
-Template](https://github.com/golioth/reference-design-template).
-
-## Local set up
-
-> Do not clone this repo using git. Zephyr's `west` meta tool should be
-> used to set up your local workspace.
-
-### Install the Python virtual environment (recommended)
-
-``` shell
-cd ~
-mkdir thingy91-golioth
-python -m venv thingy91-golioth/.venv
-source thingy91-golioth/.venv/bin/activate
-pip install wheel west ecdsa
-```
-
-### Use `west` to initialize and install
-
-``` shell
-cd ~/thingy91-golioth
-west init -m [email protected]:golioth/thingy91-golioth.git .
-west update
-west zephyr-export
-pip install -r deps/zephyr/scripts/requirements.txt
-```
+Using a pre-compiled binary (or one you build yourself), you can
+provision the device via USB and connect to the Golioth cloud.
+Time-series readings for temperature, pressure, humidity, accelerometer,
+and various other sensors will periodically be sent to the cloud. You
+can manage the device from the Golioth web console, configuring
+settings, running RPCs, viewing logs, and performing Over-the-Air
+firmware update (OTA).
 
-## Building the application
+This repository contains the firmware source code and [pre-built release
+firmware
+images](https://github.com/golioth/thingy91-golioth/releases).
 
-Build Zephyr sample application for the Thingy91 (`thingy91_nrf9160_ns`)
-from the top level of your project. After a successful build you will
-see a new `build` directory. Note that any changes (and git commits) to
-the project itself will be inside the `app` folder. The `build` and
-`deps` directories being one level higher prevents the repo from
-cataloging all of the changes to the dependencies and the build (so no
-`.gitignore` is needed).
+## Supported Hardware
+- Nordic Thingy:91
+- Nordic Thingy:91X
 
-Prior to building, update `VERSION` file to reflect the firmware version
-number you want to assign to this build. Then run the following commands
-to build and program the firmware onto the device.
+### Additional Sensors/Components
 
-> You must perform a pristine build (use `-p` or remove the `build`
-> directory) after changing the firmware version number in the `VERSION`
-> file for the change to take effect.
-
-### Build for Thingy91
-
-``` text
-west build -p -b thingy91/nrf9160/ns --sysbuild app
-west flash
-```
-
-### Build for Thingy91x
-
-``` text
-west build -p -b thingy91x/nrf9151/ns --sysbuild app
-west flash --erase
-```
-
-## Provision the device
-
-Configure PSK-ID and PSK using the device shell based on your Golioth
-credentials and reboot:
-
-``` text
-uart:~$ settings set golioth/psk-id <my-psk-id@my-project>
-uart:~$ settings set golioth/psk <my-psk>
-uart:~$ kernel reboot cold
-```
-
-## Add Pipeline to Golioth
-
-Golioth uses [Pipelines](https://docs.golioth.io/data-routing) to route
-stream data. This gives you flexibility to change your data routing
-without requiring updated device firmware.
-
-Whenever sending stream data, you must enable a pipeline in your Golioth
-project to configure how that data is handled. Add the contents of
-`pipelines/cbor-to-lightdb-with-path.yml` as a new pipeline as follows
-(note that this is the default pipeline for new projects and may already
-be present):
-
-1.  Navigate to your project on the Golioth web console.
-2.  Select `Pipelines` from the left sidebar and click the `Create`
-    button.
-3.  Give your new pipeline a name and paste the pipeline configuration
-    into the editor.
-4.  Click the toggle in the bottom right to enable the pipeline and
-    then click `Create`.
-
-All data streamed to Golioth in CBOR format will now be routed to
-LightDB Stream and may be viewed using the web console. You may change
-this behavior at any time without updating firmware simply by editing
-this pipeline entry.
+The Thingy91 Example Program doesn't require any additional sensors or
+components.
 
 ## Golioth Features
 
-This app currently implements Over-the-Air (OTA) firmware updates,
-Settings Service, Logging, RPC, and both LightDB State and LightDB
-Stream data.
+This app implements:
+
+  - [Device Settings
+    Service](https://docs.golioth.io/firmware/golioth-firmware-sdk/device-settings-service)
+  - [Remote Procedure Call
+    (RPC)](https://docs.golioth.io/firmware/golioth-firmware-sdk/remote-procedure-call)
+  - [Stream
+    Client](https://docs.golioth.io/firmware/golioth-firmware-sdk/stream-client)
+  - [LightDB State
+    Client](https://docs.golioth.io/firmware/golioth-firmware-sdk/light-db-state/)
+  - [Over-the-Air (OTA) Firmware
+    Upgrade](https://docs.golioth.io/firmware/golioth-firmware-sdk/firmware-upgrade/firmware-upgrade)
+  - [Backend
+    Logging](https://docs.golioth.io/device-management/logging/)
 
 ### Settings Service
 
@@ -114,8 +50,6 @@ The following settings should be set in the Device Settings menu of the
     Adjusts the delay between sensor readings. Set to an integer value
     (seconds).
 
-    Default value is `60` seconds.
-
   - `LED_FADE_SPEED_MS`
     Adjusts the total LED fade time from 0.5 to 10 seconds. Set to an
     integer value (milliseconds).
@@ -240,34 +174,50 @@ application.
 
 Up-counting and down-counting timer readings are periodically sent to
 the `actual` path of the LightDB Stream service. The frequency that
-these reading change is based on the `LOOP_DELAY_S` setting.
+these readings change is based on the `LOOP_DELAY_S` setting.
 
   - `desired` values may be changed from the cloud side. The device will
     recognize these, validate them for \[0..9999\] bounding, and then
     reset these endpoints to `-1`. Changes may be made while the device
     is not connected and will persist until the next time a connection
     is established.
   - `actual` values will be updated by the device whenever a valid value
-    is received from the `desired` endpoints. The cloud may read the
+    is received from the `desired` paths. The cloud may read the
     `state` endpoints to determine device status, but only the device
-    should ever write to the `state` endpoints.
+    should ever write to the `state` paths.
+
+``` json
+{
+    "desired": {
+        "counter_down": -1,
+        "counter_up": -1
+    },
+    "state": {
+        "counter_down": 9268,
+        "counter_up": 731
+    }
+}
+```
 
-## OTA Firmware Update
+### OTA Firmware Update
 
 This application includes the ability to perform Over-the-Air (OTA)
-firmware updates:
-
-1.  Update the version number in the
-    <span class="title-ref">VERSION</span> file and perform a pristine
-    (important) build to incorporate the version change.
-2.  Upload the
-    <span class="title-ref">build/app/zephyr/zephyr.signed.bin</span>
-    file as a Package for your Golioth project.
-      - Use either <span class="title-ref">thingy91</span> or
-        <span class="title-ref">thingy91x</span> as the package name,
+firmware updates. To do so, you need a binary compiled with a different
+version number than what is currently running on the device.
+
+> [!NOTE]
+> If a newer release is available than what your device is currently
+> running, you may download the pre-compiled binary that ends in
+> `_update.bin` and use it in step 2 below.
+
+1.  Update the version number in the `VERSION` file and perform a
+    pristine (important) build to incorporate the version change.
+2.  Upload the `build/app/zephyr/zephyr.signed.bin` file as a Package
+    for your Golioth project.
+      - Use either `thingy91` or `thingy91x` as the package name,
         depending on which board the update file was built for. (These
-        package names were configured in this repository's board
-        <span class="title-ref">.conf</span> files.)
+        package names were configured in this repository's board `.conf`
+        files.)
       - Use the same version number from step 1.
 3.  Create a Cohort for your device type (thingy91 or thingy91x)
 4.  Create a Deployment for your Cohort using the package name and
@@ -278,3 +228,117 @@ firmware updates:
 Visit [the Golioth Docs OTA Firmware Upgrade
 page](https://docs.golioth.io/firmware/golioth-firmware-sdk/firmware-upgrade/firmware-upgrade)
 for more info.
+
+This repo is based on the Golioth [Reference Design
+Template](https://github.com/golioth/reference-design-template).
+
+## Add Pipeline to Golioth
+
+Golioth uses [Pipelines](https://docs.golioth.io/data-routing) to route
+stream data. This gives you flexibility to change your data routing
+without requiring updated device firmware.
+
+Whenever sending stream data, you must enable a pipeline in your Golioth
+project to configure how that data is handled. Add the contents of
+`pipelines/cbor-to-lightdb-with-path.yml` as a new pipeline as follows
+(note that this is the default pipeline for new projects and may already
+be present):
+
+1.  Navigate to your project on the Golioth web console.
+2.  Select `Pipelines` from the left sidebar and click the `Create`
+    button.
+3.  Give your new pipeline a name and paste the pipeline configuration
+    into the editor.
+4.  Click the toggle in the bottom right to enable the pipeline and
+    then click `Create`.
+
+All data streamed to Golioth in CBOR format will now be routed to
+LightDB Stream and may be viewed using the web console. You may change
+this behavior at any time without updating firmware simply by editing
+this pipeline entry.
+
+## Local set up
+
+> [!IMPORTANT]
+> Do not clone this repo using git. Zephyr's `west` meta tool should be
+> used to set up your local workspace.
+
+### Install the Python virtual environment (recommended)
+
+``` shell
+cd ~
+mkdir thingy91-golioth
+python -m venv thingy91-golioth/.venv
+source thingy91-golioth/.venv/bin/activate
+pip install wheel west ecdsa
+```
+
+### Use `west` to initialize and install
+
+``` shell
+cd ~/thingy91-golioth
+west init -m [email protected]:golioth/thingy91-golioth.git .
+west update
+west zephyr-export
+pip install -r deps/zephyr/scripts/requirements.txt
+```
+
+## Building the application
+
+Build Zephyr sample application for the Thingy91 (`thingy91_nrf9160_ns`)
+from the top level of your project. After a successful build you will
+see a new `build` directory. Note that any changes (and git commits) to
+the project itself will be inside the `app` folder. The `build` and
+`deps` directories being one level higher prevents the repo from
+cataloging all of the changes to the dependencies and the build (so no
+`.gitignore` is needed).
+
+Prior to building, update `VERSION` file to reflect the firmware version
+number you want to assign to this build. Then run the following commands
+to build and program the firmware onto the device.
+
+> [!WARNING]
+> You must perform a pristine build (use `-p` or remove the `build`
+> directory) after changing the firmware version number in the `VERSION`
+> file for the change to take effect.
+
+### Build for Thingy91
+
+``` text
+west build -p -b thingy91/nrf9160/ns --sysbuild app
+west flash
+```
+
+### Build for Thingy91x
+
+``` text
+west build -p -b thingy91x/nrf9151/ns --sysbuild app
+west flash --erase
+```
+
+## Provision the device
+
+Configure PSK-ID and PSK using the device shell based on your Golioth
+credentials and reboot:
+
+``` text
+uart:~$ settings set golioth/psk-id <my-psk-id@my-project>
+uart:~$ settings set golioth/psk <my-psk>
+uart:~$ kernel reboot cold
+```
+
+## External Libraries
+
+The following code libraries are installed by default. If you are not
+using the custom hardware to which they apply, you can safely remove
+these repositories from `west.yml` and remove the includes/function
+calls from the C code.
+
+  - [zephyr-network-info](https://github.com/golioth/zephyr-network-info)
+    is a helper library for querying, formatting, and returning network
+    connection information via Zephyr log or Golioth RPC
+
+## Have Questions?
+
+Please get in touch with Golioth engineers by starting a new thread on
+the [Golioth Forum](https://forum.golioth.io/).