Radar class documentation¶

Radar class¶

class apreshttp.Radar(api_obj)¶

Wrapper class for radar operation and configuration

The Radar class exposes methods in the API to update the chirp settings, perform trial bursts and collect results, and perform a radar measurement (burst).

__init__(api_obj)¶

Assign instance of the API class

APIChild should inherently be a child of an API object hence the constructor requires an instance of API to meet this conditions.

Parameters: api_obj (apreshttp.API) – instance of API

class Results(response)¶

Container class for burst and trial results

The type parameter can be used to determine whether the results arise from trial burst or a full burst, and the parameters will depend on this.

type¶: indicates whether the results are a trial or full burst

burst(filename=None, userData=None, callback=None, updateCallback=None, wait=True)¶

Perform a measurement radar burst using the current config

Attempts to start an asynchronous radar burst, using the current configuration. Also retrieves configuration from the API.

If the burst starts successfully then the response status code should be 303 and redirect to the “results” API route.

If the status code is 403 then something is preventing the radar from starting the burst.

Parameters

filename (str) – filename to be used when saving the burst to an SD card.
callback (callable) – callback function which accepts one argument of type API.Radar.Results
updateCallback (callable) – callback function executed on each results request (to provide progress updates)
wait (boolean) – If False, the request for results takes place in a new thread.

Raises

NoChirpStartedException – Raised if the API returns a 403 indicating the radar cannot start the burst and no data is available, i.e. the radar state is idle.
RadarBusyException – Raised if the burst could not be started because the radar is already performing a burst.

config¶: Instance of a Radar.Config object which gets and sets the radar chirp config.

results(callback=None, updateCallback=None, wait=True)¶

Wait for results to be returned by the radar

Calls the function callback when the api/radar/results page indicates that the chirp has finished. If callback is None then this works as a blocking function until the radar results are ready.

If the ResultsTimeoutException is raised, it is a good indication that the radar should be reset.

Parameters

callback (callable) – callback function which accepts one argument of type API.Radar.Results
updateCallback (callable) – callback function executed on each results request (to provide progress updates)
wait (boolean) – If False, the request for results takes place in a new thread.

Returns

If wait = False, returns the thread instance executing the results code. Otherwise, returns a results object if the results are obtained.

Return type

threading.Thread

Raises

NoChirpStartedException – If the radar state is idle, no data is returned.
ResultsTimeoutException – Raised if the timeout period is exceeded and no results are returned within this period.

trialBurst(callback=None, updateCallback=None, wait=True)¶

Perform a trial burst using the current configuration

Attempts to start an asynchronous trial radar burst, using the current configuration. Also retrieves configuration from the API.

If the burst starts successfully then the response status code should be 303 and redirect to the “results” API route.

If the status code is 403 then something is preventing the radar from starting the burst.

To parse the results from the trial burst, the below gives some example code:

# Create API instance
api = apreshttp.API("http://radar.localnet")
api.API_KEY = [...]

# Define callback function
def trialResultsCallback(response):
    try:
        response_json = response.json()
        # DO SOMETHING WITH RESULTS
        ...
    except:
        print("Couldn't read results.")

# Perform trial burst
api.radar.trialBurst(trialResultsCallback) # will hang until results are returned.

Parameters

callback – If provided, callback is executed when results are available. The callback function should take a single argument of type requests.response
updateCallback (callable) – callback function executed on each results request (to provide progress updates)
wait (boolean) – If callback is provided, should the function halt execution or wait in a seperate thread

Raises

NoChirpStartedException – Raised if the API returns a 403 indicating the radar cannot start the burst and no data is available, i.e. the radar state is idle.
RadarBusyException – Raised if the burst could not be started because the radar is already performing a burst.

Radar.Config class¶

class apreshttp.Radar.Config(api_obj)¶

Retrieve and modify radar burst configuration

The Radar.Config class can be updated from the API using the get() method.

If it is desired to change values, such as individual attenuator settings or the number of sub-bursts, then the set() method should be used.

