Squashing manual changes

quartiq · Jul 15, 2021 · f1947db · f1947db
1 parent abe810f
commit f1947db
Show file tree

Hide file tree

Showing 34 changed files with 875 additions and 132 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -83,3 +83,29 @@ 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-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
+          args: --dir target/thumbv7em-none-eabihf/doc
diff --git a/.github/workflows/release-docs.yml b/.github/workflows/release-docs.yml
@@ -0,0 +1,35 @@
+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
diff --git a/.gitignore b/.gitignore
@@ -1 +1,2 @@
 /target
+docs/_site/
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -70,7 +70,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"

diff --git a/README.md b/README.md
@@ -13,79 +13,6 @@
 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
+Check out the [Documentation](https://quartiq.de/stabilizer) for more information on usage.
 
-![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.
-
-## 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
-
-## Protocol
-
-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.
diff --git a/doc/.keep-me b/doc/.keep-me
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gem "just-the-docs"
+gem "jekyll-remote-theme"
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -0,0 +1,81 @@
+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)
+    eventmachine (1.2.7-x64-mingw32)
+    ffi (1.15.3-x64-mingw32)
+    forwardable-extended (2.6.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)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (4.0.6)
+    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)
+    unicode-display_width (1.7.0)
+
+PLATFORMS
+  x64-mingw32
+
+DEPENDENCIES
+  jekyll-remote-theme
+  just-the-docs
+
+BUNDLED WITH
+   2.2.22
diff --git a/docs/README.md b/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` 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 --bins
+cp -r target/thumbv7em-none-eabihf/doc docs/firmware
+```
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,18 @@
+remote_theme: pmarsceill/just-the-docs
+title: Stabilizer
+description: "User Manual"
+logo: "/assets/stabilizer-logo.png"
+
+url: "https://quartiq.de"
+baseurl: "/stabilizer"
+
+exclude: ['README.md']
+
+plugins:
+  - jekyll-remote-theme
+
+# Enable an auxilary link in top right with a new tab open
+aux_links:
+  "Stabilizer on Github":
+    - "//github.com/quartiq/stabilizer"
+aux_links_new_tab: true
diff --git a/docs/assets/mqtt-explorer.png b/docs/assets/mqtt-explorer.png
diff --git a/docs/assets/stabilizer-jtag.jpg b/docs/assets/stabilizer-jtag.jpg
diff --git a/docs/assets/stabilizer-logo.png b/docs/assets/stabilizer-logo.png
diff --git a/stabilizer_pid.svg → docs/assets/stabilizer_pid.svg b/stabilizer_pid.svg → docs/assets/stabilizer_pid.svg
diff --git a/docs/favicon.ico b/docs/favicon.ico
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,55 @@
+---
+title: Home
+layout: default
+nav_order: 1
+permalink: /
+---
+
+# Stabilizer
+{: .no_toc }
+
+## Table of Contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+## Overview
+
+Stabilizer is a flexible tool designed for quantum physics experiments. Fundamentally, Stabilizer
+samples up two two analog input signals, performs digital signal processing internally, and then
+generates up to two output signals.
+
+Stabilizer firmware supports run-time configuration of the internal signal processing algorithms,
+which allows for a wide variety of experimental uses, such as digital filter design or
+implementation of digital lockin schemes.
+
+This documentation is intended to bring a user up to speed on using Stabilizer and the firmware
+provided by Quartiq.
+
+## Hardware
+
+The Stabilizer hardware is managed via a [separate repository](https://github.com/sinara-hw/Stabilizer).
+
+[![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, which is the compiled firmware running on the device, can compose and configure these hardware and software components to implement different use cases.
+Several applications are provided by default.
+
+The following documentation links contain the application-specific settings and telemetry
+information.
+
+| Application | Documentation | Application Description |
+| :---: | :--: | :---- |
+| `dual-iir` | [Link]({{site.baseurl}}/firmware/dual_iir/index.html) | Two channel biquad IIR filter
+| `lockin` | [Link]({{site.baseurl}}/firmware/lockin/index.html) | Lockin amplifier support various various reference sources |
+
+### Library Documentation
+The Stabilizer library docs contain documentation for common components used in all Stabilizer
+applications.
+
+The Stabilizer library documentation is available [here]({{site.baseurl}}/firmware/stabilizer/index.html).