Ruckus Unleashed Networks Binding

This binding integrates with Ruckus Unleashed Networks enabling an OpenHAB instance to leverage presence detection, view basic network information as well as blocking / unblocking clients from the network. The binding will connect to the CLI
via ssh and use an expect script style to fetch information.

Dependencies

Supported Things

  • controller - The Ruckus Wireless Master Controller
  • wirelessclient - Any wireless client connected to the Ruckus Unleashed network network

Discovery

Discovery is support and recommended. Add a new bridge thing manually and after that you can discover wireless clients by pressing the scan
button in the OpenHAB GUI. Note that only active clients on the wireless network will be discovered.

Binding Configuration

The binding has no configuration options, all configuration is done at the Bridge and Thing levels.

Bridge Configuration

You need at least one Master Controller (Bridge) for this binding to work. It requires a network accessible instance of the [Master Controller].
The system will use ssh and java-expect-scripts that will invoke the cli.

The following table describes the Bridge configuration parameters:

Parameter Description Config Default
host Hostname or IP address of the Master Controller Required -
port Port of the for the cli Required 22
username The username to access the cli Required admin
password The password to access the cli Required -
refresh Refresh interval in seconds Optional 30

Thing Configuration

You must define a Unleashed Master Controller (Bridge) before defining Unleashed (Things) for this binding to work.

The following table describes the Thing configuration parameters:

Parameter Description Config Default
MAC Address The MAC address of the client Required -
considerHome The interval in seconds to consider the client as home Optional 180

Here are some additional notes regarding the thing configuration parameters:

considerHome

The considerHome parameter allows you to control how quickly the binding marks a client as away. For example, using the default of 180 (seconds), the binding will report a client away as soon as lastSeen + 180 (seconds) < now

Channels

The Wireless Client information that is retrieved is available as these channels:

Channel ID Item Type Description Permissions
Online Switch Online status of the client Read
Os String The Operating system of the client Read
Host String The hostname of the client Read
Mac address String MAC address of the client Read
IP Address String IP address of the client Read
ap String Access point (AP) the client is connected to Read
bssid String The Network BSSID Read
Connected since DateTime The Client has been connected since this time Read
Auth Method String The authorization method Read
Wlan String The wireless network the client is connected to Read
Vlan Number The vlan the client is connected to Read
Channel Number The wireless channel in use Read
Radio String Radio connection type (ie 802.11ac for instance) Read
Signal Number Signal strength Read
Status String If it is blocked/ authorized Read
Last Seen DateTime When it was last seen Read
Blocked Switch If the client is blocked from the network Read/Write

blocked

The blocked channel allows you to block / unblock a client via the controller.
The blocking will be done using an ACL. The default ACL name is “openhab”. You will have to
manually assign the ACL openhab to all wireless networks. This is a step by step instruction
to do so. Note if you don’t want to use block / unblock functionality this is not needed.

  • Login to unleashed web-gui
  • Click on Admin & Sevices
  • Click on Services
  • Click on Access Control
  • Click on L2/MAC Access Control
  • Click on Create New
  • Enter Name “openhab”
  • Click only deny stations listed below
  • Click “OK”
  • Go back to main page
  • Click WiFi-Networks
  • Edit the networks where you want to the client to be able to be blocked
  • Click Show Advanced Options
  • Click Access Control
  • For Layer2 MAC ACL select “openhab”
  • Repeat for all networks where client should be blocked

Full Example

Please add things using the OpenHAB GUI. I’ve kept the unleashed.things for reference.

things/unleashed.things

Bridge unleashed:controller:home "Unleashed Controller" [ host="unleashedhost", port=22, username="$username", password="$password", refresh=30 ] {
	Thing wirelessclient JPhone "J's Phone" [ mac="$mac", considerHome=180 ]
}

Replace $user, $password and $mac accordingly.

items/unleashed.items

