Merge pull request #11 from NTIA/WebRelayAndStatus

Separate WebRelay class and provide status

.markdownlint.yaml

@@ -0,0 +1,6 @@
+default: true
+MD013:
+  line_length: 88
+MD033:
+  allowed_elements:
+    - "figcaption"

.pre-commit-config.yaml

@@ -0,0 +1,42 @@
+default_language_version:
+  python: python3.7
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.1.0
+    hooks:
+      - id: check-ast
+        types: [file, python]
+      - id: check-case-conflict
+      - id: check-docstring-first
+        types: [file, python]
+      - id: check-merge-conflict
+      - id: check-yaml
+        types: [file, yaml]
+      - id: debug-statements
+        types: [file, python]
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v2.34.0
+    hooks:
+      - id: pyupgrade
+        args: ["--py3-plus"]
+  - repo: https://github.com/pycqa/isort
+    rev: 5.10.1
+    hooks:
+      - id: isort
+        name: isort (python)
+        types: [file, python]
+        args: ["--profile", "black", "--filter-files", "--gitignore"]
+  - repo: https://github.com/psf/black
+    rev: 22.6.0
+    hooks:
+      - id: black
+        types: [file, python]
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.31.1
+    hooks:
+      - id: markdownlint
+        types: [file, markdown]
+        exclude: GitHubRepoPublicReleaseApproval.md|LICENSE.md

README.md

@@ -1,5 +1,10 @@
 # NTIA/ITS Preselector API
 
