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.
Permalink
Failed to load latest commit information.
demo
docs
Makefile
README.txt
cmd2dpl.c
cp2dpl.c
dstar_dv.c
dstar_dv.h
dtmf-rcq.c
dtmf-rcq.h
golay23.c
golay23.h
install.txt
msg2dpl.c

README.txt

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