Updated readme
This commit is contained in:
Ezra Taimuty-Loomis
parent
b289b73627
commit
e6a8f9df37
176
README.md
176
README.md
|
|
@ -1,57 +1,161 @@
|
|||
# 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).
|
||||
### Features
|
||||
## 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
|
||||
- System scanning
|
||||
* Traverses through a list of frequencies incrementally
|
||||
* Traverses through a JSON list of frequencies
|
||||
* Sorts channels into chunks of bandwidth to maximize scanning performance
|
||||
- Manual frequency entry
|
||||
- rtl_fm based demodulator
|
||||
- CubicSDR-based demodulator (built on liquid-dsp)
|
||||
- Configurable squelch and tuner gain
|
||||
- Configurable logging
|
||||
- Remote control through TCP
|
||||
- Remote monitoring with RTSP
|
||||
|
||||
### To-Do
|
||||
#### Short-term:
|
||||
- More efficient scanning (currently can only scan 15 channels/second)
|
||||
* Modify/rewrite the demodulator to support channelization
|
||||
* Rewrite scanning algorithm to group frequencies into sections of bandwidth (as opposed to retuning the dongle for each frequency)
|
||||
- TCP support
|
||||
* The GUI client will use this to allow remote control of the software
|
||||
## To-Do
|
||||
#### Short-term (before the first beta):
|
||||
- Replace TCP connection with WebSockets and possibly HTTP
|
||||
- CTCSS, DCS support
|
||||
- AM demodulation
|
||||
- Run-time manipulation of scan database and config
|
||||
- Temporary channel lockout
|
||||
- SDR configuration
|
||||
#### Long term:
|
||||
- P25 trunking
|
||||
- DMR trunking
|
||||
## Setup
|
||||
- Broadcastify interfacing
|
||||
|
||||
## System requirements
|
||||
- Linux OS - Debian or Ubuntu based distros recommended (untested on other distros)
|
||||
- CPU with 2+ cores
|
||||
* ARM: will work on at least an RPi 2B (900MHz BCM2836)
|
||||
* x86: should run well on most modern low-power CPUs, has been tested on dual-core Atom-class processors without maxing out the CPU
|
||||
- RAM: memory usage hasn't been officially profiled, but at least 256MB is probably a sufficient minimum
|
||||
- Disk space: 10MB is sufficient for the source, binaries, and data files, but more space will be needed depending on the verbosity you choose for the logfiles.
|
||||
- Additional Raspberry Pi notes
|
||||
* At least a small heatsink on the SoC is necessary, since the CPU will be under load for extended periods
|
||||
* Sufficient power delivery is required (the official power adapter for example) - power issues will cause the CPU to downclock resulting in poor performance
|
||||
## Setup - Build from Source
|
||||
PiScan is supported and has been tested on Debian-based systems (including Raspbian and Ubuntu).
|
||||
|
||||
### Prerequisites
|
||||
The following packages need to be installed, if not already:
|
||||
|
||||
g++
|
||||
git
|
||||
build-essential
|
||||
cmake
|
||||
libboost-all-dev
|
||||
libliquid1d, libliquid-dev
|
||||
libsoapysdr-dev, soapysdr-module-rtlsdr
|
||||
librtlsdr0
|
||||
libpulse-dev, libasound2-dev, libjack-dev
|
||||
protobuf-compiler, libprotoc-dev
|
||||
libssh-dev
|
||||
|
||||
### Initializing
|
||||
In a terminal, download the source with the command:
|
||||
|
||||
# install dependencies
|
||||
sudo apt install -y cmake g++ build-essential librtlsdr0 librtlsdr-dev libusb-1.0-0-dev
|
||||
git clone https://github.com/ezratl/PiScan
|
||||
cd PiScan
|
||||
git submodule update --init --recursive
|
||||
# create the program directories:
|
||||
# ./build will be the executable is compiled
|
||||
# ./data will contain the user files
|
||||
mkdir build data
|
||||
# run cmake
|
||||
cd build
|
||||
cmake ../src -DDETACH_KERNEL_DRIVER=ON
|
||||
# build executables
|
||||
make all
|
||||
You can now run PiScan from the build directory:
|
||||
git clone https://github.com/ezratl/PiScan
|
||||
Then configure the environment:
|
||||
|
||||
./piScan_backend | aplay -r 12000 -f s16_le -t raw -c 1
|
||||
sh ./bootstrap.sh
|
||||
There are three options available for audio output: PulseAudio, ALSA, and JACK. Your preference can be set by running one of the following commands from the `build` directory:
|
||||
|
||||
cmake ../src -DUSE_AUDIO_PULSE=ON
|
||||
cmake ../src -DUSE_AUDIO_ALSA=ON
|
||||
cmake ../src -DUSE_AUDIO_JACK=ON
|
||||
By default PulseAudio is selected, however ALSA seems to use less CPU on the RPi
|
||||
|
||||
Additionally, some versions of liquid have a different API, resulting in build errors in the "Modem" files of the `cubic` module. If that happens, try running this from `build`:
|
||||
|
||||
cmake ../src -DLIQUID_API_OLD=ON
|
||||
### Building
|
||||
Once the environment is properly configured, `cd` into `build` and build the LiveMedia library:
|
||||
|
||||
make live555
|
||||
If the build fails: If you are building in a shared folder in a VM on a Windows host, you must download and extract the Live sourcefiles manually into `src/external/live` and run the command below before trying again. This is due to Windows not playing nicely with permissions and symbolic links
|
||||
|
||||
cmake ../src -DHGFS=ON
|
||||
Now you can build PiScan:
|
||||
|
||||
make all
|
||||
Alternatively, you can build the binaries individually if you don't need all of them
|
||||
|
||||
make piScan_backend # main program
|
||||
|
||||
make piscan_hpdconv # tool to convert Uniden Sentinel files to PiScan files
|
||||
### Running
|
||||
For now, you have to be in the `build` directory to run the program. In the future there will be an install command to eliminate the need for this.
|
||||
You can now run PiScan from the command line:
|
||||
|
||||
./piScan_backend
|
||||
See **Usage** for more information on command arguments and setting up the data files
|
||||
|
||||
|
||||
## Usage
|
||||
Keep in mind this project is still in alpha in terms of completeness, so it's very likely to break if it isn't used correctly. With that being said, it's best to keep a task manager or second terminal open so you have a way to kill the program if it locks up.
|
||||
### Command Arguments
|
||||
`-v [0-9]`: stderr log verbosity. Note this does not effect generated logfiles
|
||||
`-f [0-9]`: Logfile verbosity - overrides saved config
|
||||
`-d`: Run with debug interface. This is very user-unfriendly, so interfacing through the client program is recommended
|
||||
`-p [path]`: load data from `path` rather than the default directory. Helpful for running multiple PiScan instances
|
||||
### Config and Data
|
||||
All data used by PiScan is stored in its working directory (this is the `data` directory for alpha builds). It contains a few JSON files as well as a folder for logfiles.
|
||||
- `config.json` contains all settings that can be modified by the user
|
||||
- `state.json` is used by the program to maintain its stately data between runs
|
||||
- `systems.json` contains the scan database - more on what that looks like below
|
||||
On the first run of PiScan, these files likely won't exist. It will continue running with default parameters, and a config and state file will be generated with these defaults when the program ends.
|
||||
If there is no scan file, PiScan cannot scan so it will instead hold at 100MHz. It will not allow the user to scan, but will allow manual frequency tuning.
|
||||
#### Scan Database File
|
||||
`systems.json` MUST adhere to this format for PiScan to read it correctly
|
||||
|
||||
For the software to run, you first need a file containing the frequencies to scan. Currently it only uses favorites lists generated by the Uniden Sentinel software (I will create a data format eventually, but this was the quickest route to achieve data input). To get a favorites list file go to `Documents/Uniden/BCDx36HP/FavoriteLists` where you will find the desired list as a plaintext `.hpd` file (on a Windows machine). Either by using scp or copying to a flash drive, save that file to the Linux system as `(PiScan directory)/data/list.hpd`. The list should contain some amount of conventional frequencies, as the software currently only handles those and will ignore any trunked entries.
|
||||
At this point, you can make sure an RTL dongle is connected to the system and run PiScan with
|
||||
{
|
||||
"systems": [
|
||||
{
|
||||
"systype": "analog", <- available types: analog
|
||||
"tag": "Sample System",
|
||||
"lockout": false, <- persistent system lockout
|
||||
"channels": [
|
||||
{
|
||||
"tag": "FM entry - CSQ",
|
||||
"lockout": false, <- persistent channel lockout
|
||||
"delay": 2000, <- scan resume delay in milliseconds
|
||||
"freq": 453150000, <- frequency in Hz
|
||||
"chantype": "fmc" <- available types: fmc, amc, plc, dcc
|
||||
},
|
||||
{
|
||||
"tag": "FM entry - PL",
|
||||
"lockout": false,
|
||||
"delay": 2000,
|
||||
"freq": 471837500,
|
||||
"chantype": "plc",
|
||||
"tone": "103.5" <- stored as string rather than a float
|
||||
},
|
||||
{
|
||||
"tag": "FM entry - DCS",
|
||||
"lockout": false,
|
||||
"delay": 2000,
|
||||
"freq": 460287500,
|
||||
"chantype": "dcc"
|
||||
"code": "023" <- stored as string rather than an int
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Do note that since PL and DC squelch are not yet supported, they will be squelch like a CSQ channel.
|
||||
|
||||
./piScan_backend | aplay -r 12000 -f s16_le -t raw -c 1
|
||||
### Command line arguments
|
||||
PiScan has the following arguments:
|
||||
-v [0-9]: Set the logging verbosity. The default level is 0. Everything above level 3 is basically for debugging and will flood the terminal.
|
||||
### Console input
|
||||
By default, the software accepts input from the console (which is set up to run as a client connection) for debugging purposes. This will eventually be made optional once support for TCP clients is added. Type `help` for a list of available commands.
|
||||
A scan file can be generated from an `.hpd` file, which is a plaintext format used by Uniden Sentinel to store favorites lists on a PC - this can be found in `Documents/Uniden/BCDx36HP/FavoriteLists`. To generate, run:
|
||||
|
||||
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.
|
||||
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.
|
||||
## Disclaimer
|
||||
This is a personal project; it lacks both the design standards and testing standards of commercially-built software, meaning no guarantees can be made of its reliability. Use at your own risk.
|
||||
|
||||
Do not expose the ports used by this software directly to the internet! The TCP connection has no security whatsoever, and although a more secure replacement is planned, the robustness of the software has not been tested.
|
||||
|
|
|
|||
Loading…
Reference in New Issue