<?xml version="1.0" encoding="UTF-8"?>

<section xml:id="cpAPRS"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink">

<info>
  <title>Positioning Systems</title>
</info>

<para>
  Some radios allow to send the current position using DMR or analog APRS. Consequently, there are 
  two types of positioning systems <token>dmr</token> and <token>aprs</token>. 
</para>

<para>
  As an example, consider these two position reporting systems:
</para>

<example pgwide="1">
  <title></title>
  <programlisting><![CDATA[positioning:
  - dmr:
      id: aprs1
      name: BM ARPS
      period: 300
      contact: cont21
  - aprs:
      id: aprs2
      name: APRS APAT81
      period: 300
      revert: ch104
      icon: Jogger
      message: Y07, QRG 144.675
      destination: APAT81-0
      source: DM3MAT-7
      path: [WIDE1-1, WIDE2-1] 
]]></programlisting>
</example>

<para>
  The first specifies a digital (DMR) positioning system while the latter defines a APRS system.
</para>


<section>
<info>
  <title>Common attributes</title>
</info>

<para>
  The following attributes apply to both, analog APRS and digital DMR position reporting systems.
</para>

<variablelist>
  <title>Common fields</title>
  <varlistentry>
    <term><token>id</token></term>
    <listitem>
      <para>
        Specifies the ID of the system. This can be used reference this system in 
        <xref linkend="cpChannels"/>. Any unique string is valid here.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>name</token></term>
    <listitem>
      <para>
        Specifies the name of the position reporting system. Any string is valid here.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>period</token></term>
    <listitem>
      <para>
        Specifies the update period in seconds. If omitted or set to <token>0</token>, the 
        system will not send any updates periodically.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</section>


<section>
<info>
  <title>DMR position reporting system attributes</title>
</info>

<para>
  The following attributes apply only to digital (DMR) position reporting systems.
</para>

<variablelist>
  <title>DMR position reporting system fields</title>
  <varlistentry>
    <term><token>contact</token></term>
    <listitem>
      <para>
        Specifies the digital contact, the GPS information is sent to. This must be a 
        reference to a digital contact.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>revert</token></term>
    <listitem>
      <para>
        Specifies the revert channel. That is, the channel the data is sent on. If set, 
        it must be a reference to a digital channel. If omitted or set to <token>!selected</token>,
        the currently active channel will be used to send the GPS information.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</section>


<section>
<info>
  <title>APRS attributes</title>
</info>

<para>
  The following attributes apply only for APRS position reporting systems.
</para>

<variablelist>
  <title>Analog position reporting system (APRS) fields</title>
  <varlistentry>
    <term><token>revert</token></term>
    <listitem>
      <para>
        Specifies the revert channel. That is, the channel the APRS information is sent on.
        This must be a reference to an analog channel. Usually a dedicated analog APRS channel is 
        defined and referenced here. 
      </para>
      <para>
        If omitted or set to <token>!selected</token>, the currently active channel will be used to
        send the position information. This, however, is not supported by all radios. Usually, an 
        explicit APRS revert channel must be specified.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>destination</token></term>
    <listitem>
      <para>
        Specifies the destination call and SSID, the information is sent to. This must be a
        string in the form <token>CALL-SSID</token>. Please note that the call must match the 
        format defined by the AX.25 protocol. That is, it may only contain letters and numbers and
        cannot exceed the length of 6.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>source</token></term>
    <listitem>
      <para>
        Specifies the source call and SSID. See <token>destination</token> for details.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>path</token></term>
    <listitem>
      <para>
        Specifies the optional packet path. If set, this must be a list of <token>CALL-SSID</token> 
        strings.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>icon</token></term>
    <listitem>
      <para>
        Specifies the icon name to use. The icon name will be fuzzy matched. See 
        <link xlink:href="https://dm3mat.darc.de/qdmr/libdmrconf/classAPRSSystem.html">
        for a complete list</link> of icon names.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term><token>message</token></term>
    <listitem>
      <para>
        Specifies an optional message sent along with the position information.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</section>

</section>
