Skip to main content

unified_respondd

This queries the API of a WiFi controller to get the current status of the Accesspoints and sends the information via the respondd protocol. Thus it can be picked up by yanic and other respondd queriers and shown on Freifunk maps.

It replaces the former unifi_respondd, omada_respondd and uisp_respondd. Supported controllers (backends):

Backend Controller
unifi UniFi Network controller
omada TP-Link Omada controller
uisp UISP (airFiber, airMAX, … links)
graph TD;
	A{"*respondd_main*"} -->| | B("*backend (unifi, omada, uisp)*")
    A -->| | C("*respondd_client*")
	B -->|"RestFul API"| D("controller")
    C -->|"Subscribe"| E("multicast")
    C -->|"Send per interval / On multicast request"| F("unicast")
    G{"yanic"} -->|"Request metrics"| E
    F -->|"Receive"| G

Installation

Install the package together with the dependencies of your backend, e.g. into /opt/unified-respondd:

python3 -m venv /opt/unified-respondd
/opt/unified-respondd/bin/pip install 'unified_respondd[unifi] @ git+https://github.com/freifunkMUC/unified_respondd'

Use [omada] or [uisp] for the other backends, or once a release is on PyPI simply pip install 'unified_respondd[unifi]'.

Running ./respondd.py from a checkout (after pip install -r requirements.txt) keeps working for existing deployments.

Dependencies

  • Python 3.10 or newer, pyyaml and dataclasses-json
  • unifi: pyunifi, geopy, requests
  • omada: geopy, requests (the Omada API client is vendored)
  • uisp: requests
  • The controller API and, for unifi and omada, the meshviewer nodelist to look up the offloaders
  • For unifi and omada: SNMP locations that aren't coordinates are geocoded via Nominatim (OpenStreetMap)

Configuration

Set backend in the config file. It defaults to unifi, so existing unifi_respondd configs work unchanged. See examples/ for a config per backend.

The config file is looked up in this order:

  1. UNIFIED_RESPONDD_CONFIG_FILE, then the legacy UNIFI_RESPONDD_CONFIG_FILE
  2. ./unified_respondd.yaml, then the legacy ./unifi_respondd.yaml

Keys of all backends:

Key Description
backend unifi (default), omada or uisp
multicast_enabled Answer multicast requests (true) or send per interval via unicast (false)
multicast_address, multicast_port Multicast group to join, e.g. ff05::2:1001 and 1001
unicast_address, unicast_port Where to send the data in unicast mode
interface Interface to bind to
verbose Log more details
logging_config Optional logging dictConfig
fallback_domain Optional domain if no offloader is found (default <backend>_respondd_fallback)
unknown_location APs without a location (0/0): report them at 0/0 (default), omit the location so they are listed but not shown on the map, or skip them

Keys of the backends:

Key unifi omada uisp
controller_url host, e.g. unifi.lan URL with port, e.g. https://omada.lan:8043 API base URL, e.g. https://uisp.lan/nms/api/v2.1
controller_port ✓ – –
username, password ✓ ✓ –
token – – ✓
version ✓ (e.g. v5, UDMP-unifiOS) – –
ssl_verify ✓ ✓ –
ssid_regex ✓ ✓ –
offloader_mac, nodelist ✓ ✓ –

With skip, links of other nodes to a skipped AP still show up in their neighbours.

Several controllers

One instance can query several controllers, each with its own backend and credentials. List them under controllers, the respondd keys stay at the top level:

unknown_location: report     # default of all controllers
controllers:
  - name: omada              # optional, used in the logs
    backend: omada
    controller_url: https://omada.lan:8043
    username: omada
    password: omada
    # … further omada keys
    unknown_location: omit   # per controller
  - backend: uisp
    controller_url: https://uisp.lan/nms/api/v2.1
    token: t-o-k-en
multicast_enabled: false
# … further respondd keys

A controller that can't be queried is logged and skipped, the others are reported as usual. Keys shared by several controllers can be reused with a YAML anchor, see examples/multi.yaml. A config without controllers is a single controller with its keys at the top level.

unifi and omada only report APs broadcasting an SSID that matches ssid_regex. uisp reports all connected devices except those with Router in their name, the neighbours come from the UISP data links.

