LCU Commands
Software Level
Control processes in a LOFAR station are collected in groups called software levels. The user does not need to manually start and stop a number of processes, but each level contains processes for certain actions in the station, and appropriate processes are started / stopped when entering a given level. Users can query and set the software level using the swlevel command. When software level is changed in steps larger than one, the system goes through the intermediate levels as well, and starts/stops processes as needed. Processes belonging to each level are listed in the help message of the swlevel command.
0: Stop all lofar software 1: Run Lofar daemons and PVSS 2: Run Lowlevel hardware drivers 3: Run Calculation services 4: Run Hardware and software monitors 5: Run System Health Management 6: MAC is controlling the software
Software levels 0 – 3 are relevant in single station use, the processes belonging to the higher levels 4 – 6 are intended to be used in ILT (International LOFAR Telescope) mode.
After entering software level 2, or higher if the initial level was below 2, one needs to wait for a register update to complete. Status of the registers can be displayed with the command
$ rspctl –regstat
which repeatedly prints several lines of text to the screen. The registers are up to date when all lines consist only of the characters ’.’ and ’*’, after which the rspctl process can be stopped with ctrl-c.
In short, beam forming requires software level 3, whereas other processes making use of RSP boards and TBBs require software level 2. All processes belonging to a software level below the current one are always available, so everything necessary for the single station use covered by this document is available if the system is running at software level 3.
Beam Control
Station beamforming uses the subband data produced by the polyphase filters, and produces a number of beamformed subbands called beamlets. Beams with larger spectral width can be produced by forming several beamlets with same pointing direction but different centre frequency. A LOFAR station can form up to 244 beamlets, each of which can have its own pointing direction and centre frequency. The user has large freedom in selecting the frequencies and pointing directions, but certain technical restrictions need to be taken into account:
1. A RCU has three inputs, only one of which can be active at a time. Inside a receiver the signal will go through an analogue band pass filter, where only one filter at a time can be selected. Due to these limitations, the user must select a single receiver band (a combination of an input connector and a band pass filter) for each RCU.
2. Subbands 0 – 511 are available in principle. However, the receiver passband, i.e. passband of the analogue filter in RCUs, is always narrower than the full receiver band. A few lowest and highest subbands should thus not be used. Especially subband 0 should not be used, because it has contribution from both lowest and highest ends of the receiver band and it is vulnerable to bias voltage in the receivers.
3. Third restriction arises when using the HBA array, which makes use of the analogue beamformers inside the HBA tiles. Because the tile beam can point only to one direction at a time, all digital pointing directions must be close enough to each other, so that they fall within the tile beam. Width of a tile beam is approximately 30 degrees at 150 MHz, and it is inversely proportional to the frequency. The system does not make any sanity checks about the difference between the analogue and digital beam directions, and it is on the user’s responsibility to allocate the beams properly.
A single-station user has access to the station beamforming via the beamctl command. The command can be used when the system is running at software level 3. The beamctl command can handle several tasks, such as selecting receivers and receiver modes, which are accessible via the rspctl command as well. However, beamctl is the preferred way to control also the receivers, because it automatically starts and stops the receivers as needed, and automatically starts up the system slowly enough to avoid problems with high rush-in currents.
RSP Control
Local user control of most signal processing devices in a LOFAR station, including most functionality of the RSP boards, the RCUs, and the HBA tile beamformers, is collected under the rspctl command.
The command allows the user to query and set several parameters, some of which are included as options in the beamctl command as well. When possible, it is advisable to use the beamctl command instead of rspctl, because the beamctl command takes automatically care of e.g. starting and stopping the relevant RCUs, and always starts up the receivers slowly enough to avoid problems with high rush-in currents. One should also notice that an allocated beam causes the system to regularly update all beamforming weights, and manual settings with rspctl may thus be rapidly reset by the system.5
If the beamctl command is being used to allocate beams, the user does not usually need to set any parameters with the rspctl command. However, rspctl allows the user to query several parameters, which may be interesting for checking the system status and for trouble shooting.
The rspctl command is first needed already before giving any beamctl commands for checking the register status with
$ rspctl --regstat
After allocating beams, it is useful to check that the RCUs are on and
running in correct mode with the command
$ rspctl --rcu
and to check status of the RSP boards with the command rspctl –status.
The command
$ rspctl --subbands
can be used to check which subbands are actually received from each RCU. The output is not completely self-explanatory; for even-numbered RCUs the subband numbers are multiplied by two, and for odd- numbered RCUs the subband numbers are multiplied by two and the result is incremented by 1. As an example, subband 10 is denoted as 20 in output of even-numbered RCUs and as 21 in output of odd-numbered RCUs. rspctl –subbands also prints the total number of subbands produced by each RCU, as value of the variable ”subbands”.
Spectra from individual RCUs (antenna elements) can be monitored with the command
$ rspctl --statistics,
which repeatedly plots power spectra of all receivers.6 It is also possible to plot the signal powers of each beamlet by using the command
$ rspctl --statistics=beamlet
or array covariance matrix at a selected subband with
$ rspctl --xcsubband= rspctl --xcstatistics.
The above commands also allow the signal statistics to be recorded in files. Users who want to send raw beamlet data to CEP or some other network device can switch the UDP data stream off/on and query its status with
$ rspctl --datastream[=0|1|2|3].
Only the options 0 (off) and 1 (on) are used in international stations. The options 2 and 3 are used in core stations, where the ring of RSP boards can be split in two halves, and data output from both of these need to be controlled separately.
If the user wants to use the receivers without forming beams, they need to be started manually with a couple of rspctl commands. In order to guarantee that the beam server does not reset the user-defined settings, one should begin with switching to software level 2, which disables the beam server,
$ swlevel 2
and then wait for register update, i.e. wait until the output of
$ rspctl --regstat
consists only of the characters ’*’ and ’.’.
The current receiver mode can be queried with
$ rspctl --rcu
If one wants to switch to one of the receiver modes 1 – 4, the mode can be changed with
$ rspctl --rcumode=1|2|3|4
Do not use the command rspctl –rcumode=5|6|7! This command will switch on the 48 V power supply of all HBA tiles simultaneously. The resulting rush-in current drawn from the station power supply drops its voltage down to 44 V which, in turn, causes freezing RSP boards. In order to switch to the higher receiver modes, which use the HBA array, one should use the script poweruphba.sh 5|6|7, which performs the startup slowly enough to maintain a high enough voltage. The script should be available at all stations.
After the previous commands the receivers are running in correct mode, but the data stream from the receivers to the RSP boards still needs to be started with
$ rspctl --rcuenable[=1|0]
If running in receiver mode 5, the received spectrum will be inverted, and one might be interested in inverting it back with
$ rspctl –specinv=[1|0]
Notice that this command is not needed if the receiver mode is selected with beamctl, which automatically inverts the spectrum if receiver mode 5 is selected.
After these commands one can check that the system is running properly with the commands
$ rspctl --rcu
$ rspctl --status
$ rspctl --statistics
The rspctl command allows the user to set and query numerous parameters.