Chapter 3. Extensible Codeplug File Format

Tip

This document describes the extensible codeplug file format using YAML. If you are unfamiliar with YAML, consider reading a YAML introduction first. The documentation for the old table based conf-file format, can be found in section Chapter 6, Table Based Codeplug Format.

The introduction of device specific settings (with version 0.9.0) required an extensible codeplug file format. The old table based format did not allow for any extension without braking backward compatibility. The new YAML based format allows for exactly that: Some means to extend the format for device specific settings without breaking the format while maintaining some degree of readability. (Yes, some users use the command line tool and edit their codeplug in a text editor.)

There are several levels, at which device specific extensions may appear within the codeplug. There are global extensions that apply to the entire codeplug. These extensions are located at the top level. There might also be extensions to single channels, contacts, zones, etc. These extensions are then located under the specific element that gets extended.

Radio settings

The radio settings section contains all radio-wide settings. For example the microphone level, boot text etc. For now, there aren't many.

As an example, consider the following general settings

Example 3.1. General radio-wide settings.

settings:
  micLevel: 6
  speech: false
  introLine1: qDMR
  introLine2: DM3MAT
  defaultID: id1 
  squelch: 1
  vox: 0
  power: High
  gnss:
    fixedLocationEnabled: false
    fixedLocation: JO62jl45
    systems: [GPS, Beidou]
    units: Metric
  dmr:
    privateCallMatch: true
    groupCallMatch: true
    privateCallHangTime: 5s
    groupCallHangTime: 3s
    sendTalkerAlias: false
    talkerAliasEncoding: Iso8
    smsFormat: DMR
    preamble: 100ms

Here, the microphone amplification is set to 6, the speech synthesis is disabled, the two boot text lines are set to “qDMR” and “DM3MAT” respectively and the default DMR radio ID is set to “id1”. The latter is the id of a radio ID defined below.

Also, the radio-wide default squelch, VOX and power level is set. These values can be referenced later in channels. Also, some radios do not allow for these settings to be applied on a per-channel basis. For these radios, these values are used.

Radio-wide Setting Fields

micLevel: Specifies the microphone amplification. Must be an integer between 1 and 10.
speech: Enables/disables the speech synthesis. Some radios can announce the current channel etc. for the visually impaired. To enable that feature (if supported by the radio) set this field to true. Must be a boolean value.
introLine1, introLine2: Sets the two boot text lines (if supported by the radio). These text lines will show up on the boot of the radio. If the radio is set to show a picture during boot, these lines are not shown.
defaultID: Specifies which radio ID will be used as the default DMR ID (see the section called “Radio IDs” below). If none is specified, the first defined DMR radio ID will be used.
squelch: Specifies the default squelch level. This value may be referenced in channels or represent the radio-wide squelch setting. Any value in [0-10] is valid, where 0 implies an open squelch (if supported by the radio).
vox: Specifies the default VOX sensitivity. This value may be referenced in channels or represent the radio-wide VOX sensitivity. Any value in [0-10] is valid here, where 0 disables the VOX.
power: Specifies the default transmit power. This value may be referenced in channels or represent the radio-wide power setting. Possible values are Min, Low, Mid, High and Max.

GNSS settings

This section collects some global GNSS settings that many radio support. Especially, it allows to specify a fixed location that can be used by the radio, if it does not support GPS.

Radio-wide GNSS Setting Fields

fixedLocationEnabled, fixedLocation: Specifies and enables a fixed location. This location can be used instead of a GNSS position. The location is specified in terms of a locator.
systems: Specifies the GNSSs to use in terms of a list of GPS, Glonass, Galileo, Beidou.
units: Specifies the units to use to show distances and speeds. Must be one of Metric or Archaic.

DMR settings

This section collects some global DMR settings that many radio support. Like sending a talker alias and specifying the SMS format.

Radio-wide DMR Setting Fields

privateCallMatch, groupCallMatch

Enable private and group call matches. Must either be true or false.

If private-call match is enabled, the radio only receives private calls for the radio. all other private calls are ignored.

If group-call match is enabled, the radio only receives group calls that are in the group list of the current channel. All other group calls are ignored.

privateCallHangTime, groupCallHangTime

Specifies, how long a private and group call can be answered directly by pressing PTT. That is, how long the call hangs around, before the default transmit contact for the current channel gets active again.

The duration must be specified with units. By default, the duration for private calls is 5s while the duration for group calls is 3s.

sendTalkerAlias, talkerAliasEncoding

Enables sending the talker alias -- that is, the radio name along with the DMR ID. This enables receives to show your radio name, if the receiver does not contain your DMR ID in its call-sign DB.

Current DMR networks inject the talker alias based on the global DMR ID database. Consequently, this feature is of little use. It might be relevant for commercial applications and simplex connections.

If used, talkerAliasEncoding specifies the encoding of the alias. It must be one of Iso7, Iso8 or Unicode.

preamble

Specifies the duration of the DMR transmit preamble. The duration must be specified with units. Usually this is set to 100ms.