Skip to content

Commit

Permalink
Merge pull request #42 from galactic-forensics/docs
Browse files Browse the repository at this point in the history 
Fix docs
  • Loading branch information
@trappitsch
trappitsch committed Feb 8, 2024
2 parents f3172f6 + 5c6ad9f commit d43ae95
Show file tree
Hide file tree
Showing 9 changed files with 167 additions and 125 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/package_testing.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
run: rye run test
- name: Run Lint on one python
if: ${{ matrix.python-version == env.MAIN_PYTHON_VERSION }}
run: rye run lint
run: rye lint
- name: Run Pytest with coverage
if: ${{ matrix.python-version == env.MAIN_PYTHON_VERSION }}
run: |
Expand Down
15 changes: 6 additions & 9 deletions docs/controller.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,10 @@ frida = dev.channel[0]
frida.state = True
```

Note that all channels are zero-indexed.
!!! note
Channels are zero-indexed,
as is usual in python.

You could also query the state of the channel by printing out `frida.state`.

### Commands for all channels
Expand All @@ -63,7 +66,7 @@ To turn all channels to the off state, you can call

### Number of channels

By default, the number of channels is set to 15.
By default, the number of channels is set to 16.
You could change this if your hardware is different using
the `num_channels` property, e.g., to set it to 7, use:

Expand All @@ -88,10 +91,4 @@ the interlock or software lockout is active.

Finally, to query the hardware and firmware version of the DigOutBox,
you can check out the property: `dev.identify`.
This will tell you what is currently running on the box.

## Testing your hardware

A very simple script to test your hardware is provided
[here](https://github.com/galactic-forensics/DigOutBox/blob/main/controller/examples/hw_check.py).
Read the documentation in the script for more information.
This will tell you what firmware is currently running on the box.
35 changes: 25 additions & 10 deletions docs/dev.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@

Any contributions to this project are very welcome!
If you have an idea that you would like to implement,
please raise an issue and mention that you would like to contribute.
please [raise an issue](https://github.com/galactic-forensics/DigOutBox/issues)
and mention that you would like to contribute.

## Pull requests

Expand All @@ -15,8 +16,14 @@ If you do so,
please open a draft pull request.

We use [`pre-commit`](https://pre-commit.com/)
in order to ensure formatting before committing to `git`.
in order to ensure formatting before committing to `git`
using a pre-commit hook.
Once you have installed `pre-commit`,
you can run the following command to install the pre-commit hook:

```bash
pre-commit install
```

## Documentation

Expand Down Expand Up @@ -76,17 +83,24 @@ Please make sure that code is properly linted before committing.
You can run the linter with

```bash
rye run lint
rye lint
```

!!! tip
You can also run `rye run lint --fix` to automatically fix some issues.
You can also run `rye lint --fix` to automatically fix some issues.


The code base can be formatted with the command

```
rye fmt
```

!!! info
If you are not using `rye`,
you can run `ruff` directly.
However, you will need to install `ruff` in your environment.
See the `ruff` documentation for details.
If you are not using `rye`,
you can run `ruff` directly.
However, you will need to install `ruff` in your environment.
See the `ruff` documentation for details.

### Testing

Expand All @@ -98,7 +112,7 @@ We use [`pytest`](https://docs.pytest.org/) for testing.
All tests are located in the `tests` folder.
You can run the tests with

```bash
```
rye run test
```

Expand Down Expand Up @@ -167,4 +181,5 @@ on installation.
## Hardware

