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 leaves bands empty. When the source states the direction, as a register of transmitters does, set link="downlink" on the band; OWRT then skips its own classification of that range.

  • Leave a value None when 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" in basis. Placement fills the rest from the defaults listed in Antennas and marks them "default".

  • Raise AntennaProviderError for acquisition failures; the service reports 502 instead of an empty scene.

  • A provider that reads a whole published export can pin it with the helpers in providers/snapshots.py: install it under source_cache_root(settings) / <identifier> and add snapshot(refresh=False), which returns the installed Snapshot. owrt sources refresh <identifier> calls it with refresh=True, and owrt sources list shows the release it finds in that directory. A provider without the method queries its data on each request.

Routing, configuration and identity#

  • auto_priority makes a source eligible for auto, higher priority winning among covering sources; the eligible set is further limited by OWRT_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 uses covers, and an explicit request outside it fails. auto_covers restricts only automatic routing; it suits a provider that checks its own tile index.

  • A built-in source joins the default OWRT_AUTOMATIC_ANTENNA_SOURCES only 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 in license, license_url and attribution. 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, so acma is not in the default list.

  • configured(settings) reports whether the settings supply what the source needs, such as a token or a file; auto skips an unconfigured source and an explicit request for it fails with configuration_hint, which the pages also show next to the disabled source.

  • version and configuration_identity(settings) enter the source identity recorded with every antenna selection and dataset scene.