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
D STAR Repeater
D-Star repeater mimics an Icom D-Star repeater.
###The D-Star Repeaters There is a lot of commonality between the different D-Star repeater implementations, with the main differences between them relating to the way that they interface to the radio. The D-Star Repeater uses a sound card, the DV-RPTR Repeater uses the DV-RPTR modem, the DVAP Node uses the DVAP, the GMSK Repeater uses a GMSK modem, and the Dummy Repeater uses the DV-Dongle but no radio interfacing hardware. The Split Repeater is also an oddity as it used to split the D-Star data between more than one transmitter and receiver, which can be used for a non co-sited transmitter and receiver for example with a 6m or 10m repeater, or to have multiple receivers and then the software will choose the receiver receiving the best signal.
#Hardware If you are using the sound card based repeaters you will need, as well as a PC, you'll also need a Velleman K8055 USB control board, or a URI USB combined audio card and ports, or a serial port, which handles all of the interfacing to the outside world, apart from the audio (except the URI USB). A serial port, real or virtual may also be used by the software to interface the analogue repeater to external programs or hardware. For the GMSK Repeater you will need a Satoshi compatible GMSK modem, for the DVAP Node you will need a DVAP, and for the DV-RPTR Repeater you will need a DV-RPTR modem.
For the audio D-Star Repeater the following are used:
Function Velleman URI USB PI-GPIO (Config 1), (Config 2), (Config 3) Transmit Output 1 1 12 DTR RTS RTS Output 2 13 Heartbeat Output 3 2 14 RTS DTR DTR Active Output 4 3 11 Output 1 Output 5 4 10 Output 2 Output 6 6 Output 3 Output 7 5 Output 4 Output 8 4
The meanings of the pins are identical to those used on the analogue repeater apart from only having one transmit output and no external battery input. See the definitions above for more information about the pins that are used. The GMSK Repeater and DV-RPTR Repeater also have the option to use a Velleman K8055 as an external controller in order to interface to an analogue repeater controller to form a dual-mode repeater, and to offer control options for hardware. When using the URI Serial/Radio interface You use the "Sound Card" modem. Then serial, gpio, ... for PTT
The two status outputs are Heartbeat and Active, Heartbeat toggles every one second when the software is running correctly and is an indication of the health of the software. A lack of toggling of this line indicates that the software has hung and is in need of restarting.
Active goes high when the repeater transmits and for a period afterwards, this period being set within the configuration programs. RF Transmit is to key the repeater transmitter.
The four remaining outputs, if supported, can be used to control external hardware, and are accessed from the GUI menu.
If you are using a Raspberry Pi the GPIO pins can be used, please note that you will want to compile the repeater binary with the config file appropriate for raspberry pi otherwise the GPIO functionality wont work. you will need wiringPi installed and functioning to do this as well. it would be worth the time to review https://github.com/dl5di/OpenDV/blob/master/DStarRepeater/Common/GPIOController.cpp before compiling as well
Inputs on GPIO GPIO Pins 8,9,7,0,2 are used corresponding to Input 1,2,3,4,5 respectively.
software pullups are turned on.
#Configuration The configuration of the D-Star Repeater is done either via the D-Star Repeater Configuration program, or via a text based script. An area of commonality is the configuration, and the common configuration tabs are presented below.
The command lines to invoke the configuration program are:
DStarRepeaterConfig.exe [-confdir directory] [config name]
dstarrepeaterconfig [-confdir directory] [config name]
Under Windows the configuration is read and written to the registry under “HKCU\Software\G4KLX\D-Star Repeater”, it will also write the configuration out in a file in exactly the same format as would be used under Linux, this file may be copied over to Linux and used. The configuration directory under Windows is defaulted to the users home directory, and the file name used is the same as used under Linux. Under Linux the default configuration directory is set at build time and depends on the standards of the Linux distribution in use typically this is '/home/opendv/dstarrepeater' or 'etc'
For a simple basic configuration of one gateway and one repeater, only the Callsign and Modem tabs (as well as the modem details) need to be filled in. This will not allow the full set of features to be used, but would allow for a basic functioning system.
The “config name” is an optional name that is used to identify the particular instance of the repeater being configured, the name may be almost anything, however it is recommended to use a single number or letter. If only one repeater is needed then the “config name” can be omitted. This would be used to run multiple repeater systems on one PC system.
Once the configuration has been finalized, it may be saved by choosing the Save option from the File menu. Closing the program without saving the configuration will cause your changes to be lost. In all cases the D-Star Repeater will need to (re)started for the changes to take effect. If your on Linux saving may fail if the application cant no write a config you may need to run the application with super user permissions
The CallSign Setting you enter your chosen radio Callsign without the usual D-Star suffix. The suffix is one of A, B, or C with C for 2m, B for 70cms, and A for 23cms. Other bands like 6m, 4m, 220MHz, or 928MHz are more problematic. The program will append the two parts with the correct number of spaces. The Gateway callsign is also set here, typically it will be the same as the main callsign, but need not be, the G at the end of the callsign is appended automatically.
The Mode Setting allows for the selection of “Simplex”, “Duplex”, “Gateway”, “RX Only”, “TX Only”, or “TX and RX”, with the default being Duplex. In Duplex mode the repeaters acts just like an Icom D-Star repeater and requires the use of separate transmitters and receivers, as well as cavity filters, etc. In Simplex mode only one transceiver is required, and any valid input signal is transferred over to the network without being transmitted, and any input from the network is transmitted, no acks are generated in this mode. This allows for a simple D-Star point of presence to be established.
The remaining three modes are only for use with another copy of the D-Star Repeater operating in Split mode. In “RX Only” mode, the repeater only passes received data and will never transmit, conversely the “TX Only” mode is the opposite with the repeater only transmitting data and not receiving. The “TX and RX” mode is a combination of the “TX Only” and “RX Only” mode with the transmit and receive processing operating completely independently and the Split Repeater doing the main processing.
The Gateway setting allows the software to be used as a remote access to the D-Star network (with appropriate gateway software ircDDBGateway for example) to a standalone D-Star repeater. This mode uses either a simplex or duplex radio and appears as a normal user to the standalone repeater with network access. The callsigns being sent through the standalone repeater will appear a little different to using a fully connected D-Star repeater, but it will be very similar to use.
Note that this Mode setting is more restricted when using a DVAP, because it is a simplex only device and only runs 10mW on transmit. If “Duplex” is entered then it will be changed to “Simplex” internally and logged, if “TX and RX” mode is entered it will be changed to “RX Only” internally and logged.
The Ack setting is to make the repeater software send a short transmission after each transmission, this can be thought of as an acknowledgement. This is switchable via the Ack option. Typically this will be enabled in Simplex or Duplex mode, this makes no sense in Gateway mode and is disabled, and set to Disabled when the mode is set to anything other than Simplex or Duplex. The options are “Off”, “BER”, or “Status”, with Off disabling the ack altogether, BER setting the ack text to include the callsign of any linked systems and the bit error rate (BER) of the last transmission, and Status sets the ack test to be the full link status text in the appropriate language.
Restrict Setting is used to limit the stations allowed to access the repeater to those whose first seven character of their callsign (my) is the same as the repeater. This restriction was added to allow for the creation of hot spots with limited third-party access, as required by the UK licence unless specially licenced. For example with Restrict set to Yes, and my repeater callsign was "G4KLX C", I would be able to access with my callsign set to "G4KLX x" where x may be any character. Attempts to access a restricted repeater are logged.
RPT1 Validation which is by default on, is used control access to the repeater based on RPT1. If it is on then only stations in duplex mode with the correct callsign set in the RPT1 position, this is standard behaviour for D-Star repeaters. If it is set to off then a D-Star radio in simplex mode can also access the repeater and the correct values will be inserted into RPT1 and RPT2 within the repeater software.
DTMF Blanking can be set to On or Off, the default being On. In this case any D-Star DTMF tones are filtered out and will not be heard by users of the repeater regardless of the source of these tones. When set to Off no filtering takes place. The reason for this choice is for when a D-Star Repeater is being used on a remote hilltop without Internet access and a gateway, and is using a remote D-Star Repeater in Gateway mode, letting the DTMF tones through is needed to allow DTMF control of reflector linking or of CCS, otherwise the tones would not be received at the remote repeater.
Error Reply can be set to On or Off with the default being set to On. When On the repeater will, if receiving an invalid D-Star transmission, reply to it with a special acknowledgement transmission which may be used by the D-Star radio to reprogram its RPT1 and RPT2 values in order to use the repeater next time the user transmits. In cases where there is a large overlap of coverage of two repeaters then this acknowledgement can stop being useful and become annoying as users of the other repeater may receive these special transmissions when using the other repeater. In such cases setting it to Off is advised.
The Network Tab
The Network tab is for entry of the IP address, not hostname, of the Gateway to the D-Star Reflector. This should be in standard dotted IP notation. Leaving the IP address as blank stops the Repeater from communicating with a Gateway. The port of the Gateway is set here and should be between 1 and 65535 with the default being 20010.
An entry for the Local Address is also available so that the repeater can be bound to a specific interface, real or virtual. Like the gateway address, this is in dotted IP address notation and not a hostname. Setting this entry to blank allows the repeater to bind to all network ports, the default. The local port can also be set, with the value being between 1 and 65535 and the default being 20011. It is not recommended that port numbers of 20001-20009, 30001-30009, 30051-30060, or 40000-40009 are used for either the Gateway or Local Port.
The values in this tab should match the values on the Gateway and Repeater tabs within the ircDDBGateway. When the repeater is being used in “RX Only”, “TX Only” or “TX and RX” modes, the Name should also be entered. This should be a unique name for this repeater and is entered into the Split configuration screen of the repeater in Split mode. The details of this are beyond this document, but may be found in the “Setting Up the Split Mode” document. In all other modes, this entry may be left blank.
The Timers Tab
This controls the repeater timers, the timeout, and the period of time between a transmission ending and the ack being transmitted. The defaults for these are 180s and 500ms respectively, setting the timeout to zero removes the timeout. Note that the timeout only affects radio users and not ones coming in from the network, it is expected that the remote systems will provide the required timeout.
The ack timer has a different use when in Gateway mode (see above), in that mode it is the time after the last transmission coming in via the network before the next transmission coming in via the network will be handled. This is to ensure that the repeater has time to send its ack, before the next one is transmitted.
The Announcement Tab
The Announcements tab may be used to allow for the recording of messages over the air and then the controlled repeating and deleting of those messages. If enabled, the values of Record RPT1 and Record RPT2 should be set in the radio and when received by the repeater the audio is stored in a file. These values should be completely different from those used for accessing the repeater. The transmission while being recorded will not be repeated. Recording a new message automatically deletes an old message.
The Delete RPT1 and Delete RPT2 delete this recorded file. Again, these values should be completely different from those used by the repeater under normal circumstances.
Once a file is recorded, it is repeated by the repeater Time in minutes, unless the repeater is busy of course. The recorded audio is in a file in your home directory named "Announce GB7XYZ B.dvtool" on Windows and "Announce_GB7XYZ_B.dvtool" on Linux. This file is read new each time the announcement is transmitted so can be replaced/uploaded to the computer behind the scenes if needed.
If no file named "Announce_GB7XYZ_B.dvtool" is found then it will look for a file named "Announce.dvtool" in your home directory, so that a global announcement can be sent from all repeaters, but can be overridden by a locally produced dvtool file. At the end of your transmission to the repeater to record or delete your file, the repeater will helpfully reset your RPT1 and RPT2 values for you.
The Beacon Tab
The beacon timer is used by the repeater to control the transmission of a repeater identification transmission when the repeater is not in use. The beacon may be silent with slow data text associated with it, or it may include audio which spells the callsign of the repeater as well as the slow data text.
The default beacon time is ten minutes, and setting it to zero suppresses the beacon. The text transmitted is set here, and by default is the name of the repeater software along with the version date, it is recommended that this text be replaced with something more meaningful, up to a maximum of twenty characters.
Setting the Voice entry to On enables the beacon audio, and it is important that the language is also set correctly in this case so that the sound of the beacon is correct.
The Modem Tab
The need to support so many different types of hardware means that the modem tab is only used for choosing the particular hardware type in use. The real work is done after the Configure… button is pressed, and the hardware specific dialogue box appears. The hardware types supported are: DVAP, DVMEGA, DV-RPTR V1, DV-RPTR V2, DV-RPTR V3, GMSK Modem, Sound Card, and Split. The Split is not a hardware type, but is treated as such by the repeater.
This allows for the settings on the DVAP to be set. The first entry is the Port which is the virtual serial port used by the DVAP. DVAPs come in either 2m or 70cms flavours and in order to ensure that no mistakes are made when entering the frequency, the type of DVAP needs to be selected, dependent on this setting, the range of frequencies that may be entered changes. The next entry is the Frequency, which is the transmit and receiver frequency in Hertz. Next is the transmit power in dBm which ranges from -12 dBm (0.06 mW) to +10 dBm (10 mW), the default is the full +10 dBm. Finally is the squelch level which may be in the range from -128 dBm to -45 dBm, with the default being -100 dBm.
This allows for the settings on the DVMEGA to be set. The first entry is the Port which is the virtual serial port used by the DVMEGA. Under Windows you need to ensure that the driver is loaded, which usually comes with the Arduino development software, the Arduino is not supported by default under Windows. Next you choose the type of DVMEGA. There is the choice of a basic node (modem) or a complete dual-band radio. This choice affects the options that are available to enter. The top screenshot shows the options when in Radio mode and the bottom in Node.
In Node mode the choice of inversion on transmit and receive may be made. In Radio mode the band is selected, 2m or 70cms, which is used to validate the frequency that must be entered, the frequency is entered in Hertz. The TX Delay is common to both types of DVMEGA and is used to allow for any key-up delay of the associated transmitter.
This allows for the port of the DV-RPTR modem to be set. On Linux the port is similar to /dev/ttyACM0 and on Windows it appears as a standard serial port. The other settings are common to all platforms. They are whether to invert the signal in the transmit or receive paths, which port to use on the modem, the default is the A port. The next two are sliders and control the audio level, between 0 and 100%, and the transmit delay before the audio is sent, which can be set in milliseconds.
DV-RPTR V2 & V3
Although the D-Star Repeater treats these two modems as separate types, in reality they are the same firmware with the same facilities.
Uniquely these modems may be attached to a PC either via USB or via an IP network. The top screenshot shows the setup screen when using USB and the bottom when using the network. In USB mode, the virtual serial port that the modem is using needs to be selected, and the Address and Port entries are disabled, conversely when Network mode is selected the USB Port entry is disabled and the IP address and port of the modem may be entered.
The modem does automatic receive inversion detection leaving only the transmit inversion to be set. The output level may be specified along with a TX Delay to allow for the speed of the transmitter keying up.
This allows for the type of driver, and the address, of the GMSK modem to be set. On Windows the default driver type is WinUSB, with the other option being for the LibUSB driver. On Linux the only driver is LibUSB and no option for choosing the driver is available. The default address is 0x300 which is also the default for the GMSK modem, however in order to have more than one GMSK modem attached to a PC, they need to have unique addresses. The value given here must match the value set in the firmware.
GMSK Modems can be very temperamental to use depending on the PC hardware that is connected to them. With the increased range of modems now available, I do not recommend that any new system be created that uses a GMSK modem.
##The Controller setting (GMSK and DV-RPTR) With the GMSK and DV-RPTR Repeaters, an optional controller may be specified so that the repeater may be interfaced to an analogue repeater controller, or to allow for the use of the controller to control local hardware.
The Type may only be a Velleman K8055, with the choice of up to one of four hardware addresses which are set on the Velleman PCB. The Time entry sets the hang time to be used on the active line.
This will remain high for the pre-defined period after the repeater has stopped processing an incoming D-Star transmission, this includes timeouts and inputs with an invalid RPT1 setting.
This contains the audio ports, mode and GMSK inversion. The audio ports are the ones where the audio from the discriminator and the drive to the modulator is set. Testing has shown that the best results are obtained when using the cheapest external USB sound card that you can find! Probably due to the lack of filtering on them. The RX and TX Levels are used for equalising the levels between the Analogue and D-Star repeaters when they share the same transmitter and receiver, if you are not running in such a configuration then just set leave them at 100% and forget about it.
The GMSK inversion is set when the signal from the discriminator is inverted compared to what the software expects, and a separate inversion is settable for transmission when the same is true for the modulator. The GMSK inversion is set when the signal from the discriminator is inverted compared to what the software expects, and a separate inversion is settable for transmission when the same is true for the modulator. The TX Delay sets the amount of time between setting the transmit line and the transmitter sending audio, the TX Tail does the converse and pads the audio out until the transmitter drop at the end of a transmission.
The full details on how to set up a Split repeater system are beyond the scope of this document, see Setting Up the Split Mode document. This is what that document says about this screen.
Each transmitter(s) are receiver(s) have unique name(s) (set on the Network tab) and they appear in this dialogue. The transmit/receive sites appear in both the TX and RX Names section, while the receive sites appear only in the RX Name section, and the transmit sites in the TX Name section. TRX2 is missing in the TX Name section due to a lack of space. If all of the transmitters, receivers, or transmitter/receivers are operating on the same computer then the Local Addr can be set to 127.0.0.1, otherwise it should be left blank. The Local Port should be set to a value that is not already used, 20012 would have been fine in this example (20010 and 20011 are already in use), but 20013 was chosen. This value can be almost anything as long as it doesn’t clash with another use on your computer.
The Packet timeout is used to allow the Split portion to wait long enough to receive all of the data from the different receivers before choosing the best one. This value must be determined by trial and error, and statistics logged by the Split portion of the repeater will be useful in determining the best value. Too short and data will be ignored, too long and unnecessary delays will be introduced into the system.
The Control Tabs 1 and 2
These are to allow remote control of the D-Star Repeater using values of Your, RPT1 and RPT2 callsigns. The use of these commands is enabled or disabled at the top, and if enabled then values should be entered into the four fields. They do not need to be valid callsigns, and they will not be relayed through the repeater. The correct combination of RPT1, RPT2 and the Shutdown value in Your callsign will shutdown the repeater, while the correct combination of RPT1, RPT2 and the Startup value will restart it if it is shutdown.
The control entries for Status 1, Status 2, Status 3, Status 4, and Status 5 are used for triggering the status messages from the repeater. These messages are passed to the repeater from the ircDDB Gateway and are displayed on the screen, and the correct combination of Your, Rpt1, and Rpt2 will trigger a reply from the repeater with the status message in the slow data portion of the transmission.
The Output 1 to Output 4 commands flip the state of four output lines, if they are available.
Up to two external commands may be setup to run based on combinations of Your, RPT1, RPT2 callsigns. On the screen there are two entries each for Command 1 and Command 2, the first entry is the Your callsign used to invoke them, the second entry is the command itself. This text is sent to the shell and is outside the control of the repeater software, so be careful!
Note that configuration changes do not take effect until the software is re-started. All commands are logged along with the My callsign, even for failed commands that have the correct RPT1 and RPT2 but not the correct values of Your callsign. It should be noted that the value used for RPT1 used here must be different from the callsign used for the repeater otherwise it will not correctly relay users.
The Controller Tab
An optional controller may be specified so that the repeater may be interfaced to an analogue repeater controller, or to allow for the use of the controller to control local hardware.
The Type may be a Velleman K8055, an Arduino, or a serial port. The Velleman has the choice of one of four hardware addresses which are set on the Velleman PCB. The Arduino is addressed by specifying the serial port that it is attached to, real or USB. The serial port is simply that, and allows only limited control. The Config option allows for different uses of the output pins and is only used with the serial port because it is so limited.
The Time entry sets the hang time to be used on the active line. This will remain high for the pre-defined period after the repeater has stopped processing an incoming D-Star transmission, this includes timeouts and inputs with an invalid RPT1 setting.
#Running the D-Star Repeater Under Windows the D-Star Repeater this program appears in the start menu, and if only running one instance, and the D-Star Repeater Config has also been run that way, then it should work. However if more flexibility is needed then the repeater needs to be run from the command line. This is usual under Linux, where two versions of the repeater software exist.
The commands for running the D-Star Repeater are:
DStarRepeater.exe [-nolog] [-gui] [-logdir directory] [-confdir directory] [-audiodir directory] [config name] dstarrepeater [-nolog] [-gui] [-logdir directory] [-confdir directory] [-audiodir directory] [config name] dstarrepeaterd [-daemon] [-nolog] [-logdir directory] [-confdir directory] [-audiodir directory] [config name]
On Windows the D-Star Repeater program is named DStarRepeater.exe and is a GUI based program, as is the Linux version which is named dstarrepeater also GUI. Also on Linux is a program named dstarrepeaterd which is a daemon version of the repeater. The -daemon command line switch is used on the command line version to put the program into the background, and to disassociate it from the controlling terminal. The program will return immediately, but using the ps command will show that it is running in the background.
All versions have an optional parameter which signifies the configuration to be used, and this must be set on the command line when running as well as configuring the repeater via the config program. This name will appear on the title bar as well as affecting the name of the log file used.
The location of the configuration file, which is used when running under Linux is normally found in the /etc directory, but this depends on the Linux distribution that it is built for. The -confdir option allows the location of the directory containing the configuration file to be set explicitly, it is also a valid option under Windows but performs no function. The log directory can likewise be changed from the default location.
The –gui flags switches on GUI updates in the GUI version of the program as by default GUI updates are switched off. The hardware type of the repeater appears in the title bar of the repeater in GUI mode.
The –audiodir option is used to set the location where the repeater will write .dvtool file if audio logging is enabled. The repeater will log events to a log file that has the name of the config name as well as the date that the log data refers to in its name. An example being DStarRepeater_1-20140310.log for a repeater with a config name of “1” and DStarRepeater-20140310.log for another than has no config name.
In daemon mode, a SIGUSR1 signal to the program will cause it to exit cleanly, this is preferred to sending a SIGKILL or other signal to it.
The GUI changes depending on whether it is running with a DVAP or other hardware. In DVAP mode the GUI is broadly similar, the only difference being that there is a section that displays the status of the receiver within the DVAP. In it you can see the squelch status as well as the measured level of the input signal.
The main screen simply shows the status of the repeater, and there are no controls to operate. You'll see a summary of any received stations, and a simple status panel to show what the repeater is doing.
Normally the GUI is disabled but it may be switched on in the Release build by specifying the -gui option on the command line, or by clicking on the View menu and enabling the GUI Updates.
The Status section shows the internal status of the repeater. The RX State shows the status of the receiver state machine, while the Rpt State shows the overall repeater state and it has a number of values including Listening, Waiting, Timeout, Valid and Invalid. An incoming D-Star transmission may not have the correct value in RPT1 or some other setting, and such a transmission would be received correctly but counted as Invalid and not relayed.
The TX value mirrors the transmit output pin on the DV-RPTR modem.
The Headers section shows information about the currently received D-Star transmission, the callsigns in the header, and the header flags (in hex). This header is shown only if the header isn't corrupt but is shown even if it isn't valid from the point of view of the repeater.
The Timers section shows the state of the internal timers, all of their meanings have been discussed above, except for the watchdog. The values are displayed as n1/n2 where n1 is the current counting value and n2 is the trigger value, the values of n1 may go over n2 in operation. A value of zero for n1 indicates that the time is not active as will be seen. The Gateway section displays the information sent from the gateway to the repeater which may be requested by the user, using the status command that may be set in the configuration program.
There is a menu entry named Actions which allows local use of the remote commands for the software. These are Shutdown, Startup, Command 1, Command 2, Command 3, and Command 4. The menu entry named Outputs allows hardware outputs 1, 2, 3, and 4 to be controlled from the GUI.
It is possible to write .dvtool files of all the local RF D-Star traffic by enabling the Logging option on the File menu. This creates a .dvtool file for each incoming RF transmission, and can quickly fill up a disk unless care is taken to remove old .dvtool files.
Exiting the program is done by selecting Exit from the File menu.