Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding Stabilizer User Manual #401

Merged
merged 22 commits into from
Jul 16, 2021
Merged
Show file tree
Hide file tree
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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

36 changes: 36 additions & 0 deletions .github/workflows/release-docs.yml
Original file line number Diff line number Diff line change
@@ -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
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
/target
docs/_site/
4 changes: 2 additions & 2 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -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"]
Expand Down Expand Up @@ -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"
Expand Down
85 changes: 5 additions & 80 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Empty file removed doc/.keep-me
Empty file.
4 changes: 4 additions & 0 deletions docs/Gemfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
source 'https://rubygems.org'
gem "just-the-docs"
gem "jekyll-remote-theme"
gem "html-proofer"
102 changes: 102 additions & 0 deletions docs/Gemfile.lock
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -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
```
34 changes: 34 additions & 0 deletions docs/Rakefile
Original file line number Diff line number Diff line change
@@ -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
Loading