Adding Stabilizer User Manual

.github/workflows/ci.yml

@@ -83,3 +83,57 @@ jobs:
         with:
           command: bench
           args: --package dsp --target=x86_64-unknown-linux-gnu
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions/setup-ruby@v1
+        with:
+          ruby-version: 2.7.x
+
+      - name: Setup Jekyll
+        working-directory: docs
+        run: |
+          gem update
+          gem update bundler
+          gem install jekyll bundler
+          bundler install
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          target: thumbv7em-none-eabihf
+          override: true
+      - name: Install Deadlinks
+        uses: actions-rs/cargo@v1
+        with:
+          command: install
+          args: cargo-deadlinks
+
+      - name: cargo doc
+        uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --no-deps -p miniconf -p dsp -p ad9959 -p stabilizer
+
+      - name: cargo deadlinks
+        uses: actions-rs/cargo@v1
+        with:
+          command: deadlinks
+          # We intentionally ignore fragments, as RTIC may generate fragments for various
+          # auto-generated code.
+          args: --dir target/thumbv7em-none-eabihf/doc --ignore-fragments
+
+      - name: Move firmware documents
+        run: |
+          mkdir -p docs/_site/stabilizer
+
+      - name: Test User Manual
+        working-directory: docs
+        run: |
+          rake build
+          mv target/thumbv7em-none-eabihf/doc docs/_site/stabilizer/firmware
+          rake test
+

.github/workflows/release-docs.yml

@@ -0,0 +1,36 @@
+name: Release Documentation
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+
+jobs:
+  release-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+            fetch-depth: 0
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          target: thumbv7em-none-eabihf
+          override: true
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --no-deps -p miniconf -p ad9959 -p stabilizer -p dsp
+
+      - run: mv target/thumbv7em-none-eabihf/doc docs/firmware
+
+      - uses: peaceiris/[email protected]
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs
+          enable_jekyll: true
+          publish_branch: pages
+          force_orphan: true

.gitignore

@@ -1 +1,2 @@
 /target
+docs/_site/

Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "stabilizer"
 version = "0.5.0"
+resolver = "2"
 authors = ["Robert Jördens <[email protected]>"]
 description = "Firmware for the Sinara Stabilizer board (stm32h743, eth, poe, 2 adc, 2 dac)"
 categories = ["embedded", "no-std", "hardware-support", "science"]
@@ -70,7 +71,7 @@ rev = "a2e3ad5"
 
 [patch.crates-io.miniconf]
 git = "https://github.com/quartiq/miniconf.git"
-rev = "2750533"
+rev = "9c826f8"
 
 [dependencies.smoltcp-nal]
 git = "https://github.com/quartiq/smoltcp-nal.git"

README.md

@@ -4,88 +4,13 @@
 
 # Stabilizer Firmware
 
