From 4484d063763c0be23cfe3730e9eb1c5bab70b74e Mon Sep 17 00:00:00 2001 From: Kesavan Yogeswaran Date: Mon, 2 Oct 2023 20:41:49 -0400 Subject: [PATCH] Add mdbook and calibration instructions --- .github/workflows/mdbook.yml | 37 ++++++++++++++++++++++++++++++++++++ README.md | 26 +++++++++++++------------ doc/.gitignore | 1 + doc/book.toml | 6 ++++++ doc/src/README.md | 34 +++++++++++++++++++++++++++++++++ doc/src/SUMMARY.md | 7 +++++++ doc/src/calibration.md | 37 ++++++++++++++++++++++++++++++++++++ 7 files changed, 136 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/mdbook.yml create mode 100644 doc/.gitignore create mode 100644 doc/book.toml create mode 100644 doc/src/README.md create mode 100644 doc/src/SUMMARY.md create mode 100644 doc/src/calibration.md diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml new file mode 100644 index 0000000..3ca9f07 --- /dev/null +++ b/.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: 'book' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/README.md b/README.md index ff7c6e9..e6e2868 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,18 @@

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. Assembled prototype P0.0 unit

-#### 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. diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +book diff --git a/doc/book.toml b/doc/book.toml new file mode 100644 index 0000000..5573d7f --- /dev/null +++ b/doc/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Kesavan Yogeswaran"] +language = "en" +multilingual = false +src = "src" +title = "Hangman" diff --git a/doc/src/README.md b/doc/src/README.md new file mode 100644 index 0000000..4c5eb83 --- /dev/null +++ b/doc/src/README.md @@ -0,0 +1,34 @@ +# Hangman + +

+ Assembled prototype P0.0 unit +

+ +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/ diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md new file mode 100644 index 0000000..01109a1 --- /dev/null +++ b/doc/src/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +[Hangman](./README.md) + +- [Development]() +- [Hardware]() +- [Calibration](./calibration.md) diff --git a/doc/src/calibration.md b/doc/src/calibration.md new file mode 100644 index 0000000..02f4e80 --- /dev/null +++ b/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 ` 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.