Connecting an ICOM-705 to an XLX Reflector
Introduction
There are many digital modes available to amateur radio operators - System Fusion, D-Star, DMR, P25, the list goes on. Digital operations offer more than just weak signal voice opportunities. Most of the implementations incorporate an Internet backend for long haul node linking, direct messaging, and often some form of connectable "rooms" for group communications. As with all things, each of them has their own seemingly cult following.
D-Star is an implementation from ICOM available on a variety of their modern radios. According to ICOM, "D-STAR, which stands for ‘Digital Smart Technology for Amateur Radio’ is an open digital Amateur radio standard that offers users a number of ways to connect with other users globally via a worldwide network of digital amateur radio repeaters."
Neat ... but how does one present an interface for all these options using tiny screens and a handful of buttons? Furthermore, how does one configure the appropriate networking to support Pi-Star/WPSD or terminal mode? Let's dive into some scenario configurations.
Assumptions
We'll try four variations of connecting the IC-705:
- Connect IC-705 through Pi-Star/WPSD to your own XLX Reflector
- Connect IC-705 through Terminal Mode to your own XLX Reflector
- Connect IC-705 through Pi-Star/WPSD to another XLX Reflector
- Connect IC-705 through Terminal Mode to another XLX Reflector
We're not going to talk about connecting to a D-Star repeater via RF, that's easy. Just get within range and talk to it. The problem is getting an IC-705 within about 3-5 miles of a D-Star repeater as there aren't really that many permanently running RF nodes. This leads to either using a Pi-Star/WPSD to connect or activating the IC-705's terminal mode.
We're not going to do anything extraordinarily fancy [radio-wise]. We'll communicate to an XLX reflector. There are other reflector types like REF, XRF, and DCS that each evolved over time. The XLX reflector is the most recent multi-protocol variant.
ZUMspot Elite for WPSD |
Your Pi-Star/WPSD already works. Perhaps it's not yet functioning on D-Star, but configuring the basics is outside the scope of this article. These examples use a ZUMspot Elite running WPSD (since Pi-Star hasn't been supported in years).
Your XLX reflector already exists on an Internet accessible server. You really only need to transmit the DCS protocol as UDP traffic on port 30051 to the reflector for a successful transmission connection. Setting up the XLX reflector is pretty easy, but outside the scope of this article. These examples will specifically use the XLXXME reflector at dstar.vnutz.com.
Your network connection does not support the UDP punching technique. D-Star requires that unsolicited UDP traffic on port 40000
is allowed to reach your Pi-Star/WPSD or IC-705 directly to receive any audio. Many network configurations - tethering through your phone while mobile, restrictive SOHO routers, etc. - prevent the direct traffic or don't allow DMZ host configurations. In a nutshell, this one aspect of D-Star is what makes this entire process painful.
There was a bit of chicken and egg decision to make in the article - do we assume the Pi-Star/WPSD node works and you're beating your head over the IC-705 settings or do we assume you need everything? I've chosen to get the IC-705 setup first because that may answer most people's issues rather than having you dig through the article to find it. This ultimately orders the rest of the configurations in order of least pain to most pain.
Setup IC-705 to Access WPSD
NOTE: If you're one of the lucky ones that don't require the network voodoo for receiving UDP port 40000, then you might be completely set just from this part.
Compared to everything else that might have to be configured to defeat the networking demons, this part is actually pretty easy. It's only the nuances of ICOM's menus and what quirks are required that make you doubt the setup is correct. Now, receiving the D-Star traffic is as simple as switching the IC-705 to VFO and entering the operating frequency setup on the Pi-Star/WPSD node. For these examples, just manually set to 432.150.00 Mhz which may be the default on many nodes anyway. Then press the mode button in the top left of your radio's screen and tap DV for digital voice. At this point, the IC-705 can receive and decode whatever D-Star transmissions come from the Pi-Star/WPSD.
However, one way receive operation is not what you're looking for. There are a few quirks to setup on the IC-705 to make it transmit in such a way for the Pi-Star/WPSD to recognize. First of all, D-Star requires a callsign embedded in each transmission. This is set through the DV Memory option. Both your callsign and a free text name you want to appear are configured in the same location.
- Press Menu
- Select the 2nd Page
- Select "DV Memory"
- Select "Your Call Sign"
- Long press the screen for 2 seconds to pop-up a menu
- Select "Add"
- Select "NAME," use the on-screen keyboard, and press "ENT"
- Select "CALLSIGN", use the on-screen keyboard, and press "ENT"
- Press "Add Write"
The next part is what usually makes IC-705 users wonder why their Pi-Star/WPSD node never responds. Even though the Pi-Star/WPSD is setup for simplex operation, you'll configure the IC-705 for a DV Repeater but with a 0.0 Mhz offset. It's a quirk ... the simplex configuration does not seem to activate the Pi-Star/WPSD's detection of D-Star radio traffic.
Before getting into the setup procedure, here are a few notes. When its time to enter a CALLSIGN, it's not necessarily your callsign. Rather, it's the station callsign. And that callsign will have " B" (that is space B
) appended to it which aligns with UHF operation. If you happen to configure the Pi-Star/WPSD node on VHF, you will use C
.
Similarly, there is a "GW CALLSIGN" to configure. Once again, that is the station callsign. This time, it will be appended with " G" (that is space G
) which aligns with gateway operations. For the example of my XLX reflector, that would be KD3BUG B
and KD3BUG G
As you progress through the configuration options, you'll see plenty of settings that fully imply a simplex configuration will work - options like - "TYPE," "DUP," and "OFFSET." Feel fee to try them but it won't work. Just accept it and move on.
- Press Menu
- Select the 2nd Page
- Select "DV Memory"
- Select "Repeater List"
- Scroll the Repeater Group pages to find a blank entry and select it
- Long press the screen for 2 seconds to pop-up a menu
- Select "Add"
- Select "TYPE" and choose "DV Repeater"
- Select "NAME," use the on-screen keyboard, and press "ENT"
- Optionally, do the same for "SUBNAME"
- Select "CALLSIGN" and setup as previously described
- Scroll to the second menu page
- Select "GW CALLSIGN" and setup as previously described
- Select "GROUP" and select one of the DV Repeater groups
- Select "FREQUENCY" and type in your chosen frequency
- Scroll to the third menu page
- Select "DUP" and choose either "DUP-" or "DUP+"
- Select "OFFSET FREQ" and enter 0.000.0 MHz
- Optionally, choose a "POSITION" for D-APRS functionality
- Optionally, enter a "LATITUDE" if GPS is disabled
- Scroll to the fourth menu page
- Optionally, enter a "LONGITUDE" if GPS is disabled
- Optionally, set a "UTC OFFSET" or just leave it on UTC 0
- Press "Add Write"
D-Star Repeater Screen on IC-705 |
The IC-705 now has all that is necessary for communicating to the Pi-Star/WPSD. Press and hold the "CALL" button which activates the programmed repeater functionality. But your transmission still won't go anywhere. Both the TO and FROM selections need to be set. First, configure the radio to use the Pi-Star/WPSD in the FROM field.
- Press the larger box beside "FROM"
- Select "Repeater List"
- Select the "Repeater Group" previously configured
- Select the "Pi-Star/WPSD" previously configured
Selecting Reflector Use on IC-705 Menus |
Next, change the TO field to use a reflector. Technically, the Pi-Star/WPSD receives the transmission just fine with the default "CQCQCQ" setting. However, it treats that transmission as a local signal and does not patch it across to the corresponding reflector. Instead, change the TO field so that it ultimately reads "Use Reflector CQCQCQ" and the Pi-Star/WPSD will relay the transmission through the previously configured tunnels to the XLX reflector.
- Press the larger box beside "TO"
- Select "Reflector"
- Select "Use Reflector"
At this point, key up the radio. You should be able to see the D-Star lights illuminate on the Pi-Star/WPSD unit to confirm signal reception. Furthermore, use a web browser and connect to the Pi-Star/WPSD dashboard to confirm a properly decoded signal. Lastly, if the Pi-Star/WPSD node's configured XLX Reflector has a web accessible dashboard, use a browser and confirm reception of the transmission. For these examples, the XLXXME dashboard is available at dstar.vnutz.com.
Confirming Pi-Star/WPSD Signal Reception |
Connect Pi-Star/WPSD to Your XLX Reflector
Setup WPSD for D-Star
At this point, the IC-705 can talk to a Pi-Star/WPSD node. But if that node isn't properly configured, nothing is going to happen and you're just talking to yourself. First, we'll configure the Pi-Star/WPSD node for D-Star with your XLX reflector. In a nutshell, this will involve setting a frequency, enabling D-Star, configuring D-Star, and confirming connectivity. If necessary, we'll use ssh tunnels and a tool called socat in order to get traffic through the firewalls.
Set the operating frequency of the Pi-Star/WPSD to something locally acceptable to your situation. Be a good amateur radio operator and consult your country's band plan for an appropriate frequency and monitor it to make sure there will not be interference. I chose 432.150Mhz which corresponded to "mixed-mode and weak-signal work." Depending on your Pi-Star?WPSD, this might be the default frequency anyway.
- Connect to your Pi-Star/WPSD web interface
- Click on Admin and enter your credentials
- Click on Configuration and locate the frequency setting
- Enter a frequency and click on Apply Changes
Setting Pi-Star/WPSD Frequency |
Now enable D-Star operations on the Pi-Star/WPSD and save the settings. The rest of the configurations will not be available until the mode is enabled. Presumably, you are still in the configuration menu after setting the frequency.
- Scroll down to "Radio/MMDVMHost Modem Configuration"
- Toggle the "D-Star Mode" button and click on Apply Changes
The configuration screen now offers settings specific to D-Star operation. NOTE: The two hangtime options can be left at default. These affect how long the Pi-Star/WPSD will remain in a particular mode. This is generally useful if operating in multi-mode (like with D-Star and System Fusion for instance) and will assume the device remains in that mode for the configured amount of time to avoid a lag after PTT while the device detects which protocol it's receiving.
Enabling D-Star |
Next, the Pi-Star/WPSD must be configured for which D-Star reflector it will connect to. Presumably, you are still in the configuration menu after setting enabling D-Star. The RPT1 and RPT2 callsigns are automatically set from the Pi-Star/WPSD. However, you must choose the "channel" for RPT1 which is B in this case (for UHF). The G in RPT2 refers to connecting to the Gateway channel. From the "Default Reflector" dropdown, you select your desired reflector. If your reflector is brand new, it may take a day or two to appear in the lists. The XLXXME reflector is available to test your configuration with. Neither "Time Announcements" or "Callsign Routing" are required.
- Scroll down to "D-Star Configuration"
- Select the "B" channel from the RPT1 dropdown
- Select your XLX reflector from the "Default Reflector" dropdown
- Click on Apply Changes
D-Star Configuration |
This next particular setting is entirely optional. If you're the only user connected to your Pi-Star/WPSD node, it's unnecessary to make the following change. If your Pi-Star/WPSD is shared by different amateur radio operators, their callsigns will be rejected unless Node Access Control is set to Semi-Public. Non-intuitively, the Pi-Star/WPSD will not let you toggle this choice without entering a DMR-id even if you have no intention of using DMR. You can either register a real DMR-id or just a random seven digit number into the field.
- Scroll down to "Node Access Control"
- Enter your DMR-id or a random 7 digit number
- Click the Semi-Public radio button
- Click on Apply Changes
Support Multi-Callsign Access |
Confirm the Pi-Star/WPSD node can connect to the XLX reflector.
Confirm D-Star Connectivity |
- Connect to your Pi-Star/WPSD web interface
- Click on Admin and enter your credentials
- Observe the left side panel for the D-Star status
At this point, the Pi-Star/WPSD is connected to the XLX reflector via the DCS protocol. If there is no connectivity, it is likely a network issue preventing outbound UDP packets on port 30051
to reach the reflector or the reflector is not configured properly. The previously setup IC-705 should be able to connect through the Pi-Star/WPSD node and have it's RF transmission related to the XLX reflector. Many XLX reflectors run a dashboard allowing you to confirm connectivity and traffic reception. However, under the assumption that you cannot receive UDP packets on port 40000
, you would never hear a response or any traffic from the reflector, it's all getting stopped at your local firewall.
Setup Reflector for Tunnels
This section is for the unlikely group that cannot get unsolicited UDP packets past the firewall. One way to do this is using a pair of forwarding and reversing SSH tunnels. Since SSH will only tunnel TCP, we'll also need to use the socat tool to patch UDP over to TCP to ride the SSH tunnel and then back again to UDP on the other side. To make this networking magic happen, we'll need to setup the socat tunnels on the reflector, the socat tunnels on the Pi-Star/WPSD node, and the SSH tunnels between them both.
The following ASCII diagram shows the traffic flow. We'll make a change so Pi-Star/WPSD believes your XLX reflector is actually local, on 127.0.0.1
. Then, an outbound DCS protocol connection from the Pi-Star/WPSD goes to itself, where a socat is listening for the UDP packets. Socat patches them over to TCP into an SSH forward tunnel into the XLX reflector. On the reflector, another socat listening on TCP will patch those packets into the XLX server as the expected UDP traffic. In reverse, whenever an audio stream needs to be sent, the XLX server sends them to connected clients, which includes a local 127.0.0.1
connection due to the SSH tunnels. A socat catches the audio packets on UDP and patches them into the TCP reverse SSH tunnel back to the Pi-Star/WPSD. There, another socat catches the TCP packets and patches them over as UDP where the Pi-Star/WPSD receives them and relays the audio over the configured RF to the IC-705.
ZumPi4 dstar.vnutz.com
+--------------+ +---------------+
+-(udp)-< DCS | | XLX reflector-<-(udp)-+
| | | | | |
[socat] | | | | [socat]
| | | | | |
+-(tcp)->-127.1:30051-->====(ssh tcp)=====>-ssh L tunnel-->-(tcp)-+
| | | |
| | | |
+-(tcp)-<--127.1:40000-<====(ssh tcp)=====<---127.1:40000-<-(tcp)-+
| | | | | |
[socat] | | | | [socat]
| | | | | |
+-(udp)->-Pi-Star/WPSD | | audio stream->-(udp)-+
+--------------+ +---------------+
First, connect to your XLX reflector via SSH. Create a quick file named dstar_tunnels.sh
and enter the following:
#! /bin/bash
# Handle Local TCP to UDP conversion for DCS packets
if netstat -atn | egrep ":30051"; then
echo "[*] socat tunnel for TCP->UDP 30051 detected : no action"
else
echo "[!] socat tunnel for TCP->UDP 30051 missing - putting up tunnel"
socat TCP4-LISTEN:30051,fork,bind=127.0.0.1 UDP4:127.0.0.1:30051 &
fi
# Handle Local UDP to TCP conversion for return packets
if netstat -atn | egrep ":40000"; then
echo "[*] socat tunnel for TCP->UDP 40000 detected : no action"
else
echo "[!] socat tunnel for TCP->UDP 40000 missing - putting up tunnel"
socat UDP4-LISTEN:40000,fork,bind=127.0.0.1 TCP4:127.0.0.1:40000 &
fi
The script is designed for "self-healing" operation. The "if ... then
" statements use a netstat
to make sure the corresponding port is actively listening - which means socat is working. If the port is missing, it will re-launch the corresponding socat. Optionally, you can add the "-d -d -d
" options to enable verbose debugging and the "-lf /tmp/socat.log
" option to save the debugging lines into a specified file.
Regarding the socats themselves, each listens locally on 127.0.0.1
for their respective traffic. The first listens locally on TCP port 30051
which will receive the SSH tunneled DCS traffic from the Pi-Star/WPSD, convert it back to UDP, and send them to the actual service on 127.0.0.1
which allows the XLX reflector to receive it. The second socat listens locally on UDP port 40000
for the audio stream, converts it to TCP, and drops it into the SSH reverse tunnel headed back to the Pi-Star/WPSD.
You might be wondering - why send the DCS traffic through an SSH tunnel if it already successfully connects to the XLS reflector? The problem is the source IP address. The XLX reflector will send the outbound UDP traffic to the source IP addresses that are actively connected - which means it will get blocked by your firewall. You need the UDP port 40000
traffic sent to your XLX reflector's 127.0.0.1
address in order to ride the SSH reverse tunnel through the firewall so sending the DCS connection through the tunnel will make it appear as local traffic, hence, and non-intuitively, the XLX reflector will send it back to it's own server, but the reverse tunnel catches it.
To make this work, set the script to be executable and add it to the system's cron
chmod +x dstar_tunnels.sh
crontab -e
Add the following line to the cron, adjusting the file path as appropriate for your server, and save it. Every five minutes, the script should run and keep the tunnels working without manual intervention.
*/5 * * * * /home/USERNAME/dstar_tunnels.sh
Setup WPSD for Tunnels
Now it's time to setup the Pi-Star/WPSD with its own socats and SSH tunnels. Login to your Pi-Star/WPSD either directly with ssh or through the webpage's interface (Admin|Advanced|Tools|SSH Access).
We need to install a few quick packages:
sudo apt update
sudo apt install autossh socat
Now, configure an SSH key for authenticating into your XLX reflector. The following lines will use an elliptic curve signing algorithm with EdDSA and Curve25519 along with installing the generated public key into the reflector:
ssh-keygen -o -a 256 -t ed25519
ssh-copy-id -i ~/.ssh/id_ed25519.pub USERNAME@SERVER
To automate the tunnels, create a file named dstar_tunnels.sh
and enter the following:
#! /bin/bash
# Handle Local TCP to UDP conversion for return packets
if netstat -atn | egrep ":40000"; then
echo "[*] socat tunnel for TCP->UDP 40000 detected : no action"
else
echo "[!] socat tunnel for TCP->UDP 40000 missing - putting up tunnel"
socat TCP4-LISTEN:40000,reuseaddr,fork,bind=127.0.0.1 UDP4:localhost:40000 &
fi
# Handle Local UDP to TCP conversion for outbound packets
if netstat -atn | egrep ":30051"; then
echo "[*] socat tunnel for UDP->TCP 30051 detected : no action"
else
echo "[!] socat tunnel for UDP->TCP 30051 missing - putting up tunnel"
socat UDP4-LISTEN:30051,fork,bind=127.0.0.1 TCP4:localhost:30051 &
fi
# Handle SSH Tunnels
varFLAG=false
if ssh USERNAME@SERVER 'netstat -atn | grep "127.0.0.1:40000" | grep "LISTEN"'; then
echo "[*] reverse tunnel : SSH port forward working"
else
echo "[!] reverse tunnel : SSH port forward missing"
varFLAG=true
fi
if pgrep autossh; then
if [ $varFLAG = true ]; then
echo "[!] reverse tunnel : error detected : killing autossh"
kill `pgrep autossh`
else
echo "[*] reverse tunnel normal"
fi
else
echo "[*] reverse tunnel normal"
fi
else
echo "[!] reverse tunnel missing"
varFLAG=true
fi
if [ $varFLAG = true ]; then
echo "[*] reverse tunnel errors : starting SSH tunnel"
autossh -o "ServerAliveInterval 60" -o "ServerAliveCountMax 3" -M 0 -N -L30051:127.0.0.1:30051 -R
40000:127.0.0.1:40000 USERNAME@SERVER &
fi
The first two code blocks should look familiar. They are exact opposites of the socat implementation previously configured on the XLX reflector. Each looks for an existing listening port to determine if the socat is functioning and launches it again if either is missing. The first entry catches the inbound TCP traffic from the reverse SSH tunnel on port 40000
and patches it over to Pi-Star/WPSD as UDP traffic. The second entry receives the DCS traffic on UDP port 30051
and patches it into the forwarding SSH tunnel as TCP.
The next chunks handle self-healing the SSH tunnels. First, the script authenticates to the SSH server (the XLX reflector) and runs a netstat command looking for a listening port on TCP 40000
. If that's missing, it means the SSH tunnels are broken and a flag variable is set. Second, the script checks if autossh is running. Sometimes software misbehaves and the tunnel could be missing but autossh is still running. In this case, the script will kill the running autossh process. If autossh isn't running, a flag variable is set. Lastly, the script looks to see if the flag variable was set by any prior error checks. The presence of the flag means there was a problem and autossh needs to be run again. Autossh takes a number of arguments regarding the keep-alives (to keep the tunnels up) and options for the tunnels themselves. -L30051:127.0.0.1:30051
listens on 30051
TCP locally on the Pi-Star/WPSD and drops that traffic remotely to the XLX reflectors localhost address on 30051
- hence a forward tunnel. -R40000:127.0.0.1:40000
listens on 40000
TCP remotely on the XLX reflector and drops that traffic locally on the Pi-Star/WPSD localhost address on 40000
- hence a reverse tunnel.
To make this work, set the script to be executable and add it to the system's cron
chmod +x dstar_tunnels.sh
crontab -e
Add the following line to the cron and save it. Every five minutes, the script should run and keep the tunnels working without manual intervention.
*/5 * * * * /home/pi-star/dstar_tunnels.sh
Setup WPSD to Use Tunnels
Now a tweak needs to be made on the Pi-Star/WPSD in order for it to utilize the tunnels. If you're still connected via SSH, you can edit the /root/XLXhosts.txt
file like a boss. Otherwise, just use the web interface:
- Connect to your Pi-Star/WPSD web interface
- Click on Admin and enter your credentials
- Click on Advanced
- Click on Host File Editors and select XLX Hosts
- Reference the example and enter a line for your XLX reflector as
127.0.0.1
and click on Apply Changes
Editing the XLXhosts.txt File |
At this point, the IC-705 should be able to fully access the chosen XLX reflector. To summarize everything:
- The transmission exits the radio via RF via the D-Star protocol.
- The RF is received by the Pi-Star/WPSD node, recognized as D-Star, and decoded.
- The Pi-Star/WPSD node pushes the decoded signal into an SSH tunnel on 127.0.0.1.
- The packets traverse the SSH tunnel and exit at your XLX reflector where it's processed.
- Responses on the XLX reflector reply to connected IP addresses - which include the loopback where it exited the SSH tunnel.
- The response enters the socat tunnel as UDP and gets converted to TCP and pushed into the SSH tunnel.
- The traffic emerges back on the Pi-Star/WPSD from the SSH tunnel and feeds into another socat converted it from TCP back to UDP.
- The Pi-Star/WPSD processes the UDP traffic and transmits it as D-Star RF.
- The IC-705 receives the signal, processes it, and pushes it as audio.
Use Pi-Star/WPSD to Another XLX Reflector
That's all well and good but there are two problems. What if you want to connect to an XLX reflector you don't control? You can't setup the ssh and socat tunnels on someone else's server. Similarly, what if somebody else who needs wacky networking tunnels wants to connect to your XLX reflector? Only one person at a time can have a loopback tunnel listening and you probably don't want to grant access to your server either.
To make this scenario work, you will need a VPS in the wild like from Digital Ocean or another provider. This will enable a very similar set of tunnels to exist, but they'll exit from the VPS and connect to the desired XLX reflector server. The following ASCII diagram shows the packet flow from the Pi-Star/WPSD node, through the VPS, to the XLX reflector, and back. The only real difference from the prior examples will be the VPS socats relay their packets onto another server instead of terminating them on a loopback port for a local XLX reflector.
ZumPi4 random.vps dstar.vnutz.com
+--------------+ +---------------+ +---------------+
+-(udp)-< DCS | | +------->-(udp)------------> XLX reflector |
| | | | | | | |
[socat] | | | +-socat-<-------+ | |
| | | | | | | |
+-(tcp)->-127.1:30051-->====(ssh tcp)=====>-ssh L tunnel-->-(tcp)-+ | |
| | | | | |
| | | | | |
+-(tcp)-<--127.1:40000-<====(ssh tcp)=====<---127.1:40000-<-(tcp)-+ | |
| | | | | | | |
[socat] | | | +-socat->-------+ | |
| | | | | | | |
+-(udp)->-Pi-Star/WPSD | | +-------<-(udp)------------<-audio stream |
+--------------+ +---------------+ +---------------+
to be continued ...
Use Terminal Mode to Your XLX Reflector
to be continued ...
Use Terminal Mode to Another XLX Reflector
to be continued ...
Summary
All of this pain with network traffic manipulation is necessary because ICOM chose to have unsolicited UDP port 40000
traffic come inbound. If you have full control of your edge router, this really is not a big deal but less and less vendors are providing user accessible equipment. This will definitely be the case if you tether your IC-705 through a mobile hotspot doing ham radio on the go. Once it works, D-Star is nice with easy to understand audio and a plethora of connectivity features. However, setting up complex protocol converting tunnels, forward / reverse SSH tunnels, or pre/post routing iptables rules is not something most operators want to do.
Feel free to use XLXXME at dstar.vnutz.com to verify your configurations. I setup the reflector for friends but D-Star was such a pain none of them wanted to use it.
de KD3BUG