This repository provides a general software API to control preselectors regardless of their components and control mechanisms.
Currently, this API provides a general abstract Preselector
class that uses an rf_path
array to describe the available combinations of calibration sources, filters, and amplifiers.
A simple set_state
method allows users to specify the state of the preselector by the state
key specified in the preselector config. Different switching control mechanisms are supported
by extending the base Preselector
class. Currently, this repository provides an implementation
for a WebRelayPreselector
that includes an x310 WebRelay.
See below for additional details on using the WebRelayPreselector
.
This software will grow over time to support additional components and control mechanisms.
A preselector is a device, connected between an antenna and a signal analyzer, designed to improve the RF performance and capability of a sensor. As illustrated in the diagram below, it may include a variety of components, e.g., filters, amplifiers, calibration sources, and switches. An example preselector is shown in Figure 1. Just as the components within a preselector may change, so too may the way in which the switching is controlled.
Figure 1: Block diagram showing an example RF measurement system with a preselector.To install this Python package, clone the repository and enter the directory of the project in the command line. Execute the following commands depending on your OS (you may have to adjust for your version of Python):
# Windows
py -m pip install .
# Linux
python3 –m pip install .
The WebRelayPreselector
requires a SigMF metadata file
that describes the sensor preselector and a config file to describe the WebRelay
settings for the RF paths specified in the metadata and for any other desired sources.
Below is an example config file for the WebRelayPreselector
to describe how it works:
{
"name": "preselector",
"base_url" : "http://192.168.1.2/state.xml",
"control_states": {
"noise_diode_on" : "1State=1,2State=1,3State=0,4State=0",
"noise_diode_off" : "1State=1,2State=0,3State=0,4State=0",
"antenna" : "1State=0,2State=0,3State=0,4State=0"
},
"status_states": {
"noise diode powered" : "relay2=1",
"antenna path enabled": "relay1=0",
"noise diode path enabled": "relay1=1"
},
"sensors": {
"internal_temp": 1,
"internal_humidity": 2,
"tec_intake_temp": 3,
"tec_exhaust_temp": 4
},
"digital_inputs": {
"ups_power": 1,
"ups_battery_level": 2,
"ups_trouble": 3,
"ups_battery_replace": 4
},
"analog_inputs": {
"door_sensor": 1,
"5vdc_monitor": 2,
"28vdc_monitor": 3,
"15vdc_monitor": 4,
"24vdc_monitor": 5
}
}
Note, the config above is specifically for a prelector with a ControlByWebWebRelay.
Other Preselectors and WebRelays may require a different configuration.
The base_url
and name
keys are the only required keys for the WebRelayPreselector
.
The base_url
should map to the base URL to interact with the WebRelay
(see https://www.controlbyweb.com/x310
for more info). The keys within the control_states
key should correspond to RF paths
documented in the SigMF metadata. The keys within the status_states
should map to the
RF paths documented in the SigMF metadata, or to understandable states of the
preselector for which it is desired to determine whether they are enabled or disabled.
The get_status
method of the preselector will provide each of the keys specified in the
status_states
entry mapped to a boolean indicating whether the preselector states match
those specified in the mapping. Each of the entries in the config provide mappings to the
associated web relay input states and every RFPath
defined in the sensor definition json
file should have an entry in the preselector config.
The sensors
, digital_inputs
, and analog_inputs
keys define the sensors,
digital inputs and analog inputs configured on the device. Within each of the sections,
each key provides the name of the sensor or input and the value specifies the assigned
sensor or input number. The get_satus
method will provide each sensor/input value with
the specified label. Every status_state, sensor, and input must have a unique name.
Attempting to create aControlByWebWebRelay
with duplicate status_states,
sensors, or inputs will cause a ConfigurationException.
In this example, there are noise_diode_on
and noise_diode_off
keys to correspond to the
preselector paths to turn the noise diode on and off, and an antenna key to indicate the
web relay states to connect to the antenna.
Note: with this example configuration, you would have to set the path by the name of the
source rather than the index in the rf_paths
array.
import json
from its_preselector.web_relay_preselector import WebRelayPreselector
with open('config/metadata.sigmf-meta') as sensor_def_file:
sensor_def = json.load(sensor_def_file)
with open('config/config.json') as config_file:
preselector_config = json.load(config_file)
preselector = WebRelayPreselector(sensor_def, preselector_config)
preselector.set_state('antenna')
preselector.amplifiers[0].gain
- ...
preselector.get_amplifier_gain(rf_path_index)
preselector.get_amplifier_noise_figure(rf_path_index)
preselector.get_frequency_low_passband(rf_path_index)
preselector.get_frequency_high_passband(rf_path_index)
preselector.get_frequency_low_stopband(rf_path_index)
preselector.get_frequency_high_stopband(rf_path_index)
preselector.set_state(rf_path_name)
Set up a development environment using a tool like Conda
or venv, with python>=3.7
. Then,
from the cloned directory, install the development dependencies by running:
pip install .[dev]
This will install the project itself, along with development dependencies for pre-commit hooks, building distributions, and running tests. Set up pre-commit, which runs auto-formatting and code-checking automatically when you make a commit, by running:
pre-commit install
The pre-commit tool will auto-format Python code using Black
and isort. Other pre-commit hooks are also enabled, and
can be found in .pre-commit-config.yaml
.
This project uses Hatchling as a backend. Hatchling makes versioning and building new releases easy. The package version can be updated easily by using any of the following commands.
hatchling version major # 1.0.0 -> 2.0.0
hatchling version minor # 1.0.0 -> 1.1.0
hatchling version micro # 1.0.0 -> 1.0.1
hatchling version "X.X.X" # 1.0.0 -> X.X.X
To build a new release (both wheel and sdist/tarball), run:
hatchling build
See LICENSE
For technical questions, contact Doug Boulware, dboulware@ntia.gov