Prequisites
-----------

The beacon satellite receiver has only been tested with Linux. With
small modifications, the receiver should work in any operating system
that supports python, R, USRP and gnuradio.

In terms of hardware, you will need a RF frontend capable of providing
RF signals on 150 MHz and 400 MHz (or any other beacon satellite
frequencies). This usually involves a dual-band antenna,
preamplifiers and some filters. Also, a USRP1, USRP2, or USRPN210
software defined radio device is required, along with a daughterboard
capable of measuring the two frequencies that are measured. For
150/400 MHz beacon satellite work, we have successfully used the
BasicRX (150 MHz), WBX (150 and 400 MHz) and TVRX2 (150 and 400 MHz)
daughterboards. We have succesfully used USRP1, USRP2, and USRP N210. 

The software comes in one package that can be untarred in any
directory. There are two main directories that are needed for the
system: 

1. The binary directory, which is the directory where all of the
   programs and scripts recide.
2. The data directory, where all of the acquired and analyzed data is
   stored in. 

A typical layout would be:

Binary directory:
/home/user/beacon

Data directory:
/home/user/beacon/data

The location of the data directory is defined within the beacon.conf
configuration file.

As for data storage requirements, there are two options. If you want
to store the raw 40 kHz signal for all of the satellite passes, you
will accumulate about 10-30 GB of storage each day. However, if you
are willing to delete these files once you have analyzed the phase
curves, the typically storage requirement is dropped down to 100-400
MB a day. 

Software dependencies
---------------------

python, gnuradio, pyephem, uhd, R

Installation
------------

Untar the beacon distribution

> tar xvfz beacon-?.?.?.tar.gz
> cd beacon-?.?.?

If you haven't installed gnuradio and uhd, they can be installed in
Ubuntu system with the following script provided with the distribution:

> sudo ./build-gnuradio

The beacon receiver itself has to also be compiled. It might be
necessary to modify the paths to the headers and libraries within the
Makefile. 

> make

Additionally, several other packages are required (openntpd is needed
to synchronize the clocks between the stations)

> sudo apt-get install sendmail openntpd r-recommended python-pip screen

The ephemeris calculation routines require pyephm, which can be
installed with 

> sudo easy_install pyephem 

The following R packages also are required

> sudo R
> install.packages(c("maps","mapproj","sendmailR"))

The local R packages that come with the receiver also need to be
installed:

> sudo R CMD INSTALL gursipr stuffr physconstr beaconr 

To test that the beacon recorded has been successfully compiled, type 

> ./beacon --help

And to list the available USRP devices connected to the receiver, type

> uhd_find_devices

In order for the beacon receiver and analysis programs to run
reliably, we will need to use large receiver buffers. Also, the
phasecurve analysis program sometimes requires large amounts of
memory. For this reason, it is recommended that the OOM-kill feature
is disabled, to prevent the operating system from killing the beacon
recorded process. It is thus recommended that the following sysctl
lines are added to /etc/sysctl.conf

# Updates for Gnu Radio
net.core.rmem_max=100000000
net.core.wmem_max=100000000
vm.overcommit_memory=2


Binary directory
----------------

All of the configuration files, scripts and binary files are located under the so called
binary directory. The sh and R-scripts should be run from this
directory, as they assume that the configuration files are within the
same directory. This is perhaps not the unix-way of doing things, but
this makes sense in terms of portability, as the whole distribution is
self-contained, and it doesn't install any files in system
directories. 

The most important files in the binary directory are:

- beacon.conf          #  The local configuration file, which contains
                          information about the local station
                          installation. This includes the station
                          coordinates, usrp hardware configuration
                          device, frequency offsets, data directory
                          locations etc.

- satellites.txt       # The list of satellites and their frequencies. 
			 CSV format 1st column: NORAD name, 2nd column central freq. 
			 150e6+150e6*ppm/1e6  

- satellites.all       # The list of all satellites and their frequencies. 
                         Copy this list to satellites.txt and remove satellites 
		         that are not needed. The entries in satellites.txt
                         are the ones tracked by the receiver. 

- beacon.r             #  The top-level program which downloads
                          ephemeris information, and calculates new
                          satellite pass predictions on a daily
                          basis. This script also runs the beacon
                          satellite data acquisition program
                          automatically. 

- beacon_calc.sh       #  This continuously monitors the data
                          directory for new measurements and performs
                          relative phase curve analysis when new data
                          is available. It outputs the results in the
                          data directory.

In addition to these three scripts, there are several helper programs
that the user typically doesn't need to operate manually, as it is
done automatically by beacon.r and beacon_calc.sh. However, they can
be usefull for stand-alone operation. 

- beacon               #  The C++ program that records band-limited
                          raw IQ data files according to the specified
                          satellite ephemeris files. A user doesn't
                          need to run this program, unless a special
                          mode of operation is needed.

- ./get_beacontle.py   # A script that downloads the satellite
                         ephemeris files from various locations and
                         writes them to disk in a form readable by the
                         satellite pass prediction program. Searches
                         for ephemeris to satellites in satellites.txt

- ./predict_passes.py  # A script that reads in the ephemeris file and
                         predicts future satellite passes above the
                         receiver station. Writes the information about
                         passes to /datadir/YYYY.MM.DD/passes.txt and
                         to /datadir/YYYY.MM.DD/flight-%06d.pass

