Voter.conf

From AllStarLink Wiki
Revision as of 22:41, 2 February 2022 by VE7FET (talk | contribs)
Jump to navigation Jump to search

Introduction

This file sets up the chan_voter channel driver to interface with app_rpt.


Remember, in rpt.conf, you will need a directive to use the chan_voter channel driver:

rxchannel = Voter/1999


The 1999 should match the corresponding instance stanza defined in voter.conf that holds all the definitions for your clients.


The VOTER/RTCM may be used in any of 3 modes:

  • non-voting client mode
  • voting mode
  • voting and simulcast mode


See the VOTER page for additional information.


voter.conf

The voter.conf file is generally going to be located with the rest of the Asterisk configuration files, in /etc/asterisk.


There must be a [general] stanza that contains directives that are common to all the chan_voter instances. Some directives may be allowed in the [general] stanza and/or be defined on a per-client basis with the client definition directive.


In addition, there must be at least one instance stanza defined. An instance is a group of clients that are all related to each other. In a typical voting repeater scenario, the instance would typically be the node number, and all the clients would be the transmitter client and all the voting receiver clients associated with that repeater.


It is a valid configuration to only have one client defined in an instance. You might have this if you are just using the VOTER/RTCM as a RoIP adapter to connect a remotely located repeater back to a host over Ethernet.


You may have more than one client defined as a transmitter, as in the case of a simulcast system. Any client with a transmitter directive defined will be sent transmit audio packets associated to that instance.


Each client directive has a number of optional attributes associated with it that may, or may not, be required depending on your system configuration.


There are also configuration directives that apply to an entire instance (and all the defined clients within it).


The voter.conf file is structured as shown below (as in all other Asterisk configuration files, lines preceded with a semi-colon ";" are treated as a comment):

[general]
;bindaddr = 10.10.10.1		; specify a particular IP address to bind to (not generally used, defaults to bind to all interfaces)
port = 667			; specifies the UDP port to use for incoming connections
buflen = 480			; specifies the receive buffer length in milliseconds.
				; This parameter should be set to the maximum expected network latency,
				; plus a little padding (100 milliseconds of padding is a good amount).
				; The default is 480 milliseconds, the minimum is 320 milliseconds.
				; Buffer length may be specified on a per-stanza and per-client basis, see below.

password = secret_password	; password common to all clients (Main Menu Item 6 - Host Password, on RTCM/VOTER)
utos = y			; Turn on IP TOS for Ubiquiti (ToS is enable by default on the RTCM/VOTER) from the host TO the clients

;sanity = 0			; disable sanity checking of clients (debug use only) defaults to 1 if not specifically set to 0
;puckit = 1			; KLUDGE to try and fix random Garmin LVC-18 pucks that may or may not be 1 second off (defaults to 0 if not specified or set to 1)

[1999]				; define the 1999 instance stanza
Main = secret,transmit,master	; master,transmit,adpcm,nulaw,nodeemp,hostdeemp,noplfilter,buflen=value,gpsid[=value],prio=value
				; 
				; master - this client is the Master Timing source (the RTCM client that is on the same LAN as the Asterisk server.)
				; There can only be 1 Master Timing source per ENTIRE Asterisk server.
				; 
				; secret - password unique to this client
				; transmit - this client is intended to have transmit audio sent to it and will have a transmitter connected to it.
				; adpcm - this client is to be sent audio in 8000 samples/sec, 4-bit, IMA ADPCM format, rather than default G.711 Mulaw (aka ulaw).
				; nulaw - this client is to be sent audio in 4000 samples/second Mulaw (Nulaw, as we call it), rather than the standard 8000 samples/second.
				; nodeemp - this client is not to perform de-emphasis of the receiver audio  (This is only to be used with non-voting clients). Switches 
				; the hardware de-emphasis filter OUT on the client
				; hostdeemp - this client is to force the use of the host's DSP FIR Integrator providing de-emphasis at 8000 samples/sec.
				; noplfilter - this client is to not to perform hardware pl filtering of the audio. Switches the hardware PL filter OUT on the client.
				; buflen=value - receive buffer length override for this client only.
				; gpsid[=value] - This specifies a gps identity to associate with the specified client (as referred in the /etc/asterisk/gps.conf file).
				; prio=value - define a specific priority for this client when voting. Lower numbers are higher priority. Default is 0 if nothing specified.