-## Hardware
-
-[![Hardware](https://github.com/sinara-hw/Stabilizer/wiki/Stabilizer_v1.0_top_small.jpg)](https://github.com/sinara-hw/Stabilizer)
-
 ## Applications
 
-This firmware offers a library of hardware and software functionality targeting the use of the Stabilizer hardware in various digital signal processing applications commonly occurring in Quantum Technology.
-It provides abstractions over the fast analog inputs and outputs, time stamping, Pounder DDS interfaces and a collection of tailored and optimized digital signal processing algorithms (IIR, FIR, Lockin, PLL, reciprocal PLL, Unwrapper, Lowpass, Cosine-Sine, Atan2).
-An application can compose and configure these hardware and software components to implement different use cases.
-Several applications are provides by default:
-
-### Dual-IIR
-
-![Flow diagram](stabilizer_pid.svg)
-
-* dual channel
-* SPI ADC
-* SPI DAC
-* up to 800 kHz rate, timed sampling
-* down to 2 µs latency
-* f32 IIR math
-* generic biquad (second order) IIR filter
-* anti-windup
-* derivative kick avoidance
-
-### Lockin
-
-* Up to 800 kHz sampling
-* Up to 400 kHz modulation frequency
-* Reciprocal PLL for external reference
-* Internal reference
-* Adjustable PLL and locking time constants
-* Adjustable phase offset and harmonic index
-* Different output modes (in-phase, quadrature, magnitude, log2 power, phase, frequency)
-
-## Minimal bootstrapping documentation
-
-* Clone or download this
-* Get [rustup](https://rustup.rs/)
-* Minimum supported Rust version (MSRV) is 1.52.0
-* Install target support: `rustup target add thumbv7em-none-eabihf`
-* Install `probe-run`: `cargo install probe-run`
-* `cargo run --release --bin dual-iir`
-* When using debug (non `--release`) mode, increase the sample interval significantly.
-  The added error checking code and missing optimizations may lead to the code
-  missing deadlines and panicing.
+Check out the [Documentation](https://quartiq.de/stabilizer) for more information on usage,
+configuration, and development.
 
-## Alternative flashing tools
-
-### Cargo-embed
-
-* Install `cargo-embed`: `cargo install cargo-embed`
-* Program the device: `cargo embed --bin dual-iir --release`
-
-### GDB/OpenOCD
-
-* Get a recent openocd, a JTAG adapter ("st-link" or some clone) and
-  everything connected and permissions setup. Most
-  [Nucleo](https://www.digikey.de/short/p41h4v) boards have a
-  detachable ST-Link v2 and are cheap.[^swd]
-* Get a multiarch `gdb` (or a cross arm gdb and edit `.cargo/config` accordingly)
-* `openocd -f stabilizer.cfg` and leave it running
-* `cargo run --release`
-
-### USB-DFU
-
-* Get [cargo-binutils](https://github.com/rust-embedded/cargo-binutils/)
-* `cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin` or `arm-none-eabi-objcopy -O binary target/thumbv7em-none-eabihf/release/dual-iir dual-iir.bin`
-* Install the DFU USB tool (`dfu-util`)
-* Connect to the Micro USB connector below the RJ45
-* Short JC2/BOOT
-* `dfu-util -a 0 -s 0x08000000:leave -D dual-iir.bin`
-
-### ST-Link virtual mass storage
-
-* Prepare `dual-iir.bin` like above
-* Connect the ST-Link debugger
-* Copy `dual-iir.bin` to the `NODE_H743ZI` virtual mass storage device
+## Hardware
 
-## Protocol
+[![Stabilizer](https://github.com/sinara-hw/Stabilizer/wiki/Stabilizer_v1.0_top_small.jpg)](https://github.com/sinara-hw/Stabilizer)
 
-Stabilizer can be configured via MQTT. Refer to
-[`miniconf`](https://github.com/quartiq/miniconf) for more information about topics.
-A basic command line interface is available in [`miniconf.py`](miniconf.py).
-Telemetry is published via MQTT as well.
+[![Pounder](https://user-images.githubusercontent.com/1338946/125936814-3664aa2d-a530-4c85-9393-999a7173424e.png)](https://github.com/sinara-hw/Pounder/wiki)

docs/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+gem "just-the-docs"
+gem "jekyll-remote-theme"
+gem "html-proofer"

docs/Gemfile.lock

@@ -0,0 +1,102 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.9)
+    em-websocket (0.5.2)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0.6.0)
+    ethon (0.14.0)
+      ffi (>= 1.15.0)
+    eventmachine (1.2.7-x64-mingw32)
+    ffi (1.15.3-x64-mingw32)
+    forwardable-extended (2.6.0)
+    html-proofer (3.19.2)
+      addressable (~> 2.3)
+      mercenary (~> 0.3)
+      nokogumbo (~> 2.0)
+      parallel (~> 1.3)
+      rainbow (~> 3.0)
+      typhoeus (~> 1.3)
+      yell (~> 2.0)
+    http_parser.rb (0.6.0)
+    i18n (1.8.10)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.0)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-remote-theme (0.4.3)
+      addressable (~> 2.0)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
+      rubyzip (>= 1.3.0, < 3.0)
+    jekyll-sass-converter (2.1.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-seo-tag (2.7.1)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.3.3)
+      jekyll (>= 3.8.5)
+      jekyll-seo-tag (~> 2.0)
+      rake (>= 12.3.1, < 13.1.0)
+    kramdown (2.3.1)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.5.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    nokogiri (1.11.7-x64-mingw32)
+      racc (~> 1.4)
+    nokogumbo (2.0.5)
+      nokogiri (~> 1.8, >= 1.8.4)
+    parallel (1.20.1)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    racc (1.5.2)
+    rainbow (3.0.0)
+    rake (13.0.6)
+    rb-fsevent (0.11.0)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.26.0)
+    rubyzip (2.3.2)
+    safe_yaml (1.0.5)
+    sassc (2.4.0-x64-mingw32)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    typhoeus (1.4.0)
+      ethon (>= 0.9.0)
+    unicode-display_width (1.7.0)
+    yell (2.2.2)
+
+PLATFORMS
+  x64-mingw32
+
+DEPENDENCIES
+  html-proofer
+  jekyll-remote-theme
+  just-the-docs
+
+BUNDLED WITH
+   2.2.22

docs/README.md

@@ -0,0 +1,20 @@
+This folder represents the Github Pages site that is used to host Stabilizer's user guide.
+
+The site is hosted with Jekyll and utilizes the "Just the Docs" theme.
+
+To run locally:
+1. Install Ruby
+1. Install [Jekyll](https://jekyllrb.com/)
+1. Install [Bundler](https://bundler.io/)
+1. From this directory:
+```
+bundle install
+bundle exec jekyll serve
+```
+1. Navigate to `localhost:4000/stabilizer/` in a web browser
+
+Note: Some of the links in the docs rely on Cargo's documentation. To make all links work locally, run:
+```
+cargo doc --no-deps -p dsp -p miniconf -p stabilizer -p ad9959
+cp -r target/thumbv7em-none-eabihf/doc docs/firmware
+```

docs/Rakefile

@@ -0,0 +1,34 @@
+# Rakefile taken from:
+# https://seankilleen.com/2019/09/how-to-check-your-jekyll-based-blog-for-dead-links/
+
+# Ensures we have the html-proofer library available to use
+require 'html-proofer'
+
+# The function that will run the proofer, so that we can re-use it between our two rake tasks
+def run_htmlproofer()
+  options = {
+    # Assumes html file extensions
+    assume_extension: true,
+
+    file_ignore: [ /stabilizer\/firmware\/.*/ ],
+
+    # The options for the curl library that's used.
+    :typhoeus => {
+      # This will stop you from getting errors when certs can't be parsed, which doesn't matter in this case.
+      :ssl_verifypeer => false
+    },
+    # Won't fail for local links
+    allow_hash_href: true,
+  }
+
+  # Calls html-proofer and uses the Jekyll _site folder
+  HTMLProofer.check_directory("./_site", options).run
+end
+
+task :test do
+  run_htmlproofer()
+end
+
+task :build do
+  sh "bundle exec jekyll build -d _site/stabilizer"
+end