System Software
To control the receiver a set of system software has been developed to allow tuner registers and PLLs to be programmed remotely. This software includes a tuner control library with appropriate register mapping, a command line tuner control tool for testing, a tuner control service for status generation and state monitoring, a tuner remote control cgi program, and a python class for remote interface to the tuner from other applications.
Building the tuner control software
The tuner control software is built using the associated Makefile. It is important to make sure that the #define LTUNER_DEBUG_MODE 1 is not defined for use with the actual hardware. The software is built using the nios2-gcc tool chain and it is very important that the stack size be greater than the memory allocated on it in the programs which are compiled. A typical command line for compiling manually looks as follows assuming that libtuner is in the same build directory as the compiled program. Here we have set the stack size to 32k : nios2-linux-gcc -o tcr midasm_tcr.c libtuner.c -I. -DUHF_TUNER_REV1 -lrt -elf2flt="-s 32768"
libtuner
The libtuner provides a generic interface and framework for the tuners designed with a register based control architecture on the NIOS2. The firmware registers defined in the nios2 processor are assumed to be Altera Avalon PIO components which can be directly written and/or read as appropriate.
The libtuner defines a set of base registers for every tuner. These registers may be divided up into a number of offset registers which allow multiple control registers to logically divide a single base register. Base registers have an address defined by the firmware in the Altera nios2 SOPC builder. Offset registers have a direction, alignment, and bit width. Tuner controls are defined to associate a name and default value with an offset register. The tuner control is the basis of the logical organization of the tuner and the defined name is used to identify a register for software control. The libtuner also defines a phase locked loop control type appropriate for control of the Synergy microwave PLLs and the library supports bit banging programming of this tuner series. An overall tuner structure supports all the registers and PLLs associated with a given hardware device. The particular tuner is selected using a command line flag and the details of the tuners available are defined in the midasm_tuners.h file. The tuner defined in the midasm_tuners.h file must have a register mapping which corresponds both to the firmware and hardware configuration of the receiver. In general the tuners are defined by statically allocated arrays. The libtuner supports an API for control of the registers and PLLs in a generic manner using the control names as the key for selecting correct locations to write to and read from.
When writing registers the libtuner methods have the option to persist existing state. This preserves the underlying state of the base register for bits which are not being modified. In general this is the correct way to use the control registers. It is sometimes useful to not do this during debugging. When persist is not used the the underlying base register will be cleared in the bits which are not being directly modified by the offset register. This can cause the tuner state to become incorrect if this is not intended.
Tuner Command Line
The tuner command line (tcmd) provides a means of directly programming receiver control registers and PLLs from the command prompt. The program can either write directly to the hardware memory or communicate the commands to the Tuner Control Service via a posix message queue interface. The later is useful for testing the functionality of the tuner control service. The general method is to use a register or PLL name to set a value associated with that control. The program may request the register status which will print out a full list of all known registers and PLL names along with the values set during the last invocation of the program.
Note values set to the hardware in one execution of the program are not retained for the next execution of the program. The hardware itself is not a stateful register. That is done at the software level and is the reason a tuner service program exists.
The tcmd program has the following options:
MIDAS-M RF Tuner Test Program
revision $Id: midasm_tcmd.c 48 2008-01-23 21:29:35Z flind $
usage : tuner_tester [-v] [-p] [-r] [{-c "<control> <hex value>"}] [{-f "<pll> <frequency>"}] [-s] [-h]
-v provides verbose debugging output as registers are set and read.
-p maintains a persistent value for registers. This should in general be used.
-r remote mode using the posix message queue interface. The tuner control service must be running.
-c set the named <control> register with the provided <hex value>. This is the means to set a register value.
-f set the named <pll> phase locked loop to the provided <frequency> in Hz. Scientific format is okay so 314.0E6 will set 314 MHz.
-s provide a printout of the register status. This should be done after setting registers and plls to provide a list of the values which are set.
-h print the usage shown above.
A typical example of usage is as follows
bin/tcmd -p -c "a_s0_noise_enable 0x0" -c "a_s0_lo_enable 0x1" -c "a_s0_lo_select 0x0" -c "a_s0_rf_path 0x0" -c "a_s0_rf_output 0x1" -c "a_s0_rf_input 0xB" -c "a_s0_attenuator 0x0" -f "pll_a 314E6" -s
Assuming a common directory for all files. The software can be compiled manually using the following command
nios2-linux-gcc -o tcmd midasm_tcmd.c libtuner.c -I. -DUHF_TUNER_REV1 -lrt -elf2flt="-s 32000"
Tuner Control Service
The Tuner Control Service (tcs) provides for a service which maintains and reports the state of the receiver registers and PLLs. This service provides a posix message queue interface that allows registers to be set, PLLs to be programmed, and appropriate status information read back. The tcs software is designed to be activated on startup by the booting system. The software then updates an output file (normally /home/httpd/index.html) periodically to provide a means of monitoring tuner state via the boa web server. The file location and name as well as the update interval can be set from the command line. The service blocks for the update interval waiting for an message queue command, performs any received command, and then immediately updates the status file on command completion. Each command also returns appropriate status information via a status message queue.
The tcs program has the following options:
MIDAS-M RF Tuner Control Service revision $Id: midasm_tcs.c 49 2008-01-23 21:50:51Z flind $ usage : bin/tcs [-f <status file>] [-r <update rate (sec)>] [-h]
-f the path and file name to place the updating html status file, default is ''/home/httpd/index.html'.
-r the status file update rate in seconds, default is 10 seconds.
-h print the usage shown above.
A typical usage example is to place the software into the rc startup file for initiation on boot :
/bin/tcs -f /home/httpd/index.html -r 10&
Assuming a common directory for all files. The software can be compiled manually using the following command
nios2-linux-gcc -o tcs midasm_tcs.c libtuner.c -I. -DUHF_TUNER_REV1 -lrt -elf2flt="-s 32000"
Tuner Control Remote
The Tuner Control Remote (tcr) software is a common gateway interface (CGI) program designed to be activated by the boa web server. This software provides a CGI interface to the Tuner Control System posix message queue interface. The CGI interface may be executed directly from a web browser for manual testing and debugging. It is intended to be used by a remote service via the Remote Receiver Interface. It accepts CGI commands in a simple and fairly inflexible format of one command and value per cgi request. The software returns text status messages most of which are generated by the Tuner Control Service.
The tcr software supports the following cgi commands :
?command=control&<register name>=<hex value> A register name and hex value are set remotely.
?command=frequency&<pll name>=<frequency> A PLL of the given name is set to the provided frequency in Hz. Scientific notation okay, 314E6, etc.
?command=defaults Sets the tuner to the hardwired default settings that are compiled into the libtuner software.
?command=list Returns a list of all registers and PLLs.
?command=status Returns the status readout of each register and PLL.
?command=quit Causes the tuner control service to exit. It will not automatically restart.
Example of setting a control register :
Entering the following http://192.52.65.237/cgi-bin/tcr?command=control&a_s0_noise_enable=0x1 in a web browser where the receiver IP address is as above sets the appropriate register and returns : a_s0_noise_enable=1
Example of obtaining status information :
Entering the following http://192.52.65.237/cgi-bin/tcr?command=status in a web browser where the receiver IP address is as above returns : MIDAS-M UHF_TUNER=1.0 UTC=Tue Nov 30 02:37:01 1999 trigger=0001 pps=0000 a_s0_noise_enable=0001 a_s0_lo_enable=0001 a_s0_lo_select=0000 a_s0_rf_path=0000 a_s0_rf_output=0001 a_s0_rf_input=000b a_s0_attenuator=0000 a_s1_noise_enable=0000 a_s1_lo_enable=0000 a_s1_lo_select=0000 a_s1_rf_path=0000 a_s1_rf_output=0001 a_s1_rf_input=000d a_s1_attenuator=001f b_s0_noise_enable=0000 b_s0_lo_enable=0001 b_s0_lo_select=0000 b_s0_rf_path=0000 b_s0_rf_output=0001 b_s0_rf_input=000b b_s0_attenuator=0000 b_s1_noise_enable=0000 b_s1_lo_enable=0000 b_s1_lo_select=0000 b_s1_rf_path=0000 b_s1_rf_output=0001 b_s1_rf_input=000d b_s1_attenuator=001f a_mode=0002 a_interval=0000 a_delay=0000 b_mode=0002 b_interval=0000 b_delay=0000 pll_a_enable=0000 pll_a_clk=0000 pll_a_data=0000 pll_a_attenuator=0000 pll_a_lock=0001 pll_a_error=0001 pll_b_enable=0000 pll_b_clk=0000 pll_b_data=0000 pll_b_attenuator=0000 pll_b_lock=0001 pll_b_error=0001 pll0=pll_a pll_a_current_freq=314000000.000000 pll_a_default_freq=314000000.000000 pll_a_max_freq=760000000.000000 pll_a_min_freq=240000000.000000 pll_a_freq_spacing=500000.000000 pll1=pll_b pll_b_current_freq=314000000.000000 pll_b_default_freq=314000000.000000 pll_b_max_freq=760000000.000000 pll_b_min_freq=240000000.000000 pll_b_freq_spacing=500000.000000 pll1=pll_b pll_b_current_freq=314000000.000000 pll_b_default_freq=314000000.000000 pll_b_max_freq=760000000.000000 pll_b_min_freq=240000000.000000 pll_b_freq_spacing=500000.000000
MIDAS-M Tuner Configuration Software
This software programs a MIDAS-M series tuner using the http based TCR (tuner control remote) cgi interface. An config ini file is loaded to provide the tuner parameters. Alternatively the tuner frequencies and parameters may be remotely set from the command line. Tuner type is parameterized via inheritance to allow support of multiple tuner types. Currently only UHF tuners are supported.
Web based control of the UHF tuners via the device web servers.
Use of text based INI files for configuration parameters. These can be created and revision controlled easily (do so!).
Control of multiple tuners from a single INI file.
Command line frequency and override parameters for direct control from the command line.
A verbose mode for diagnosing sent commands and returned results. Also gets the tuner status.
A debug mode which generates commands but does not send them to the end points.
The tuner configuration software supports the use of INI files for tuner configuration via an http cgi interface. These INI files do no sanity checking although all the parameters required for a tuner must exist with the correct names. The exception to this is for PLL frequency settings which are checked to be within fixed bounds.
The cgi interface runs on the tuner FPGA Linux distribution which must start the TCR service on boot. The performance of the FPGA server is somewhat limited so setting a configuration can take several seconds (there are a lot of parameters). Single parameters and frequency settings can be set rapidly from the command line and these command line parameters will override values from the INI file. Typically the tuner exists on an internal network and a web proxy may be used to obtain access on other networks.
Configuration files are in the format supported by the Python ConfigParser module. Multiple tuner states are parameterized using arrays. The mapping of tuner control settings to values is designed to eliminate much of the low level register manipulation required by the more direct control methods described above.
An example configuration file specific to the UHF tuner is as follows :
# # UHF Tuner Configuration Example # # $Id: uhf_tuner.ini 66 2008-11-17 19:06:40Z flind $ # # Configure the MIDAS-M UHF radar tuner. # [tuner_a] # set the tuner mode # The tuner has two states (lower and upper) for bit level parameters. # lower | upper | trigger_asserted | pps_alternation | trigger_alternation # trigger_interval | pps_interval | trigger_delay # mode : lower # interval for tuner A modes in 100 nanosecond ticks interval : 0 # delay for tuner A modes in 100 nanosecond ticks delay : 0 # Tuner settings # The tuner has an upper and a lower state which can be selected or # switched between depending on the tuner mode. # enable the noise source noise_enable : [False, False] # enable the local oscillator lo_enable : [True, True] # select the LO source : PLL | External lo_select : [PLL,PLL] # select the RF path on the input side : internal | bypass rf_path : [internal, internal] # select the RF path on the output side : internal | bypass rf_output : [internal, internal] # select the RF source for the input side : input_a | input_b | noise_diode | terminator rf_input : [input_a, input_b] # attenuator value in 1 dB steps, integer attenuator : [0,0] [tuner_b] # set the tuner mode # The tuner has two states (lower and upper) for bit level parameters. # lower | upper | trigger_asserted | pps_alternation | trigger_alternation # trigger_interval | pps_interval | trigger_delay # mode : lower # interval for tuner B modes in 100 nanosecond ticks interval : 0 # delay for tuner B modes in 100 nanosecond ticks delay : 0 # Tuner settings # The tuner has an upper and a lower state which can be selected or # switched between depending on the tuner mode. # enable the noise source noise_enable : [False, False] # enable the local oscillator lo_enable : [True, True] # select the LO source : pll | external lo_select : [pll,pll] # select the RF path on the input side : internal | bypass rf_path : [internal, internal] # select the RF path on the output side : internal | bypass rf_output : [internal, internal] # select the RF source for the input side : input_a | input_b | noise_diode | terminator rf_input : [input_a, input_b] # attenuator value in 1 dB steps, integer attenuator : [0,0] [pll_a] # pll frequency setting ; PLLs have limited range and step sizes ; in Hz floating point frequency : 276.0E6 # 0 to 16 dB in half dB steps, value in half dB steps, integer attenuator : 0 [pll_b] # pll frequency setting ; PLLs have limited range and step sizes ; in Hz floating point frequency : 276.0E6 # 0 to 16 dB in half dB steps, value in half dB steps (0 to 31), integer attenuator : 0
The software is used from the command line and requires Python 2.5 or later and the Numpy library. The command line options for the tuner software are :
midasm_tuner_config.py usage: -h, --help : display the usage information. -u <uri> , --uri=<uri> : URI of the tuner(s) to control. -c <file> , --config=<file> : configuration input file name -t <type> , --type=<type> : tuner type by name. -f <channel>:<freq> , --frequency=<channel>:<freq> : set channel frequency -o <channel>:<value> , --override=<channel>:<value> : override a configuration parameter in the config file -d , --debug : activate in debug mode which just prints command output -v , --verbose : verbose output of resulting tuner state Primary tuning is accomplished using ini files so that configs may be revision controlled. The frequency and control parameters of a channel may be set independent of the use of a config file. If control parameters are given the values provided on the command line override those in the ini file. Multiple tuners may be controlled from a single config file file.
Examples of using the tuner are as follows :
Set a tuner with address isis-uhf001 using a config file python midasm_tuner_config.py -c uhf_tuner.ini -u http://isis-uhf001/.
Set a tuner with a proxied address using a config file in verbose mode python midasm_tuner_config.py -c uhf_tuner.ini -u http://lltrailer2.gb.nrao.edu/isis-uhf001/.
Set a tuner with a config file and override the PLL and a noise diode setting python midasm_tuner_config.py -c uhf_tuner.ini -f pll_a:280.0E6 -o a_s0_noise_enable:1 -u http://isis-uhf002/.
Set a tuner frequency directly from the command line python midasm_tuner_config.py -f pll_a:300.0E6 -u http://isis-uhf002/.