Skip to content

UniFiSharp Brings Ubiquiti UniFi SDN Automation to C#

License

Notifications You must be signed in to change notification settings

PeterHagen/UniFiSharp

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

7e20839 · Aug 15, 2021

History

51 Commits
Apr 2, 2021
Aug 15, 2021
Mar 18, 2018
Mar 18, 2018
Jun 11, 2021
Mar 18, 2018

Repository files navigation

UniFiSharp

Original project: https://github.com/anthturner/UniFiSharp

Bringing Ubiquiti UniFi Orchestration Automation to C#

UniFiSharp provides a basic C# API for Ubiquiti UniFi controllers, as well as an orchestration overlay to more easily visualize network topology and execute device commands. UniFiSharp also implements both v1 and v2 of the Ubiquiti discovery protocol for automated controller discovery.

As of UniFiSharp v1.1.0, the API surface has changed slightly to improve usability and maintainability; please read the usage documentation below.

This project is written for any .NET application that can consume a .NET Standard 2.0 library. All future contributions are planned to continue to enable cross-platform use.

Basic API Usage

The UniFiApi class provides all base-level API features:

// Instantiate the API object
using (var api = new UniFiSharp.UniFiApi(new Uri("https://controller:8443"), "username", "password", "siteName"))
{
    // Manually calling .Authenticate() forces the API to proactively authenticate.
    // Otherwise, the request will be automatically authenticated upon receiving an unauthorized error.
	await api.Authenticate();

	// ... for example, enumerate all UniFi devices known by the controller:
    IEnumerable<UniFiSharp.Json.JsonNetworkDevice> uniFiDevices = await api.NetworkDeviceList();

	// ... or to upgrade the firmware on a device:
	await api.NetworkDeviceUpgrade("01:23:45:67:89:AB");
}

UBNT Cloud

The UniFiApi class can also be used with UBNT Cloud-hosted services by changing the base URI to match the UBNT Cloud format:

var api = new UniFiSharp.UniFiApi(new Uri("https://demo.ubnt.com/"), "username", "password")

Note: At the time of this writing, Ubiquiti's cloud will accept the above demo credentials and allow the user to work in a sandboxed, artificial environment. This demo setup includes approximately 130 UniFi devices and 1200 clients.

Orchestration Usage

In order to make this system more developer-friendly, it also ships with an orchestration overlay that wraps the UniFiApi object and associates common information to their devices, as well as attempting to converge a basic topology based on the device objects:

// Instantiate the API object
using (var api = new UniFiSharp.UniFiApi(new Uri("https://controller:8443"), "username", "password", "siteName"))
using (var orchestrator = new UniFiSharp.Orchestration.UniFiOrchestrator(api))
{    
    // Calls api.Refresh() under the hood
    await orchestrator.Refresh();
    
    // ... for example, retrieve the first AP and turn on its locator for 5 seconds:
    await orchestrator.InfrastructureDevices.First(d => d is UniFiSharp.Orchestration.Devices.AccessPointInfrastructureNetworkedDevice).Locate(5000);
    
    // ... or to browse the network topology from the edge inwards, start from:
    INetworkedDevice networkRoot = orchestrator.TopologicalRoot;
    
    // ... or to create a new port forward (to 192.168.1.100:TCP/80):
    await orchestrator.PortForwards.Add(
              UniFiSharp.Orchestration.Models.PortForward.Create(
                  name: "abc",
                  proto: "tcp",
                  source: "any",
                  sourcePort: 80,
                  dest: "192.168.1.100",
                  destPort: 80
              ));
}

Disclaimer

This software is not affiliated with nor supported by Ubiquiti Networks and is offered under the license as described in LICENSE. This software should never be used in a production environment without exhaustive, independent testing.

About

UniFiSharp Brings Ubiquiti UniFi SDN Automation to C#

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • C# 100.0%