= Digital Voice Modem

== Technical Note
=== dvmhost Air Interface Tuning

Document Identifier: TN.1101

Author: Bryan Biedenkapp, N2PLL

Editors: Bryan Biedenkapp, N2PLL

Contributors: N/A

Abstract: Describes the procedures required for appropriate alignment/calibration of an air interface.

Status: Draft

== 1. Introduction
This document describes, as simply as possible, the procedures required to align/calibrate an air interface.

== 2. Alignment Procedures

=== 2.1 Initial Setup Steps
The following setups assume the host is compiled with the setup TUI mode (if available) [NOTE: Steps 3 - 5 only apply to the air interface modem.]. It is possible to setup the modem without the setup TUI, and requires manually modifying `config.yml` and the `iden_table.dat` files.

[start.1]
. Create/Edit `config.yml` and ensure the settings for the modem are correct, find the "modem" section in "system". Check that the uart settings have the appropriate UART port and port speed set (the config.yml defaults to /dev/ttyUSB0 and 115200).
    .. If using the air modem interface, ensure the the modem protocol mode is set to "air".
    .. If using the V.24 DFSI modem interface, ensure the modem protocol mode is set to "dfsi".
        .... The V.24 DFSI modem has multiple firmware revisions, it is required to use firmware version 2.0 or greater for use with dvmhost.
. Start `dvmhost` as follows: `/path/to/dvmhost -c /path/to/config.yml --setup`. This will start the dvmhost setup TUI mode.
. Using the TUI user interface, use the "Setup" menu to set default parameters.
    .. The "Logging & Data Configuration" submenu allows you to alter the various logging file paths and levels, as well as paths to data files (such as the `iden_table.dat` file).
    .. The "System Configuration" submenu allows you to alter various modem port and speed, system settings, and mode settings configuration.
    .. The "Site Parameters" submenu allows you to alter various CW morse identification, and site parameters.
    .. The "Channel Configuration" submenu allows you to alter the configured channel for the modem you are configuring.
. After altering settings, use the "File" menu, "Save Settings" menu option to save the desired configuration.
. Quit setup mode (some settings changes require a restart of the software to be effective) using, "File" menu, "Quit".

=== 2.2 (Air Interface) Transmit Calibration

==== 2.2.1 Using setup TUI, if available
[start.1]
. Start `dvmhost` as follows: `/path/to/dvmhost -c /path/to/config.yml --setup`. This will start the dvmhost setup TUI mode. The best way to calibrate the DVM is to use a radio from which you can receive and transmit the appropriate test patterns (for example using ASTRO25 Tuner and an XTS radio to use the "Bit Error Rate" functions under Performance Testing).
. Depending on which protocol you are calibration with, use the "Calibrate" menu, and select the appropriate mode using the "Operational Mode" submenu. (For example, select [Tx] DMR BS 1031 Hz Test Pattern for DMR or [Tx] P25 1011 Hz Test Pattern (NAC293 ID1 TG1) for P25.)
. Open the "Level Adjustment" window by either, using the "Calibrate" menu and selecting "Level Adjustment" or if capable, pressing F5 on the keyboard.
. Ensure the TX Level is set to 50 (it should be by default, you can use the spinbox in the "Level Adjustment" window to change the value, if necessary to set it to 50).
. If the hardware in use has a TX potentiometer, set it to the to minimum level.
. Start Tx (click "Transmit" or press F12 on the keyboard).
. While observing the BER via whatever means available, adjust the TX potentiometer (if the modem hardware allows) for the lowest received BER. Adjust the software TX Level for some fine tuning with the spinbox in the "Level Adjustment" window.
. Stop Tx (click "Transmit" or press F12 on the keyboard).
. After altering settings, use the "File" menu, "Save Settings" menu option to save the desired configuration.
. Quit setup mode, if done doing calibration, using, "File" menu, "Quit".

==== 2.2.2 Using old calibration CLI
[start.1]
. Start `dvmhost` as follows: `/path/to/dvmhost -c /path/to/config.yml --cal`. This will start the dvmhost calibration mode. The best way to calibrate the DVM is to use a radio from which you can receive and transmit the appropriate test patterns (for example using ASTRO25 Tuner and an XTS radio to use the "Bit Error Rate" functions under Performance Testing).
. Depending on which protocol you are calibration with, enter DMR BS 1031 Hz Test Pattern (M) or P25 1011 Hz Test Pattern (NAC293 ID1 TG1) (P).
. Ensure the TXLevel is set to 50 (it should be by default, "\`" will display current values, use "T" [increase] and "t" [decrease] if necessary to set it to 50).
. If the hardware in use has a TX potentiometer, set it to the to minimum level.
. Start Tx (press spacebar to toggle Tx).
. While observing the BER via whatever means available, adjust the TX potentiometer (if the modem hardware allows) for the lowest received BER. Adjust the software TXLevel for some fine tuning with the "T" (increase) and "t" (decrease).
. Stop Tx (press spacebar to toggle Tx).
. Save the configuration using "s" and quit calibration mode with "q".