NOTE: when instance attributes, such as nAttenuators are accessed, these are not automatically updated from the API and default to their last values, hence care should be taken to call get() when it is desired to have the most recent configuration values.

By default, instance variables are initialised to None until a get() request is made.

afGain¶: RF attenuator settings (list of float)

get()¶

Retrieve the latest radar burst configuration

Returns: Returns self
Raises: BadResponseException – Raised in the event of an unexpected error code or missing JSON keys.

nAttenuators¶: Number of attenuator settings (int)

nAverages¶: Number of averages for a trial burst (int)

nSubBursts¶: Number of sub-bursts per burst (int)

parseRFAttnAFGain(type, arg, nAtts)¶

Validate RF attenuation and AF gain parameters to get()

Raises

ValueError – Raised if nAtts is greater than 1 and a single AF or RF value is provided.
KeyError – Raised if the key in arg does not match rfAttn[1-4] or afGain[1-4]

readResponse(response)¶

Read values from a response to radar/config into Config object

Raises: BadResponseException – Raised if there are missing fields from the radar configuration JSON response.

rfAttn¶: AF gain settings (list of float)

set(nAtts=None, nAverages=None, nBursts=None, rfAttnSet=None, afGainSet=None, txAnt=None, rxAnt=None, userData=None)¶

Updates the radar burst configuration with the given parameters

Parameters

nAtts (int or None) – Set the number of attenuator settings to be used (1-4)
nBursts (int or None) – Set the number of chirps to be averaged for a trial burst, or repeated for a full burst.
rfAttnSet (int, list, dict or None) – Set the values of the ApRES RF attenuator. If using a dictionary, keys should be “rfAttn1”, “rfAttn2”, etc. and may be excluded if no update is desired.
afGainSet (int, list, dict or None) – Set the values of the ApRES AF gain. If using a dictionary, keys should be “afGain1”, “afGain2”, etc. and may be exlcuded if no update is desired.
txAnt (int or list) – If using a MIMO board, set the active transmit antennas
userData (str) – 32-char string representing the current radar task (printed to bursts)

Raises

BadResponseException – If an unexpected status code was returned
DidNotUpdateException – If the config settings were not updated

NOTE: Calling set() will incur a call to get() to retrieve the latest configuration.

To update the number of attenuators

Config.set(nAtts = 3)

To update the number of sub-bursts

Config.set(nBursts = 10)

To update RF attenuator or AF gain values (i.e. replace rfAttnSet with afGainSett)

# Update rfAttn1 to 16.5 dB
Config.set(rfAttnSet = 16.5)
# Update rfAttn1, rfAttn2 and rfAttn4 using list
Config.set(rfAttnSet = [0, 10, None, 23.5])
# Update using rfAttn2 and rfAttn3 using dict
rfSettings = {"rfAttn2" : 12.5, "rfAttn3" : 6.0}
Config.set(rfAttnSet = rfSettings)

WARNING: If nAttenuators has been set in the same or a previous call to set() and an RF attenuator or AF gain value with an index greater than nAtts has been set, then an error is thrown, i.e.

# Set nAtts to 2, but try setting rfAttn3
Config.set(nAtts = 2, rfAttnSet = [0, 10, 20])
# Exception occurs!
...
Config.set(afGainSet = [-14, -14, -14])
# Exception occurs (trying to change nAtts to 3)

Similarly, trying to assign a single attenuator value when nAttenuators is greater than 1 will cause an error

# Set nAtts to 2
Config.set(nAtts = 2)
# Try to assign a single attenuator value
Config.set(afGainSet = -4)
# Exception occurs

If using a MIMO board, providing txAnt or rxAnt with an eight element tuple allows the user to choose which antennas are enabled, i.e.

# Use the 1st, 4th and 8th antennas to transmit
Config.set(txAnt = (1,0,0,1,0,0,0,1))
# Use the 2nd and 7th antennas to receive
Config.set(rxAnt = (0,1,0,0,0,0,1,0))

Radar class documentation¶

Radar class¶

Radar.Config class¶

Table of Contents

Previous topic

Next topic

This Page