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

Migrating documentation to Github Pages #217

Merged
merged 15 commits into from
Apr 20, 2022
Merged
Changes from all 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
46 changes: 46 additions & 0 deletions .github/workflows/release-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Release Documentation

on:
workflow_dispatch:
push:
branches:
- develop

jobs:
release-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0

- uses: Swatinem/rust-cache@v1

- name: Install Linkcheck
uses: actions-rs/cargo@v1
with:
command: install
args: mdbook-linkcheck

- name: Install ToC
uses: actions-rs/cargo@v1
with:
command: install
args: mdbook-toc

- uses: peaceiris/actions-mdbook@v1
with:
mdbook-version: '0.4.12'

- name: Build Book
working-directory: book
run: mdbook build

- uses: peaceiris/[email protected]
with:
deploy_key: ${{ secrets.PAGES_DEPLOY }}
publish_dir: book/booster-manual/html
enable_jekyll: true
publish_branch: pages
force_orphan: true
external_repository: quartiq/booster-doc
174 changes: 4 additions & 170 deletions README.md
Original file line number Diff line number Diff line change
@@ -14,6 +14,10 @@ access to the source code to modify it but the number of installed instances is
limited and certified. Once the development and maintenance investments have
been recovered the firmware will be offered under an open source license.

# Documentation

