unifi-events
unifi-events is a Node.js module that allows you to listen for events from and call methods on the UniFi API (UniFi is Ubiquiti Networks wifi controller software).
Requirements
- Node.js v6 or later
- UniFi-Controller v5
Installation
$ npm install unifi-events
Example
const Unifi = require('unifi-events')
const unifi = new Unifi({
host: 'unifi', // The hostname or ip address of the unifi controller (default: 'unifi')
port: 8443, // Port of the unifi controller (default: 8443)
username: 'admin', // Username (default: 'admin').
password: 'ubnt', // Password (default: 'ubnt').
site: 'default', // The UniFi site to connect to (default: 'default').
insecure: true, // Allow connections if SSL certificate check fails (default: false).
unifios: false // For devices with UnifiOS turn this on
});
// Listen for any event
unifi.on('**', function (data) {
console.log(this.event, data);
});
Events
unifi-events uses EventEmitter2 and namespaced events.
ctrl
namespace These events indicate the status of the connection to the UniFi controller
-
ctrl.connect
- emitted when the connection to the controller is established -
ctrl.disconnect
- emitted when the connection to the controller is lost -
ctrl.error
- -
ctrl.reconnect
-
wu
, wg
, lu
, ...
namespaces This JSON file shows all possible events: https://demo.ubnt.com/manage/locales/en/eventStrings.json?v=5.4.11.2
The prefix EVT_
gets stripped, the first underscore is replaced by the namespace separating dot, everything is
converted to lower case. Some events such as EVT_AD_LOGIN
(Admin Login) are not emitted by the UniFi Controller.
Example Wireless User events
-
wu.connected
- Wireless User connected -
wu.disconnected
- Wireless User disconnected -
wu.roam
- Wireless User roamed from one AP to another -
wu.roam_radio
- Wireless User changed channel on the same AP
Example Wireless Guest Events
-
wg.connected
- Wireless Guest connected -
wg.disconnected
- Wireless Guest disconnected -
wg.roam
- Wireless Guest roamed from one AP to another -
wg.roam_radio
- Wireless Guest changed channel on the same AP -
wg.authorization_ended
- Wireless Guest became unauthorised
Wildcard usage
Example listing for events on Guest Wireless networks only:
unifi.on('wg.*', function (data) {
console.log(this.event, data);
})
Example listening for connected events on all network types:
unifi.on('*.connected', function (data) {
console.log(this.event, data);
});
Methods
connect()
Connect to the UniFi controller. Is called in the constructor, so normally you don't need to call it (except if you want to re-establish a connection that was closed before).
close()
Closes the connection to the UniFi controller
UniFi API Methods
Following methods operate on the configured site. The path gets prefixed with
https://<host>:<port>/api/s/<site>/
if it does not start with a slash, otherwise it gets prefixed with
https://<host>:<port>
. To explore available API endpoints you can use the
UniFi-API-browser.
These methods are returning a promise.
get(path)
Do a HTTP GET on the API.
Examples:
- Get a list of all clients
unifi.get('stat/sta').then(console.log);
- Get infos of a specific client
unifi.get('stat/user/<mac>').then(console.log);
- Get alarms
unifi.get('list/alarm').then(console.log);
- Get wireless network IDs
unifi.get('rest/wlanconf').then(res => {
res.data.forEach(wlan => {
console.log(wlan.name, wlan._id);
});
});
- Get device IDs
unifi.get('stat/device').then(res => {
res.data.forEach(dev => {
console.log(dev.name, dev._id);
});
});
del(path)
Do a HTTP DELETE on the API.
post(path, body)
Do a HTTP POST on the API.
Examples:
- Enable all LEDs of all APs
unifi.post('set/setting/mgmt', {led_enabled: true}).then(console.log);
- Disable a WLAN
unifi.post('upd/wlanconf/<wlan_id>', {enabled: false}).then(console.log);
put(path, body)
Do a HTTP PUT on the API.
Examples:
- Enable LED of AP
unifi.put('rest/device/<device_id>', {led_override: 'on'}).then(console.log);
License
- MIT © 2017-2021 oznu
- MIT © 2018 Sebastian Raff