=== 2.3 (Air Interface) Receive Calibration 

==== 2.3.1 Using setup TUI, if available
[start.1]
. Start `dvmhost` as follows: `/path/to/dvmhost -c /path/to/config.yml --setup`. This will start the dvmhost setup TUI mode. The best way to calibrate the DVM is to use a radio from which you can receive and transmit the appropriate test patterns (for example using ASTRO25 Tuner and an XTS radio to use the "Transmitter Test Pattern" functions under Performance Testing).
. Depending on which protocol you are calibration with, use the "Calibrate" menu, and select the appropriate mode using the "Operational Mode" submenu. (For example, select [Rx] DMR BS 1031 Hz Test Pattern for DMR or [Rx] P25 1011 Hz Test Pattern (NAC293 ID1 TG1) for P25.)
. Open the "Level Adjustment" window by either, using the "Calibrate" menu and selecting "Level Adjustment" or if capable, pressing F5 on the keyboard.
. Ensure the RX Level is set to 50 (it should be by default, you can use the spinbox in the "Level Adjustment" window to change the value, if necessary to set it to 50).
. If the hardware in use has a RX potentiometer, set it to the to minimum level. (If using something like the RepeaterBuilder STM32 board, decrease both the coarse and fine potentiometers to minimum level.)
. While observing the BER via the setup TUI (Receive BER shows a large window in the top-right corner of the TUI when in a Rx BER test mode), adjust the RX potentiometer(s) for the lowest received BER. If necessary also adjust the software RX Level for some fine tuning with the spinbox in the "Level Adjustment" window.
. After altering settings, use the "File" menu, "Save Settings" menu option to save the desired configuration.
. Quit setup mode, if done doing calibration, using, "File" menu, "Quit".

==== 2.3.2 Using old calibration CLI
[start.1]
. Start `dvmhost` as follows: `/path/to/dvmhost -c /path/to/config.yml --cal`. This will start the dvmhost calibration mode. The best way to calibrate the DVM is to use a radio from which you can receive and transmit the appropriate test patterns (for example using ASTRO25 Tuner and an XTS radio to use the "Transmitter Test Pattern" functions under Performance Testing).
. Depending on which protocol you are calibration with, enter DMR BS 1031 Hz Test Pattern (M) or P25 1011 Hz Test Pattern (P).
. Ensure the RXLevel is set to 50 (it should be by default, "\`" will display current values, use "R" [increase] and "r" [decrease] if necessary to set it to 50).
. If the hardware in use has a RX potentiometer, set it to the to minimum level. (If using something like the RepeaterBuilder STM32 board, decrease both the coarse and fine potentiometers to minimum level.)
. Depending on which protocol you are calibration with, enter DMR MS 1031 Hz Test Pattern (J) or P25 1011 Hz Test Pattern (j).
. While observing the BER via the calibration console, adjust the RX potentiometer(s) for the lowest received BER. If necessary also adjust the software RXLevel for some fine tuning with the "R" (increase) and "r" (decrease).
. Save the configuration using "s" and quit calibration mode with "q".

== Appendix A (Air Interface) Calibration Notes

* If you have access to appropriate RF test equipment (or equivilant equipment) that is capable of monitor the overall transmitted *analog* FM deviation; if is important to adjust both the modem and the connected radios so that the overall transmitted *analog* FM deviation be between 2.75khz and 2.83khz (a center average of 2.80khz *analog* FM deviation is best).
* When using a repeater/modem board attached to an appropriate FM repeater/radio, it *may* be necessary to "de-tune" the repeater/radio slightly, most commercial grade equipment operating within a 12.5khz channel may impose a strict 2.5khz (and no greater) maximum *analog* FM deviation, this is well below what is required for good digital operation. It may be necessary using whatever tuning/alignment tools to "de-tune" or adjust the equipments alignment to allow for a wider *analog* FM deviation, as close to 2.80khz as possible.
* In some situations, it may be necessary to adjust the symbol levels directly. Normally this isn't required as the DVM will just work, but some radios require some fine adjustment of the symbol levels, this is exposed in the calibration mode. It is however recommended, that these adjustments *not* be made unless appropriate RF test equipment is available.
* Unusually high BER >10% and other various receive problems may be due to the radio/hotspot being off frequency and requiring some adjustment. Even a slight frequency drift can be catastrophic for proper digital modulation. The recommendation is to ensure the interfaced radio does not have an overall reference frequency drift > +/- 150hz. An unusually high BER can also be explained by DC level offsets in the signal paths, or issues with the FM deviation levels on the interfaced radio being too high or too low.
* For hotspot operation, it may be necessary to enable/disable the AFC (automatic frequency correction) or change the gain mode. Both of these options can be altered using the setup TUI or directly in the `config.yml` file. In some cases when operating in trunking mode, for example, it may be necessary to change the orientation of the transmit antenna by using a 90 degree adapter as well as changing the gain mode to "Low" to prevent Rx desense.
