Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
DTMF decoder and RadioChannel Quality tool for D-STAR http://villazeebries.krbonne.net/hams…
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
D-STAR DTMF decoder / Radio-Channel Quality logger * Introduction: The original inspiration for this program grew out of the idea of using DTMF-codes to control certain aspects of a D-STAR repeater. Althou DTMF is very common on analog FM-repeaters, it use on D-STAR repeaters has sofar been as good as unexisting. This is probably much related to the fact that D-STAR linking is controlled by using the "yourcall" setting, unlike echolink or IRLP on analog repeaterswhich you DTMF codes. This program is written as a "proof of concept" to show that DTMF-decoding on D-STAR is possible and to allow people to experiment with it. As most open-source application, this application is largly based on code written by other people. Most of it comes from the program "ircDDB-mheard" written by MMichael DL1BFF. As the program-code of Michael did not just allow the extracting DTMF- information. It also provided statistics on the BER (Bit Error Rate) and the number of "silence frames" inside the DV-stream. It soon became clear that this application could also be used for other purposes then just DTMF-decoding and, hence, "DMTF" application became "DTMF-RCQ". (RCQ means "Radio Channel Quality") Later, program-code was added to monitor missing frames in the DV-stream. * Use This application is based on a trick used by quite some D-STAR application: it monitors the traffic that is send on the ethernet-interface between the I-com gateway controller and the I-com gateway server and decodes the D-STAR DV-stream as it goes by. That way, it is able to detect DTMF-codes send by users on a D-STAR radio-channel and create statistics of the DV-stream. Hence, It can be used in two ways: - as an application to monitor the radio-quality parameters of incoming streams (FEC-errors, lost frames and silent frames), the application can be started as a standalone application which just dumps data in a text-file for later processing. - as part of an multi-layer application which executes commands on a D-STAR repeater, controlled by DTMF-keys entered by a user. The package includes a general framework for this kind of application and some demo programs. 1/ Use of dtmf-rcq as a standalone application: The application can be started as an standalone application to monitor the D-STAR repeater radio-channels. On an i-com repeater gateway-server, it will probably be executed like this: sudo dtmf-rcq -t 50 -i eth1 "src host 172.16.0.1 and udp port 20000" Started like this, the application will listen on the port ethernet port "eth1" (the ethernet-port that interconnects the repeater-controller and the gateway- server) applying a pcap-filter that selects only DV-traffic ("udp port 2000") from the repeater-controller ("src host 172.18.0.1") to the gateway-server. In this example, the "tracking" option is enabled, so the program will generate an intermediate line with statistics every second (50 DV-frames). The program will output lines on a number of events it monitors: - the start of a stream containing DV information (like callsigns) - the end of a stream containing statistical information - the reception of a complete 20-bytes broadcast-message - a DTMF key-press - a DTMF key-depress - (optional) intermediate frames during a stream containing statistical information All information generated by the application is in a plain text-based CSV (Comma Seperated Value) format. The document "readme_output.txt" gives more information on the exact format used by this application. A possible use of the dtmf-rfq application in this mode is to analyse the coverage of a D-STAR repeater. This can be done by combining the radio-quality information -as received by the repeater- of a transmittor in a known location. This can be a mobile station equiped with a D-STAR radio and a GPS-device with logging-facilities (a so called "photo tagging" GPS) The link between the radio-quality information -as received by the repeater- and the location of the transmittor can be established via the timestamps that is present in both measurements; the output of the dtmf-rcq and the GPS-logs. 2/ Use as a DTMF-decoder: The dtmf-rfq application can also be used as the lowest layer of a multi-layer application that issues commands on the repeater, based on DTMF keyboard input of the users. There are several ways this can be implemented. This packages contains a demo- application to show this and allow people to experiment with this. This demo software-package is based on a three-layer approach: -> The bottom layer, "dtmf-rcq" interfaces with the hardware, detects DTMF events on the radio-channel and forwards this information to the next software-layer. -> The 2nd layer consist of a perl-script "dtmf-dispatcher.pl". It receives the raw DTMF-data from the dtmf-rcq application, deals with keybounce and errors and executes an external script, based on the DTMF-codes entered. The demo-application has 3 different events: 1/ Quality Announcement: DMTF code "111" or sending " Q" in the yourcall field: Trigger an external script ("announcecounters.sh") to read out the statistics of the last DV-stream using voice-announcement software 2/ Linking / Unlinking DTMF-keys ** will unlink a module DTMF-keys *xxxY (where x is [0-9] and Y is [A‑C]) will link the module to reflector "REFxxxY" (As an alternative) DTMF-keys *xxxy (where x is [0-9] and y is [1‑3]) will link the module to reflector "REFxxxY" (Y is A to C, depending on the value of y) 3/ Error-handling If an unknown DTMF-sequence is received, the application will send a message containing "Unknown DTMF" * The files: - dtmf-rcq: low-level application that reads input from the ethernet- connection to D-STAR gateway controller. - README.txt: this document - install.txt: installation guide - cp2dpl, msg2dpl, cmd2dpl: Applications, running as setuid, needed to allow playing out voice-announcements, sending text-messages and sending commands to dplus for non-root users. - demo/*: demo-application run applets on a D-STAR repeater controlled by DTMF-keys: -> dtmf-dispatcher.pl: reads events from dtmf-rcq and triggers actions -> announcecounters.sh: external script that generates and play-out a voice-announcement message giving information on the radio-quality of the last radio-stream. This script does NOT need a DVdongle to play out voice-announcements. -> *.ambe: ambe pre-encoded audio-samples containing audio-fragments used to create the voice-announcement - demo/wav-files/*: wav-files used to create the .ambe audio-fragments. Created by the "festival" speech2audio software package. - docs/*: documentation folder -> output.txt: description of output messages created by dtmf-rcq -> programming.txt: additional information on how to expand the demo-application with your own applets. * SECURITY As any unix security-guide will tell you, running application as root on a unix-box is something that SHOULD BE AVOIDED AT ALL COST. I repeat: DO *NOT* RUN ANY APPLICATION WHICH YOU DO NOT TRUST AS ROOT. For that reason, even though the "dtmf-rcq" application is designed as a proof-of-concept, special care has been taken to make sure the dtmf-rcq decoder can be run as a normal user. Please read the "install.txt" document which explains how to set up a DTMF- driven application on the gateway-server PC, without the need to run the application as root. Release-info: 25 jan. 2011: Version 0.1.0: Initial release 73 Kristoff ON1ARF