Custom component: EdgeOS

EdgeOS

Description

Provides an integration between EdgeOS (Ubiquiti) routers to Home Assistant.

GitHub | Changelog

How to

Requirements

  • EdgeRouter with at least firmware version 2.0
  • EdgeRouter User with ‘Operator’ level access or higher
  • Traffic Analysis set to ‘Enabled’ (both dpi and export enabled under system/traffic-analysis)
  • To enable / disable interfaces an admin role is a required

Installations via HACS

  • In HACS, look for “Ubiquiti EdgeOS Routers” and install and restart
  • In Settings → Devices & Services - (Lower Right) “Add Integration”

Setup

To add integration use Configuration → Integrations → Add EdgeOS
Integration supports multiple EdgeOS devices

Fields name Type Required Default Description
Host Textbox + - Hostname or IP address to access EdgeOS device, can hold also port (HOST:PORT), default port is 443
Username Textbox + - Username of user with Operator level access or higher, better to create a dedicated user for that integration for faster issues identification
Password Textbox + -
EdgeOS Device validation errors
Errors
Cannot reach device (404)
Invalid credentials (403)
General authentication error (when failed to get valid response from device)
Could not retrieve device data from EdgeOS Router
Export (traffic-analysis) configuration is disabled, please enable
Deep Packet Inspection (traffic-analysis) configuration is disabled, please enable
Unsupported firmware version
Encryption key got corrupted

If a persistent notification popped up with the following message:

Encryption key got corrupted, please remove the integration and re-add it

It means that encryption key was modified from outside the code,
Please remove the integration and re-add it to make it work again.

Options

Configuration → Integrations → {Integration} → Options

Fields name Type Required Default Description
Host Textbox + - Hostname or IP address to access EdgeOS device, can hold also port (HOST:PORT), default port is 443
Username Textbox + - Username of user with Operator level access or higher, better to create a dedicated user for that integration for faster issues identification
Password Textbox + -
Clear credentials Check-box + Unchecked Will reset username and password (Not being stored under options)

Debugging

To set the log level of the component to DEBUG, please set it from the options of the component if installed, otherwise, set it within configuration YAML of HA:

logger:
  default: warning
  logs:
    custom_components.edgeos: debug

Components

System

Entity Name Type Description Additional information
{Router Name} Unit Select Sets whether to monitor device and create all the components below or not
{Router Name} CPU Sensor Represents CPU usage
{Router Name} RAM Sensor Represents RAM usage
{Router Name} Uptime Sensor Represents last time the EdgeOS was restarted
{Router Name} Unknown devices Sensor Represents number of devices leased by the DHCP server Attributes holds the leased hostname and IPs
{Router Name} Firmware Updates Binary Sensor New firmware available indication Attributes holds the url and new release name
{Router Name} Log incoming messages Switch Sets whether to log WebSocket incoming messages for debugging

Changing the unit will reload the integration

Per device

Entity Name Type Description Additional information
{Router Name} {Device Name} Monitored Sensor Sets whether to monitor device and create all the components below or not
{Router Name} {Device Name} Received Rate Sensor Received Rate per second Statistics: Measurement
{Router Name} {Device Name} Received Traffic Sensor Received total traffic Statistics: Total Increment
{Router Name} {Device Name} Sent Rate Sensor Sent Rate per second Statistics: Measurement
{Router Name} {Device Name} Sent Traffic Sensor Sent total traffic Statistics: Total Increment
{Router Name} {Device Name} Device Tracker Indication whether the device is or was connected over the configured timeframe

Per interface

Entity Name Type Description Additional information
{Router Name} {Interface Name} Status Switch Sets whether to interface is active or not Available only if user level is admin
{Router Name} {Interface Name} Status Binary Sensor Indicates whether interface is active or not Available only if user level is not admin
{Router Name} {Interface Name} Connected Binary Sensor Indicates whether interface’s port is connected or not
{Router Name} {Interface Name} Monitored Switch Sets whether to monitor interface and create all the components below or not
{Router Name} {Interface Name} Received Rate Sensor Received Rate per second Statistics: Measurement
{Router Name} {Interface Name} Received Traffic Sensor Received total traffic Statistics: Total Increment
{Router Name} {Interface Name} Received Dropped Packets Sensor Received packets lost Statistics: Total Increment
{Router Name} {Interface Name} Received Errors Sensor Received errors Statistics: Total Increment
{Router Name} {Interface Name} Received Packets Sensor Received packets Statistics: Total Increment
{Router Name} {Interface Name} Sent Rate Sensor Sent Rate per second Statistics: Measurement
{Router Name} {Interface Name} Sent Traffic Sensor Sent total traffic Statistics: Total Increment
{Router Name} {Interface Name} Sent Dropped Packets Sensor Sent packets lost Statistics: Total Increment
{Router Name} {Interface Name} Sent Errors Sensor Sent errors Statistics: Total Increment
{Router Name} {Interface Name} Sent Packets Sensor Sent packets Statistics: Total Increment

