terra_client package

Submodules

terra_client.LocationPipeline module

class terra_client.LocationPipeline.LocationPipeline(data_source, network_client, region, override_time=None, channel_width=400000)

Bases: object

This class contains everything required to produce a location estimate on a client mobile receiver.

Parameters:

  • data_source (terra_dsp.DataSource) – Input signal source for this receiver

  • network_client (terra_client.NetworkClient) – Network connection for this receiver

  • region (str) – The rough geographic region of the receiver. Used to determine which reference features to serve. This should be a three character geohash.

  • override_time (int, optional) – For testing. This overrides the receiver start time so that recorded data can be used. Defaults to None.

  • channel_width (int, optional) – Channel bandwidth in Hz. Defaults to 400_000.

C = 299705543
FEATURE_LEN = 400
calculate_clock_offset(features_in, rx_signal, rx_start_time, fs)

Calculate the rough clock offset between the client and the reference receiver. This function uses a sparse correlation between the features and the received data to reduce the size of future correlations

Parameters:

  • features_in (list[Feature]) – input features from the reference receiver

  • rx_signal (array-like complex) – Baseband received signal

  • rx_start_time (int) – Receive window start time in nanoseconds from the epoch

  • fs (float) – Sample rate in Hz. Used only for printed output.

Returns:

Clock offset.

Return type:

float

calculate_sample_rate_offset(rx_signal, features_in)

Calculate the sample rate offset by comparing the location of the correlation peak for features at the beginning and end of the receive window.

Parameters:

  • rx_signal (array-like complex) – Received baseband signal.

  • features_in (list[Feature]) – List of features.

Returns:

resampling rate.

Return type:

float

get_best_station()

Identify the most powerful station.

Returns:

Index of the most powerful station.

Return type:

int

get_lo_correction(data_bb)

Compute the LO offset by comparing the detected station center frequency to the known “true” station reference frequency. The detected center frequency is calculated by convolving the PSD of the signal with itself, and assumes a symmetric PSD.

Parameters:

data_bb (array-like complex) – Baseband signal data.

Returns:

LO offset in radians/second.

Return type:

float

get_lo_correction_from_features(rx_signal, features_in, num_lags=40, phase_lags=40, pad=5000)

Calculate the local oscillator correction by tracking phase change across a single feature.

Parameters:

  • rx_signal (array-like complex) – Baseband received signal.

  • features_in (list[Feature]) – list of valid features.

  • num_lags (int, optional) – Number of lags in the correlation. Defaults to 40.

  • phase_lags (int, optional) – Number of lags to include for each phase step. Defaults to 40.

  • pad (int, optional) – Correlation pad length. Defaults to 5000.

Returns:

Local oscillator error in radians/second.

Return type:

float

get_pseudorange(data_baseband, mfeatures, station_name=None)

Estimate a pseudorange for a single station using all of the valid features.

Parameters:

  • data_baseband (array-like complex) – baseband received data.

  • mfeatures (list[Feature]) – valid features for a single station.

  • station_name (str, optional) – Station name for generating plots. Defaults to None.

Returns:

the pseudorange.

Return type:

float

get_valid_features(features_in, rx_start_time, rx_samples, pad=5000)

Use the clock offset to drop features which fall outside of the receive window.

Parameters:

  • features_in (list[Feature]) – Features from the reference receiver.

  • rx_start_time (int) – Receive window start time in nanoseconds from the epoch.

  • rx_samples (int) – Number of samples in the receive window.

  • pad (int, optional) – Half-width of the correlation. Defaults to 5000.

Returns:

A dictionary mapping StationIDs to valid features.

Return type:

dict

plot_solve(t, x, y, center, ref_location, pseudoranges, locations)

Function for plotting solutions on a blank map.

Parameters:

  • t (float) – Time offset between client and reference receiver clocks.

  • x (float) – Horizontal distance between solution and center in meters.

  • y (float) – Vertical distance between solution and center in meters.

  • center (list[Latitude, Longitude]) – reference location for plotting

  • ref_location (list[latitude, longitude]) – Location of the reference receiver.

  • pseudoranges (list[float]) – Pseudoranges in the same order as locations

  • locations (list[list[latitude, longitude]]) – List of station locations

solve()

Receive RF data, request signals from the server, and attempt to produce a location

Raises:

ValueError – Raises a ValueError if the pfb channelizer is used and an invalid channel is requested.

Returns:

A dictionary containing the location estimate, the pseudoranges, and the time offset.

Return type:

dict

terra_client.NetworkClient module

class terra_client.NetworkClient.APIClient(url)

Bases: NetworkClient

A NetworkClient that uses an internet connection to fetch features from the Terra backend using a the Terra API.

Parameters:

url (str) – API URL

get_features(stations, time)

Retrieve features from the backend.

Parameters:

  • stations – List of Station objects to request features for.

  • time (int) – Receive window start time in nanoseconds from the epoch.

Returns:

Dictionary mapping StationIDs to a list of Feature objects for that station.

Return type:

dict

get_served_stations(region, start_time)

Find stations with recent features in the region.

Parameters:

  • region (str) – geohash for the region.

  • start_time (int) – Receive window start time in nanoseconds from the epoch. Not used.

Returns:

list of nearby stations with available features.

Return type:

list[Station]

get_token()
class terra_client.NetworkClient.FileClient(feature_dir, stations_file)

Bases: NetworkClient

An offline NetworkClient that serves features from a file for testing.

Parameters:

  • feature_dir (str) – Directory containing feature files.

  • stations_file (str) – File path for station definition json file.

get_features(stations, time)

Retrieve features from the file.

Parameters:

  • stations – 3 letter geohash of client receiver location. Not used.

  • time (int) – Receive window start time in nanoseconds from the epoch. Not used.

Returns:

Dictionary mapping StationIDs to a list of Feature objects for that station.

Return type:

dict

get_served_stations(region, time)

Find stations with recent features in the region.

Parameters:

  • region (str) – geohash for the region. Not used.

  • start_time (int) – Receive window start time in nanoseconds from the epoch. Not used.

Returns:

list of nearby stations with available features.

Return type:

list[Station]

class terra_client.NetworkClient.LocalClient(url)

Bases: NetworkClient

A NetworkClient that uses an internet connection to fetch features from a Local Terra backend..

Parameters:

url (str) – API URL

get_features(region, time)

Retrieve features from the backend.

Parameters:

  • region (str) – 3 letter geohash of client receiver location.

  • time (int) – Receive window start time in nanoseconds from the epoch.

Returns:

Dictionary mapping StationIDs to a list of Feature objects for that station.

Return type:

dict

get_served_stations(region, start_time)

Find stations with recent features in the region.

Parameters:

  • region (str) – geohash for the region.

  • start_time (int) – Receive window start time in nanoseconds from the epoch.

Returns:

list of nearby stations with available features.

Return type:

list[Station]

class terra_client.NetworkClient.NetworkClient

Bases: object

Prototype class for receiver network connections

get_features()
get_served_stations()

terra_client.WebSocketSender module

class terra_client.WebSocketSender.WebSocketSender

Bases: object

URI = 'ws://localhost:5000/'
static send(data)