Update docs

README.md

@@ -1,5 +1,8 @@
 # PiScan
 This software can take a Raspberry Pi (or another embedded computer) and turn it into a radio scanner. With only a $40 Pi and a $20 RTL-SDR dongle, you can build an inexpensive scanner with the capabilities of much more expensive equipment (at least that's the goal for this).
+
+![PiScan on a Raspberry Pi](doc/img/pi-deployment.JPG)
+
 ## License
 A license hasn't been selected yet, though it's likely to be GPL - have to make sure there won't be issues down the line when trunking is added
 ## Features
@@ -160,12 +163,10 @@ A scan file can be generated from an `.hpd` file, which is a plaintext format us
 	build/scan/piscan_hpdconv -i <path_to_hpd_file> -o <directory_for_output_file>
 A generator for CSV input will probably come soon, followed eventually by a GUI editor
 ### Interfacing
-The primary way to interact with PiScan is through the [client program](https://github.com/ezratl/PiScan-Client). Guides on its usage can be found there.
+The primary way to interact with PiScan is through the [client program](client/). Guides on its usage can be found there.
 In short, it communicates through a TCP connection, with a default port 1234.
 
-To listen to PiScan's audio feed remotely, use a stream client that supports RTSP, such as VLC, and enter the MRL `rtsp://<host_address>:8554/audio`. Setting a low network caching time is advised to reduce audio latency.
-
-Note: The client is being migrated to this repository to simplify API development. The version in the separate repo is still recommended for now, but it will be deprecated in the next update.
+To listen to PiScan's audio feed remotely without the client, use a stream client that supports RTSP, such as VLC, and enter the MRL `rtsp://<host_address>:8554/audio`. Setting a low network caching time is advised to reduce audio latency.
 
 ## Troubleshooting
 If build errors are occuring with ModemAM.cpp or similar sources, the LIQUID_API_OLD CMake flag needs toggled. Generally it needs to be set to OFF for liquid versions >= 1.3.2, but swapping its value may help in other cases.

client/README.md

@@ -1,42 +1,93 @@
 # PiScan Client
+
 This is the client program used to control the [PiScan software](https://github.com/ezratl/PiScan)
+
 Currently, this repo contains only the cross-platform Python GUI client. Goals for the future include an Android client and an iOS client.
+
 ## Python GUI
 This client is compatible with any system that has a desktop interface supported by Qt (Windows, macOS, Linux)
-To use it, clone this repo in a directory of your choice, then navigate to the `py` directory.
+To use it, navigate to the `py` directory.
+
+**Python 3 is required to run the GUI**
 
 First, install the prerequisites:
 
-	pip3 install -r requirements.txt
+	pip install -r requirements.txt
+
+If you are on Linux, you may also have to install these packages through the system package manager:
+
+	python3-pyside2.qtcore
+	python3-pyside2.qtgui
+	python3-pyside2.qtuitools
+	python3-pyside2.qtwidgets
+	python3-pyside2.qtxml
+	python3-vlc
+
 Then you can run it from there:
 
-	python3 ./client.py
+	python ./client.py
 For the time being, the script needs to be run from the `py` directory, otherwise it will not be able to locate its resource files and fail to run.
 
 The following command options are available:
-`-l`: Bypasses the connect dialog and connects to PiScan on localhost
+
 `-a <host>`: Specify the address of the system where PiScan is running (e.g. localhost). Using this option bypasses the connection dialog.
+
 `-p <port>`: Specify the port to use if it's other than the default (1234). Only necessary in conjunction with `-a`
-`-w`: Starts client maximized with title bar hidden. Intended to be used on a Raspberry Pi with a 3.5inch display
+
+`-s`: Used with previous options. Using this will connect to the RTSP audio stream (default no audio)
+
+`-r`: Used with previous options. Specify the port for the RTSP stream if othern than the default (8554)
+
+`-l`: Bypasses the connect dialog and connects to PiScan on localhost. Audio stream is not automatically connected.
+
+`-w`: Starts client maximized with title bar hidden. Intended to be used in an embedded application such as a Raspberry Pi with a 3.5inch display
+
 ### Interface
 #### Connecting
-The connect dialog will appear on opening, if an address wasn't already specified. Here you can specify an address and port, which by default are localhost and 1234. 
-![Connection dialog](img/client-connect.png)
 
-Once you hit the `Connect` button it will attempt to connect to PiScan. Once successful, you will be presented with the scanner screen.
+The connect dialog will appear on opening, if an address wasn't already specified. Here you can specify an address and port, which by default are localhost and 1234. If `Audio` is checked another text box will appear to specify the port for the RTSP audio stream, which is 8554 by default.
+
+![Connection dialog](doc/img/connect/dialog-audio.png)
+
+Once you hit the `Connect` button it will attempt to connect to PiScan. Once successful, you will be presented with the scanner interface.
 #### Scanning
-![Scanner screen](img/client-idle.png) ![Scanner hold](img/client-hold.png)
 
-Buttons:
-- `Scan`: resumes scanning from a paused state
-- `Hold`: pauses scanning on the currently active channel or whatever channel the scanner is currently checking
-- `Manual`: opens a dialog to manually tune to a frequency
-- `Settings` is disabled; it's a placeholder for functionality that hasn't been implemented
+![Scanner interface](doc/img/scan/interface-labeled.png)
+
+Left sidebar:
+
+1. Disconnect session: Will disconnect you from the PiScan server and return you to the connection dialog
+2. Volume slider and mute button: Adjusts volume if audio is enabled. Will be hidden if the audio stream is not connected.
+
+Control Buttons:
+
+3. Scan: resumes scanning from a paused state
+4. Hold: pauses scanning on the currently active channel or whatever channel the scanner is currently checking
+5. Manual: opens a dialog to manually tune to a frequency
 
 Right sidebar:
-- The squelch slider's range is set by the PiScan it's connected to. By default, the value will be in dBm
-- The gain slider sets the tuner gain. The default it automatic gain, but can be set in a range of 0-50
-- The grey button left of the sliders will collapse/open the sidebar, to hide the sliders when they are not needed
+
+6. The gain slider sets the tuner gain. The default it automatic gain, but can be set in a range of 0-50. The current value is displayed top left of the slider.
+7. The grey button left of the sliders will show or hide the sidebar, to hide the sliders when they are not needed.
+8. The squelch slider's range is set by the PiScan it's connected to (depending on the configured squelch method). By default, the value will be in dBm. The current value is displayed top left of the slider.
+
+#### Monitoring
+
+![Scan hold interface](doc/img/hold/interface-labeled.png)
+
+1. Title bar: "Scanning" will be displayed while actively scanning, the entry index and entry tag will be displayed while paused. Useful if the client is minimized.
+2. The index of the current entry in a `[system number]-[channel number]` format. Will display `MAN` when in manual tuning mode.
+3. The tag of the current entry's system.
+4. The tag of the current entry
+5. The current tuned frequency being monitored
+6. The modulation of the entry - will display the entry's code if a code squelch is used (PL tone for example)
+7. The strength of the signal on the frequency being monitored, relative to the signal floor and ceiling
+
 #### Manual Entry
 The dialog gives a text field to enter a frequency in MHz, as well as a drop down containing the modulations supported by the connected PiScan instance. Clicking `Tune` will request PiScan to tune to the manual channel you specified. If all the parameters are valid, it will hold and monitor the manual channel.
-![enter image description here](img/client-manentry.png)
+
+![Manual entry dialog](doc/img/manentry/dialog.png)
+
+Once tuned, channel will appear as a regular entry with index `MAN`, system `Manual` and tag `Manual entry`, as well as the selected frequency and modulation.
+
+![Manual entry monitoring](doc/img/manentry/receive.png)

client/py/requirements.txt

@@ -1,2 +1,3 @@
 PySide2
 protobuf
+python-vlc