If you would like to contribute hardware designs,
please get in touch with us by raising an issue.
please get in touch with us by
[raising an issue](https://github.com/galactic-forensics/DigOutBox/issues).
68 changes: 40 additions & 28 deletions docs/firmware.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,12 @@ You can find the current version `v0.2.0`
[on GitHub](https://github.com/galactic-forensics/DigOutBox/tree/main/firmware).

The firmware consists of two files:

- `DigOutBox_fw_v*.ino`: This is the main file that contains the firmware.
- `config.h`: This file contains the configuration of the firmware.
You can find the configuration for the existing setups in the folder `configs` on GitHub.
If you want to use a new setup,

You can find the configuration for the existing setups in the folder `configs` on GitHub.
If you want to use a new setup,
you will need to create a new configuration file.

Please read the following sections
Expand All @@ -27,12 +29,12 @@ flashing the firmware, and communicating with the Arduino via serial.
Once finished with this section,
your box can be used with the remote.
You can also use our [GUI](gui.md)
or [Python Interface](controller)
or [Python Interface](controller.md)
for computer control.

## Overview of the configuration

The important file to understand, assuming you use the existing setups, is `config.h`.
The important file to understand, assuming you use the existing configuration, is `config.h`.
This file contains the configuration of the firmware.
It has three sections:

Expand All @@ -41,11 +43,14 @@ It has three sections:
This section contains the configuration of the DigOutBox hardware.
It contains the following variables:

- `numOfChannels`: The number of channels that are available.
- `numOfChannels`: The number of channels that are available in the DigOutBox.
- `numOfRemoteButtons`: The number of buttons on the remote control.
- `fw_version`: The firmware version.
- `hw_version`: The hardware version.

If you followed the instructions exactly,
these values do not have to be changed.

### User setup

This section contains the user setup.
Expand All @@ -68,9 +73,11 @@ The section contains the following variables:
- `RFChannels`: Array that maps the buttons of the remote control to the channels of the DigOut Box.
This array has `numOfRemoteButtons` elements.
Each element is an integer that maps the button to a channel.
"Channel" `-1` means that this button will turn all channels off.
"Channel" `-2` means that this button will be used to toggle the software lockout.
"Channel" `-3` means that this button is unused.

- "Channel" `-1` means that this button will turn all channels off.
- "Channel" `-2` means that this button will be used to toggle the software lockout.
- "Channel" `-3` means that this button is unused.

- `DOutInvert`: Array that defines the "off-state" of a channel.
This array has `numOfChannels` elements.
Each element is either `0` or `1` and defines the "off-state" of a channel.
Expand Down Expand Up @@ -108,9 +115,9 @@ and open the `Serial Terminal`.
If you press a remote control button,
the serial terminal will print out a message like:

```Valid RF Remote code received: 4543804 / Channel associated: -2```
```Valid RF Remote code received: 4543804 / Channel associated: -3```

If the code has not been set up, the associated channel will be `-2` (i.e., do nothing).
If the code has not been set up, the associated channel will be `-3` (i.e., do nothing).
For every button on your remote, write down the code that is received by the Arduino.
Do this for every remote that you would like to add to the instrument.

Expand Down Expand Up @@ -162,9 +169,11 @@ Below is a table with frequency codes that we have mapped already:

## Flash firmware

**Important: Make sure that the jumper on the board connecting the reset pin via the capacitor to ground is open!
Otherwise, you will not be able to flash firmware.
After you are done flashing firmware, close the connection with a jumper again.**
!!! warning
Make sure that the jumper on the board connecting the reset pin via the capacitor to ground
is removed (open connection).
Otherwise, you will not be able to flash firmware.
After you are done flashing firmware, close the connection with a jumper again.**

The following libraries are required to compile the firmware:

Expand All @@ -177,30 +186,33 @@ Many tutorials are out there on how to flash the firmware to the Arduino.
You will need to install the [Arduino IDE](https://www.arduino.cc/en/Main/Software).
You can find help with the IDEs, e.g., here [Arduino website](https://docs.arduino.cc/software/ide-v2).

## SCPI commands
## SCPI commands and serial connection

We use the `Vrekrer_scpi_parser.h` library to enable SCPI communication
with the DigOutBox. The following commands can be sent to set/query the device:
The Arduino can be controlled via a serial interface using a standard set of
[SCPI commands](https://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments).
Open a serial terminal and connect to the Arduino (`9600` baud).
Then, the following commands can be used:

| Command | Parameters | Description | Example |
|---------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| `*IDN?` | None | Query identity of device | `>>> *IDN?`<br/>`DigIOBox, Hardware v0.1.0, Firmware v0.1.0` |
| `DO#?` | - `#`: Number of channel | Query status of channel.<br/>Returns:<br/>- `0`: Channel off<br/>- `1`: Channel on | Status of channel 5 (on):<br/>`>>> DO5?`<br/>`1` |
| `DO# S` | - `#`: Number of channel<br/>- `S`: Status (`0` off, `1` on) | Set status of channel. | Turn channel 3 off:<br/>`>>> DO3 0` |
| `ALLDO?` | None | Query status of all channels. | `>>> ALLDO?`<br/>`1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0`<br/>Here, channel 1 reports as being on, all others are off. |
| `ALLOFF` | None | Turn off all channels. | `>>> ALLOFF` |
| `INTERLOCKS?` | None | Query the interlock state.<br/>- `1`: Interlocked<br/>- `0`: Not interlocked | `>>> INTERLOCKS?`<br/>`1`<br/> |
| `SWL?` | None | Query the software lockout state.<br/>- `1`: Software lockout active<br/>- `0`: Software lockout inactive | `>>> SWL?`<br/>`1`<br/> |
| Command | Description | Parameters | Example |
|---------------|-----------------------------------------------------------------------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| `*IDN?` | Query identity of device. | None | `>>> *IDN?`<br/>`DigIOBox, Hardware v0.1.0, Firmware v0.1.0` |
| `DO#?` | Query status of channel.<br/>Returns:<br/>- `0`: Channel off<br/>- `1`: Channel on | - `#`: Number of channel | Status of channel 5 (on):<br/>`>>> DO5?`<br/>`1` |
| `DO# S` | Set status of channel. | - `#`: Number of channel<br/>- `S`: Status (`0` off, `1` on) | Turn channel 3 off:<br/>`>>> DO3 0` |
| `ALLDO?` | Query status of all channels. | None | `>>> ALLDO?`<br/>`1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0`<br/>Here, channel 1 reports as being on, all others are off. |
| `ALLOFF` | Turn off all channels. | None | `>>> ALLOFF` |
| `INTERLOCKS?` | Query the interlock state.<br/>- `1`: Interlocked<br/>- `0`: Not interlocked | None | `>>> INTERLOCKS?`<br/>`1`<br/> |
| `SWL?` | Query the software lockout state.<br/>- `1`: Lockout active<br/>- `0`: Lockout inactive | None | `>>> SWL?`<br/>`1`<br/> |

Command sending is indicated with `>>>`.
Note that all commands must be terminated with a newline character (`\n`).
!!! note
Command sending is indicated with `>>>`.
All commands must be terminated with a newline character (`\n`).

## Testing

If all works, you can send SCPI commands to the device and see the LEDs turn on and off,
but also see the voltage output assume the desired value.
A simple testing script that allows you to measure each channel individually
and to test the remote and SCPI commands is provided with the python software
and to test the remote and SCPI commands is provided with the python interface
in the
[`controller/examples`](https://github.com/galactic-forensics/DigOutBox/tree/main/controller/examples)
folder.
27 changes: 16 additions & 11 deletions docs/gui.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,20 +32,21 @@ Unplug and replug the Arduino after installation.

If it still does not work,
open the device manager,
look for the COM port of the Arduino.
and look for the COM port of the Arduino.
The properties of the device, in extras,
will mention that the device needs further installation.
Update the driver by searching the local computer for drivers
where you installed the Arduino IDE.
This path is most likely:
```bash
```
C:\Users\<USERNAME>\AppData\Local\Arduino15\packages\arduino\hardware\avr\1.8.3\drivers
```


## Usage

The easiest usage is to download an installer.
The simplest way to use the GUI is to download an installer
from our [releases](https://github.com/galactic-forensics/DigOutBox/releases).
We provide installers for Windows.
This is especially recommended for air-gapped systems,
since no internet connection is required.
Expand Down Expand Up @@ -75,7 +76,10 @@ The settings and configuration files are by default saved to the following locat

If you encounter issues with the software,
it might be worth deleting these files and restarting the program.
Note that you will lose your configuration and settings if you do so!

!!! warning
If you delete these files,
you will lose your configuration and settings.

The following settings files are used:

Expand Down Expand Up @@ -104,7 +108,8 @@ This file will only be written if it does not exist already.
## First startup

On the first startup,
the standard hardware configuration file are and settings file are written.
the standard hardware configuration file (if not existent)
and settings file are written.
The settings file is written with the default settings.
No channels are configured.
Before you get to the main UI,
Expand All @@ -130,12 +135,12 @@ since no channels are configured.
At the bottom is the statusbar,
which will display messages and menubar tooltips.

!!! note
!!! tip
All buttons and menubar entries have tool tips implemented.
Hover over them to get more information.

Once your channels are configured,
the UI might look something like this:
the user interface might look something like this:

![Main UI with channels](img/gui/main_ui.png)

Expand All @@ -154,8 +159,8 @@ The status indicator has four states:
- Green: The channel is on.
- Red: The channel is off.
- Orange: Some channels in the software group are on, some are off.
This status only applies for software groups
- Grey: The channel state is unknown.
This status only applies to software groups
- Gray: The channel state is unknown.

## Configuration of channels

Expand All @@ -172,7 +177,7 @@ and select which display section "individual" or "grouped" this channel should b
You can add more channels by clicking "Add" and
delete a channel by clicking "Delete".
Pressing cancel will discard all changes.
"Save" check if the configuration is valid and save it.
"Save" checks if the configuration is valid and saves it.

!!! note
Channel names have to be unique,
Expand Down Expand Up @@ -215,7 +220,7 @@ You will be presented with a window like this:

Here you can configure if you want the status of channels to be automatically read
(if so, set the checkbox as in the picture)
and how often (in seconds) this should be done.
and how frequently (in seconds) this should be done.
When you are done, hit "Ok" to save the settings.

## Lockouts
Expand Down
Loading

0 comments on commit d43ae95

Please sign in to comment.