Antenna-source plugins#
An antenna source uses the same record as a building source, DataSource: an identifier, a
title, an implementation version, a factory that builds an asynchronous provider, and
optional coverage, routing, configuration and attribution fields. Installed packages register
one through the openworld_radio_twin.antenna_sources entry-point group; the entry-point name
must equal the identifier. The explorer, the batch page, GET /api/antenna-sources and
owrt sources list list it, and the Python loader accepts its identifier, without further
changes.
# pyproject.toml
[project.entry-points."openworld_radio_twin.antenna_sources"]
myregister = "owrt_my_register:antenna_source"
# owrt_my_register/__init__.py
from openworld_radio_twin.models import AntennaFeature, FrequencyBand
from openworld_radio_twin.providers.base import AntennaProviderError, AntennaQueryResult
from openworld_radio_twin.providers.registry import DataSource, region
class MyRegister:
def __init__(self, settings, client):
self.client = client
async def antennas(self, latitude, longitude, radius_m) -> AntennaQueryResult:
records = [
AntennaFeature(
feature_id="myregister:1234",
source="myregister",
source_release="2026-09",
site_id="site-17",
operator="Example Mobile",
radios=["LTE"],
bands=[FrequencyBand(label="LTE 1800", low_mhz=1805, high_mhz=1880)],
latitude=52.3762,
longitude=4.8993,
height_agl_m=31.0, # leave a value None when the register has none
azimuth_deg=120.0,
)
]
return AntennaQueryResult(records, provider="My register", release="2026-09")
def antenna_source() -> DataSource:
return DataSource(
identifier="myregister",
title="My register",
version="1",
factory=MyRegister,
covers=region("netherlands"),
auto_priority=None, # explicit selection only until listed for auto
attribution="Example regulator",
license="CC BY 4.0",
)
Provider contract#
antennas(latitude, longitude, radius_m)returns the records around the square scene domain as the source has them. OWRT cuts them to the exact square, classifies each registered range as downlink, uplink or TDD, selects operator, radio and channel, and places them; the provider does none of that.Give every range the source registers in
bands, uplink and downlink as listed, each with the source’s system label. A source that records a cell’s carrier gives a range as narrow as that carrier; a source without frequencies leavesbandsempty. When the source states the direction, as a register of transmitters does, setlink="downlink"on the band; OWRT then skips its own classification of that range.Leave a value
Nonewhen the source does not record it. A value the source gives counts as"source"; mark one computed from source data, such as a centroid, as"derived"inbasis. Placement fills the rest from the defaults listed in Antennas and marks them"default".Raise
AntennaProviderErrorfor acquisition failures; the service reports502instead of an empty scene.A provider that reads a whole published export can pin it with the helpers in
providers/snapshots.py: install it undersource_cache_root(settings) / <identifier>and addsnapshot(refresh=False), which returns the installedSnapshot.owrt sources refresh <identifier>calls it withrefresh=True, andowrt sources listshows the release it finds in that directory. A provider without the method queries its data on each request.
Routing, configuration and identity#
auto_prioritymakes a source eligible forauto, higher priority winning among covering sources; the eligible set is further limited byOWRT_AUTOMATIC_ANTENNA_SOURCES.covers(latitude, longitude)restricts explicit and automatic selection. A register read from a snapshot cannot tell that a query lies outside its country, so it usescovers, and an explicit request outside it fails.auto_coversrestricts only automatic routing; it suits a provider that checks its own tile index.A built-in source joins the default
OWRT_AUTOMATIC_ANTENNA_SOURCESonly when its publisher’s terms let anyone use, adapt and share the data and results derived from it for any purpose, with at most attribution and share-alike conditions; it names them inlicense,license_urlandattribution. A source without such terms stays selectable by its identifier, and a deployment may add it to the setting itself. The ACMA licence forbids using licensee details for unsolicited marketing and reproducing the details of licensees who are natural persons, soacmais not in the default list.configured(settings)reports whether the settings supply what the source needs, such as a token or a file;autoskips an unconfigured source and an explicit request for it fails withconfiguration_hint, which the pages also show next to the disabled source.versionandconfiguration_identity(settings)enter the source identity recorded with every antenna selection and dataset scene.