plfilter = y			; use DSP IIR 6 pole High pass filter, 300 Hz corner with 0.5 db ripple (note clients filter PL by default already)
txctcss = 100.0			; Transmit CTCSS frequency
txctcsslevel = 62		; Transmit CTCSS level (default of 62 if txctcss is supplied, but txctcsslevel is not set)
txtoctype = phase		; Transmit tone control type: none,phase,notone
				; none - CTCSS tone encoding with no hang time (default)
				; phase - encode CTCSS and reverse phase (AKA "reverse burst") before unkeying TX
				; notone - encode CTCSS and stop sending tone before unkeying TX (AKA "chicken burst")

;gtxgain = 3.0			; adjust the audio gain to all transmitters (in db voltage gain)
;hostdeemp = 1			; force the use of the DSP FIR Integrator providing de-emphasis at 8000 samples/sec. Used with Duplex Mode 3 setting in RTCM/VOTER

thresholds = 255,110=5		;
; linger=6			; linger default is 6 if no other value specified
; streams = 67.215.233.178:1667 ; location to send voter data stream for this instance (used only with votemond Java program, which is deprecated)

; isprimary = y			; used in redundant server applications only. must be set on the primary server only
; primary = 10.20.20.1:667,mypaswd	; used in redundant server applications only. must be ONLY set on the secondary server to point to the primary

[1998]				; define another voting instance on this server (for another node). Three simulcast transmitters and four receivers.
				; NOTE: there is NO "master" in this instance, since we already have a master timing source on this server defined above 

NORTH = password_1,transmit		; transmit/receive site
SOUTH = Password_2,transmit		; transmit/receive site
EAST = password_3,nodeemp		; receive-only site, bypass de-emphasis filter in RTCM
WEST = Password_4,transmit,noplfilter	; transmit/receive site, bypass CTCSS filter in RTCM


Of course, the above denotes all the possible options that you can define in voter.conf. A typical "bare minimum" to get on the air would be more along the lines of:

[general]
port = 667			; specifies the UDP port to use for incoming connections
buflen = 480			; specifies the receive buffer length in milliseconds.
				; This parameter should be set to the maximum expected network latency,
				; plus a little padding (100 milliseconds of padding is a good amount).
				; The default is 480 milliseconds, the minimum is 320 milliseconds.
				; Buffer length may be specified on a per-stanza and per-client basis, see below.

password = secret_password	; password common to all clients (Main Menu Item 6 - Host Password, on RTCM/VOTER)
utos = y			; Turn on IP TOS for Ubiquiti (ToS is enable by default on the RTCM/VOTER) from the host TO the clients


[1999]				; define the 1999 instance stanza

Main = secret,transmit,master	; master - this client is the Master Timing source (the RTCM client that is on the same LAN as the Asterisk server.)
				; There can only be 1 Master Timing source per ENTIRE Asterisk server.
				; secret - password unique to this client
				; transmit - this client is intended to have transmit audio sent to it and will have a transmitter connected to it.

Remote = secret2		; satellite receiver site only 


[general] Stanza

The [general] stanza defines all the configuration directives that apply to chan_voter, and all instances in the voter.conf file.


[general]
;bindaddr = 10.10.10.1		; specify a particular IP address to bind to (not generally used, defaults to bind to all interfaces)
port = 667			; specifies the UDP port to use for incoming connections
buflen = 480			; specifies the receive buffer length in milliseconds.
				; This parameter should be set to the maximum expected network latency,
				; plus a little padding (100 milliseconds of padding is a good amount).
				; The default is 480 milliseconds, the minimum is 320 milliseconds.
				; Buffer length may be specified on a per-stanza and per-client basis, see below.

password = secret_password	; password common to all clients (Main Menu Item 6 - Host Password, on RTCM/VOTER)
utos = y			; Turn on IP TOS for Ubiquiti (ToS is enable by default on the RTCM/VOTER) from the host TO the clients