Please see the [Online Documentation](https://quartiq.de/booster-doc) for usage information.

# License

Copyright (C) 2020 QUARTIQ GmbH - All Rights Reserved
@@ -31,176 +35,6 @@ The open hardware designs and hardware discussions are located at
https://github.com/sinara-hw/Booster/wiki.
The hardware is available from Creotech, QUARTIQ, Technosyste, and M-Labs.

# Getting Started

This section is intended to acquaint the user with the Booster NGFW application.

There are three ways to interface with the Booster application:
1. Pressing any of two the front-panel buttons
1. Communicating with Booster over the USB port
1. Communicating with Booster over ethernet via MQTT

## Front Panel

There are two buttons on the front of booster. One is labeled "Interlock Reset" and the other is
labeled "Standby".

The "Standby" button places all channels into an RF-disabled state. In this state, the channel is
not powered and no output will be generated. Pressing the "Standby" button repeatedly will not have
any effect.

The "Interlock Reset" has the effect of powering up all of the channels and resetting any tripped
interlocks. After powering up, channels require a few hundred milliseconds to fully enable, so there
is a short delay after the button press before outputs fully enable. The "Interlock Reset" button
may be pressed while all channels are already powered to reset any tripped interlocks to re-enable
RF output.

Each output channel is composed of 3 LEDs - one red, one yellow/orange, and one green. If no RF
module is installed for a given channel, no LEDs on the channel will be illuminated. If an RF
channel is detected, at least one of the LEDs will illuminate.

The red LED is illuminated if a channel fault is detected. A fault cannot be cleared by the
"Interlock Reset" button, the channel is powered down, and the channel cannot be used. The only way
to clear this type of error is to power cycle Booster. The red LED nominally indicates a fault at a
hardware level that likely requires further investigation. Any indication of the red LED should
warrant further investigation of the device.

The yellow LED and the green LED are used to indicate the status of an operational RF amplification
channel. When the yellow LED is illuminated, the RF input is disabled on the channel. When a
channel is in standby or powered down, the yellow LED will illuminate without the green LED.

The green LED indicates that the RF channel is powered. If only the green LED is illuminated,
the channel is operational and outputting normally. If the green LED and the yellow LED are both
illuminated, this indicates that an RF channel interlock has tripped. The
channel may be reset from this state by pressing the "Interlock Reset" button.

The ethernet port contains a green and an orange/yellow LED. The yellow LED illuminates when Booster
has successfully connected with an ethernet switch. The green LED will flash whenever there is
ethernet traffic detected.

## USB Port

The USB port on booster enumerates as a serial port and can be opened with any terminal emulation
program (e.g. Pyserial's miniterm, TeraTerm, picoterm, putty, or your desired serial port reader).
The USB port serves two purposes:
* Human-readable logging
* Basic network and MQTT configuration

No control of the RF channels is exposed over the USB serial port. Channels may only be controlled
over MQTT or through the front-panel buttons.

When connecting to the USB port, a help menu is displayed to the user to outline what can be
configured over the USB port. Any configuration made over the USB port will not take effect
immediately - in order for new configurations to apply, booster must be reset.

The USB port allows for configuration of:
* The MQTT ID of Booster
* The MQTT broker IP address
* The ethernet netmask
* The ethernet gateway (if connected to the internet)
* The IP address of booster

Additionally, the USB port allows the user to:
* Read the MAC address
* Reboot the device
* Enter DFU mode remotely for upgrading firmware over USB

## Booster Units

Booster uses SI units (Volt, Ampere, Celsius) for telemetry messages and properties. Power measurements are specified in dBm.

## Ethernet Telemetry and Control

Refer to [Appendix: Ethernet Configuration](#appendix-ethernet-configuration) for information on
configuring Booster's ethernet interface.

Please refer to [Stabilizer's documentation](https://quartiq.de/stabilizer/setup.html#mqtt-broker)
for instructions on getting MQTT configured.

Booster uses MQTT for telemetry and control of RF channels. All booster MQTT topics are prefixed
with `dt/sinara/booster/<ID>`, where <ID> is the MAC address of the device (e.g.
`12-34-56-78-90-ab`). Telemetry is generated on the `<prefix>/telemetry/ch<N>` topics, where
N is an integer from 0 to 7. Telemetry is only reported for connected channels. Telemetry is
transmitted in human-readable JSON format for logging purposes.

We recommend using [`mqtt-explorer`](http://mqtt-explorer.com/) to view telemetry and run-time
settings.

Booster leverages [`miniconf`](https://crates.io/crates/miniconf) to manage run-time settings and
configuration identical to Stabilizer. Please refer to [Stabilizer's Miniconf
Documentation](https://quartiq.de/stabilizer/usage.html#miniconf-run-time-settings) to get
started.

Booster supports RF channel bias tuning and saving active channel settings configuration to EEPROM
via the Booster python package located in the `py` folder of the repository. Execute the
following to install the package and see how to use it:
```sh
pip install py
python -m booster --help
```

When settings are saved in booster, the saved channel configuration will be applied to
the channel when Booster boots. Note that saving channel settings overwrites any existing channel
configuration and calibrations including those from the old legacy firmware. The legacy firmware
settings are incompatible.


### Appendix: Ethernet Configuration

Because Booster currently works with static IP addresses, it is recommended to operate Booster on a
closed, internal network. As such, it is likely that you may need to configure IP routing on the
broker computer so that communication with Booster can succeed.

Given an ethernet interface on the broker machine called `<ETHERNET_INTERFACE>`, the broker can be
configured with an IP address of 10.0.0.2 on the local machine and told to communicate with a
booster using an IP address of 10.0.0.X on the provided interface using the following commands:

```
sudo ip route add 10.0.0.0/24 dev <ETHERNET_INTERFACE>
sudo ip address add 10.0.0.2 dev <ETHERNET_INTERFACE>
```

Note that you will likely also need to run mosquitto with a special configuration file. Contents of
the configuration file `mosquitto.conf` may look as follows:
```
bind_interface <ETHERNET_INTERFACE>
```

Mosquitto would then be started by calling `moqsuitto -c mosquitto.conf` to run mosquitto on the
provided ethernet interface.

# DFU Instructions

**Prerequisites**
* Ensure `dfu-util` is installed. On Ubuntu, install it from `apt` using `sudo apt-get install
dfu-util`
* If building your own firmware, [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils#installation)) must be installed:
```
cargo install cargo-binutils
rustup component add llvm-tools-preview
```

The following instructions describe the process of uploading a new firmware image over the DFU
Bootloader USB interface.

1. Generate the firmware image: `cargo build`
- Note: You may append `--release` to build the firmware with more optimization and less debugging information.
- Note: You may also use the latest [pre-built](https://github.com/quartiq/booster/releases) assets instead of building firmware.

1. Generate the binary file for your firmware build: `cargo objcopy -- -O binary booster.bin`
- Note: If you built with `--release`, use the commmand: `cargo objcopy --release -- -O binary booster.bin`

1. Reset Booster into DFU mode. This can be done via the USB serial port or by doing the following:
- Insert a pin into the DFU Bootloader hole to press the DFU button
- While the DFU button is pressed, power cycle booster by turning off the power switch for at
least 10 seconds and then turn the power switch on.

1. Verify Booster is in DFU mode: `dfu-util -l` should show 4 entries beginning with `Found DFU: [0483:df11]`
1. Upload the DFU file to Booster:
```
dfu-util -a 0 -s 0x08000000:leave --download booster.bin
```

# Generating Releases

When a release is ready, `develop` must be merged into `master`.
1 change: 1 addition & 0 deletions book/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
booster-manual
18 changes: 18 additions & 0 deletions book/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# User Manual

This folder hosts the source used for generating the user manual.

The user manual is generated using `mdbook`, which can be installed via cargo:
```
cargo install mdbook
cargo install mdbook-toc
cargo install mdbook-linkcheck
```

To build the user manual locally and then serve the book:
```
mdbook serve book
```

Once the `mdbook serve` command is run, the manual can be found on a web browser at
`localhost:3000`.
21 changes: 21 additions & 0 deletions book/book.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
[book]
authors = ["Ryan Summers"]
language = "en"
multilingual = false
src = "src"
title = "Booster Documentation"

[build]
create-missing = false
build-dir = "booster-manual"

[preprocessor.toc]
marker = "<-- TOC -->"
command = "mdbook-toc"
renderer = ["html"]

[output.html]
site-url = "/booster-doc"
git-repository-url = "https://github.com/quartiq/booster"

[output.linkcheck]
6 changes: 6 additions & 0 deletions book/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Summary

- [Overview](overview.md)
- [Front Panel Operation](front-panel.md)
- [Network Interface](network-interface.md)
- [Appendix: Firmware Update](firmware-update.md)
Binary file added book/src/assets/booster-creotech-v1.3.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added book/src/assets/booster-settings-example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added book/src/assets/booster-telemetry-example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added book/src/assets/user-interface-example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
33 changes: 33 additions & 0 deletions book/src/firmware-update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Firmware Upgrade Instructions

These instructions provide information on how to upgrade the firmware on Booster to a newer release.

**Prerequisites**
* Ensure `dfu-util` is installed. On Ubuntu, install it from `apt` using `sudo apt-get install
dfu-util`
* If building your own firmware, [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils#installation)) must be installed:
```
cargo install cargo-binutils
rustup component add llvm-tools-preview
```

The following instructions describe the process of uploading a new firmware image over the DFU
Bootloader USB interface.

1. Generate the firmware image: `cargo build`
- Note: For production usage, you should append `--release` to build the firmware with more optimization and slightly less debugging information.
- Note: You may also use the latest [pre-built](https://github.com/quartiq/booster/releases) assets instead of building firmware.

1. Generate the binary file for your firmware build: `cargo objcopy -- -O binary booster.bin`
- Note: If you built with `--release`, use the commmand: `cargo objcopy --release -- -O binary booster.bin`

1. Reset Booster into DFU mode. This can be done via the USB serial port or by doing the following:
- Insert a pin into the DFU Bootloader hole to press the DFU button
- While the DFU button is pressed, power cycle booster by turning off the power switch for at
least 10 seconds and then turn the power switch on.

1. Verify Booster is in DFU mode: `dfu-util -l` should show 4 entries beginning with `Found DFU: [0483:df11]`
1. Upload the DFU file to Booster:
```
dfu-util -a 0 -s 0x08000000:leave --download booster.bin
```
90 changes: 90 additions & 0 deletions book/src/front-panel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Front Panel

<-- TOC -->

The front panel of Booster is used to physically clear channel interlocks to enable channels. It is also used to power down Booster and observe the operational status of the
channels and ethernet interface.

## User Buttons
There are two buttons on the front of booster. One is labeled "Interlock Reset" and the other is
labeled "Standby".

The "Standby" button places all channels into an RF-disabled state. In this state, the channel is
not powered and no output will be generated. Pressing the "Standby" button repeatedly will not have
any effect.

The "Interlock Reset" has the effect of powering up all of the channels and resetting any tripped
interlocks. After powering up, channels require a few hundred milliseconds to fully enable, so there
is a short delay after the button press before outputs fully enable. The "Interlock Reset" button
may be pressed while all channels are already powered to reset any tripped interlocks to re-enable
RF output.

There is also a much smaller, recessed button labeled "DFU Bootloader". This button may be pressed
while power is cycled to Booster to force the device into DFU mode. Booster NGFW exposes a mechanism
to reset to DFU mode via the USB port, so this button is not generally necessary.

# Channel LED Indications

Each output channel is composed of 3 LEDs - one red, one yellow/orange, and one green. If no RF
module is installed for a given channel, no LEDs on the channel will be illuminated. If an RF
channel is detected, at least one of the LEDs will illuminate.

The red LED is illuminated if a channel fault is detected. A fault cannot be cleared by the
"Interlock Reset" button, the channel is powered down, and the channel cannot be used. The only way
to clear this type of error is to power cycle Booster. The red LED nominally indicates a fault at a
hardware level that likely requires further investigation. Any indication of the red LED should
warrant further investigation of the device.

The yellow LED and the green LED are used to indicate the status of a
channel. When the yellow LED is illuminated, the RF input is disabled on the channel. When a
channel is in standby or powered down, the yellow LED will illuminate without the green LED.

The green LED indicates that the channel is powered. If only the green LED is illuminated,
the channel is operational and outputting normally. If the green LED and the yellow LED are both
illuminated, this indicates that an channel interlock has tripped. The channel may be reset from
this state by pressing the "Interlock Reset" button.

### Example

![Front Panel Example](assets/user-interface-example.png)

_Figure 1_: Sample Booster front-panel indications.

In the example above, it can be seen that CH0 is enabled.

Channel 2 is enabled, but one of the protection interlocks has tripped. This channel interlock can
be cleared by pressing the "Interlock Reset" button after the trip source has been removed.

Channels 1 and 3-7 are all powered up, but outputs are disabled.

# Ethernet Port

The ethernet port contains a green and an orange/yellow LED. The yellow LED illuminates when Booster
has successfully connected with an ethernet switch. The green LED will flash whenever there is
ethernet traffic detected.

# USB Port

The USB port on booster enumerates as a serial port and can be opened with any terminal emulation
program (e.g. Pyserial's miniterm, TeraTerm, picoterm, putty, or your desired serial port reader).
The USB port serves two purposes:
* Human-readable logging
* Basic network and MQTT configuration

No control of the channels is exposed over the USB serial port. Channels may only be controlled
over MQTT or through the front-panel buttons.

When connecting to the USB port, a help menu is displayed to the user to outline what can be
configured over the USB port. Any configuration made over the USB port will not take effect
immediately - in order for new configurations to apply, booster must be reset.

The USB port allows for configuration of:
* The MQTT ID of Booster
* The MQTT broker IP address
* Default fan speeds

Additionally, the USB port allows the user to:
* Read the MAC address
* Reboot the device
* Enter DFU mode remotely for upgrading firmware over USB
* Request device service information
56 changes: 56 additions & 0 deletions book/src/network-interface.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Ethernet Telemetry and Control

<-- TOC -->

Booster uses MQTT for telemetry reporting, settings configuration, and control of the channels. All
booster MQTT topics are prefixed with `dt/sinara/booster/<ID>`, where <ID> is the MAC address of the
device by default(e.g. `12-34-56-78-90-ab`). The ID is configurable via the USB port.

Please refer to [Stabilizer's documentation](https://quartiq.de/stabilizer/setup.html#mqtt-broker)
for instructions on getting MQTT configured.

We recommend using [`mqtt-explorer`](http://mqtt-explorer.com/) to view telemetry and run-time
settings.

## Measurement Units

Booster uses SI units (Volt, Ampere, Celsius) for telemetry and settings. Power measurements are
specified in dBm.


## Telemetry

Telemetry is generated on the
`<prefix>/telemetry/ch<N>` topics, where N is an integer from 0 to 7. Telemetry is only reported for
connected channels. Telemetry is transmitted in human-readable JSON format for logging purposes.


![Sample Booster Telemtry Topics](assets/booster-telemetry-example.png)

_Figure 1_: Example display of Booster telemetry on all 8 channels reported via MQTT Explorer.

## Settings

Booster leverages [`miniconf`](https://crates.io/crates/miniconf) to manage run-time settings and
configuration identical to Stabilizer. Please refer to [Stabilizer's Miniconf
Documentation](https://quartiq.de/stabilizer/usage.html#miniconf-run-time-settings) to get
started.

When settings are saved in booster, the saved channel configuration will be applied to
the channel when Booster boots. Note that saving channel settings overwrites any existing channel
configuration and calibrations including those from the old legacy firmware. The legacy firmware
settings are incompatible.

![Sample Booster Settings](assets/booster-settings-example.png)

_Figure 2_: Example display of Booster settings tree reported via MQTT Explorer.

## Control

Booster supports channel bias tuning and saving active channel settings configuration to EEPROM
via the Booster python package located in the `py` folder of the repository. Execute the
following to install the package and see how to use it:
```sh
pip install py
python -m booster --help
```
28 changes: 28 additions & 0 deletions book/src/overview.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Booster NGFW (Next-Generation Firmware) User Manual

This document is intended to provide an overview of the Booster NG firmware, which is a rewrite of
Booster firmware to align it with other projects, resolve qualify issues, and enable continued
maintenance and improvements.

The firmware is offered as an option to Booster and licensed on a restrictive
per-device basis with redistribution and reuse prohibited. End users obtain
access to the source code to modify it but the number of installed instances is
limited and certified. Once the development and maintenance investments have
been recovered the firmware will be offered under an open source license.

# Hardware

![Booster Creotech Front Panel](assets/booster-creotech-v1.3.jpg)

Booster is an 8 channel RF power amplifier in the Sinara open hardware ecosystem.
The open hardware designs and hardware discussions are located at
https://github.com/sinara-hw/Booster/wiki.
The hardware is available from Creotech, QUARTIQ, Technosystem, and M-Labs.

# Getting Started

There are three ways to interface with the Booster application that are covered in the chapters of
this manual:
1. Pressing any of two the front-panel buttons
1. Communicating with Booster over the USB port
1. Communicating with Booster over ethernet via MQTT
Binary file added book/theme/favicon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.