+![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/NTIA/Preselector?display_name=tag&sort=semver)
+![GitHub all releases](https://img.shields.io/github/downloads/NTIA/Preselector/total)
+![GitHub issues](https://img.shields.io/github/issues/NTIA/Preselector)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
 This repository provides a general software API to control preselectors regardless of their
 components and control mechanisms.
 
@@ -9,71 +14,89 @@ A simple `set_state` method allows users to specify the state of the preselector
 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](https://www.controlbyweb.com/x310/).
-See below for additional details on using the `WebRelayPreselector`.  
+See below for additional details on using the `WebRelayPreselector`.
 
 This software will grow over time to support additional components and control mechanisms.
 
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Usage](#usage)
+- [Development](#development)
+- [License](#license)
+- [Contact](#contact)
+
 ## Introduction
 
- 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.
+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.
 
 ![Preselector Diagram](/docs/img/preselector.png)
-<p style="text-align: center;"><figcaption align = "center"><b>Figure.1 - Example Preselector</b></figcaption></p>
+<figcaption>Figure 1: Block diagram showing an example RF measurement system with a preselector.</figcaption>
 
+## Usage
 
-## Installation
-
-To install this Python package, clone the repository and enter the directory of the project in
-the command line (should be the same location as `setup.cfg`). Execute the following commands
-depending on your OS (you may have to adjust for your version of Python):
+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):
 
 ```bash
 # Windows
-py –m build 
-py -m pip install dist/its-preselector-2.0.1.tar.gz 
+py -m pip install .
 
 # Linux
-python3 -m build
-python3 –m pip install dist/its-preselector-2.0.1.tar.gz 
-
+python3 –m pip install .
 ```
 
-## `WebRelayPreselector` Configuration
+### `WebRelayPreselector` Configuration
 
 The `WebRelayPreselector` requires a [SigMF metadata file](https://Github.com/NTIA/sigmf-ns-ntia)
-that describes the sensor preselector and a config file to describe the x310 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:
+that describes the sensor preselector and a config file to describe the x310 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:
 
 ```json
 {
-  "base_url" : "http://192.168.130.32/state.xml",
-  "noise_diode_on" : "1State=1,2State=1,3State=0,4State=0",
-  "noise_diode_off" : "1State=0,2State=1,3State=0,4State=0",
-  "antenna" : "1State=0,2State=0,3State=0,4State=0"
+  "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"
+  }
 }
 ```
 
-The `base_url` key is the only required key for the `WebRelayPreselector` and should map to the
-base URL to interact with the WebRelay (see [https://www.controlbyweb.com/x310](https://www.controlbyweb.com/x310)
-for more info). The other keys should correspond to RF paths documented in the SigMF metadata.
-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 keys in the dictionary may use the name of the RFPath or the index of the RFPath in
-the RFPaths array.
+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](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 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 keys in the dictionary may use the
+name of the RFPath or the index of the RFPath in the RFPaths array.
 
 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.
+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.
+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.
 
-## `WebRelayPreselector` Initialization
+### `WebRelayPreselector` Initialization
 
 ```python
 import json
@@ -90,14 +113,14 @@ preselector = WebRelayPreselector(sensor_def, preselector_config)
 preselector.set_state('antenna')
 ```
 
-## Preselector Interactions
+### Preselector Interactions
 
-### Access instance properties
+#### Access instance properties
 
 - `preselector.amplifiers[0].gain`
 - ...
 
-### Helper methods
+#### Helper methods
 
 - `preselector.get_amplifier_gain(rf_path_index)`
 - `preselector.get_amplifier_noise_figure(rf_path_index)`
@@ -106,13 +129,54 @@ preselector.set_state('antenna')
 - `preselector.get_frequency_low_stopband(rf_path_index)`
 - `preselector.get_frequency_high_stopband(rf_path_index)`
 
-### Control
+#### Control
 
 - `preselector.set_state(rf_path_name)`
 
+## Development
+
+Set up a development environment using a tool like [Conda](https://docs.conda.io/en/latest/)
+or [venv](https://docs.python.org/3/library/venv.html#module-venv), with `python>=3.7`. Then,
+from the cloned directory, install the development dependencies by running:
+
+```bash
+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:
+
+```bash
+pre-commit install
+```
+
+The pre-commit tool will auto-format Python code using [Black](https://github.com/psf/black)
+and [isort](https://github.com/pycqa/isort). Other pre-commit hooks are also enabled, and
+can be found in [`.pre-commit-config.yaml`](.pre-commit-config.yaml).
+
+### Building New Releases
+
+This project uses [Hatchling](https://github.com/pypa/hatch/tree/master/backend) 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.
+
+```bash
+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:
+
+```bash
+hatchling build
+```
+
 ## License
 
-See [LICENSE](LICENSE.md).
+See [LICENSE](LICENSE.md)
 
 ## Contact
 

config/config.json

@@ -1,6 +1,14 @@
 {
+  "name": "preselector",
   "base_url" : "http://192.168.1.2/state.xml",
-  "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"
+  "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"
+  }
+
 }

pyproject.toml

@@ -1,7 +1,61 @@
 [build-system]
-requires = [
-    "setuptools>=42",
-    "wheel",
-    "requests>=2.25.1"
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "its-preselector"
+dynamic = ["version"]
+description = "A package to control the ITS web relay-based preselector"
+readme = "README.md"
+requires-python = ">=3.7"
+license = { file = "LICENSE.md" }
+
+authors = [
+    { name = "The Institute for Telecommunication Sciences" },
 ]
-build-backend = "setuptools.build_meta"
+
+maintainers = [
+    { name = "Doug Boulware", email = "dboulware@ntia.gov" },
+]
+
+keywords = [
+    "preselector", "SDR", "NTIA", "web relay", "API",
+    "radio", "NTIA", "ITS", "telecommunications", "spectrum",
+]
+
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Telecommunications Industry",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+]
+
+dependencies = [
+    "requests>=2.25.1",
+    "defusedxml>=0.7.1"
+]
+
+[project.optional-dependencies]
+dev = [
+    "hatchling>=1.6.0,<2.0",
+    "pre-commit>=2.20.0",
+    "pytest>=7.1.2",
+    "pytest-cov>=3.0.0",
+    "twine>=4.0.1,<5.0"
+]
+
+[project.urls]
+"Repository" = "https://github.com/NTIA/Preselector"
+"Bug Tracker" = "https://github.com/NTIA/Preselector/issues"
+"NTIA GitHub" = "https://github.com/NTIA"
+"ITS Website" = "https://its.ntia.gov"
+
+[tool.hatch.version]
+path = "src/its_preselector/__init__.py"