- ./beacon_calc.r      # The underlying R-script that performs the
                         analysis loop. beacon_calc.sh merely calls
                         this script repeatedly in a loop to avoid 
			 memory leaks in the R graphics routines.

- ./beacon_info.r      # Displays some information about the system
                         status. Not very helpful at the moment. 

- beacon_global.conf   # An OPTIONAL configuration file,
                         which contains information about the whole
                         network of satellite receivers. This
                         configuration file is used by the commands
                         that can be used to access all of the
                         computers in the network. It contains e.g.,
                         the hostnames of individual stations. This
                         can then be used to e.g., monitor the health
                         of the receivers within the network, and to
                         fetch measured phase curves and data from
                         within the receiver network. If stand-alone
                         operation is sufficient, then this file is
                         not needed

- ./beacon_fetch_data.r # A script to fetch data files from remote
                          receiver stations. This simply reads the
                          beacon_global.conf and rsyncs the data files
                          over to a central location. 

Data directory
--------------

The data directory contains all of the data and log-files produced by
the beacon satellite receiver. The layout of the directory is
organized by days. All of the measurements and results for one day are
contained within a separate subdirectory directory.

data
├── 2011.06.25        
├── 2011.06.26
├── 2011.06.27
│   ├── analyzed.log            # list of analyzed passes
│   ├── beacon.tle              # ephemeris on this specific day
│   ├── flight-000000.001.bin   # raw IQ data for the pass. ch. 1
│   ├── flight-000000.002.bin   # raw IQ data for the pass. ch. 2
│   ├── flight-000000.pass      # ascii ephemeris info
│   ├── flight-000000spec.png   # overview plot of analysis results
│   ├── flights.log             # list of recorded satellite passes
│   ├── passes.txt              # list of all passes on this day
│   ├── phasecurve-000000.Rdata # the R file containing the analysis results
├── receiver.log                # beacon receiver log file
└── rout.log                    # the verbose output of the receiver state

The *.bin files are the largest files, and it will probably be a good
idea to purge them every once in a while in continuous operations,
otherwise they will fill up the hard drive. The software currently
does not automatically perform this, as it is still in development
state, and it is possible that an improved version of the phase curve 
calculation will be developed, and the raw voltage data allows
re-analysis of the data at a later time. 

Configuration
-------------

To configure the system, one must edit the beacon.conf file with
values that reflect the system setup. 

beacon.addr defines the  device address string. Refer to this
document for more information on choosing the correct value:

http://www.ettus.com/uhd_docs/manual/html/identification.html

beacon.subdev determines the daughterboard configuration. Refer
to this document for determining the correct value for this: 

http://www.ettus.com/uhd_docs/manual/html/dboards.html

For example, two WBX cards in a usrp1 device, with 150 connected to A
and 400 MHz connected to te RXB side requires the following subdev
spec:

beacon.subdev <- "A:0 B:0"

A TVRX2 card on the A side of a usrp1 with 150 MHz going to port RX1 and 400 MHz going to port
RX2 requires the following subdev spec: 

beacon.subdev <- "A:RX1 A:RX2"

With usrp1, it is recommended that you increase the usb buffer to
avoid overflows. This can be done by using the following device
address string:

beacon.addr <- "recv_frame_size=4096,num_recv_frames=4096"

The usrp1 device can be additionally specified based on the serial
number.

beacon.addr <- "serial=123456,recv_frame_size=4096,num_recv_frames=4096"

For usrp2 or usrp n210, the receiver buffer size and device address
can be  specified as e.g.,

beacon.addr <- "addr=192.168.10.2,recv_buffer_size=200000000"

In addition to this, we need to specify the sample rate. It is
recommended to use a combination that results in 1 MHz. However, a
wider or more narrow band can also be used. To achieve 1 MHz in a
usrp2, one would use

beacon.refclock <- 100000000 

and 

beacon.decim <- 100 

And on a usrp1, one would use

beacon.refclock <- 64000000 

and 

beacon.decim <- 64

The gains on the 150 and 400 MHz channels are defined with  (20 and 30 dB)

beacon.gain1 <- 20

and

beacon.gain2 <- 30

Another important option of the frequency offset option. If the
receiver clock is not locked to a global reference, it might be a good
idea to calculate the frequency offset on the 150 and 400 MHz
channels. Also, due to a driver bug in the TVRX2 daughter board, the
driver reports the wrong frequencies when tuning. Therefore when using
the TVRX2 daughterboard, the offsets need to be set as follows: 

beacon.offset <- 0.70710994574392038725
beacon.offset2 <- 24.32312035473312405998

As these will approximately give the correct tuning with TVRX2. Other
daughterboards, such as BasicRX or WBX report the correct frequency,
so no offset is needed. 

All of the other settings are trivial, and explained within the
comments of the beacon.conf file. 


Operation
---------

Once the beacon receiver has been configured, it can be started by
issueing the following commands under the installation directory:

> sudo ./beacon.r 
> sudo sh beacon_calc.ch

The first one will start the raw voltage data receiver, and the second
one will start the analysis loop. 

Alternatively, it might be a good idea to use screen, so that the programs can be run on the background:

> screen
> sudo ./beacon.r
# and then press ctrl-a ctrl-c to create a new terminal in screen
> sudo sh beacon_calc.sh
# you can navigate between screens with ctrl-a + n and ctrl-a + p
# and then you can go out of the screen with ctrl-a ctrl-d