Unit of measurement for Traffic and Rate are according to the unit settings of the integration

Services

Update configuration

Allows to set:

  • Consider away interval - Time to consider a device without activity as AWAY (any value between 10 and 1800 in seconds)
  • Log incoming messages - Enable / Disable logging of incoming WebSocket messages for debug
  • Store debug data - Enable / Disable store debug data to ‘./storage’ directory of HA for API (edgeos.debug.api.json) and WS (edgeos.debug.ws.json) data for faster debugging or just to get more ideas for additional features
  • Unit of measurement
  • Update API interval - Interval in seconds to update API data
  • Update Entities interval - Interval in seconds to update entities

More details available in Developer toolsServicesedgeos.update_configuration

service: edgeos.update_configuration
data:
  device_id: {Main device ID}
  unit: Bytes
  log_incoming_messages: true
  consider_away_interval: 180
  update_api_interval: 30
  update_entities_interval: 1

Changing the unit will reload the integration

Endpoints

Endpoint Name Method Description
/api/edgeos/list GET List all the endpoints available (supporting multiple integrations), available once for integration
/api/edgeos/{ENTRY_ID}/ha GET JSON of all HA processed data before sent to entities, per integration
/api/edgeos/{ENTRY_ID}/api GET JSON of all raw data from the EdgeOS API, per integration
/api/edgeos/{ENTRY_ID}/ws GET JSON of all raw data from the EdgeOS WebSocket, per integration

Authentication: Requires long-living token from HA

Examples

List

Request

curl https://ha_url:8123/api/edgeos/list
   -H "Accept: application/json"
   -H "Authorization: Bearer {token}"

Home Assistant Data

Request

curl https://ha_url:8123/api/edgeos/{ENTRY_ID}/ha
   -H "Accept: application/json"
   -H "Authorization: Bearer {token}"

WebSockets Data

Request

curl https://ha_url:8123/api/edgeos/{ENTRY_ID}/ws
   -H "Accept: application/json"
   -H "Authorization: Bearer {token}"

API Data

curl https://ha_url:8123/api/edgeos/{ENTRY_ID}/api
   -H "Accept: application/json"
   -H "Authorization: Bearer {token}"
20 Likes

Just tried to add this to my custom_components folder. Added the example lines to my configuration.yaml, changing the values to match my system but when restarting I get the following in my log

Setup failed for edgeos: Component not found

Along with another couple of similar lines about not being able to find the edgeos Component.

Inside my custom_components folder I created an edgeos folder and inside is the contents of the custom_components folder on the GitHub repo. Have I missed something, everything looks similar to the other custom_components I have working in HASS.

Any help appreciated, this Component sounds great.

Realised that I needed to copy everything from the custom_components folder of the Github Repo straight to my custom_components folder. So it should contain the edgeos.py file and the device_tracker folder.

Looking at it now that was obvious, it’s late and confused me because the other custom components I have are under sensor or media_center folders.

The next issue I have is around the cert config line, I left it blank and threw an error, removed the whole line from my configuration.yaml and now I get:

Invalid config for [edgeos]: string value is None for dictionary value @ data['edgeos']['cert_file']. Got None. (See /config/configuration.yaml, line 404). Please check the docs at https://home-assistant.io/components/edgeos/

Do I have to use a certificate on my ERL-3, I said False to SSL in the config of this component. I think I may need to wait until some documentation is written, I’m obviously missing something.

I tried this path for the cert file “/etc/lighttpd/server.pem” but keeps coming back with verify failed:

