node-red-contrib-unifi-ultimate 1.0.1

Node-RED nodes for Ubiquiti UniFi integrations, including UniFi Protect, UniFi Access, and UniFi Network.

npm install node-red-contrib-unifi-ultimate

node-red-contrib-unifi-ultimate

Control and monitor UniFi Network, UniFi Protect, and UniFi Access from Node-RED without building API requests by hand.

View Changelog

Watch news and tutorials on YouTube

Install

In Node-RED:

1. Open Manage palette.
2. Select Install.
3. Search for node-red-contrib-unifi-ultimate.
4. Install the package.

Quick Start

1. Add the config node for your UniFi application: Unifi Network Config, Unifi Protect Config, or Unifi Access Config.
2. Enter the UniFi host/IP and API credentials.
3. Add the matching device or utility node.
4. Select the item to control or monitor.
5. Select the action.
6. Deploy.
7. Send any message into the node to run the configured action.

For most actions, the incoming message is only a trigger and the node uses the item/action configured in the editor.
Exception: in Unifi Network Control POE, action POE controlled by msg.payload uses msg.payload (true = enable PoE, false = disable PoE).

Use Network nodes to work with:

• sites
• UniFi devices such as switches and access points
• clients such as phones, computers, and IoT devices
• switch ports
• PoE control
• client presence

Common uses:

• Check whether a client is online.
• Restart a UniFi device.
• Power-cycle a PoE port.
• Turn PoE on or off for a selected switch port.
• Select a client and let the PoE node find the connected switch and port when the information is available.

Editor conveniences:

• Device and client fields are searchable.
• Port lists show port status and connected clients when UniFi exposes that information.
• Selecting an item updates the node Name automatically.

Use Protect nodes to work with:

• cameras
• sensors
• lights
• chimes
• viewers
• live views
• NVR information

Common uses:

• Receive motion, ring, contact, tamper, leak, and battery events.
• Read the current state of a camera or sensor.
• Take camera snapshots.
• Control PTZ cameras.
• Show doorbell messages.
• Switch viewer live views.
• Update supported device properties.

For supported observables, the node can output normalized values while still keeping the raw UniFi event details available (true/false for event states, numeric values for sensor metrics like temperature and humidity).

Use Access nodes to work with:

• doors
• Access devices
• door events
• lock rules
• emergency mode
• doorbell actions

Common uses:

• Unlock a door.
• Read or set a temporary lock rule.
• Enable lockdown or evacuation mode.
• Receive Access events.
• Trigger or cancel an intercom doorbell action.

Outputs

Most nodes send the result on output 1.

Protect and Access device nodes emit both state and live event messages on the same output pin when Receive Events is selected. On Access nodes, the Event selector can filter the stream to official UniFi Access event families, or use All for full passthrough.

Useful metadata is attached to the output message, for example:

• msg.topic (node Name from the editor)
• msg.deviceName (remembered/observed client or device name)
• msg.eventName (event/trigger that produced the output message)
• msg.details.unifiNetwork
• msg.details.unifiNetworkPresence
• msg.details.unifiNetworkPoe
• msg.details.unifiProtect
• msg.details.unifiAccess

When msg.payload is an object, it also includes payload.deviceName with the same value.

Output Examples

Unifi Network Device

{
  "topic": "Switch Soffitta",
  "deviceName": "Soffitta",
  "eventName": "request:readState",
  "payload": {
    "id": "8c072de0-d71d-37bd-a6f5-eac67c95a314",
    "name": "Soffitta",
    "state": "READY",
    "deviceName": "Soffitta"
  },
  "details": {
    "unifiNetwork": {
      "nodeType": "device",
      "deviceType": "device",
      "capability": "readState",
      "source": "request"
    }
  }
}

Unifi Network Presence

{
  "topic": "iPhone Massimo Presence",
  "deviceName": "iPhone-Massimo",
  "eventName": "connected",
  "payload": true,
  "present": true,
  "details": {
    "unifiNetworkPresence": {
      "nodeType": "presence",
      "source": "poll",
      "reason": "connected"
    }
  }
}

Unifi Network Control POE

{
  "topic": "POE Soffitta Port 2",
  "deviceName": "Soffitta",
  "eventName": "request:enable",
  "payload": {
    "status": "ok",
    "deviceName": "Soffitta",
    "portIdx": 2,
    "portName": "Port 2",
    "portPowerW": 2.6,
    "powerConsumptionSwitchTotal": 36.4
  },
  "details": {
    "unifiNetworkPoe": {
      "nodeType": "poe-control",
      "action": "enable",
      "portIdx": 2,
      "portPowerW": 2.6,
      "powerConsumptionSwitchTotal": 36.4
    }
  }
}

Power fields for Unifi Network Control POE:

Unifi Protect Device

{
  "topic": "Front Door Camera",
  "deviceName": "Front Door Camera",
  "eventName": "smartDetectZone",
  "payload": {
    "device": {
      "id": "camera-id"
    },
    "event": {
      "type": "smartDetectZone"
    },
    "deviceName": "Front Door Camera"
  },
  "details": {
    "unifiProtect": {
      "nodeType": "device",
      "deviceType": "camera",
      "capability": "observe",
      "source": "events"
    }
  }
}

Unifi Access Device

{
  "topic": "Main Door",
  "deviceName": "Main Door",
  "eventName": "door.unlock",
  "payload": {
    "event": "door.unlock",
    "deviceName": "Main Door"
  },
  "details": {
    "unifiAccess": {
      "nodeType": "device",
      "deviceType": "door",
      "capability": "observe",
      "source": "events"
    }
  }
}

Example Flows

Import from examples/:

Notes

• You need valid API credentials for the UniFi application you want to use.
• Some actions depend on what the selected UniFi device supports.
• UniFi API behavior can vary between application versions.
• For safety, actions exposed by the nodes are intentionally limited to known supported operations.