;sanity = 0			; disable sanity checking of clients (debug use only) defaults to 1 if not specifically set to 0
;puckit = 1			; KLUDGE to try and fix random Garmin LVC-18 pucks that may or may not be 1 second off (defaults to 0 if not specified or set to 1)


bindaddr, port, password

Typically, bindaddr is not specified (it defaults to "INADDR_ANY"). It is supported, however, should you need to bind your VOTER clients to a specific IP interface on the server.


The port directive specifies the listening UDP port that chan_voter is listening on for incoming connections from clients. When clients power on, they attempt to contact the VOTER Server Address at the VOTER Server Port, defined in their on-board configuration settings. See VOTER Menus for further explanation of those configuration settings. This is the incoming port you may need to let through your firewall.


The password directive specifies the Host Password that needs to be configured in the VOTER client. This is the password for the server as a whole for the clients to authenticate with.


utos

Short for "Ubiquity Type of Service". When set, it will mark outbound packets (from the host to the client) with the ToS header flag of 0xC0. This is ToS precedence Level 6 or "Internetwork Control".


Used in traffic shaping. If your network is that congested that you need to shape traffic... you might have bigger issues. However, it doesn't hurt to flag the traffic when transiting the Internet to remote sites.


Note: As of VOTER/RTCM firmware >v2.00, the clients will automatically mark their outbound traffic (to the host) with the same flag. That can now be disabled by setting the appropriate Debug Option. Older versions of firmware (<2.00) did not flag the traffic by default, and required it to be enabled with the Debug Option.


sanity, puckit

These directives are really only for debugging.


sanity tells chan_voter to disable all sanity checks for clients. You would never want to do that in production.


puckit attempts to fix a problem with Garmin GPS pucks. Use at your own risk. Per Jim's notes in the source:

/* This is just a horrendous KLUDGE!! Some Garmin LVC-18 GPS "pucks"
 *sometimes* get EXACTLY 1 second off!! Some don't do it at all.
 Some do it constantly. Some just do it once in a while. In an attempt
 to be at least somewhat tolerant of such swine poo-poo, the "puckit"
 configuration flag may be set, which makes an attempt to deal with
 this problem by keeping a "time differential" for each client (compared
 with the "master") and applying it to time information within the protocol.
 Obviously, this SHOULD NEVER HAVE TO BE DONE. */


VOTER Instances

Within voter.conf, there may exist more than one instance. That is defined by a stanza that is not named [general], and is typically named for the node number it is associated with in rpt.conf.


This must match the name of the channel driver that is referenced from rpt.conf in the node definition there:

rxchannel = Voter/1999


