ocolin/uisp-extended

SSH-based device management for Ubiquiti radios, extending the UISP API with features not available through the standard interface.

v0.1.0 2026-04-26 02:31 UTC

Requires

• php: ^8.2
• phpseclib/phpseclib: ^3.0

Requires (Dev)

• ocolin/easyenv: ^3.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^13.1

MIT

• Colin Miller

• network
• ssh
• wave
• radio
• ubiquiti
• uisp
• airmax
• airos

README

Ubiquiti's UISP platform provides a comprehensive API for managing network devices, but certain administrative tasks are not exposed through the API and must be performed directly on the device via SSH. ocolin/uisp-extended fills that gap by providing a clean PHP interface for SSH-based device management, designed to complement the ocolin/uisp package.

Experimental

This is currently experimental and has not been fully tested on every known device.

Requirements

• PHP ^8.2
• phpseclib/phpseclib ^ 3.0

Installation

composer require ocolin/uisp-extended

Configuration

Arguments

When creating a Ubiquiti device class, there are a few parameters that you can use:

Name	Type	Default	Description
ip	string	REQUIRED	IP address of device
password	string	REQUIRED	Password for login
username	string	admin	Username for login
port	integer	22	SSH port

Logging in

Upon instantiation, you will log into the device automatically. An error is thrown if the connection fails or authentication does not pass.

Example

// Minimal
$device = new Ocolin\UispExtended\Device( 
    ip: '192.168.1.100', password: 'rosebud' 
);

// Customized
$device = new Ocolin\UispExtended\Device( 
    ip: '192.168.1.100', password: 'rosebud', username: 'admin', port: 2222
)

Exceptions

• AuthenticationException — thrown if login credentials are incorrect
• ConnectionException — thrown if the device is unreachable

Functions

Get Device Information

You can get information about the device such as the type name, model, family, and firmware.

Output Object

Name	Type	Description
name	string	Name of the device model
model	string	Model of device
family	string	Family of device model
firmware	string	Device firmware version

Example

$info = $device->getDeviceInfo();
print_r( $info );
/*
Ocolin\UispExtended\DTO\DeviceInfo Object
(
    [name] => PowerBeam 5AC
    [model] => PBE-5AC-Gen2
    [family] => WA
    [firmware] => 8.7.11
)
 */

Get MAC table

This provides a MAC/bridge table on the device. It outputs an array of MAC entry objects.

Object parameters

Name	Type	Description
mac	string	MAC address
interface	string	Interface address is on
isLocal	boolean	Is MAC address a local one?
agingTimer	float	Age of MAC address

Example:

$macs = $device->getMacTable();
print_r( $macs );
/*
Array
(
    [0] => Ocolin\UispExtended\DTO\MacEntry Object
        (
            [mac] => 00:0b:78:66:db:d0
            [interface] => eth0
            [isLocal] => 
            [agingTimer] => 2.11
        )

    [1] => Ocolin\UispExtended\DTO\MacEntry Object
        (
            [mac] => 04:f1:7d:05:07:c7
            [interface] => eth0
            [isLocal] => 
            [agingTimer] => 289.92
        )
)
 */

Update password

This function allows you to update the password on a device. This function returns void, but will throw an error upon failure which will state where in the process it failed.

This will auto-detect the model of radio and execute the corresponding password update procedure automatically.

Example:

$device->changePassword( newPassword: 'myUpdatedPassword' );

Exceptions

• ConnectionException - Error connecting to device.
• PasswordChangeException - Error updating the password with message.
• ScriptNotFoundException - Internal error reading CLI shell script.

Update Wave Password

This function was created in the event of a user wants to specifically change password on a Wve device instead of relying on changePassword() which automatically detects the type of device.

The same errors will be thrown as changePassword().

Example

$device->changePasswordWave( newPassword: 'myUpdatedPassword' );

Update AirOS Password

This function was created in the event a user wants to specifically change the password on a non-Wave type of device.

The same errors will be thrown as changePassword().

Example

$device->changePasswordAirOS( newPassword: 'myUpdatedPassword' );

Reboot

While UISP has a reboot function, one was added here in case it needed to be used as standalone.

Example

$device->reboot();