Group    gUnleashed
Group    JPhone               "JPhone Super Android Phone"                       (gUnleashed)
Switch   JPhoneOnline         "JPhone Online [MAP(unleashed.map):%s]" (JPhone) { channel="unleashed:client:jphone:online" } 
String   JPhoneOs             "JPhone OS"                       (JPhone) { channel="unleashed:client:jphone:os" } 
String   JPhoneHost           "JPhone Host"                     (JPhone) { channel="unleashed:client:jphone:host" }
String   JPhoneMac            "JPhone Mac"                      (JPhone) { channel="unleashed:client:jphone:mac" }
String   JPhoneIp             "JPhone IP"                       (JPhone) { channel="unleashed:client:jphone:ip" }
String   JPhoneAp             "JPhone AP"                       (JPhone) { channel="unleashed:client:jphone:ap" }
String   JPhoneBssid          "JPhone Bssid"                    (JPhone) { channel="unleashed:client:jphone:bssid" }
DateTime JPhoneCS             "JPhone Connected Since [%1$tY.%1$tm.%1$td %1$tH:%1$tM]" (JPhone) { channel="unleashed:client:jphone:connected-since" }       
String   JPhoneAuthMethod     "JPhone Auth Method"              (JPhone) { channel="unleashed:client:jphone:auth-method" }
Number   JPhoneVlan             "JPhone Vlan"                   (JPhone) { channel="unleashed:client:jphone:vlan" }
String   JPhoneWlan             "JPhone Wlan"                   (JPhone) { channel="unleashed:client:jphone:wlan" }
String   JPhoneRadio             "JPhone Radio"                   (JPhone) { channel="unleashed:client:jphone:radio" }
Number   JPhoneChannel           "JPhone Wireless Channel"                   (JPhone) { channel="unleashed:client:jphone:channel" }
Number   JPhoneSignal             "JPhone Wireless Signal Strength"                   (JPhone) { channel="unleashed:client:jphone:signal" }
String   JPhoneStatus             "JPhone Status"                   (JPhone) { channel="unleashed:client:jphone:status" }
DateTime JPhoneLastSeen         "JPhone Last Seen [%1$tY.%1$tm.%1$td %1$tH:%1$tM]" (JPhone) { channel="unleashed:client:jphone:last-seen" }
Switch   JPhoneBlocked           "JPhone Blocked [%s]"       (JPhone) { channel="unleashed:client:jphone:blocked" }

transform/unleashed.map

ON=Home
OFF=Away
-=Unknown
NULL=Unknown

sitemaps/unleashed.sitemap

sitemap unleashed label="Unleashed Binding" {
	Frame {
		 Group item=gUnleashed
	}
}

Changelog

BETA10

  • Major refactoring, removed external dependencies to expect and ssh.

BETA9

  • Added auto discovery

BETA8

  • OpenHAB 3.1x compatability by removing apache-commons

Roadmap

  • Reboot Single AP or Controller
  • Get notification when new device is connected to guest network
  • APs information

Resources

https://github.com/seaside1/unleashed/raw/master/bin/org.openhab.binding.unleashed-openhab3-beta11.jar

2 Likes

Made some bugfixes to the binding, please download or build a new snapshot.

Created a new BETA3 version. Fixed some synchronization issues with block / unblock client.

1 Like

any updates for the OH 2.5.9?

I’ve built a version for 2.5.9. I have not tested it myself since I’m still on 2.5.7 in my production system, and development is on 2.5.10.

Also updated the docker image.

/S

I am getting these errors with the binding:

==> /logs/openhab.log <==

2020-09-25 13:52:26.751 [ERROR] [nternal.parser.UnleashedClientParser] - Error parsing clients: String index out of range: -1

==> /logs/events.log <==

2020-09-25 13:52:26.759 [hingStatusInfoChangedEvent] - ‘unleashed:controller:paragon’ changed from ONLINE to OFFLINE (COMMUNICATION_ERROR): Error communicating with the Unleashed controller

==> /logs/openhab.log <==

2020-09-25 13:52:26.768 [WARN ] [.core.thing.binding.BaseThingHandler] - Handler UnleashedControllerThingHandler tried updating the thing status although the handler was already disposed.

@epicurean I’ve updated my system to 2.5.9 as well. Both the old 2.5.7 binding and the new 2.5.9 seem to work fine under 2.5.9.

Maybe you are missing ssh or expect. Write ssh and expect at the prompt to see that those are present.
(inside the docker container if you are running it in docker).
If so the next step is to enable debug to see what is happening.

I’ve updated the original post with instructions on how to test docker and how to enable debug.

I’ve added a new beta-jar which contains a bit more debugging, when debug is set to on.

My openhab is a docker container. And I did install expect and openssh-client inside the docker.

these are the debug logs
2020-09-25 17:28:21.144 [DEBUG] [dler.UnleashedControllerThingHandler] - Refreshing the Unleased Controller unleashed:controller:paragon

2020-09-25 17:28:21.151 [DEBUG] [ternal.api.model.UnleashedController] - Updating clients cache

2020-09-25 17:28:21.160 [DEBUG] [ernal.context.UnleashedScriptContext] - Loading script as resource: scripts/unleashed-refresh.sh

