1SVXLINK.CONF(5) File Formats SVXLINK.CONF(5)
2
3
4
6 svxlink.conf - Configuration file for the SvxLink server
7
9 svxlink is a general purpose voice service system for ham radio use.
10 This man-page describe the SvxLink server configuration file format.
11
12 SvxLink look for configuration files in a number of places. First it
13 try to find a user specific configuration file. SvxLink will look for a
14 user specific configuration file in two places:
15 $HOME/.svxlink/svxlink.conf or $HOME/.svxlinkrc. The latter is depre‐
16 cated. Use the one that will best fit your need. If no user specific
17 configuration file can be found, SvxLink will look for the system wide
18 configuration file /etc/svxlink.conf. The --config command line option
19 may also be used to specify an arbitrary configuration file.
20
22 The configuration file is in the famous INI-file format. A generic
23 example of how such a file might look like is shown below.
24
25 [SECTION1]
26 VALUE1=1
27 VALUE2="TWO "
28 VAULE3="Multi "
29 "line"
30
31 [SECTION2]
32 VALUE1=2
33
34 This is a simple format that contain name=value pairs that belong to a
35 section. In written text, a specific configuration variable can be
36 referred to as SECTION1/VALUE2 meaning "configuration variable VALUE2
37 in section SECTION1".
38
39 The same variable name can exist in two different sections. For example
40 VALUE1 in section SECTION1 have the value 1 and VALUE1 in section SEC‐
41 TION2 have the value 2. Values containing spaces at the beginning or
42 end of the line must be surrounded by citation characters (see SEC‐
43 TION1/VALUE2). Likewise with a multi line value (see SECTION1/VALUE3).
44
46 Here is the description of all configuration variables that SvxLink
47 understands. The configuration variables are described section for sec‐
48 tion.
49
50 GLOBAL
51 The GLOBAL section contains application global configuration data.
52
53 MODULE_PATH
54 Specify where the SvxLink modules can be found. The default is
55 /usr/lib/svxlink
56
57 LOGICS Specify a comma separated list of logic cores that should be
58 created. The logic core is the thing that ties the transciever
59 and the voice services (modules) together. It contains the rules
60 for how the radio interface should be handled. The specified
61 name of a logic core must have a corresponding section specified
62 in the config file. This is where the behaviour of the logic
63 core is specified.
64
65 CFG_DIR
66 Specify the path to a directory that contain additional configu‐
67 ration files. If a relative path is specified, the path will be
68 relative to the directory where the main configuration file is
69 at. All files in the specified directory will be read as addi‐
70 tional configuration. Filenames starting with a dot are ignored.
71
72 TIMESTAMP_FORMAT
73 This variable specifies the format of the timestamp that is
74 written in front of each row in the log file. The format string
75 is in the same format as specified in the strftime(3) manual
76 page. The default is "%c" which is described as: "the preferred
77 date and time representation for the current locale". The envi‐
78 ronment variables LC_TIME, LC_ALL and LANG will affect how this
79 time format will look. For example, setting LC_TIME="sv_SE.UTF8"
80 will give you swedish timestamp representation. Other examples
81 of format specifiers are:
82
83 · %d - The day of the month as a decimal number (range 01 to
84 31)
85
86 · %b - The abbreviated month name according to the current
87 locale
88
89 · %Y - The year as a decimal number including the century
90
91 · %H - The hour as a decimal number using a 24-hour clock
92 (range 00 to 23)
93
94 · %M - The minute as a decimal number (range 00 to 59)
95
96 · %S - The second as a decimal number (range 00 to 61)
97
98 So, TIMESTAMP_FORMAT="%d %b %Y %H:%M:%S" would give a timestamp
99 looking something like: "29 Nov 2005 22:31:59".
100
101 CARD_SAMPLE_RATE
102 This configuration variable determines the sampling rate used
103 for audio input/output. SvxLink always work with a sampling rate
104 of 8kHz internally but there still are som benefits from using a
105 higher sampling rate. On some sound cards the filters look
106 pretty bad at 8kHz and the amplitude response will not be uni‐
107 form which among other things can cause problems for the soft‐
108 ware DTMF decoder.
109
110 Some sound cards also sound very bad at 8kHz due to insufficient
111 anti-alias filtering or resampling effects. These, often
112 cheeper, sound cards sound OK at 48kHz.
113
114 The downside of choosing a higher sampling rate is that it puts
115 a little bit more load on the CPU so if you have a very slow
116 machine (<300MHz), it might not have the computational power to
117 handle it.
118
119 Supported sampling rates are: 8000, 16000 and 48000.
120
121 Simplex Logic Section
122 The Simplex Logic section contains configuration data for a simplex
123 logic core. The SvxLink server can handle more than one logic core. The
124 name of the section, which in the example configuration file is Sim‐
125 plexLogic, must have a corresponding list item in the GLOBAL/LOGICS
126 config variable for this logic core to be activated. The name "Simplex‐
127 Logic" is not magic. It could be called what ever you want but it must
128 match the namespace name in the SimplexLogic.tcl script.
129
130 TYPE The type of logic core this is. In this case we are setting up a
131 simplex logic core so it should be set to "Simplex".
132
133 RX Specify the configuration section name of the receiver to use.
134 All configuration for the receiver is done in the specified con‐
135 figuration section.
136
137 TX Specify the configuration section name of the transmitter to
138 use. All configuration for the transmitter is done in the speci‐
139 fied configuration section.
140
141 MODULES
142 Specify a comma separated list of configuration sections for the
143 modules to load. This tells SvxLink which modules to actually
144 load on startup.
145
146 CALLSIGN
147 Specify the callsign that should be announced on the radio
148 interface.
149
150 SHORT_IDENT_INTERVAL
151 The number of minutes between short identifications. The purpose
152 of the short identification is to just announce that the station
153 is on the air. Typically just the callsign is transmitted. For a
154 repeater a good value is ten minutes and for a simplex node one
155 time every 60 minutes is probably enough. The LONG_IDENT_INTER‐
156 VAL must be an even multiple of the SHORT_IDENT_INTERVAL so if
157 LONG_IDENT_INTERVAL is 60 then the legal values for
158 SHORT_IDENT_INTERVAL are: 1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30,
159 60. If unset or set to 0, disable short identifications.
160
161 LONG_IDENT_INTERVAL
162 The number of minutes between long identifications. The purpose
163 of the long identification is to transmit some more information
164 about the station status (new voice mails etc). The time of day
165 is also transmitted. A good value here is 60 minutes. If unset
166 or set to 0, disable long identifications.
167
168 IDENT_ONLY_AFTER_TX
169 This feature controls when identification is done. By default,
170 identification is done every time the SHORT_IDENT_INTERVAL
171 expires. If this feature is enabled, identification will be done
172 only if there has been a recent transmission. This feature is
173 good for nodes using an RF link to provide echolink to a
174 repeater. Often, in this situation, it is not desirable for the
175 link to identify unless legally necessary. Note that
176 SHORT_IDENT_INTERVAL still have to be set for this feature to
177 work. That config variable will then be interpreted as the mini‐
178 mum number of seconds between identifications. The
179 LONG_IDENT_INTERVAL will not be affected by this parameter.
180
181 EXEC_CMD_ON_SQL_CLOSE
182 Specify a time, in milliseconds, after squelch close after which
183 entered DTMF digits will be executed as a command without the
184 need to send the # character. This really only is of use when
185 using a radio that it is difficult to send DTMF digits from,
186 like the Yaesu VX-2 handheld. The down side of enabling this
187 option is that the DTMF detection some times false trigger on
188 voice. This can cause interresting situations when all of a sud‐
189 den a module get activated in the middle of a QSO.
190
191 EVENT_HANDLER
192 Point out the TCL event handler script to use.
193
194 RGR_SOUND_DELAY
195 The number of milliseconds to wait after the squelch has been
196 closed before a roger beep is played. The beep can be disabled
197 by specifying a value of -1 or commenting out this line. Often
198 it is best to use the SQL_HANGTIME receiver configuration vari‐
199 able to specify a delay instead of specifying a delay here. This
200 configuration variable should then be set to 0.
201
202 REPORT_CTCSS
203 If set, will report the specified CTCSS frequency upon manual
204 identification (* pressed). It is possible to specify fractions
205 using "." as decimal comma. Disable this feature by commenting
206 out (#) this configuration variable.
207
208 TX_CTCSS
209 This configuration variable controls if a CTCSS tone should be
210 transmitted. There are two possible values: ALWAYS or SQL_OPEN.
211 The ALWAYS alternative will always add a CTCSS tone as soon as
212 the transmitter is turned on. The SQL_OPEN alternative will add
213 a CTCSS tone only when the squelch is open. For a simplex logic
214 the only sane value is ALWAYS. Commenting out this configura‐
215 tion variable will disable CTCSS transmit. The tone frequency
216 and level is configured in the transmitter configuration sec‐
217 tion.
218
219 MACROS Point out a section that contains the macros that should be used
220 by this logic core. See the section description for macros below
221 for more info.
222
223 LINKS Specify the name of a configuration section that contains logic
224 linking infomation. There is an example section in the default
225 configuration file called [LinkToR4]. Right now only one link
226 can be specified. A LINKS variable is only needed in the logic
227 that the link should be activated from.
228
229 FX_GAIN_NORMAL
230 The gain (dB) to use for audio effects and announcements when
231 there is no other traffic. This gain is normally set to 0dB
232 which means no gain or attenuation.
233
234 FX_GAIN_LOW
235 The gain (dB) to use for audio effects and announcements when
236 there is other traffic. This gain is normally set to something
237 like -12dB so that announcements and audio effects are attenu‐
238 ated when there is other traffic.
239
240 MUTE_RX_ON_TX
241 Set to 1 to mute the receiver when the transmitter is transmit‐
242 ting (default) or set it to 0 to make the RX active during
243 transmissions. One might want to set this to 0 if the link is
244 operating on a split frequency. Then the link can accept com‐
245 mands even when it's transmitting. The normal setting is 1, to
246 mute the RX when transmitting.
247
248 Repeater Logic Section
249 A Repeater Logic section contains configuration data for a repeater
250 logic core. The SvxLink server can handle more than one logic core. The
251 name of the section, which in the example configuration file is
252 RepeaterLogic, must have a corresponding list item in the GLOBAL/LOGICS
253 config variable for this logic core to be activated. The name
254 "RepeaterLogic" is not magic. It could be called what ever you want but
255 it must match the namespace name in the RepeaterLogic.tcl script.
256
257 TYPE The type of logic core this is. In this case we are setting up a
258 repeater logic core so it should be set to "Repeater".
259
260 RX Specify the configuration section name of the receiver to use.
261 All configuration for the receiver is done in the specified con‐
262 figuration section.
263
264 TX Specify the configuration section name of the transmitter to
265 use. All configuration for the transmitter is done in the speci‐
266 fied configuration section.
267
268 MODULES
269 Specify a comma separated list of configuration sections for the
270 modules to load. This tells SvxLink which modules to actually
271 load on startup.
272
273 CALLSIGN
274 Specify the callsign that should be announced on the radio
275 interface.
276
277 SHORT_IDENT_INTERVAL
278 The number of minutes between short identifications. The purpose
279 of the short identification is to just announce that the station
280 is on the air. Typically just the callsign is transmitted. For a
281 repeater a good value is ten minutes and for a simplex node one
282 time every 60 minutes is probably enough. The LONG_IDENT_INTER‐
283 VAL must be an even multiple of the SHORT_IDENT_INTERVAL so if
284 LONG_IDENT_INTERVAL is 60 then some of the legal values for
285 SHORT_IDENT_INTERVAL are: 5, 10, 15, 20, 30.
286
287 LONG_IDENT_INTERVAL
288 The number of minutes between long identifications. The purpose
289 of the long identification is to transmit some more info about
290 the station status (new voice mails etc). The time of day is
291 also transmitted. A good value here is 60 minutes. It must be
292 set to whole hours (60,120, 180 etc) otherwise the time of day
293 announcement will sound strange since it just announces the
294 hour.
295
296 EXEC_CMD_ON_SQL_CLOSE
297 Specify a time, in milliseconds, after squelch close after which
298 entered DTMF digits will be executed as a command without the
299 need to send the # character. This really only is of use when
300 using a radio that it is difficult to send DTMF digits from,
301 like the Yaesu VX-2 handheld. The down side of enabling this
302 option is that the DTMF detection some times false trigger on
303 voice. This can cause interresting situations when all of a sud‐
304 den a module gets activated.
305
306 EVENT_HANDLER
307 Point out the TCL event handler script to use.
308
309 NO_REPEAT
310 Set this to 1 if you do NOT want SvxLink to play back the incom‐
311 ing audio. This can be used when the received audio is directly
312 coupled by hardware wiring to the transmitter. What you win by
313 doing this is that there is zero delay on the repeated audio.
314 When the audio is routed through SvxLink there is always an
315 amount of delay. What you loose by doing this is the audio pro‐
316 cessing done by SvxLink.
317
318 IDLE_TIMEOUT
319 The number of seconds the repeater should have been idle before
320 turning the transmitter off.
321
322 OPEN_ON_1750
323 Use this configuration variable if it should be possible to open
324 the repeater with a 1750Hz tone burst. Specify the number of
325 milliseconds the tone must be asserted before the repeater is
326 opened. A value of 0 will disable 1750 Hz repeater opening.
327
328 OPEN_ON_CTCSS
329 Use this configuration variable if it should be possible to open
330 the repeater with a CTCSS tone (PL). The syntax of the value is
331 tone_fq:min_length. The tone frequency is specified in whole Hz
332 and the minimum tone length is specified in milliseconds. For
333 examples if a 136.5 Hz tone must be asserted for two seconds for
334 the repeater to open, the value 136:2000 should be specified.
335
336 OPEN_ON_DTMF
337 Use this configuration variable if it should be possible to open
338 the repeater with a DTMF digit. Only one digit can be specified.
339 DTMF digits pressed when the repeater is down will be ignored.
340
341 OPEN_ON_SQL
342 Use this configuration variable if it should be possible to open
343 the repeater just by keeping the squelch open for a while. The
344 value to set is the minimum number of milliseconds the squelch
345 must be open for the repeater to open.
346
347 OPEN_SQL_FLANK
348 Determines if OPEN_ON_SQL and OPEN_ON_CTCSS should activate the
349 repeater when the squelch open or close. If set to OPEN, the
350 repeater will activate and start retransmitting audio immedi‐
351 ately. No identification will be sent. If set to CLOSE, the
352 repeater will not activate until the squelch close. An identifi‐
353 cation will be sent in this case.
354
355 IDLE_SOUND_INTERVAL
356 When the repeater is idle, a sound is played. Specify the inter‐
357 val in milliseconds between playing the idle sound. An interval
358 of 0 disables the idle sound.
359
360 RGR_SOUND_DELAY
361 The number of milliseconds to wait after the squelch has been
362 closed before a roger beep is played. The beep can be disabled
363 by specifying a value of -1 or commenting out this line. Often
364 it is best to use the SQL_HANGTIME receiver configuration vari‐
365 able to specify a delay instead of specifying a delay here. This
366 configuration variable should then be set to 0.
367
368 REPORT_CTCSS
369 If set, will report the specified CTCSS frequency upon manual
370 identification (* pressed). It is possible to specify fractions
371 using "." as decimal comma. Disable this feature by commenting
372 out (#) this configuration variable.
373
374 TX_CTCSS
375 This configuration variable controls if a CTCSS tone should be
376 transmitted. There are two possible values: ALWAYS or SQL_OPEN.
377 The ALWAYS alternative will always add a CTCSS tone as soon as
378 the transmitter is turned on. The SQL_OPEN alternative will add
379 a CTCSS tone only when the squelch is open. Commenting out this
380 configuration variable will disable CTCSS transmit. The tone
381 frequency and level is configured in the transmitter configura‐
382 tion section.
383
384 MACROS Point out a section that contains the macros that should be used
385 by this logic core. See the section description for macros below
386 for more info.
387
388 LINKS Specify the name of a configuration section that contains logic
389 linking infomation. There is an example section in the default
390 configuration file called [LinkToR4]. Right now only one link
391 can be specified. A LINKS variable is only needed in the logic
392 that the link should be activated from.
393
394 FX_GAIN_NORMAL
395 The gain (dB) to use for audio effects and announcements when
396 there is no other traffic. This gain is normally set to 0dB
397 which means no gain or attenuation.
398
399 FX_GAIN_LOW
400 The gain (dB) to use for audio effects and announcements when
401 there is other traffic. This gain is normally set to something
402 like -12dB so that announcements and audio effects are attenu‐
403 ated when there is other traffic.
404
405 SQL_FLAP_SUP_MIN_TIME
406 Flapping squelch suppression is used to close the repeater down
407 if there is interference on the frequency that open the squelch
408 by short bursts. This configuration variable is used to specify
409 the minimum time, in milliseconds, that a transmission must last
410 to be classified as a real transmission. A good value is in
411 between 500-1000ms.
412
413 SQL_FLAP_SUP_MAX_COUNT
414 Flapping squelch suppression is used to close the repeater down
415 if there is interference on the frequency that open the squelch
416 by short bursts. This configuration variable is used to specify
417 the maximum number of consecutive short squelch openings allowed
418 before shutting the repeater down. A good value is in between
419 5-10.
420
421 ACTIVATE_MODULE_ON_LONG_CMD
422 This configuration variable activate a feature that might help
423 users not aware of the SvxLink command structure. The idea is to
424 activate the specified module when a long enough command has
425 been received. The typical example is an EchoLink user that is
426 used to just typing in the node ID and then the connection
427 should be established right away. Using this configuration vari‐
428 able, specify a minimum length and a module name. If no module
429 is active and at least the specified number of digits has been
430 entered, the given module is activated and the command is sent
431 to it. To be really useful this feature should be used in coop‐
432 eration with EXEC_CMD_ON_SQL_CLOSE.
433
434 For example, if this configuration variable is set to
435 "4:EchoLink" and the user types in 9999, the EchoLink module is
436 first activated and then the command 9999 is sent to it, which
437 will connect to the ECHOTEST server.
438
439 Macros Section
440 A macros section is used to declare macros that can be used by a logic
441 core. The logic core points out the macros section to use by using the
442 MACROS configuration variable. The name of the MACROS section can be
443 chosen arbitrarily as long as it match the MACROS configuration vari‐
444 able in the logic core configuration section. There could for example
445 exist both a [RepeaterLogicMacros] and a [SimplexLogicMacros] section.
446
447 A macro is a kind of shortcut that can be used to decrease the amount
448 of key presses that have to be done to connect to common EchoLink sta‐
449 tions for example. On the radio side, macros are activated by pressing
450 "D" "macro number" "#". A macros section can look something like the
451 example below. Note that the module name is case sensitive.
452
453 [Macros]
454 1=EchoLink:9999#
455 2=EchoLink:1234567#
456 9=Parrot:0123456789#
457
458 For example, pressing DTMF sequence "D1#" will activate the EchoLink
459 module and connect to the EchoTest conference node.
460
461 Logic Linking
462 A logic linking configuration section is used to specify information
463 for a link between two SvxLink logics. Such a link can for example be
464 used to connect a local repeater to a remote repeater using a separate
465 link transceiver. The link is activated/deactivated using DTMF com‐
466 mands. To be able to define two SvxLink logics, the computer must be
467 equipped with two sound cards. When the link is active, all audio
468 received by one logic will be transmitted by the other logic.
469
470 The name of the logic linking section can be chosen freely. In the
471 example configuration file there is a section called [LinkToR4]. To use
472 a logic linking section in a logic core it must be pointed out by the
473 LINKS configuration variable. So for example, RepeaterLogic/LINKS=Link‐
474 ToR4 would make it possible to connect the RepeaterLogic core to the
475 SimplexLogic core using a DTMF command.
476
477 Note: At the moment only locally received audio will be transmitted to
478 the other logic. EchoLink audio will for example not go through. This
479 will be fixed in a future release.
480
481 NAME The name of the link. The default action on activation/deactiva‐
482 tion of the link is to spell the value of this variable. In
483 other words, a callsign is a good value.
484
485 LOGIC1 The name of the first logic core that should be linked.
486
487 LOGIC2 The name of the second logic core that should be linked.
488
489 COMMAND
490 The command prefix to use to activate/deactivate this link. The
491 full command consists of one more digit that is either 0 or 1
492 where 0 means "deactivate" and 1 means "activate". If you for
493 example set COMMAND=94, the received DTMF command "941#" will
494 activate the link and "940#" will deactivate the link.
495
496 Local Receiver Section
497 A local receiver section is used to specify the configuration for a
498 receiver connected to the sound card. In the default configuration file
499 there is a Local configuration section called Rx1. The section name
500 could be anything. It should match the RX configuration variable in the
501 logic core where the receiver is to be used. The available configura‐
502 tion variables are described below.
503
504 TYPE Always "Local" for a local receiver.
505
506 AUDIO_DEV
507 Specify the audio device to use. Normally /dev/dsp.
508
509 AUDIO_CHANNEL
510 Specify the audio channel to use. SvxLink can use the left/right
511 stereo channels as two mono channels. Legal values are 0 or 1.
512
513 SQL_DET
514 Specify the type of squelch detector to use. Possible values
515 are: VOX, CTCSS, SERIAL or SIGLEV. The VOX squelch detector
516 determines if there is a signal present by calculating a mean
517 value of the sound samples. The VOX squelch detector behaviour
518 is adjusted with VOX_FILTER_DEPTH and VOX_LIMIT.
519
520 The CTCSS squelch detector checks for the precense of a tone
521 with the specified frequency. The tone frequency is specified
522 using the CTCSS_FQ config variable. The required level is spec‐
523 ified using the CTCSS_THRESH config variable.
524
525 The SERIAL squelch detector use a pin in a serial port to detect
526 if the squelch is open. This squelch detector can be used if the
527 receiver have an external hardware indicator of when the squelch
528 is open. Specify which serial port/pin to use with SERIAL_PORT
529 and SERIAL_PIN.
530
531 The SIGLEV (signal level) squelch detector use a simple algo‐
532 rithm to determine the strength of the incoming signal. The
533 detector must first be calibrated using the SIGLEV_SLOPE and
534 SIGLEV_OFFSET configuration variables. Then the
535 SIGLEV_OPEN_THRESH and SIGLEV_CLOSE_THRESH configuration vari‐
536 ables can be used to set the open and close thresholds. Since
537 the detector is not perfect (it's affected by speech) you will
538 also want to setup SQL_HANGTIME to prevent it from closing in
539 the middle of a transmission. A value between 100-300ms is prob‐
540 ably what you need. If using this squelch type in cooperation
541 with a voter, you'll also probably need to setup SQL_DELAY to
542 get correct signal level measurements. A value of about 40ms
543 seems to be OK. Note that the SIGLEV squelch will only work with
544 unsquelched input.
545
546 SQL_START_DELAY
547 The squelch start delay is of most use when using VOX squelch.
548 For example, if the transceiver makes a noise when the transmit‐
549 ter is turned off, that might trigger the VOX and cause an infi‐
550 nite loop of squelch open/close transmitter on/off. Specify the
551 number of milliseconds that the squelch should be "deaf" after
552 the transmitter has been turned off.
553
554 SQL_DELAY
555 Specify a delay in milliseconds that a squelch open indication
556 will be delayed. This odd feature can be of use when using a
557 fast squelch detector in combination with the signal level
558 detector. A squelch delay will allow the signal level detector
559 to do its work before an indication of squelch open is sent to
560 the logic core. A delay might be needed when using the voter to
561 choose among multiple receivers. A normal value could be some‐
562 where in between 20-100ms.
563
564 SQL_HANGTIME
565 How long, in milliseconds, the squelch will stay open after the
566 detector has indicated that it is closed. This configuration
567 variable will affect all squelch detector types.
568
569 SQL_TIMEOUT
570 Use this configuration variable to set an upper limiti, in sec‐
571 onds, for how long the squelch is allowed to be open. If the
572 timeout value is exceeded the squelch is forced to closed. If
573 the squelch close for real, everthing is back to normal. When it
574 opens the next time a squelch open will be signalled. For exam‐
575 ple, use this feature to make sure that a faulty receiver cannot
576 block the system indefinitly.
577
578 VOX_FILTER_DEPTH
579 The number of milliseconds to create the mean value over. A
580 small value will make the vox react quicker (<200) and larger
581 values will make it a little bit more sluggish. A small value is
582 often better.
583
584 VOX_LIMIT
585 The threshold that the mean value of the samples must exceed for
586 the squlech to be considered open. It's hard to say what is a
587 good value. Something around 1000 is probably a good value. Set
588 it as low as possible without getting the vox to false trigger.
589
590 CTCSS_FQ
591 If CTCSS (PL,subtone) squelch is used (SQL_DET is set to CTCSS),
592 this config variable sets the frequency of the tone to use. The
593 tone frequency ranges from 67.0 to 254.1 Hz. The detector is not
594 very exact so it will detect tones that is near the specified
595 tone. Only whole Hz can be specifid so the value should be in
596 the range 67 to 254 Hz.
597
598 CTCSS_THRESH
599 If CTCSS (PL, subtone) squelch is used (SQL_DET is set to
600 CTCSS), this config variable sets the required tone level to
601 indicate squelch open. The value is some kind of strange signal
602 to noise dB value. Don't try to make any sense out of it though.
603 Higher values will require a higher level and lower values will
604 cause the squelch to open easier. A normal value is -5.
605
606 SERIAL_PORT
607 If SQL_DET is set to SERIAL, this config variable determines
608 which serial port should be used for hardware squelch input (COS
609 - Carrier Operated Squelch). Note: If the same serial port is
610 used for the PTT, make sure you specify exactly the same device
611 name. Otherwise the RX and TX will not be able to share the
612 port. Example: SQL_PORT=/dev/ttyS0
613
614 SERIAL_PIN
615 If SQL_DET is set to SERIAL, this config variable determines
616 which pin in the serial port that should be used for hardware
617 squelch input (COS - Carrier Operated Squelch). It is possible
618 to use the DCD, CTS, DSR or RI pin. The squelch-open-level must
619 also be specified. This is done using the syntax
620 SQL_PIN=PIN:LEVEL, where PIN is one of the pins above and LEVEL
621 is either SET or CLEAR. Example: SQL_PIN=CTS:SET
622
623 SIGLEV_SLOPE
624 The slope (or gain) of the signal level detector. See chapter
625 CALIBRATING THE SIGNAL LEVEL DETECTOR below for more informa‐
626 tion.
627
628 SIGLEV_OFFSET
629 The offset of the signal level detector. See chapter CALIBRATING
630 THE SIGNAL LEVEL DETECTOR below for more information.
631
632 SIGLEV_OPEN_THRESH
633 This is the squelch open threshold for the SIGLEV squelch detec‐
634 tor. Make sure to first calibrate the signal level detector
635 using the SIGLEV_SLOPE and SIGLEV_OFFSET configuration vari‐
636 ables. The signal level detector should normally be calibrated
637 so that full signal strength is 100 and no signal is 0. Depend‐
638 ing on your background noise level a good value for this config‐
639 uration variable is between 5 and 20.
640
641 SIGLEV_CLOSE_THRESH
642 This is the squelch close threshold for the SIGLEV squelch
643 detector. Make sure to first calibrate the signal level detector
644 using the SIGLEV_SLOPE and SIGLEV_OFFSET configuration vari‐
645 ables. The signal level detector should normally be calibrated
646 so that full signal strength is 100 and no signal is 0. Depend‐
647 ing on your background noise level a good value for this config‐
648 uration variable is between 1 and 10.
649
650 DEEMPHASIS
651 Apply a deemphasis filter on received audio. The deemphasis fil‐
652 ter is used when taking audio directly from the detector in the
653 receiver, like when using a 9k6 packet radio connector. If not
654 using a deemphasis filter the high frequencies will be amplified
655 resulting in a very bright (tinny) sound.
656
657 SQL_TAIL_ELIM
658 Squelch tail elimination is used to remove noise from the end of
659 a received transmission. This is of most use when using CTCSS or
660 SILEV squelch with unsquelched input audio. A normal value is a
661 couple of hundred milliseconds. Note that the audio will be
662 delayed by the same amount of milliseconds. This does not matter
663 much for a simplex link but for a repeater the delay might be
664 annoying since you risk hearing the end of your own transmis‐
665 sion.
666
667 PREAMP The incoming signal will be amplified by the specified number of
668 dB. This can be used as a last measure if the input audio level
669 can't be set high enough on the analogue side. A value of 6dB
670 will double the signal level. Note that this is a digital ampli‐
671 fication. Hence it will reduce the dynamic range of the signal
672 so usage should be avoided if possible. It's always better to
673 correct the audio level before sampling it.
674
675 PEAK_METER
676 This is a help to adjust the incoming audio level. If enabled it
677 will output a message when distorsion occurs. To adjust the
678 audio level, first open the squelch. Then increase the audio
679 level until warning messages are printed. Decrease the audio
680 level until no warning messages are printed. After the adjust‐
681 ment has been done, the peak meter can be disabled. 0=disabled,
682 1=enabled.
683
684 DTMF_DEC_TYPE
685 Specify the DTMF decoder type. Set it to INTERNAL to use the
686 internal software DTMF decoder. To use the S54S interface fea‐
687 turing a hardware DTMF decoder, set it to S54S.
688
689 DTMF_MUTING
690 Mute the audio during the time when a DTMF digit is being
691 received. Note that the audio will be delayed 50ms to give the
692 DTMF detector time to do its work. This does not matter much on
693 a simplex link but on a repeater it could be annoying. Legal
694 values are 0=disabled, 1=enabled.
695
696 DTMF_HANGTIME
697 This configuration variable can be used if the DTMF decoder is
698 too quick to indicate digit idle. That does not matter at high
699 signal strengths but for weaker signals and mobile flutter it's
700 not good at all. Each DTMF digit will be detected multiple
701 times. Using this configuration variable, the time (ms) a tone
702 must be missing to be indicated as off can be extended. Setting
703 this value too high will cause the decoder to be a bit sluggish
704 and it might consider two digits as one. The hang time only
705 affect consecutive digits of the same value (e.g. 1 1). If a
706 detected digit differs from the previously detected digit (e.g 1
707 2), the hang time is immediately canceled and the detected digit
708 is considered as a new one. A good default value is 50-100ms.
709
710 DTMF_SERIAL
711 When using an external hardware DTMF decoder this config vari‐
712 able is used to specify a serial port (e.g. /dev/ttyS0).
713
714 DTMF_MAX_FWD_TWIST
715 DTMF use two tones to encode digits 0-9, A-F. These two tones
716 should normally have the sample amplitude. The difference in
717 amplitude is called twist. Forward twist is when the higher fre‐
718 quency tone is lower in amplitude than the lower frequency tone.
719 According to the standards, 8dB forward twist should be allowed.
720 Some transmitters do not correctly modulate the DTMF tones to
721 get zero twist. The most common situation is that the forward
722 twist is too large. Increasing this configuration variable above
723 8dB might allow DTMF from these transmitters to be detected.
724 When doing this, the DTMF detector will be more sensitive to
725 noise and might cause more false triggers.
726
727 DTMF_MAX_REV_TWIST
728 DTMF use two tones to encode digits 0-9, A-F. These two tones
729 should normally have the sample amplitude. The difference in
730 amplitude is called twist. Reverse twist is when the lower fre‐
731 quency tone is lower in amplitude than the higher frequency
732 tone. According to the standards, 4dB reverse twist should be
733 allowed. The most common reason for getting reverse twist is a
734 bad de-emphasis filter or that none at all is used, like when
735 taking audio directly from the FM discriminator. Have a look at
736 the DEEMPHASIS configuration variable before starting to modify
737 this configuration variable.
738
739 Voter Section
740 Receiver type "Voter" is a "receiver" that combines multiple receivers
741 and selects one of them to take audio from when the squelch opens.
742 Which receiver to use is selected directly after squelch open. Another
743 selection is not done until the selected receivers squelch is closed
744 and another receivers squelch is opened. In the default configuration
745 file there is a voter section called Voter.
746
747 TYPE Always "Voter" for a voter.
748
749 RECEIVERS
750 Specify a comma separated list of receivers that the voter
751 should use. Example: RECEIVERS=Rx1,Rx2,Rx3
752
753 VOTING_DELAY
754 Specify the delay in milliseconds that the voter will wait after
755 the first sqeulch open detection until the decision of which
756 receiver to use is made. This time must be set sufficiently high
757 to allow all receivers to calculate and report the signal level.
758 Incoming audio and DTMF digits will be buffered for all
759 receivers during the delay time so nothing will be lost. But of
760 course the audio will be delayed the specified amount of time.
761 This is most noticeble when using a repeater logic. Use the BUF‐
762 FER_LENGTH configuration variable to adjust the buffer length.
763
764 BUFFER_LENGTH
765 Use this configuration variable to adjust the length of the vot‐
766 ing delay buffer. If not specified, the buffer length will be
767 the same as the voting delay. When using the voter with a
768 repeater logic, try to keep this variable at 0 to reduce the
769 latency. Only increase it if you feel audio is lost in the
770 beginning of transmissions.
771
772 Networked Receiver Section
773 A networked receiver section is used to specify the configuration for a
774 receiver connected through a TCP/IP network. In the default configura‐
775 tion file there is a networked receiver configuration section called
776 NetRx. The section name could be anything. It should match the RX con‐
777 figuration variable in the logic core where the receiver is to be used.
778 The available configuration variables are described below. How to use a
779 networked receiver is further described in the remotetrx(1) manual
780 page.
781
782 TYPE Always "Net" for a networked receiver.
783
784 HOST The hostname or IP address of the remote receiver host.
785
786 AUTH_KEY
787 This is the authentication key (password) to use to connect to
788 the RemoteTrx server. The same key have to be specified in the
789 RemoteTrx configuration. If no key is specified in the
790 RemoteTrx config, the login will be unauthenticated. A good
791 authentication key should be 20 characters long. If the same
792 RemoteTrx is used for both RX and TX, the same key must be spec‐
793 ified in the RX as well as in the TX configuration section. The
794 key will never be transmitted over the network. A HMAC-SHA1
795 challenge-response procedure will be used for authentication.
796
797 CODEC The audio codec to use when transfering audio from this remote
798 receiver. Available codecs are: RAW (256kbps), S16 (128kbps),
799 GSM (13.2kbps), SPEEX (4-25kbps). These are raw bitrate values.
800 There will be some overhead added to this so the real bitrates
801 on the wire are a little bit higher.
802
803 SPEEX_ENC_FRAMES_PER_PACKET
804 Speex encoder setting. Each Speex frame contains 20ms audio. If
805 using a low bitrate configuration, the network overhead will be
806 quite noticeable if sending each frame in its own packet. One
807 way to lower the overhead is to send multiple frames in each
808 network packet. The drawback with doing this is that you get
809 more delay. If setting this option to something like 4
810 (default), the delay will be about 4x20=80ms.
811
812 SPEEX_ENC_QUALITY
813 Speex encoder setting. Specify the encoder quality using a num‐
814 ber between 0-10. Lower values give poorer quality and lower
815 bitrates.
816
817 SPEEX_ENC_BITRATE
818 Speex encoder setting. Specify the bitrate to use. Speex will
819 snap to the nearest lower possible bitrate. Possible values
820 range from 2150 to 24600 bps. You should probably not specify
821 quality at the same time as bitrate. Not sure though...
822
823 SPEEX_ENC_COMPLEXITY
824 Speex encoder setting. The complexity setting (0-10) tells the
825 encoder how much CPU time it should spend on doing a good job.
826 The difference in SNR between the lowest and highest value is
827 about 2dB. Set it as high as possible without overloading the
828 CPU on the encoding computer (check CPU usage using command
829 "top").
830
831 SPEEX_ENC_VBR
832 Speex encoder setting. Enable (1) or disable (0) variable
833 bitrate encoding. If enabled, the encoder will try to keep a
834 constant quality by increasing the bitrate when needed.
835
836 SPEEX_ENC_VBR_QUALITY
837 Speex encoder setting. The quality (0-10) to use in variable
838 bitrate mode.
839
840 SPEEX_ENC_ABR
841 Speex encoder setting. The average bitrate encoding will try to
842 keep a target bitrate by continously adjusting the quality. This
843 configuration variable specify the target bitrate and enable
844 ABR. It also need to have VBR enabled so don't force it to off.
845
846 SPEEX_DEC_ENHANCER
847 Speex decoder setting. Enable (1) or disable (0) the perceptual
848 enhancer in the decoder. Perceptual enhancement is a part of
849 the decoder which, when turned on, attempts to reduce the per‐
850 ception of the noise/distortion produced by the encoding/decod‐
851 ing process. In most cases, perceptual enhancement brings the
852 sound further from the original objectively (e.g. considering
853 only SNR), but in the end it still sounds better (subjective
854 improvement).
855
856 Local Transmitter Section
857 A local transmitter section is used to specify the configuration for a
858 local transmitter. In the default configuration file there is a config‐
859 uration section called Tx1. The section name could be anything. It
860 should match the TX configuration variable in the logic core where the
861 transmitter is to be used. The available configuration variables are
862 described below.
863
864 TYPE Always "Local" for a local transmitter.
865
866 AUDIO_DEV
867 Specify the audio device to use. Normally /dev/dsp.
868
869 AUDIO_CHANNEL
870 Specify the audio channel to use. SvxLink can use the left/right
871 stereo channels as two mono channels. Legal values are 0 or 1.
872
873 PTT_PORT
874 Specify the serial port that the PTT is connected to. E.g.
875 /dev/ttyS0 for COM1.
876
877 PTT_PIN
878 Specify the pin(s) in the serial port that the PTT is connected
879 to. It is possible to specify one or two pins. Some interface
880 boards require that you specify two pins since one pin does not
881 provide enough drive power to the circuit. A "!" in front of the
882 pin name indicates inverted operation. Some of the possible val‐
883 ues are RTS, DTRRTS, !DTR!RTS or even DTR!RTS.
884
885 TIMEOUT
886 This is a feature that will prevent the transmitter from getting
887 stuck transmitting. Specify the number of seconds before the
888 transmitter is turned off. Note that this is a low level secu‐
889 rity mechanism that is meant to only kick in if there is a soft‐
890 ware bug in SvxLink. Just so that the transmitter will not
891 transmit indefinately. It is not meant to be used to keep people
892 from talking too long.
893
894 TX_DELAY
895 The number of milliseconds (0-1000) to wait after the transmit‐
896 ter has been turned on until audio is starting to be transmit‐
897 ted. This can be used to compensate for slow TX reaction or
898 remote stations with slow reacting squelches.
899
900 CTCSS_FQ
901 The frequency in Hz of the CTCSS tone to transmit. It is possi‐
902 ble to specify fractions using "." as decimal comma (e.g.
903 136.5). For the tone to be transmitted the CTCSS_LEVEL variable
904 must also be setup and also the TX_CTCSS variable in the logic
905 core configuration section.
906
907 CTCSS_LEVEL
908 The level in percent (0-100) of the CTCSS tone to transmit. What
909 level to set is hard to say. The FM modulation swing of the tone
910 should be in between 500-800 Hz. That is a bit hard to measure
911 if you don't have the right equipment. A normal FM station have
912 a maximum swing of 5kHz so if you manage to calibrate everything
913 so that you get maximum swing when the sound card audio is at
914 peak level, the tone level should be in between 10-16%. However,
915 most often the audio settings are configured a bit higher than
916 max since the audio seldom reaches maximum level. Then the level
917 of the CTCSS tone should be reduced. The default in the configu‐
918 ration file is 9%. For the tone to be transmitted the CTCSS_FQ
919 variable must also be setup and also the TX_CTCSS variable in
920 the logic core configuration section.
921
922 Note: The level of the tone affects the level of the rest of the
923 audio in SvxLink. This is to avoid distorision when the two
924 audio streams are mixed together. For example, if a tone level
925 of 9% is setup the rest of the audio will be attenuated by 9%.
926 This is true even if the CTCSS_FQ and TX_CTCSS configuration
927 variables are not set so comment this configuration variable out
928 if CTCSS on TX is not used.
929
930 PREEMPHASIS
931 [EXPERIMENTAL] Enable this feature if you are modulating the FM
932 modulator directly, like through a 9k6 packet radio input. If no
933 preemphasis filter is applied to the audio, it will sound very
934 dark when received. If you modulate the transmitter through the
935 microphone input the radio will apply a preemphasis filter so
936 this feature should be disabled. 0=disabled, 1=enabled.
937
938 DTMF_TONE_LENGTH
939 The length, in milliseconds, of DTMF digits transmitted on this
940 transmitter. 100ms is the default.
941
942 DTMF_TONE_SPACING
943 The spacing, in milliseconds, between DTMF digits transmitted on
944 this transmitter. 50ms is the default.
945
946 DTMF_TONE_AMP
947 The amplitude, in dB, of DTMF digits transmitted on this trans‐
948 mitter. Zero dB is the maximum amplitude. -18dB is the default.
949
950 Networked Transmitter Section
951 A networked transmitter section is used to specify the configuration
952 for a transmitter connected through a TCP/IP network. In the default
953 configuration file there is a networked transceiver configuration sec‐
954 tion called NetTx. The section name could be anything. It should match
955 the TX configuration variable in the logic core where the transmitter
956 is to be used. The available configuration variables are described
957 below. How to use a networked transmitter is further described in the
958 remotetrx(1) manual page.
959
960 TYPE Always "Net" for a networked transmitter.
961
962 HOST The hostname or IP address of the remote transmitter host.
963
964 AUTH_KEY
965 This is the authentication key (password) to use to connect to
966 the RemoteTrx server. The same key have to be specified in the
967 RemoteTrx configuration. If no key is specified in the
968 RemoteTrx config, the login will be unauthenticated. A good
969 authentication key should be 20 characters long. If the same
970 RemoteTrx is used for both RX and TX, the same key must be spec‐
971 ified in the RX as well as in the TX configuration section. The
972 key will never be transmitted over the network. A HMAC-SHA1
973 challenge-response procedure will be used for authentication.
974
975 CODEC The audio codec to use when transfering audio to this remote
976 transmitter. Available codecs are: RAW (256kbps), S16
977 (128kbps), GSM (13.2kbps), SPEEX (4-25kbps). These are raw
978 bitrate values. There will be some overhead added to this so the
979 real bitrates on the wire are a little bit higher.
980
981 SPEEX_ENC_FRAMES_PER_PACKET
982 Speex encoder setting. Each Speex frame contains 20ms audio. If
983 using a low bitrate configuration, the network overhead will be
984 quite noticeable if sending each frame in its own packet. One
985 way to lower the overhead is to send multiple frames in each
986 network packet. The drawback with doing this is that you get
987 more delay. If setting this option to something like 4
988 (default), the delay will be about 4x20=80ms.
989
990 SPEEX_ENC_QUALITY
991 Speex encoder setting. Specify the encoder quality using a num‐
992 ber between 0-10. Lower values give poorer quality and lower
993 bitrates.
994
995 SPEEX_ENC_BITRATE
996 Speex encoder setting. Specify the bitrate to use. Speex will
997 snap to the nearest lower possible bitrate. Possible values
998 range from 2150 to 24600 bps. You should probably not specify
999 quality at the same time as bitrate. Not sure though...
1000
1001 SPEEX_ENC_COMPLEXITY
1002 Speex encoder setting. The complexity setting (0-10) tells the
1003 encoder how much CPU time it should spend on doing a good job.
1004 The difference in SNR between the lowest and highest value is
1005 about 2dB. Set it as high as possible without overloading the
1006 CPU on the encoding computer (check CPU usage using command
1007 "top").
1008
1009 SPEEX_ENC_VBR
1010 Speex encoder setting. Enable (1) or disable (0) variable
1011 bitrate encoding. If enabled, the encoder will try to keep a
1012 constant quality by increasing the bitrate when needed.
1013
1014 SPEEX_ENC_VBR_QUALITY
1015 Speex encoder setting. The quality (0-10) to use in variable
1016 bitrate mode.
1017
1018 SPEEX_ENC_ABR
1019 Speex encoder setting. The average bitrate encoding will try to
1020 keep a target bitrate by continously adjusting the quality. This
1021 configuration variable specify the target bitrate and enable
1022 ABR. It also need to have VBR enabled so don't force it to off.
1023
1024 SPEEX_DEC_ENHANCER
1025 Speex decoder setting. Enable (1) or disable (0) the perceptual
1026 enhancer in the decoder. Perceptual enhancement is a part of
1027 the decoder which, when turned on, attempts to reduce the per‐
1028 ception of the noise/distortion produced by the encoding/decod‐
1029 ing process. In most cases, perceptual enhancement brings the
1030 sound further from the original objectively (e.g. considering
1031 only SNR), but in the end it still sounds better (subjective
1032 improvement).
1033
1034 Module Section
1035 A module section contain the configuration for a specific module. It
1036 have some general configuration variables and some module specific con‐
1037 figuration variables. The general configuration variables are listed
1038 below.
1039
1040 NAME The name of the module. This name must match the namespace used
1041 in the TCL event handling script. If not set, NAME will be set
1042 to the section name.
1043
1044 PLUGIN_NAME
1045 The base name of the plugin. For example if this configuration
1046 variable is set to Foo, the core will look for a plugin called
1047 ModuleFoo.so. If not set, PLUGIN_NAME will be set to the same
1048 value as NAME.
1049
1050 ID Specify the module identification number. This is the number
1051 used to access the module from the radio interface.
1052
1053 TIMEOUT
1054 Specify the timeout time, in seconds, after which a module will
1055 be automatically deactivated if there has been no activity.
1056
1057 Module specific configuration variables are described in the man page
1058 for that module. The documentation for the Parrot module can for exam‐
1059 ple be found in the ModuleParrot.conf(5) manual page.
1060
1062 The signal level detector is used when using multiple receivers or when
1063 using the SIGLEV squelch. The signal level is used by a voter to choose
1064 the receiver with the highest signal strength. The choice is made
1065 directly after squelch open. For the voter to make a correct choice,
1066 the signal level detector must be calibrated on each receiver.
1067
1068 There are two configuration variables that is used to calibrate the
1069 detector. They are SIGLEV_SLOPE and SIGLEV_OFFSET in a local receiver
1070 section. The slope is the gain of the detector and the offset is used
1071 to adjust the detector so that when there is no input signal, the
1072 detector will return 0. The goal is to adjust the detector so that when
1073 no signal is received, a value of 0 is produced and when full signal
1074 strength is received, a value of 100 is produced. It will never be
1075 exakt but that does not matter.
1076
1077 The calibration is normally done by using the siglevdetcal(1) applica‐
1078 tion. To be able to do a correct calibration, it must be possible to
1079 open the squelch so that only noise is received. The antenna cable
1080 should be disconnected or a dummy load should be used. WARNING: Before
1081 starting the siglevdetcal application, pull the PTT cable since the PTT
1082 might get triggered during the calibration procedure.
1083
1084 If the siglevdetcal application cannot be used for some reason, the
1085 manual procedure below might be used. However, this procedure will only
1086 work for a receiver with unsquelched audio. Note: To calibrate a
1087 remote receiver it must be connected to the SvxLink server. Otherwise
1088 the squelch will not open.
1089
1090 1 Connect a dummy load or disconnect the antenna from the
1091 transceiver. If you disconnect the antenna, make sure to
1092 also disconnect the PTT.
1093
1094 2 Set SIGLEV_SLOPE=1 and SIGLEV_OFFSET=0 and restart SvxLink.
1095
1096 3 Open the squelch so that there is only noise coming into
1097 SvxLink.
1098
1099 4 Use a second transceiver to make a short, unmodulated trans‐
1100 mission. Release the PTT when the "Squech OPEN" message is
1101 printed. Repeat this for about five times.
1102
1103 5 Calculate the mean diff (open level - close level) and the
1104 mean lower (squelch close) value. Make sure to use at least
1105 four significant digits in your calculations.
1106
1107 6 SIGLEV_SLOPE = 100 / (mean diff)
1108
1109 7 SIGLEV_OFFSET = - (mean lower) * SIGLEV_SLOPE
1110
1111 8 After changing SIGLEV_SLOPE and SIGLEV_OFFSET, restart
1112 SvxLink and check to see that the squelch open value is now
1113 around 100 and the squelch close value is around 0.
1114
1116 /etc/svxlink.conf
1117 The system wide configuration file.
1118
1119 ~/.svxlink/svxlink.conf or ~/.svxlinkrc
1120 Per user configuration file.
1121
1122 /etc/svxlink.d/*
1123 Additional configuration files. Typically one configuration file
1124 per module.
1125
1127 Tobias Blomberg (SM0SVX) <sm0svx at users dot sourceforge dot net>
1128
1130 svxlink(1), remotetrx(1), siglevdetcal(1)
1131
1132
1133
1134Linux APRIL 2008 SVXLINK.CONF(5)