From 834df87fc49fc7ee25022ac1fb505cb404542959 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Thu, 8 Oct 2020 18:14:54 +0200 Subject: [PATCH 1/2] Adding documentation for using Booster --- README.md | 178 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 176 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7328153d..ab1f1934 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,186 @@ Proprietary and confidential. You may purchase a [license](LICENSE) to use this software from [QUARTIQ](mailto:sales@quartiq.com). +# 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 output 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 and operational. Note that this does not +indicate that the channel is outputting (this is denoted by the yellow LED). 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. If only the green LED +is illuminated, the channel is operational and outputting normally. + +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, or your desired serial port reader). The USB +port serves two purposes: +* Logs are generated out the USB port +* Basic network and MQTT configuration can be completed + +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 of Booster +* Reset booster +* Enter DFU mode for upgrading firmware + +## Ethernet + +Booster uses MQTT for telemetry and control of RF channels. All booster MQTT topics are prefixed +with the booster ID, which defaults to a combination of `booster` and the MAC address of the device. +Telemetry is generated on the `/ch` topics, where N is an integer from 0 to 7. Telemetry is +only reported for connected channels and is nominally transmitted at a rate of 2Hz. Telemetry is +transmitted in human-readable JSON format for logging purposes. + +Booster also supports a control interface over MQTT using the following topics: +* `/channel/state` - Used to configure the power state of an RF channel +* `/channel/tune` - Used to tune the drain current of an RF channel to tune the amplification +* `/channel/read` - Used to read Booster properties, such as the interlock thresholds or the + power transforms +* `/channel/write` - Used to write Booster properties, such as the interlock thresholds or the + power transforms + +When a valid message is received on any of these channels, Booster will process the message and +respond to the `ResponseTopic` property provided with the MQTT message. If no `ResponseTopic` +property is provided, Booster will respond by default to `/log`. + +For a reference implementation of the API to control booster over MQTT, refer to `booster.py` + +### Special Note on Booster properties + +When reading or writing Booster properties of `/channel/read` or `/channel/write`, the +serialized property is encoded in JSON format, but all double quotes (") are replaced with a single +quote ('). + + +## Configuring MQTT + +Booster utilizes MQTT for much of the configuration, control, and telemetry functionality. In order +to use MQTT, a broker must be run on a central machine for Booster to connect to. + +The recommended MQTT broker to work with booster is the Mosquitto broker. This can be installed in +Ubuntu by running: `sudo apt-get install mosquitto`. + +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 ``, 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 +sudo ip address add 10.0.0.2 dev +``` + +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 +``` + +Mosquitto would then be started by calling `moqsuitto -c mosquitto.conf` to run mosquitto on the +provided ethernet interface. + +## Configuring Booster + +Once an MQTT broker is connected and communicating with Booster, the `booster.py` Python script can +be used to configure Booster RF channels. + +To use `booster.py`, first install the prerequisites: +``` +python -m pip install gmqtt +``` + +To enable a specific RF channel: +``` +python booster.py --booster-id --enable +``` + +To disable a specific RF channel: +``` +python booster.py --booster-id --disable +``` + +To configure interlock thresholds for a channel: +``` +python booster.py --booster-id --thresholds +``` + +To tune the bias current of an RF channel to a desired drain current: +``` +python booster.py --booster-id --bias +``` + +Once a channel is configured as desired, the configuration can be stored permanently in Booster +using: +``` +python booster.py --booster-id --save +``` + +When settings are saved in booster, the current channel configuration will be the default state of +the channel when Booster boots. + # 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, install `cargo-binutils`: `cargo install cargo-binutils` The following instructions describe the process of uploading a new firmware image over the DFU Bootloader USB interface. @@ -36,7 +210,7 @@ Bootloader USB interface. - 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 DFU file for your firmware build: `dfu-tool convert target/thumbv7em-none-eabihf/debug/booster booster.dfu` +1. Generate the binary file for your firmware build: `cargo objcopy -- -O binary booster.bin` - Note: If you built with `--release`, replace `debug` with `release` in the above command. 1. Reset Booster into DFU mode: @@ -47,5 +221,5 @@ Bootloader USB interface. 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 -d 0483:df11 -a 0 --download booster.dfu +dfu-util -d 0483:df11 -a 0 -s 0x08000000:leave --download boosterbin. ``` From 66caca6b73e38419ac23b371039415902863ff51 Mon Sep 17 00:00:00 2001 From: Ryan Summers Date: Fri, 9 Oct 2020 07:23:38 +0200 Subject: [PATCH 2/2] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Jördens --- README.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index ab1f1934..b419e3c6 100644 --- a/README.md +++ b/README.md @@ -57,14 +57,13 @@ hardware level that likely requires further investigation. Any indication of the 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 output is disabled on the channel. When 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 RF channel is powered and operational. Note that this does not -indicate that the channel is outputting (this is denoted by the yellow LED). 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. If only the green LED -is illuminated, the channel is operational and outputting normally. +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 @@ -73,7 +72,7 @@ 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, or your desired serial port reader). The USB +program (e.g. Pyserial's miniterm, TeraTerm, picoterm, putty, or your desired serial port reader). The USB port serves two purposes: * Logs are generated out the USB port * Basic network and MQTT configuration can be completed @@ -129,10 +128,10 @@ quote ('). ## Configuring MQTT Booster utilizes MQTT for much of the configuration, control, and telemetry functionality. In order -to use MQTT, a broker must be run on a central machine for Booster to connect to. +to use MQTT, a broker must be run on a central machine for Booster to connect to. The broker must accept connections without authentication and must support MQTT version 5. The recommended MQTT broker to work with booster is the Mosquitto broker. This can be installed in -Ubuntu by running: `sudo apt-get install mosquitto`. +Ubuntu by running: `sudo apt-get install mosquitto`. Note that `mosquitto` in Debian stable/buster does not yet support MQTT version 5. 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 @@ -193,7 +192,7 @@ python booster.py --booster-id --save ``` When settings are saved in booster, the current channel configuration will be the default state of -the channel when Booster boots. +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. # DFU Instructions @@ -221,5 +220,5 @@ Bootloader USB interface. 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 -d 0483:df11 -a 0 -s 0x08000000:leave --download boosterbin. +dfu-util -a 0 -s 0x08000000:leave --download booster.bin ```