Getting Started

This page describes the process of setting up a client device.

run_terra_client is the main entry point for client receivers. It can be run with arguments from a command line, but works best with a setup contained in a .env file which is loaded with dotenv.

Obtaining Credentials

We are currently beta testing. If you were provided with an access token, you can use it to obtain credentials for the backend:








Radio Configuration


Terra is designed to work with a variety of software defined radios. Several drivers are provided
for the most popular vendors, and adding new drivers is straightforward. To specify your radio setup,
create a .json file in Receiver/config/sources with structure like this:


{
    "driver":"soapy",
    "fs":6000000,
    "fc":94900000,
    "chunk_length":7200000,
    "source_kwargs":{
        "device_string":"driver=lime",
        "antenna":"LNAW",
        "gains":{
            "LNA":13,
            "TIA":9,
            "PGA":-6
        }
    }
}





The parameters are:




driver:


‘soapy’, ‘uhd’, or ‘iio’ are provided by default.




fs:


Sample rate in Hz




fc:


Center frequency in Hz. This will depend on the stations (see the following section)




chunk_length:


The computer-side buffer size for RF data.




source_kwargs:


Keyword arguments to be passed to the radio constructor. These will depend on the radio.






Some radios have local oscillators that are so far from the correct frequency that they will not be
able to correct for it automatically. It is possible to override the initial LO offset parameter in
LocationPipeline for a specific radio.






Environment Setup


We highly recommend using a .env file to configure the receiver. A good starting point contains the following:


CLIENT_GEOHASH=drt2
DATASOURCE_FILE=config/sources/[your-radio-json-file]
SERVER_URL=https://ajtaaxxrmj.execute-api.us-east-1.amazonaws.com/dev
FEATURE_CLIENT_ID=[your-client-id]
FEATURE_CLIENT_SECRET=[your-client-secret]
COGNITO_DOMAIN='https://us-east-1cssiwx7hl.auth.us-east-1.amazoncognito.com'





CLIENT-GEOHASH is required to identify the region for which stations should be provided, we recommend a 4-character
geohash for the receiver region.


Software defined radios are notoriously tricky to set up. We highly recommend radioconda. Install radioconda, then
create a new python virtual environment using the python version in the radioconda install directory and use system site
packages, eg: ~/radioconda/bin/python3 -m venv .venv --system-site-packages. This will use the radioconda versions of
SDR libraries like iio and uhd, but keep your radioconda installation clean.


Check that you can import the SDR libraries you need, then pip install -r requirements.txt.






Starting the Receiver


python run_terra_client.py That should be it!






Web Interface


We have provided a leaflet-based map/web interface for viewing solutions and the receiver location.