Expose port.up as a binary_sensor entity for switch port link state

[bluenazgul]

Integration name

UniFi Network

Link to integration documentation on our website

https://www.home-assistant.io/integrations/unifi/

Describe the enhancement

The integration currently exposes port link speed (sensor._port_link_speed) and port enable/disable (switch.port*), but never exposes whether a port has an active physical link.

The aiounifi library already provides port.up (bool | None) in its Port model:

@property
def up(self) -> bool | None:
    """Is port up."""
    return self.raw.get("up")

This value is delivered via the existing WebSocket device:sync message — no polling or API changes needed.

Today, to determine if a port has an active link, third-party tools must infer it from the switch.port entity — which actually represents the admin port enable setting, not physical link state. These are two distinct concepts:

• Port enabled: admin decision (should this port be active?)
• Port link up: physical fact (is a cable connected and negotiated?)

Proposed addition — a new binary_sensor per port, disabled by default, consistent with the integration's existing port entity patterns:

key="port_link"
device_class=BinarySensorDeviceClass.CONNECTIVITY
entity_category=EntityCategory.DIAGNOSTIC
entity_registry_enabled_default=False
name_fn=lambda port: f"{port.name} link"
unique_id_fn=lambda hub, obj_id: f"port_link-{obj_id}"
value_fn=lambda _, port: port.up

This covers all port types already modelled via api.ports: standard RJ45 ports (10/100/1000 Mbit), SFP/SFP+ ports, and WAN ports on gateway devices (UCG Ultra, UCG Max, UDM Pro, UDM SE).

Use cases

1. Dashboard cards — show which physical ports have an active link (cable plugged in), independent of PoE state or admin enable setting.

2. Automations triggered by a device physically connecting or disconnecting from a specific switch port.

3. WAN / SFP port monitoring — alert when an uplink or WAN port loses its link, which is more reliable than polling client state.

4. Wired presence detection based on port link state rather than client tracking, which can be affected by MAC randomization or reconnect delays.

Anything else?

The existing sensor.*_port_link_speed entity partially addresses observability, but its entity ID includes the connected client's port label (configured in the UniFi console), making stable programmatic matching by port index unreliable.

A binary_sensor with a port-index-based unique_id solves this cleanly and complements the already existing speed sensor.

Related community card that motivated this request: https://github.com/bluenazgul/unifi-device-card

[github-actions[bot]]

🏷️ I've automatically added the integration: unifi label to help categorize this feature request.