DTMF decoder and RadioChannel Quality tool for D-STAR
Switch branches/tags
Nothing to show
Clone or download
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
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

- 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 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") 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

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

-> 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.


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.

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.

25 jan. 2011: Version 0.1.0: Initial release

Kristoff ON1ARF