Add mdbook and calibration instructions

.github/workflows/mdbook.yml

@@ -0,0 +1,37 @@
+name: mdbook
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Build Book
+        run: |
+          cd doc
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v2
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: 'doc/book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

README.md

@@ -5,16 +5,18 @@
 </p>
 
 A Bluetooth-enabled crane scale compatible with the custom [Tindeq Progressor Bluetooth service][API],
-which allows it to be used with compatible tools like the Tindeq mobile app. Crane scales have
-become popular in the climbing community as a means to train and rehab fingers.
+which allows it to be used with compatible tools like the Tindeq mobile app. 
 
-The hardware retrofits a cheap (~$23) crane scale from Amazon with a custom PCB based around a
+The hardware retrofits a cheap (~$23) 150kg crane scale from Amazon with a custom PCB based around a
 Nordic nRF52 microcontroller and a differential ADC. The firmware uses [Embassy][Embassy], an
 embedded async framework written in Rust, as well as Nordic's SoftDevice Bluetooth stack.
 
-This is primarily a fun project to learn and practice various concepts I was unfamiliar or rusty
-with: BLE 101, async Rust on embedded, nRF52 development, SMT soldering and PCB design, etc. Maybe
-it'll even help my fingers get stronger.
+## Why?
+
+Crane scales have become popular in the climbing community as a means to train and rehab fingers.
+This is a fun project to learn and practice various concepts I was unfamiliar or rusty with: BLE
+101, async Rust on embedded, nRF52 development, SMT soldering and PCB design, etc. Maybe it'll even
+help my fingers get stronger.
 
 ## Status
 
@@ -25,6 +27,12 @@ There are still a few more software updates planned. See the Issues section for
 
 ### Hardware revisions
 
+#### P1.0
+
+See title picture. A custom PCB based on a Fanstel BT832 nRF52832-based module and a Texas
+Instruments ADS1230 ADC. Thanks to a better ADC and PCB layout, noise performance should be improved
+over previous revisions and most importantly, it's much prettier.
+
 #### P0.0
 
 A custom PCB based on a nRF52840 USB dongle and an HX711 ADC, the same differential ADC used on the
@@ -34,12 +42,6 @@ Tindeq.
   <img src ="boards/dongle_proto/assembled.jpg" width="300" alt="Assembled prototype P0.0 unit">
 </p>
 
-#### P1.0
-
-A custom PCB based on a Fanstel BT832 nRF52832-based module and a Texas Instruments ADS1230 ADC.
-Thanks to a better ADC and PCB layout, noise performance should be improved over the previous
-revisions and most importantly, it's much prettier. See title picture.
-
 ## Shoutouts
 
 * The [Embassy](https://embassy.dev) project for bringing asynchronous Rust to the embedded world.

doc/.gitignore

@@ -0,0 +1 @@
+book

doc/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Kesavan Yogeswaran"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Hangman"

doc/src/README.md

@@ -0,0 +1,34 @@
+# Hangman
+
+<p align="center">
+  <img src ="../../boards/proto1_0/assembled.jpg" width="600" alt="Assembled prototype P0.0 unit">
+</p>
+
+Hangman is a Bluetooth-enabled crane scale compatible with the custom [Tindeq Progressor Bluetooth service][API],
+which allows it to be used with compatible tools like the Tindeq mobile app.
+
+The hardware retrofits a cheap (~$23) 150kg crane scale from [Amazon][Amazon scale] with a custom
+PCB based around a Nordic nRF52 microcontroller and a differential ADC. The firmware uses [Embassy][Embassy],
+an embedded async framework written in Rust, as well as Nordic's SoftDevice Bluetooth stack.
+
+## Why?
+
+Crane scales have become popular in the climbing community as a means to train and rehab fingers.
+This is a fun project to learn and practice various concepts I was unfamiliar or rusty with: BLE
+101, async Rust on embedded, nRF52 development, SMT soldering and PCB design, etc. Maybe it'll even
+help my fingers get stronger.
+
+## Status
+
+The scale is feature-complete. Weight measurement works great with the Tindeq mobile app. Battery
+life is guesstimated to be in the range of several months to a couple of years depending on usage.
+
+## Disclaimer
+
+This is not an officially supported Google product. Wouldn't that be funny though?
+
+This has no affiliation with Tindeq.
+
+[Amazon scale]: https://www.amazon.com/dp/B07MTFXSJW
+[API]: https://tindeq.com/progressor_api/
+[Embassy]: https://embassy.dev/

doc/src/SUMMARY.md

@@ -0,0 +1,7 @@
+# Summary
+
+[Hangman](./README.md)
+
+- [Development]()
+- [Hardware]()
+- [Calibration](./calibration.md)

doc/src/calibration.md

@@ -0,0 +1,37 @@
+# Calibration
+
+Hangman uses a two-point calibration routine where one of the points is zero. Calibration needs to
+be run once before use. The generated calibration constants are saved across power cycles so there
+shouldn't be a need to be calibrate multiple times, but you can re-calibrate at any time if you feel
+like the scale is inaccurate.
+
+## Instructions
+
+1. Install the nRF Connect app or any similar tool that can be used to connect to BLE devices and
+write data to GATT characteristics.
+1. Wake up Hangman by pressing the power button.
+1. Connect to Hangman using nRF Connect. It'll be named something starting with `Progressor`.
+1. Hang "zero" weight from the scale. It's okay if this isn't actually zero. What's important is
+that you know the difference in weight between this stage and the second calibration point. Any
+deviation from zero at this point will be tared out later.
+1. Write the ByteArray `6900000000` to the `7e4e1703-1ea6-40c9-9dcc-13d34ffead57` GATT
+characteristic. This should be the only writable characteristic. This sends the 0x69
+(`AddCalibrationPoint`) opcode along with 0.0 as a 32-bit float.
+1. Add a known reference weight to the scale, ideally something that's at or more than the expected
+maximum weight but less than 150kg, the maximum capacity of the scale.
+1. Convert the known weight, in kg, to a 32-bit floating point number in little-endian format. Write
+`69 <your hex bytes here>` to the same characteristic as earlier. As an example, if your known
+weight were 100.0 kg, you would send `690000f042`.
+1. If you mess up entering in either meaurement, feel free to resend the corresponding command.
+1. Once you're set, write `0x6A` to the same characteristic to save the calibration.
+1. At this point, disconnect from Hangman and test it out using the Tindeq mobile app or something
+compatible.
+
+## Tips
+
+* If the measurements are wildly off after calibration, try re-calibrating and using a big-endian
+float. Different programs disagree on how these bytes should be entered 🤷
+* The two calibration points can be written in any order. However, it's probably a little better to
+write the zero point first, in case there is some hysteresis.
+* 0x69 is the `AddCalibrationPoint` opcode.
+* 0x6A is the `SaveCalibration` opcode.