2019-02-08 10:31:23 ERROR (SyncWorker_15) [custom_components.edgeos] Failed to perform heartbeat, Error: HTTPSConnectionPool(host=‘192.168.1.1’, port=443): Max retries exceeded with url: /api/edge/heartbeat.json?t=1549593083 (Caused by SSLError(SSLError(1, ‘[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:847)’),))
2019-02-08 10:31:23 ERROR (SyncWorker_15) [custom_components.edgeos] Failed to load static-devices, Error: HTTPSConnectionPool(host=‘192.168.1.1’, port=443): Max retries exceeded with url: /api/edge/get.json (Caused by SSLError(SSLError(1, ‘[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:847)’),))

I added configuration file with details about each settings, your configuration is missing path to the full chain certificate,
Later today i’ll change it to avoid checking the certificate, hopefully it will solve that issue,
Alternatively, you can create full chain certificate (combine cert with key to one file)

Hi @grantc, the path you entered probably is just the certificate, as written in previous post - it requires the full chain

Hi bar, thanks for the reply - any idea how to get that information? Thanks

openssl s_client -showcerts -connect 192.168.1.1:443

not sure what part of the output is the full chain :slight_smile:

I’ll find later the article I used to create it, basically you create pem file consisted with the content of:

  1. Key
  2. Intermediate certificate
  3. Certificate

Creating a .pem with the Private Key and Entire Trust Chain:
https://www.digicert.com/ssl-support/pem-ssl-creation.htm

-----BEGIN RSA PRIVATE KEY-----
(Your Private Key: your_domain_name.key)
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
(Your Primary SSL certificate: your_domain_name.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Intermediate certificate: DigiCertCA.crt)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your Root certificate: TrustedRoot.crt)
-----END CERTIFICATE-----

Updated the component, no SSL verification for HTTPS requests,
please try and let me know if now it works for you

Confused now, so no .pem file path is required

Sorry for that :slight_smile:

I updated it once again (removed the SSL verification from login request as well),
Now you don’t need to fill in the cert_file

No longer getting complaint regarding the certificate, instead now get these 2 which are less friendly error messages.

error from callback <bound method EdgeOSWebSocket.on_error of <custom_components.edgeos.EdgeOSWebSocket object at 0x7fc82b824c18>>: on_error() takes 2 positional arguments but 3 were given
error from callback <bound method EdgeOSWebSocket.on_close of <custom_components.edgeos.EdgeOSWebSocket object at 0x7fc82b824c18>>: on_close() takes 1 positional argument but 2 were given

Thanks

found out that it can be caused due to incompetible version of websocket-client,
just to be sure, can you run the following command and let me know which version installed in your system (if you are running python virtual environment, please run it from within it):
pip freeze | grep lxml

Mine is 0.54.0, according to forums, it can be caused when it lower than 0.53.0

thanks

sorry, wrong past, should be:
pip freeze | grep websocket-client

Anyway, I pushed another fix, added the requirements of websocket-client,
If it’s not working, please post the version of your websocket-client

thanks

Unfortunately still not working and I run hass.io, which is a docker container. pip isn’t installed, so can’t use that command to get the version.

I imagine lots of other people will have similar issues with more and more people using using hass.io now.

Any other idea who to check the version without pip?

in both docker and hass.io pip installed, that’s the way it installs python packages,
you can create a command line sensor that you will get the value into its state:
sensor:

  • platform: command_line
    command: ‘pip freeze | grep websocket-client’

@stevenhorner, any progress with the version / issue?

thanks

Sorry away for the weekend, will try on Monday.
Thanks for the help.

Hi bar,

Couple of errors in the log trying to get this up and running;

  1. 2019-02-11 08:44:13 ERROR (MainThread) [homeassistant.config] Invalid config for [edgeos]: string value is None for dictionary value @ data[‘edgeos’][‘cert_file’]. Got None. (See /home/homeassistant/.homeassistant/configuration.yaml, line 134). Please check the docs at https://home-assistant.io/components/edgeos/
    2019-02-11 08:44:13 ERROR (MainThread) [homeassistant.setup] Setup failed for edgeos: Invalid config.

I added the cert_file line back in (with no value) and then comment the line out still get the same error. I thought you removed this pre-req?

  1. 2019-02-11 08:44:15 ERROR (SyncWorker_13) [custom_components.device_tracker.edgeos] Failed to initialize EdgeOS Scanner, Error: ‘edgeos_ham’, Line: 37
    2019-02-11 08:44:15 ERROR (MainThread) [homeassistant.components.device_tracker] Error setting up platform edgeos

Thanks