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