It is not recommended to use anything other than numerical digits for the instance definition. Unpredictable results will happen (read, doesn't work).


This instance holds one or multiple client definitions that are associated with each other (ie. all operating on the same transmit/receive frequencies as part of the same repeater system).

[1999]				; define the 1999 instance stanza

Main = secret,transmit,master	; master - this client is the Master Timing source (the RTCM client that is on the same LAN as the Asterisk server.)
				; There can only be 1 Master Timing source per ENTIRE Asterisk server.
				; secret - password unique to this client
				; transmit - this client is intended to have transmit audio sent to it and will have a transmitter connected to it.

Remote = secret2		; satellite receiver site only 


The example above defines an instance named 1999, and has two clients defined, which are named Main and Remote.


Client Definition

Each client in an instance is defined by its client_name, followed by all the options that are associated with that particular client. A client is a particular VOTER/RTCM hardware device that is located somewhere, connected to Etherent and a radio, and is feeding receive audio to (and optionally receiving transmit audio from) the Asterisk host and the configured channel in rpt.conf through app_rpt.

Main = secret,transmit,master


The client_name (in this case "Main"), can be any alpha-numeric, non-breaking string, up to 50 characters in length. You probably want to keep it short, since you may need to type it on the Asterisk Console for debugging. You can use "_" in the name. This is the name that will be displayed on the Allmon/Supermon screens, when looking at voting clients.


The secret is a unique value for each client that must match the Client Password that is programmed into a particular VOTER/RTCM hardware device. This is how chan_voter determines which hardware client to associate with which client definition in the voter.conf file. The password may be up to 50 characters in length.


There must be one and only one client in the whole voter.conf file that has the master option set, regardless of how many instances are defined. This must be a VOTER/RTCM hardware device that is located on the same physical LAN (ie. same switch) that the Asterisk server resides on. This VOTER/RTCM does not necessarily need a radio attached to it (but that is common), but it does need a GPS. It does not need to be a transmitter, it can just be a receiver site, if desired. This is the client that chan_voter uses for master timing of all operations, and will be the reference timing source that all clients will be compared with. A master is not required in "General-purpose" or "Mixed Mode" client applications, where GPS is not required at all.


Client Options

In addition to the above, there are a number of options that can be associated with any client.


transmit

This client will have transmit audio sent to it by the channel driver. More than one client may have transmit audio sent to them, as in a simulcast application.


adpcm/nulaw

By default, audio is sent between the client and the host in G.711 Mulaw (aka ulaw) format. This is the default, if neither adpcm or nulaw options are associated with a client.


adpcm will configure this client to exchange audio in 8000 samples/sec, 4-bit, IMA ADPCM format.


nulaw will configure this client to exchange audio in 4000 samples/second Mulaw (Nulaw, as we call it), rather than the standard 8000 samples/second.


nodeemp

nodeemp tells this client 'not to perform de-emphasis of the receiver audio using the on-board hardware de-emphasis filter. This option manually switches the hardware de-emphasis OUT on the client. This is only to be used with non-voting clients.


hostdeemp

hostdeemp forces audio from this client to be sent through the host's DSP FIR Integrator providing de-emphasis at 8000 samples/sec. Normally, de-emphasis is done on the VOTER/RTCM hardware client before being sent to the host. This option is used in special applications only.


noplfilter

noplfilter tells this client not to pass the receive audio through the on-board hardware CTCSS filter. Normally, audio is filtered to remove any CTCSS tones on the VOTER/RTCM hardware client before being sent to the host. This option manually switches the hardware CTCSS filter OUT on the client.


buflen=value

buflen=value sets a specific receiver buffer length for this client. This option is used in special applications only.


gpsid=value

gpsid[=value] specifies a gps identity to associate with the specified client (as referred in the /etc/asterisk/gps.conf file). It is also used as the filename to create "GPS Work and Data Files" associated to the client. If no value is specified, default filenames are used. If a value is specified, it appends the supplied value to the filename with a "_".


This appears to be associated with app_gps, which can be used for reporting AllStarLink's position to APRS. Information on gps.conf can be found here. Sorry, better documentation is required on how to configure this option and how it works. Feel free to contribute!


prio=value

prio=value will define a specific priority for this client when voting. Lower numbers are higher priority. Default is 0 if nothing specified. This is normally not specified, and voting will take place based on the best RSSI from all clients. This option is used in special applications only.


Instance Options

plfilter = y			; use DSP IIR 6 pole High pass filter, 300 Hz corner with 0.5 db ripple (note clients filter PL by default already)
txctcss = 100.0			; Transmit CTCSS frequency
txctcsslevel = 62		; Transmit CTCSS level (default of 62 if txctcss is supplied, but txctcsslevel is not set)
txtoctype = phase		; Transmit tone control type: none,phase,notone
				; none - CTCSS tone encoding with no hang time (default)
				; phase - encode CTCSS and reverse phase (AKA "reverse burst") before unkeying TX
				; notone - encode CTCSS and stop sending tone before unkeying TX (AKA "chicken burst")

;gtxgain = 3.0			; adjust the audio gain to all transmitters (in db voltage gain)
;hostdeemp = 1			; force the use of the DSP FIR Integrator providing de-emphasis at 8000 samples/sec. Used with Duplex Mode 3 setting in RTCM/VOTER

thresholds = 255,110=5		;
; linger=6			; linger default is 6 if no other value specified
; streams = 67.215.233.178:1667 ; location to send voter data stream for this instance (used only with votemond Java program, which is deprecated)

; isprimary = y			; used in redundant server applications only. must be set on the primary server only
; primary = 10.20.20.1:667,mypaswd	; used in redundant server applications only. must be ONLY set on the secondary server to point to the primary