From 3a4c391b077557b40204706e3e125f678b1e4596 Mon Sep 17 00:00:00 2001 From: Tom Early Date: Fri, 18 Jan 2019 16:11:15 -0700 Subject: [PATCH] Documentation --- ACKNOWLEDGEMENTS | 3 + BUILDING | 193 --------------------------------------- CONFIG+INSTALL | 155 +++++++++++++++++++++++++++++++ DTMF+REMOTE+VOICE.README | 18 +--- ITAP.README | 83 ----------------- CONFIGURING => OPERATING | 4 +- qnadmin | 3 + 7 files changed, 168 insertions(+), 291 deletions(-) delete mode 100644 BUILDING create mode 100644 CONFIG+INSTALL delete mode 100644 ITAP.README rename CONFIGURING => OPERATING (98%) diff --git a/ACKNOWLEDGEMENTS b/ACKNOWLEDGEMENTS index 686dcff..bbe8892 100644 --- a/ACKNOWLEDGEMENTS +++ b/ACKNOWLEDGEMENTS @@ -5,6 +5,9 @@ QnetGateway uses IRCDDB software written by Michael Dirska, DL1BFF. Both Scott a version 2 of the GNU General Public License. The current form of QnetGateway would be completely impossible without Scott and Michael's contribution. Thank you for a great starting point of this current project! +Some parts of are also inspired from ircDDBGateway by Jonathan Naylor, G4KLX and his copyright appears in those files +that used his ideas. The TCPReaderWriterClient is copied in whole. Thanks Jonathan! + QnetGateway continues to be published under Version 2 of the GNU General Public License, see the LICENSE file. Tom diff --git a/BUILDING b/BUILDING deleted file mode 100644 index 5d5943a..0000000 --- a/BUILDING +++ /dev/null @@ -1,193 +0,0 @@ -Creating a hotspot based on a Raspberry Pi or a BeagleBone Black that can connect to -XRF and DCS reflectors as well as XREF reflectors based on QnetGateway software is -easy. - -Start with a Raspberry Pi with the latest Raspbian image (see http://raspberrypi.org) -or most any other computer with the latest Debian-based image. For this latest version -of QnetGateway requires the c++ compiler of at least version 4.9. - -Even if you are building an MMDVMHost-based hot-spot, the executables and their -source code are very small, so you can get away with a system with minimum storage -capacity. We have build gui-less versions on two gigabyte partitions! You don't need -to overclock the RPi for QnetGateway, the default clock rate is just fine. - -If you are using a DVAP Dongle or a DVRPTR_V1, or connecting to an Icom Terminal and -Access Point enabled radio,login and plug in your device to see if the OS is -recognizing it. The kernel should auto load drivers and you will see that with the -"lsusb" command. The DVAP and the Icom radio digital-to-serial cable uses a FTDI chip -and the DVRPTR uses Atmel. If you don't see an approprite output from "lsusb" after -your device is plugged in, you need to enable it by executing: - -sudo depmod -sudo modprobe - -where YOURDEVICEMODULE is "ftdi_sio" for the DVAP or is "cdc_acm" for the DVRPTR. -After a reboot you should see the device in the "lsusb" list. If you don't see -the device listed, QnetGateway software will never be able to open it either. - -You will need several packages to build the QnetGateway gateway. You will probably -already have all or most of these but it still doesn't hurt to be sure: - -sudo apt-get update -sudo apt-get upgrade -sudo apt-get install make g++ unzip git - -If you are building a QnetGateway + MMDVMHost system, please use the instructions -in the MMDVM.README file. If you are building a QnetGateway for an Icom repeater, -you'll need to switch branches of this repository after downloading it (see below): - -git checkout lastudp - -Then you can use the qn.icom.cfg configuration file as a starting point for your -configuration. - -If you are building a QnetGateway for a DVAP or a DVRPTR_V1 read on... - -git clone git://github.com/n7tae/QnetGateway.git - -This will create a QnetGateway directory with everything you need to build a dvap or -dvrptr ircddb gateway. - -The first thing to do is change to the build directory with "cd QnetGateway" and then -choose a target to make. There are targets for each of the supported devices: -. "make itap" will build all programs needed for Icom Terminal mode. -. "make dvap" will build all programs needed for the DVAP Dongle. -. "make dvrptr" will build all programs needed for the DVRPTR_V1. -. "make mmdvm" will build all programs needed for MMDVMHost support. (You need - to download and build MMDVMHost separately, see the MMDVM.README file for more info. -. "make" will build all the QnetGateway executables. This is useful if you are - experimenting around with lots of different devices. - -Next, create your qn.cfg configuration file. Use the menu-driven configuration -script. Type: - -./configure - -You can configure up to three different modules: a, b and/or c. - -The configure script will show you the default values of every parameter the -QnetGateway programs use. In most cases, the defaults are just fine and you don't -need to override them with your own values. Mostly you need to specify you callsign -for the IRC login, specify at least one module and most users will want to enable -the D-Plus legacy authorization. For a DVAP Dongle or a DVRPTR V1, there are some -parameters that must be specified, like the serial number. After you are happy with -your configuration, be sure to write it out. After you install and try out your -system, you may find that you need to change some configuration values. In that -case just start the configure script again. It will read the current qn.cfg file -when it start. - -Of course, you can always build your own qn.cfg file. There are three example for -you to look at: -. qn.everything.cfg contains all parameter with comments about what - each parameter does. The definitions that are commented out are defined with - their default value. -. qn.dvap.cfg is the simplest possible configuration for a 2m DVAP. If you have - a 70cm DVAP rename the module to "b" and change the frequency. -. qn.mmdvm.cfg is the starting place for configuring an MMDVMHost repeater. Be sure - the module assignment agrees with the module configured in your MMDVM.cfg file. -. qn.itap.cfg is a simple configuration file for Icom's Terminal and Access Point - Mode. Please read ITAP.README for more information. - -Remeber the 'everything' file file contain detailed comments about all of -the values you can set. Just read through it and edit accordingly. In the end you will -need a configuration file called "qn.cfg". - -Additional information about the configuration as well as other important and -useful features are also in the CONFIGURING file. - -Authorization to the the Trust DPlus system is first obtained by registering, -see www.dstargateway.org for instructions. Once registered, make sure to enable -it in you software, please see the "dplus" section in the example cfg files. -By default DPlus authorization is off. When you turn it on, the authorizing server -will provide QnetLink with a list of REF reflectors and repeaters on the DPlus -system. In the "dplus" section of you qn.cfg file, you have control over which -systems you want added to your gwy database. Your gwys.txt file is read AFTER -DPlus authorization so any entries their will over-write REF any downloaded -from the DPlus authorization server. - -The information downloaded from the DPlus server is dynamic and will change -from hour to hour. You can update QnetLink by sending " F" to your system. -This will purge the current table and re-authorize with the DPlus server and -then reload gwys.txt. - -Because of the way DPlus authorization works, QnetLink can't actually confirm -that the authorization was successful. If your system is unlinked after trying -to transmit into a DPlus system, it means that your authorization was -unsuccessful. This might indicate that their may be a problem with your -DPlus registration. - -The gwys.txt file is the internet address and port numbers for any gateway you -would like your ircddb gateway to be able to connect to. The one delivered with -this package is special: It has only DCS reflectors, X-reflectors and DStar -reflectors and the X-reflectors are configured with the 20001 port instead of the -default 30001 prot. This will allow you to connect to these XREF reflectors without -creating any port-forwarding rules on your home router. You will also want to move -X-reflectors to port 20001 if you are going to tether you device via WiFi to a -smart-phone for internet access. Most phone companies will not let you configure -port-forwarding rules on you phone internet account. If you operate behing a -router/firewall without port forwarding in place, you will not be able to -do most callsign routing techniques discussed in CONFIGURING.txt, but you should -still be able to connect to reflectors. You will be able to route to the new -smart-group-server if you are mobile. They have solved the "mobile routing -problem"! - -There are MANY OTHER gateways to which you can connect. Executing get_gwys_list.sh -will download a HUGE list of reflectors and gateways from www.va3uv.com with port -address that may need port-forwarding to your sytem. - -There is another script, reflist.sh, that will download REF, XRF and DCS reflectors -from another source. This is probably the preferred method to getting a gwys.txt -file. This source is extremely up-to-date, and it also contains the DPlus REF -reflectors. If you want to use data from the DPlus authorization server, be sure -to remove any REF definitions that might over-write DPlus entries. - -Based on the above discussion, execute either "./reflist.sh" or "./get_gwy_list.sh" -and then edit it to your needs. - -If you plan on using DTMF, you need to copy "qndtmf.sh" to "qndtmf". This is the -file that interprets dtmf command and executes them. As supplied, it parses the -DTMF string and executes a QnetRemote command to perform linking and unlinking -and other useful tasks. It is a /bin/bash script so you can modify it! You can -change the commands or create new commands. - -You are now ready to install your QnetGateway system. If you are installing an -MMDVM-based system, follow the instructions in MMDVM.README. - -If you are installing Icom's Terminal and Access Point mode, please follow the -instructions in ITAP.README. - -To install either DVAP or DVRPTR_V1, type "sudo make installdvap" or "sudo make -installdvrptr", respectively. If you are installing on an Icom repeater, type -"sudo make installicom". This should get you up and running. It will take a few -minutes for QnetGateway to get fully connected to the IRCDDB network. - -Finally, if you want/need DTMFS, type "sudo make installdtmfs". - -The service scripts in /lib/systemd/system and everything else in /usr/local: -The executables will be in /usr/local/bin and the qn.cfg file and other data -will be in /usr/local/etc. Please note that the qn.cfg file and the gwys.txt -file are actually symbolic links and point back to the files you created in -the build directory. So if you want modify them later, modify the files in the -build directory. - -If you are having trouble connecting, use journalctl to view the log output -of each process. "sudo journalctl -u will show the log from that -service. The QnetGateway service is qngateway, QnetLink is qnlink, QnetDVAP is -qndvap and QnetDVRPTR is qndvrptr. - -The beginning of each log file will report the values of all the configuration -parameters (even the ones you didn't specify in qn.cfg) and after that -you will see the verbose reports of what each service is doing. These logs are -invaluable for traking down problems with your qn.cfg file. You can see in real -time what is being added to the logs during operation appending "-f" to the -journalctl command. - -You can clean up the build directory of intermediate *.o files, *.d file and the -executables with "make clean". - -If you want to uninstall everything return to the build directory and type -"sudo make unistalldvap", "sudo make uninstalldvrptr" or "sudo make uninstallicom" -and possibly "sudo make uninstalldtmfs". This will shutdown the services and -remove the service scripts and everything from /usr/local. - -Tom Early, n7tae (at) arrl (dot) net diff --git a/CONFIG+INSTALL b/CONFIG+INSTALL new file mode 100644 index 0000000..b26829f --- /dev/null +++ b/CONFIG+INSTALL @@ -0,0 +1,155 @@ +Creating a hotspot based on a Raspberry Pi or a BeagleBone Black that can connect to +XRF and DCS reflectors as well as XREF reflectors based on QnetGateway software is +easy. + +Start with a Raspberry Pi with the latest Raspbian image (see http://raspberrypi.org) +or most any other computer with the latest Debian-based image. For this latest version +of QnetGateway requires the c++ compiler of at least version 4.9. + +Even if you are building an MMDVMHost-based hot-spot, the executables and their +source code are very small, so you can get away with a system with minimum storage +capacity. We have build gui-less versions on two gigabyte partitions! You don't need +to overclock the RPi for QnetGateway, the default clock rate is just fine. + +If you are using a DVAP Dongle or a DVRPTR_V1, or connecting to an Icom Terminal and +Access Point enabled radio, login and plug in your device to see if the OS is +recognizing it. The kernel should auto load drivers and you will see that with the +"lsusb" command. The DVAP and the Icom radio digital-to-serial cable uses a FTDI chip +and the DVRPTR uses Atmel. If you don't see an approprite output from "lsusb" after +your device is plugged in, you need to enable it by executing: + +sudo depmod +sudo modprobe + +where YOURDEVICEMODULE is "ftdi_sio" for the DVAP or is "cdc_acm" for the DVRPTR. +After a reboot you should see the device in the "lsusb" list. If you don't see +the device listed, QnetGateway software will never be able to open it either. + +You will need several packages to build the QnetGateway gateway. You will probably +already have all or most of these but it still doesn't hurt to be sure: + +sudo apt-get update +sudo apt-get upgrade +sudo apt-get install make g++ unzip git + +If you are building a QnetGateway + MMDVMHost system, please use the instructions +in the MMDVM.README file in order to setup and start your MMDVMHost. + +If you are building a QnetGateway for an Icom repeater, you'll need a different +git repository. Please look for QnetICOMGateway. + +If you are building an MMDVM, DVAP, DVRPTR_V1 or an ICOM Terminal mode gateway, +start by cloning this repository. + +git clone git://github.com/n7tae/QnetGateway.git + +This will create a QnetGateway directory with everything you need to build your +Gateway system. + +The first thing to do is change to the build directory with "cd QnetGateway" and then +define and create your configuration file, qn.cfg: + +./qnconfig + +This will start a menu driven script. In this mode, only the most common, useful +parameters are available. If you want access to absolutely every parameter use: + +./qnconfig expert + +Please be sure you know what you are doing if you change these normally hidden parameters. +The configuration script will show you the default value for a parameter. For most cases +the default value is fine, so your qn.cfg file will usually be rather small. + +At a minimum, you need to specify an IRCDDB login (please use your legal callsign) and +at least one module. By convention, specify a 23cm module on A, a 70cm module on B and +a 2M module on C. QnetGateway supports a maximum of three modules. + +The configure script will show you the default values of every parameter the +QnetGateway programs use. In most cases, the defaults are just fine and you don't +need to override them with your own values. If you need to override the default value, +the general method is to type the key followed by the new value. If you want to delete +an overridden value, type a "u" followed by the key you want to unset. Boolean values +(true or false) can be toggled by just entering the key. + +For a DVAP Dongle or a DVRPTR V1, there are some parameters that must be specified, +like the serial number. The two "inverse" parameters for the DVRPTR will probably +have to change. If you don't hear traffic on a connected system, try toggling the +dvrptr_inverse_rx parameter. If you aren't heard, toggle the dvrptr_inverse_tx +parameter. + +If you want to use the closed-source, legacy D-Plus reflectors and repeaters, you +need to make sure you are authorized to use those systems. They require that you +are a registered user, see www.dstargateway.org for more information. If you are +a registered user, you can enable QnetGateway to used this closed-source system +by DPlus. By default, when QnetLink registers your callsign you will download +both repeaters and reflectors. You can control this with configuration parameters. +You can also control the priority of D-Plus reflectors and repeaters. By default, +QnetLink first loads the legacy systems first (if enabled) and then the systems +in your gwys.cfg file. Since XLX systems can be linked as REF or XRF reflectors, +there can be name collisions and the last read system will overwrite any previous +system. By setting the dplus_priority to true, the legacy D-Plus systems will be +read after your qn.cfg file. + +The information downloaded from the DPlus server is dynamic and will change +from hour to hour. You can update QnetLink by sending " F" to your system. +This will purge the current table and re-authorize with the DPlus server and +then reload gwys.txt. + +Because of the way DPlus authorization works, QnetLink can't actually confirm +that your authorization was successful. If your system is unlinked after trying +to transmit into a DPlus system, it means that your authorization was +unsuccessful. This might indicate that their may be a problem with your +DPlus registration. + +If you want to see what's going on inside the programs, there are logging options +available that will cause a lot more log entries. These extra entries can be +useful if you are trying to track down problems with your system. + +After you are happy with your configuration, be sure to write it out with the 'w' +key in the main menu. It will show you your qn.cfg file after it writes it out. +After you install and try out your system, you may find that you need to change +some configuration values. In that case just start the configure script again. +It will read the current qn.cfg file when it start and initialize the menus +accordingly. + +Of course, you can always build your own qn.cfg file. There are three example for +you to look at: +. qn.everything.cfg contains all parameter with comments about what + each parameter does. The definitions that are commented out are defined with + their default value. +. qn.dvap.cfg is the simplest possible configuration for a 2m DVAP. If you have + a 70cm DVAP rename the module to "b" and change the frequency. +. qn.mmdvm.cfg is the starting place for configuring an MMDVMHost repeater. Be sure + the module assignment agrees with the module configured in your MMDVM.cfg file. +. qn.itap.cfg is a simple configuration file for Icom's Terminal and Access Point + Mode. Please read ITAP.README for more information. + +Once you have your qn.cfg file, your ready to compile and install your system, type: + +./qnadmin + +The first thing you want to do is to create your gwys.txt file. use the 'gw' key +to get into that sub-menu. There are several choices to initialize your gwys.txt +file. Choose one and then you can edit the file to your satisfaction. + +You are now ready to install your QnetGateway system. If you are installing an +MMDVM-based system, follow the instructions in MMDVM.README to get MMDVMHost +up and running. + +Now, you can compile and install your system with the 'is' key. qnadmin will +use your qn.cfg file to figure out what needs to be compiled and how it is to +be installed. + +If you plan on using DTMF, use the 'id' key to install it. Once you install +something, the qnadmin will dynamically change and show you how to uninstall the +installed items. + +The maintenance sub-menu accessed with the 'm' key will let you stop and start +different programs in your installed package. Note that this just uses +systemctl to start and stop a service. It will not uninstall the service. +You might want to do this if you have changed your configuration file. + +The log sub-menu accessed with the 'l' key can be use to put a "tail" on different +log files and you can watch a log file in real-time. + +Tom Early, n7tae (at) arrl (dot) net diff --git a/DTMF+REMOTE+VOICE.README b/DTMF+REMOTE+VOICE.README index 7e62400..73b61e9 100644 --- a/DTMF+REMOTE+VOICE.README +++ b/DTMF+REMOTE+VOICE.README @@ -4,19 +4,12 @@ DTMF is available with the QnetGateway Software. You can do things like linking and unlinking from you radio's keyboard, if present. For example, typing "B75703" should link you to XRF757 C. -DTMF is not enabled by default. To enable it, first create a DTMF script called -"qndtmf" in the build directory. A complete, functional script is included -and is called "qndtmf.sh", so you can start by just copying it to the target: +DTMF is not enabled by default. You can install and uninstall it from the +qnadmin script. -cp qndtmf.sh qndtmf - -Then you can install DTMF: sudo make installdtmf - -To uninstall DTMF: sudo make uninstalldtmf - -Be sure to look at the script. It contains examples of all the DTMF commands it -supports. You can add more if you are good at shell programming and understand -how qnremote works. +Be sure to look at the 'dtmf' script. It contains examples of all the DTMF +commands it supports. You can add more if you are good at shell programming +and understand how qnremote works. ######## QnetRemote ######### @@ -89,4 +82,3 @@ sudo cp ./id.dat /usr/local/etc That way, when you pull down a new release and build and install it, you can quickly update the voice messages with your own. - diff --git a/ITAP.README b/ITAP.README deleted file mode 100644 index 3165fbb..0000000 --- a/ITAP.README +++ /dev/null @@ -1,83 +0,0 @@ - - Building QnetGateway support for Icom's Terminal and Access Point Mode - - Copyright (C) 2018 by Thomas A. Early N7TAE - -I'll assume you'll be doing this on a Raspberry Pi, but any modern Debian-based -system should work. It just needs a g++ compiler with version greater than 4.9. -These instructions assume you have configured your system with the locale, keyboard -and time zone. When choosing locale, always choose a "UTF-8" version of your -locale. And make sure you do "sudo apt-get update && sudo apt-get upgrade" before -your start. On a Raspberry Pi, you can do all of this with the configuration menu: -"sudo raspi-config". - -1) Install the only external library you need: sudo apt install libconfig++-dev - Yeah! No wxWidgets! - -2) From your home directory, clone the QnetGateway software: - git clone git://github.com/n7tae/QnetGateway.git - -3) Get into the build directory: cd QnetGateway - -4) Then compile: make itap - If you are building on a multi-core computer, don't forget the -j option! - On a Raspberry Pi 2 or 3, use "-j4". Sorry, a Raspberry Pi Zero or a Beagle - Bone Black just has a single core. - -5) You need a configuration file called qn.cfg for QnetGateway. A good, nearly - working config file is qn.itap.cfg. Copy it to qn.cfg and edit it. The default - device for the Icom digital cable is "/dev/ttyUSB0". If you have muliple - USB devices on your system the device might end up somewhere else. Do "ls /dev" - before and after plugging in your cable to figure out where it is. If it's - not on /dev/ttyUSB0, uncomment the device line and put in the correct device. - If you are planning on linking to a Trust DPlus (REF) reflector or repeater, - please look over the "dplus" section to enable this. You need to already be - registered (www.dstargateway.org) to do this. - -6) You need a gwys.txt file for all the systems to which you may wish to link. - If you want to be able to link to repeaters: ./get_gwy_list.sh - If you are only interested in linking to reflectors: ./reflist.sh - This will download and format your gwys.txt file. If the reflector(s) or - repeater(s) you use most often are not present in the gwys.txt file, you can - add them manually, using the same syntax as the existing entries, at the end - of the file. If you find you can no longer connect to a system, it may be - because its IP address has changed. You can execute either script again, copy - it to /usr/local/etc, and then: either reboot you system, or put " F" in - your URField and key your radio, or: sudo systemctl restart qnlink - -7) Now it's time to get the Icom radio ready. Plug in the digital cable to the - radio and use the approprite cable to connect to your hot-spot. Turn on the - radio and press the menu key and go to the "DV Gateway" menu item and press - the enter key and select either Access Point or Terminal mode. If you select - Access Point, adjust the frequency in the usual way. - - If you are using Access Point mode, you'll probably want to turn down the - volume and disable other audio prompts from the radio that is operating - as an access point. Please refer to the Icom manual to do this. - - Please note that Access Point Mode is a work in progress. There are still - significant performance issues, especially when the radio in AP Mode is - transmitting. It is usable, but just barely. Terminal Mode works well. - -8) We have a gwys.txt file and a qn.cfg in the build directory, so we are ready - to install and start the three QnetGateway services: sudo make installitap - - You should be up and running now! Congratulations! - -9) You can see the log of any of the 3 services that make up the QnetGateway - system: - sudo journalctl -u qngateway -f - sudo journalctl -u qnlink -f - sudo journalctl -u qnitap -f - - You can do all three of these in one terminal window (that you can detach from!) - by using "screen": sudo apt install screen - If you don't know how to use screen: http://aperiodic.net/screen/quick_reference - Being able to detach from a screen session is very useful, especially if you are - operating "headless"! - -10) DTMF is _not_ enabled by default if you want it, you need to do two things: - First, create a working DTMF script. In the build directory: cp qndtmf.sh qndtmf - Then, install the DTMF service: sudo make installdtmf - You should be good to go, The DTMF command "00" should announce the linked - status of you module. See DTMF+REMOTE.README for more information. diff --git a/CONFIGURING b/OPERATING similarity index 98% rename from CONFIGURING rename to OPERATING index 32a9b12..30529c3 100644 --- a/CONFIGURING +++ b/OPERATING @@ -84,10 +84,10 @@ YRCALL=_ _ _ _ _ _ _E 2) For Voice Mail: YRCALL=_ _ _ _ _ _ S0 -The above command will Store/create voice mail in the dvtool file +The above command will Store/create voice mail in a proprietary file x_voicemail.dat. YRCALL=_ _ _ _ _ _ R0 -The above command will Recall/playback voice mail from the dvtool file +The above command will Recall/playback voice mail from the recorded file x_voicemail.dat. YRCALL=_ _ _ _ _ _ C0 The above command will Clear/delete voice mail. File x_voicemail.dat will be diff --git a/qnadmin b/qnadmin index 51c94b4..46c68b5 100755 --- a/qnadmin +++ b/qnadmin @@ -496,6 +496,9 @@ while [[ "$ans" != q* ]]; do elif [[ "$ans" == us* ]]; then InstallSystem un elif [[ "$ans" == id* ]]; then + [ ! -e qndtmf ]; then + cp qndtmf.sh qndtmf + fi sudo make installdtmf elif [[ "$ans" == gw* ]]; then GatewayMenu