Unifi API Integration?

[Oggy512]

Hi all,
I'm using an Ubiquiti UDM Pro as Gateway, behind my Vodafone (DE) Station, which is in Bridgemode.
Due to some Internet Problems in the past I do have a 4G Fail over WAN Uplink, therefore I do not really notice so much VF outtakes anymore.

My question is, if it's possible to integrate the Unifi API in Docsight?
With that one could maybe monitor/log the WAN outtakes from VF automatically?

[itsDNNS]

Hey @Oggy512,

interesting idea - I want to make sure I understand the use case correctly though.

DOCSight already monitors DOCSIS signal quality directly on your Vodafone Station, so signal degradation and modem-level issues are covered. But I'm guessing the problem is your connection monitor: with a 4G failover on the UDM Pro, DOCSight's connectivity checks will always come back as "online" even when your cable WAN is actually down, because traffic just routes over LTE. Is that what you're running into?

If so, pulling WAN failover events from the Unifi API would make sense - the UDM Pro knows exactly when it switches from WAN1 (cable) to WAN2 (4G) and back.

That said, I don't own any Unifi hardware myself, so I couldn't realistically build, test, or maintain this. This sounds like a great candidate for a community module though. DOCSight has a modular driver architecture, and the Unifi API is well documented. If you (or anyone else with a UDM) want to take a stab at it, I'm happy to help with the integration side and review PRs.

Let me know if I'm reading the problem right or if there's something else you're after.

[Oggy512]

Yes, that‘s the usecase. I‘d like to „map“ or align the events DOCsight tracks with actual WAN down events.
Currently I got a lot of statistics directly from the VF Station, multiple signal modulations or drops etc pp.
Not all of them lead to a internet outtake, but some. And even if VF internet is down, the UDM does the failover and my BQM as well as my connectionmonitor shows just a quick ping drop, if any…

With a Unifi module those WAN (1) down events could potentially be (automatically?) maped or displayed together with the data from Docsight/VF Station.

I‘m not really a programmer, however I‘m an IT Admin with some programming skills. I‘ll try to do some vibe coding and get something together and see, if I can get results when querying the UI API. Maybe I need some additional help or pointing from your side as well :-)

[Oggy512]

Hi @itsDNNS

I did some testing, coding and vibe-coding by claude.ai and came up with an initial draft of a community module. It does basically what I described above. I'm not sure, how the events, created by the module now can be aligned with other events form DOCsight?

If you want to have a look at the module (even if you don't own an UDM):
https://github.com/Oggy512/UDM-WAN-Monitor

[itsDNNS]

Hey @Oggy512,

I had a look at your UDM-WAN-Monitor module and I have to say, this is solid work for a first community module. The collector architecture is clean, the state tracking per interface makes sense, and events landing in the global DOCSight event log means correlation with DOCSIS signal data works out of the box. That was the key piece you were asking about -- WAN failover events next to modem signal drops on the same timeline.

A few things I noticed that would be worth cleaning up before publishing:

i18n: Some event messages are hardcoded in German ("nicht erreichbar", "wieder online"). For a community module, English as default with German translations in the i18n folder would be better. The module already has an i18n directory, so the wiring is there.

URL construction: _build_cfg_from builds the base URL with an f-string and appends the port directly. If someone passes a host that already includes the protocol or port, this can produce broken URLs. A small validation step would help.

urllib3 warnings: urllib3.disable_warnings() at module level disables SSL warnings globally for the entire process. Better to set verify=False only on the session object (which you already do) and skip the global disable.

Blueprint static path: The blueprint declares a static_url_path but there is no static/ directory in the module. Not a bug, but Flask logs a warning on startup.

Event storage: The save_events() / save_event() fallback with hasattr checks works but is fragile. DOCSight's storage always has save_event(), so you can drop the save_events path and call save_event() directly in a loop.

Once you have addressed those, I would suggest submitting this as a PR to the docsight-modules repo. That way other UDM Pro users can install it directly and it gets visibility in the module registry.

Really glad to see someone building on the module system. If other Unifi users pick this up, there is potential for more integration -- WAN latency history, client count correlation, maybe even AP health. Keep going with this.

[Oggy512]

I (and/or claude.ai) incorporated the changes and submitted the PR.

Should I disable local modules again (by removing the entry in the docker-compose.yml?) and switch to the community version, once it is online?

[itsDNNS]

Hey @Oggy512, nice work on getting the PR up that quickly! You went from idea to a full working module with collector, state tracking, and i18n in just a few days. Doesn't matter what tools you use to get there, the result speaks for itself.

Yes, once the module is live in the registry you can remove the local entry from your docker-compose.yml and install it through the Module Manager instead. That way you also get future updates automatically.

I'll review the PR shortly.

[itsDNNS]

Merged! The module is now in the registry.

I pushed a few hardening commits to your branch before merging (auth on routes, XSS escaping, i18n parity for FR/ES, and a couple of smaller things). You can check the commit history on the PR for details.

[Oggy512]

Community module has been created :-)