|
LibDMRConf
0.5.0
A library to program DMR radios.
|
Classes | |
| class | CSVHandler |
| Basic parse-handler interface. More... | |
| class | CSVReader |
| Implements the text-file codeplug reader. More... | |
| class | CSVWriter |
| Writing config files. More... | |
The config file format is a text-file format to describe generic code-plugs (a.k.a., the Config class). This format is aimed at being human-readable and allows to write codeplugs by hand (e.g., using a text editor). This section describes this format, as well as all classes used to read and write that file format.
The most convenient way of reading and writing config files, however, is to use the Config::readCSV and Config::writeCSV methods of the Config class. For example,
As mentioned above, the configuration file represents a generic configuration (the Config class) for a wide varity of radios. It is a simple text file containtin simple key-value definitions like the DMR ID as well as tables like the table of channels, contacts, etc.
The aim of this config format is to be human-readable and writable. This would allow users to write config file by hand and share them easily, as well as enable users to modify shared configurations using a text editor. To this end, the format must be intuitive and to some degree self-documenting.
Within the following sections, I will describe that text format in some detail.
To document your configuration, you may use so-called line-comments. These comments start with the character '#' and end at the end-of-line.
The general configuration settings of some radios can be overly complex with a huge amount of options. The vast majority of these settings, however, are useless for hamradio purposes. Thus the possible settings for the general configuration of the radio are reduced to 6 key-value pairs.
The DMR ID of cause, is absolutely neccessary and specifies your personal DMR number. Keep in mind, that you do NOT need to get a unique DMR ID for each radio you own! All your radios can share the same DMR ID. The DMR ID is specified using the "ID" keyword as
The radio name is a string, that the radio may display somewhere on the screen. It does not have any effect on the behavior of the radio or gets transmitted. You may set this entry to your callsign. For example:
The two intro lines might be shown on the screen of your radio on startup. You may set these to any string you like. They are also cosmetic and don't have any effect on the behavior of your radio. For example
The microphone sensitivity/amplification can also be set (on some radios) using the MicLevel entry. This entry is also a number between 1 and 10. The larger the level the larger the microphone amplification. This value may vary heavily from model to model.
The "Speech" option enables the speech synthesis of the radio if supported. Possible settings are "on" and "off".
The contact table is a list of DMR contacts like
These contacts can be personal contacts like DM3MAT, so-called all-calls and group calls. The contact table starts with the "Contact" keyword and ends with an empty line. The remaining keywords ("Name", "Type", "ID", "RxTone") are ignored, however, they are part of the self-documentation of the config file.
Following the "Contact" keyword, each line represents a single contact in the contact list. The first column represents a unique internal ID for the contact. It must not necessarily be in ascending order, any unique number will do. The second column is the name of the contact. Any string can be used here. The third column specifies the type of the contact. This must be one of the keywords "Private", "Group" or "All", meaning private, group or all-calls, respectively. The fourth column specifies the DMR ID for the contact. Please note, that an all-call requires the specific DMR ID 16777215 to work as an all-call. The last colum specifies, whether an incomming call from this contact will cause a ring-tone. Here "+" means enabled/yes and "-" disabled/no.
RX group lists are simple named lists of one ore more contacts. These lists may include group, all or even private calls. RX group lists are assigned to channels. They form a group of contacts (e.g., talk groups) you may want to listen to on a particular channel. Usually these group lists form a collection of talk groups that are specific for a particular region.
RX group lists are defined within the config file like
The group list table starts with the keyword "Grouplist". The following keywords (Name & Contacts) are ignored, but form a kind of self-documentation for the config file.
Following the "Grouplist" keyword, each RX group list is defined by a single line. The first column specifies the internal unique ID for the group list. This can be any number as long as it is unique. The second column contains the name of the group list as a string. This can be any non-empty string. The third column contains the commma-separated list of contact IDs that form that group list.
The digital channel table defines all digital DMR channels. As digital channels have some different options compared to analog channels, they are not defined within the same table. However, they share the same IDs. So be careful not to assign the same identifier to analog and digital channels.
The digital channel table has the form
The digital-channel table starts with the keyword "Digital" and ends with an empty line. The next keywords (Name, Receive, Transmit, Power, Scan, TOT, RO, Admit, CC, TS, RxGL and TxC) are ignored and are maintained for the self-documentation of the configuraion file.
Each channel is defined within a single line. The first column is the unique channel identifier (any unique number among analog AND digital channels). The second column specifies the channel name as a string. The third column specifies the RX frequency in MHz and the fourth column the TX frequency in MHz. Alternatively, a TX frequency can also be specified in terms of an offset relative to the RX frequency. In this case, the offset must be prefixed with either "+" or "-". The 5th (Power) column specifies the power level to use. Here, either the "High" or "Low" keyword must be used. The 6th (Scan) column specifies the ID of the scanlist (see below) attached to the channel. This list will be used whenever a scan is started on this channel. The 7th column (TOT) column speifies the TX time-out-timer in seconds or "-", if disabled. The 8th column (RO) specifies whether the channel is RX only ("+") or not ("-"). If enabled, you cannot transmit on that particular channel. The 9th (Admit) colum specifies the TX admit criterion for the channel. This must be either "-" or one of the keywords "Free" and "Color". "-" indicates that there is no restriction in transmitting on that channel. The radio will transmit whenever PTT is pressed. The "Free" keyword indicates that the radio will only transmit if the channel is free. The "Color" keyword indicates that the radio will only transmit if the channel is free and the colorcode of the repeater matches the specified color-code of the channel (see next column). The 10th column specifies the colorcode of the channel. The 10th (CC) column specifies the color-code of the channel. To avoid interference between neighbouring radios and repreaters on the same frequency (in case of DX conditions), the repeater and radio will only react to tranmissions on a channel with the matching color-code. The color-code can be any number between 0 and 15. The 11th (TS) column specifies the time-slot for this channel. Due to the audio compression used in DMR, it is possible to operate two independent channels on a single frequency by using time-sliceing. DMR uses two time-slots. This option specifies which of the two time-slots is used for the channel. On simplex channels, this time-sliceing is irrelevant, as there is no central instance (the repeater) that defines what time-slot 1 or 2 is. The 12th (GPS) column specifies the GPS system (see below) to use on that channel.
The analog channel table collects all analog (FM) channels. As digital channels have some different options compared to analog channels, they are not defined within the same table. However, they share the same IDs. So be careful not to assign the same identifier to analog and digital channels.
The analog channel table has the form
The analog channel table starts with the "Analog" keyword and ends with an empty line. The remaining keywords right after "Analog" (i.e., "Name", "Receive", "Transmit", "Power", "Scan", "TOT", "RO", "Admit", "Squelch", "RxTone", "TxTone" and "Width") are ignored but are part of the self-documentation of the config file.
Each line within the table specifies a single channel. The first column specifies the unique ID of the channel. This ID can by any number that is unique among analog AND digital channels. The second (Name) column specifies the name of the channel as a string. Any string can be used here. The third (Receive) column specifies the RX frequency of the channel in MHz. The fourth (Transmit) column specifies the TX frequency in MHz or alternatively, an offset relative to the receive frequency in MHz by prefixing "+" or "-". The 5th (Power) column specifies the transmit power. This must be either the "High" or "Low" keyword. The 6th (Scan) column specifies the scanlist ID for this channel or "-" if there is no scanlist assigned to the channel. A scanlist (see below) is just a collection of channels that gets scanned whenever scanning is started on a particular channel. The 7th (TOT) column specifies the transmit time-out in seconds or "-" if disabled. The 8th (RO) column specifies whether this channel is receive-only with either "-" meaing disabled and "+" enabled. If enabled, it is impossible to transmit on that channel. The 9th column specifies the admit criterion on that channel. This must be either "-" meaning that there is no restriction when to send on that channel, the keyword "Free" meaning that the channel must be free to transmit or the keyword "Tone" meaning that the channel must be free and the RxTone must match. The 10th (Squelch) column specifies the squelch level for the channel. This must be a number between [0-10]. The larger the value, the stronger the signal must be to open the squelch. The value 0 disables the squelch. The 11th (RxTone) specifies the receive CTCSS tone frequency in Hz. The quelch will then only open, if the signal is strong enough (see previous column) and the specified tone is received. If set "-" the RX tone is disbled and the squelch will open if the signal is strong enough. The 12th (TxTone) column specifies the CTCSS tone to transmit in Hz or "-" if disabled. This feature is used by some repeaters to open their squelch and to start repeating to avoid conflicts between repeaters operating on the same frequency (e.g., in case of DX conditions). Finally the 13th (Width) colum specifies the bandwidth of the channel in kHz. This can be 12.5kHz narrow-band or 25kHz wide-band.
Zones are just collections of channels. Typical radios can hold thousands of channels. To keep large numbers of channels manageable, they can be organized into zones. Usualy, these zones represent a geographical area and all repeaters in that area are then grouped into zones. Of cause, a single channel can be added to multiple zones. Please note that for many radios, channels can only be accessed via a zone. That means, a channel that is not a member of any zone may not be accessible.
The zone table is defined within the configuration file as
The zone table starts with the keyword "Zone" and ends with an empty line. The remaining keywords (Name and Channels) are ignored but are part of the self-documentation of the configuration file. The first colum specifies an unique identifier for each zone. This can be any integer as log as it is unique. The second (Name) column specifies the name of the zone as a string. Any string is valid here. The third column specifies the VFO (either A or B) for that zone. This allows to specify different channels for the two VFOs of the radio. For example, it allows to specify a list of repeater channels for VFO A and some simplex and calling frequencies on VFO B. The fourth column contains the comma-separated list of channel IDs for the zone anc VFO. A reference to any channel-type can be used here, analog and digital.
A scan list is list of channels, that are scanned whenever scanning is started on a channel the scan list is associated with. A single scan list might be associated with several channels. For example, all channels within that scan list.
The list of scan lists has the following form
The list of scan lists starts with the "Scanlist" keyword and ends with an empty line. The remaining keywords (Name, PCh1, PCh2 & Channels) are ignored but part of the self-documentation of the configuration file format. A scan list is defined with every other line. The first column specifies the unique identifier of the scan list. The second (Name) column specifies the name of the scan list as a string. Any string will do. The third and fourth columns specify the first and second priority channels for the scan list respectively. These priority channels are visited more frequently during the scan. That is, the first priority channel is visited 50% of the time while the second is visited 25% of the time. These channels might also be set to "-" indicating that there is no priority channel. The 5th column specifies the transmit channel during the scan. Possible options are "Last", "Sel" and any valid channel index. The "Sel" keyword implies that the radio will transmit on the selected channel when the scan started. The "Last" keyword implies that the radio will transmit on the channel at which the scan stopped on, while specifying any channel index implies, that the radio will transmit on that channel. Finally the 6th column specifies the comma-separated list of channels that form the scan list.
The GPS System list just specifies the contact to which some positional information is send to (which usually gets forwarded to the APRS system) and at which period this information is send.
The first column specifies the ID of the GPS system. This can be any number >0. The second column (Name) specifies the name of the GPS system. The third column specifies the destination contact ID (see Contacts above), the position information is send to. The fourth column (Period) specifies the update period in seconds. The fifth column (Revert) specifies the revert channel. In amateur radio, this can be left blank ("-").
1.8.17