Adding Stabilizer User Manual

.github/workflows/ci.yml

@@ -129,8 +129,11 @@ jobs:
       - name: Move firmware documents
         run: |
           mkdir -p docs/_site/stabilizer
-          mv target/thumbv7em-none-eabihf/doc docs/_site/stabilizer/firmware
 
       - name: Test User Manual
         working-directory: docs
-        run: rake test
+        run: |
+          rake build
+          mv target/thumbv7em-none-eabihf/doc docs/_site/stabilizer/firmware
+          rake test
+

README.md

@@ -4,15 +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.
+Check out the [Documentation](https://quartiq.de/stabilizer) for more information on usage,
+configuration, and development.
+
+## Hardware
 
-Check out the [Documentation](https://quartiq.de/stabilizer) for more information on usage.
+[![Stabilizer](https://github.com/sinara-hw/Stabilizer/wiki/Stabilizer_v1.0_top_small.jpg)](https://github.com/sinara-hw/Stabilizer)
 
+[![Pounder](https://user-images.githubusercontent.com/1338946/125936814-3664aa2d-a530-4c85-9393-999a7173424e.png)](https://github.com/sinara-hw/Pounder/wiki)

docs/README.md

@@ -11,10 +11,10 @@ To run locally:
 bundle install
 bundle exec jekyll serve
 ```
-1. Navigate to `localhost:4000` in a web browser
+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 --bins
+cargo doc --no-deps -p dsp -p miniconf -p stabilizer -p ad9959
 cp -r target/thumbv7em-none-eabihf/doc docs/firmware
 ```

docs/Rakefile

@@ -9,6 +9,9 @@ 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.
@@ -23,6 +26,9 @@ def run_htmlproofer()
 end
 
 task :test do
-  sh "bundle exec jekyll build -d _site/stabilizer"
   run_htmlproofer()
 end
+
+task :build do
+  sh "bundle exec jekyll build -d _site/stabilizer"
+end

docs/_config.yml

@@ -3,8 +3,8 @@ title: Stabilizer
 description: "User Manual"
 logo: "/assets/stabilizer-logo.png"
 
-url: "https://quartiq.de"
-baseurl: "/stabilizer"
+#url: "https://quartiq.de"
+#baseurl: "/stabilizer"
 
 exclude: ['README.md']
 

docs/pages/getting-started.md

@@ -13,16 +13,18 @@ nav_order: 2
 ---
 
 # Getting Started
+{: .no_toc }
 
 There are a number of steps that must be completed when first getting started with Stabilizer.
-1. Set parameters in the firmware source code, such as IP addresses and sampling rate.
-1. Build the application by compiling the source code.
-1. Upload the application and programming it onto the device.
+1. Update the Stabilizer Application
+    1. Set parameters in the firmware source code, such as IP addresses and sampling rate.
+    1. Build the application by compiling the source code.
+    1. Upload the application and programming it onto the device.
 1. Set up MQTT for telemetry and configuration.
 
 The following sections will walk you through completing each of these steps.
 
-# Program Stabilizer
+# Update Stabilizer
 
 Firmware is compiled and loaded onto Stabilizer to program a specific application.
 

docs/pages/networking.md → docs/pages/usage.md

@@ -1,10 +1,8 @@
 ---
-title: Networking
+title: Usage
 layout: default
 nav_order: 4
-permalink: /networking/
-has_children: true
-has_toc: false
+permalink: /usage/
 ---
 
 ## Table of Contents
@@ -13,7 +11,7 @@ has_toc: false
 1. TOC
 {:toc}
 
-## MiniConf Run-time Settings
+## Miniconf Run-time Settings
 Stabilizer supports run-time settings configuration using MQTT.
 
 Settings can be stored in the MQTT broker so that they are automatically applied whenever
@@ -27,8 +25,42 @@ to another. Disambiguation of devices is done by using Stabilizer's MAC address.
 Settings are specific to an application. If two identical settings exist for two different
 applications, each application maintains its own independent value.
 
-Refer to the [documentation](run-time-settings) for information on how to configure run-time
-settings.
+### Setup
+
+In order to use `miniconf.py`, run the following command:
+```
+python -m pip install gmqtt
+```
+
+### Usage
+The `miniconf.py` script utilizes a unique "device prefix". The device prefix is always of the
+form `dt/sinara/<app>/<mac-address>`, where `<app>` is the name of the application and
+`<mac-address>` is the MAC address of the device, formatted with delimiting dashes.
+
+Settings have a `path` and a `value` being configured. The `value` parameter is JSON-encoded data
+and the `path` value is a path-like string.
+
+As an example, for configuring `dual-iir`'s `stream_target`, the following information would be
+used:
+* `path` = `stream_target`
+* `value` = `{"ip": [192, 168, 0, 1], "port": 4000}`
+
+```
+python miniconf.py --broker localhost dt/sinara/dual-iir/00-11-22-33-44-55 stream_target='{"ip": [192, 168, 0, 1], "port": 4000}'
+```
+
+The prefix can be found for a specific device by looking at the topic on which telemetry that is
+being published.
+
+Refer to the [application documentation]({{site.baseurl}}/#applications) for the exact settings and values exposed
+for each application.
+
+The rules for constructing `path` values are documented in [`miniconf`'s
+documentation](https://github.com/quartiq/miniconf#settings-paths)
+
+Refer to the documentation for [Miniconf]({{site.baseurl}}/firmware/miniconf/enum.Error.html) for a
+description of the possible error codes that `miniconf.py` may return if the settings update was
+unsuccessful.
 
 ## Telemetry
 

src/net/telemetry.rs

@@ -49,13 +49,13 @@ pub struct TelemetryBuffer {
 #[derive(Serialize)]
 pub struct Telemetry {
     /// Most recent input voltage measurement.
-    adcs: [f32; 2],
+    pub adcs: [f32; 2],
 
     /// Most recent output voltage.
-    dacs: [f32; 2],
+    pub dacs: [f32; 2],
 
     /// Most recent digital input assertion state.
-    digital_inputs: [bool; 2],
+    pub digital_inputs: [bool; 2],
 }
 
 impl Default for TelemetryBuffer {