Running

systemd

examples/unified-respondd@.service is a template unit, one instance per controller:

install -m 0600 unifi.yaml /etc/unified-respondd/unifi.yaml
systemctl enable --now unified-respondd@unifi

The unit runs as an unprivileged DynamicUser and gets the config via LoadCredential, which needs systemd 247 or newer. The unit file explains the alternative for older systemd.

To run several controllers on one host, either use one instance with a controllers list or one instance per controller. In multicast mode only one instance can bind the multicast port, so there all controllers have to be in one instance.

For OpenWrt there is a procd script in examples/unified-respondd.init.d.

Testing against a controller

--dry-run queries the controller once, prints the respondd data per node as JSON and exits without sending anything:

UNIFIED_RESPONDD_CONFIG_FILE=/etc/unified-respondd/unifi.yaml unified-respondd --dry-run

It exits with 1 if a controller couldn't be queried, the data of the other controllers is printed anyway.

Operations

  • Logging: Everything is logged to stderr, with systemd to the journal: journalctl -u unified-respondd@unifi. Failed controller or nodelist requests are logged as ERROR, with several controllers as Could not fetch the APs of controller <name>. The query is retried in the next interval. The format and level can be changed with logging_config.
  • Monitoring: systemd restarts the service if it exits (Restart=always). HTTP requests time out after 30 seconds, so a hanging controller doesn't block the service. unified-respondd --dry-run can be used as a check, it fails if a controller is unreachable. Whether the nodes are current can be seen on the map or in yanic.
  • Rollback: Install the previous version (pip install 'unified_respondd[…] @ git+https://github.com/freifunkMUC/unified_respondd@<tag>' or check out the previous tag) and restart the service. When migrating from omada_respondd or uisp_respondd, keep the old installation and leave controller_port in the config until the new service runs fine: the old versions require it and ignore the new backend key.

Migrating

From unifi_respondd

Nothing to change, the config and respondd.py keep working. Optionally add backend: unifi and rename the config to unified_respondd.yaml.

From omada_respondd

  1. Install unified_respondd[omada] (or pip install -r requirements.txt in a checkout).
  2. Add backend: omada to the config. controller_port is no longer used, the port is part of controller_url.
  3. Rename OMADA_respondd.yaml to unified_respondd.yaml or point UNIFIED_RESPONDD_CONFIG_FILE to it. OMADA_RESPONDD_CONFIG_FILE is not read anymore.
  4. Check the output with --dry-run, then restart the service.

Behaviour changes compared to omada_respondd:

  • APs whose Freifunk SSID is disabled (ssidEnabled: false) are no longer reported.
  • APs without an SNMP location are reported (with the location from the controller, or 0/0).
  • The uplink neighbour MAC is lowercase, so it matches the node MAC.
  • One login per query for all sites, followed by a logout.
  • A failing site or AP is skipped and logged instead of aborting the whole query.

From uisp_respondd

  1. Install unified_respondd[uisp] (or pip install -r requirements.txt in a checkout).
  2. Add backend: uisp to the config. controller_port is no longer used. controller_url is the API base URL without /devices, e.g. https://uisp.example.org/nms/api/v2.1.
  3. Rename uisp_respondd.yaml to unified_respondd.yaml or point UNIFIED_RESPONDD_CONFIG_FILE to it. UISP_RESPONDD_CONFIG_FILE is not read anymore.
  4. Check the output with --dry-run, then restart the service.

Behaviour changes compared to uisp_respondd:

  • The firmware base is UISP instead of UniFi.
  • fallback_domain sets the domain of the devices (default uisp_respondd_fallback).
  • The data links are fetched once per query instead of once per device.
  • Requests time out after 30 seconds, failed requests are logged.
  • The statistics contain gateway*: null and wireless: [], the nodeinfo owner.contact: null and devices without a link an empty neighbour list, like the other backends.

Controller setup

Linking an Offloader to a Site by MAC Address