2020-09-25 17:28:21.167 [DEBUG] [unleashed.internal.api.UnleashedUtil] - Script Resources: bundleresource://269.fwk1741786839/scripts/unleashed-refresh.sh

2020-09-25 17:28:21.183 [DEBUG] [ternal.api.model.UnleashedController] - Creating new UnleashedCliContext using: UnleashedCliInfoContext [username=admin, password= ******, host=192.168.1.16, port=22, acl=openhab]

2020-09-25 17:28:21.187 [DEBUG] [ernal.script.UnleashedScriptExecutor] - Executing: UnleashedCliInfoContext [username=admin, password= ******, host=192.168.1.16, port=22, acl=openhab]

2020-09-25 17:28:21.196 [DEBUG] [ernal.script.UnleashedScriptExecutor] - Executing command: [expect, /openhab/userdata/tmp/unleashed2158681901253518710.sh, admin, *********, 192.168.1.16, 22, openhab]

2020-09-25 17:28:58.860 [WARN ] [.core.thing.binding.BaseThingHandler] - Handler UnleashedControllerThingHandler tried updating the thing status although the handler was already disposed.

2020-09-25 17:29:22.524 [ERROR] [nternal.parser.UnleashedClientParser] - Error parsing clients: String index out of range: -1

If you use the beta5 jar you will get more debug as to what it fails parsing.
You can also execute on the command line:

expect /openhab/userdata/tmp/unleashed2158681901253518710.sh admin [yourpassword] 192.168.1.16 22 openhab

and see what it returns.

2020-09-26 10:47:17.939 [DEBUG] [ternal.api.model.UnleashedController] - Request Cli Info result size: 457

2020-09-26 10:47:17.940 [DEBUG] [nternal.parser.UnleashedClientParser] - Parsing clients from string size: 457

2020-09-26 10:47:17.940 [ERROR] [nternal.parser.UnleashedClientParser] - Error parsing clients: String index out of range: -1

2020-09-26 10:47:17.941 [DEBUG] [nternal.parser.UnleashedClientParser] - Failed to parse clients. Original clientString: spawn ssh admin@192.168.1.16

The authenticity of host ‘192.168.1.16 (192.168.1.16)’ can’t be established.

RSA key fingerprint is SHA256:EUowwz7zQrO8sT3PxWQbB4sH8/Dy8V83sQUm1Jmq/3U.

Are you sure you want to continue connecting (yes/no)? admin

Please type ‘yes’ or ‘no’: ******

Please type ‘yes’ or ‘no’: enable

Please type ‘yes’ or ‘no’: show l2acl name openhab

Please type ‘yes’ or ‘no’: show current-active-clients all

Please type ‘yes’ or 'n

Thanks, this should be fixable with a small modification to the script. I’ll post a update once I get some time.

/S

Hi! I’ve updated the scripts now in a beta6 version.
It’s connecting with StricKeyVerficiation set to no, this should resolve the issue.

1 Like

Latest beta6 did the trick!
However, I am only able to get the wireless things registered inside OH via the paperui or habamin. Could not do so with the manual example.
Can you consider also making the binding work with wired clients? like the unifi binding?

Hi!
How are the wired clients connected? Are they connected to the Ruckus Accesspoint in the secondary port (for instance on R710 / R510) or in some other manner?
Are you using 802.1x authentication for the clients?
As per official info from Ruckus, only wired clients using 802.1x authentication will be visible.

What do you want to do with the wired clients? Block them or view if they are online?

My wired clients are connected to a ICX6450 switch, and of which the Ruckus master controller takes up one of the ports.
Yes, I only wish to view the wired clients

Yeah the unleashed controller can’t see those clients, so it’s not possible.
The options for you is to use:

  • snmp (there is a binding)
  • or write a script that arp-pings those clients and reports status using mqtt
  • Possibly use the network binding

I have a couple of Juniper switches myself, and I’m writing a binding for handling those clients, it could be possible to just exchange the scripts in there to suit the Brocade CLI, but it is far from done, and I’m already working on a UniFi Protect binding and a Pfsense binding in parallell.

Regards S

1 Like

I’ve updated the binding for OpenHAB 3.0. It is still untested in OpenHAB3, but if you like you can give it a shot. I’ll work a bit on this binding adding auto discovery and trying to get rid of the external dependency. Once that is done I will submit a PR.

Regards, S

I’ve updated the docker-image for Openhab3.0 as well.

1 Like