To link an offloader to your site (unifi and omada), specify the MAC address of the offloader in your YAML configuration file. This enables unified_respondd to identify the offloader device and mark it correctly on the map. The key is the name of the site in the controller.

  1. Open your YAML configuration file (e.g., unified_respondd.yaml).
  2. Add or find the section for offloader settings. (Sectionname offloader_mac)
  3. Insert the MAC address of your offloader device like this:
    offloader_mac:
        SiteName: 00:00:00:00:00:00
    
  4. Save the YAML file.
  5. Restart the service to apply the changes.
image

Setting Location for UniFi Devices

To set the GPS location of each UniFi Access Point (AP):

  1. Open the UniFi Controller web interface.
  2. Go to the Devices section.
  3. Select the Access Point you want to configure.
  4. Click on Settings for that AP.
  5. Under SNMP, enter the GPS coordinates as latitude and longitude separated by a comma in the Location field, e.g., 48.1351, 11.5820.
  6. Save your changes.

This sets the location for the AP, helping with accurate device placement on Freifunk maps.

image

Setting Contact Information for UniFi Devices

To set contact information for each UniFi Access Point (AP):

  1. Open the UniFi Controller web interface.
  2. Go to the Devices section.
  3. Select the Access Point you want to configure.
  4. Click on Settings for that AP.
  5. Under SNMP, enter contact details (email, phone, etc.) in the Contact field.
  6. Save your changes.

This free-text field helps identify device ownership or provides general contact info which is shown on the Freifunk maps.

Setting Location for Omada Devices

To set the GPS location of each Omada Access Point (AP):

  1. Open the Omada Controller web interface.
  2. Go to the Devices section.
  3. Select the Access Point you want to configure.
  4. Click on Config for that AP.
  5. Under Services, enter the GPS coordinates as latitude and longitude separated by a comma in the Location field under SNMP, e.g., 48.1351, 11.5820.
  6. Save your changes.

If the SNMP location is empty, the location configured for the AP in the controller is used.

Setting Contact Information for Omada Devices

To set contact information for each Omada Access Point (AP):

  1. Open the Omada Controller web interface.
  2. Go to the Devices section.
  3. Select the Access Point you want to configure.
  4. Click on Config for that AP.
  5. Under Services, enter contact details (email, phone, etc.) in the Contact field under SNMP.
  6. Save your changes.

UISP

The location of a device is taken from UISP. The neighbours are the links configured in UISP.

Development

pip install -r requirements-dev.txt -e '.[unifi,omada,uisp]'
pytest
ruff check . && ruff format --check .

A new backend is a module in src/unified_respondd/backends/ implementing the Backend protocol from backends/__init__.py (a ControllerConfig dataclass and get_infos(cfg) returning model.Accesspoints) and registered in BACKENDS there. A test checks every registered backend against the protocol.

Ownership

Maintained by @freifunkMUC/firmware. Please report issues and send pull requests on GitHub.

Metadata

Release files for unified-respondd 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for unified-respondd 0.1.0
File Size Uploaded Provenance Actions
unified_respondd-0.1.0.tar.gz 62.7 kB With provenance Details for unified_respondd-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for unified-respondd 0.1.0
File Interpreter ABI Platform Actions
unified_respondd-0.1.0-py3-none-any.whl Python 3 none any Details for unified_respondd-0.1.0-py3-none-any.whl

Total release size: 108.6 kB

Release files / unified_respondd-0.1.0.tar.gz

Download URL unified_respondd-0.1.0.tar.gz
Size 62.7 kB
Tags Source
SHA-256 checksum
How to use checksums
93d4c3bbf1344d0d4e516ef0b3a62e858466e327387fe92e29cc0731858f9126
BLAKE2b-256 checksum
How to use checksums
03097386d891e834c2c0dd27e0de4a2b06882cd1b8e1b06306861cd53989b597
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.

Transparency log

Release files / unified_respondd-0.1.0-py3-none-any.whl

Download URL unified_respondd-0.1.0-py3-none-any.whl
Size 45.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5138058b044c1c5e315507f7610fa092cf2e128bda6ebac296998ee99f04d30f
BLAKE2b-256 checksum
How to use checksums
78bc6ff1b773857b26cb5ce244192d41e8b70215986522e4140049f29193732d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.

Transparency log

Security for unified-respondd 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for unified_respondd-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page