search

uvjim / linksys_velop

Home Assistant integration for the Linksys Velop
43 stars 6 forks source link

readme

Linksys Velop

Home Assistant integration for the Linksys Velop Wi-Fi system.

Table of Contents

Description

This custom component has been designed to for Home Assistant and enables access to the functions that would be useful in the Home Assistant environment.

Installation

The integration can be installed using HACS. The integrations is not available in the default repositories, so will need to add a the URL of this repository as a custom repository to HACS (see here).

Definitions

Entities Provided

Where applicable the sub-items in the list detail the additional attributes available.

All device entities are only available if the UI Device is enabled.

Binary Sensors

Buttons

N.B. Buttons with an interval in brackets start a long running task. When they are pressed or the corresponding binary_sensor realises that the task is running a secondary timer is started, using the specified interval.

N.B. There is deliberately no button provided to restart the Primary node. Restarting the Primary node will cause all nodes in the Mesh to reboot and I consider this to be quite a destructive action. There is no confirmation in the HASS UI when a button is pressed so there is no time to warn anyone. If you'd like to reboot the Primary you node you must use the service with the is_primary flag provided, or the Mesh: Reboot the Whole Mesh button.

Device Trackers

These are selectable and are presented as part of the configuration at both install time and from reconfiguring the integration.

Select

Sensors

Switches

Update (only if HASS > 2022.4.0)

Events Fired

The integration fires an event with type linksys_velop_event. Withing the data object there is a subtype value which denotes the reason for the event. This section shows the available subtypes.

logging_stopped

This event is fired when logging was turned on in the configurable options (see here) and has stopped.

The event looks as follows: -

event_type: linksys_velop_event
data:
  name: 192.168.1.254
  subtype: logging_stopped
origin: LOCAL
time_fired: "2022-10-05T14:06:34.120984+00:00"
context:
  id: 01GEM7GDM8VE5Q4S27P3WPNTX4
  parent_id: null
  user_id: null

new_device

This event is fired when a brand-new device appears on the Mesh. A device is considered new if it presents a device ID (determined by the Velop) that was not seen at the last poll period. This means that it will not fire for devices that change from online to offline and vice-versa.

The event is fired for each new device that is discovered. The data is as the Velop mesh sees it, i.e. there is no magic by the integration to establish the manufacturer, model, operating system or serial.

N.B. The name will default to Network Device if there is no name established by the Velop or assigned by the user.

The event looks as follows: -

event_type: linksys_velop_event
data:
  connected_adapters: []
  description: null
  manufacturer: null
  model: null
  name: Network Device
  operating_system: null
  parent_name: null
  serial: null
  status: false
  unique_id: e053a99e-f8b6-4061-b9d3-7a19a38ec079
  mesh_device_id: f31f325891bc59506bdf98a54e23fcdd
  subtype: new_device
origin: LOCAL
time_fired: "2022-10-05T13:47:38.933813+00:00"
context:
  id: 01GEM6DS1NND3PG936RFBGTGFJ
  parent_id: null
  user_id: null

new_node

This event is fired when a new node is found on the Mesh. A node is considered new if it is not currently configured in HASS. It may not be configured for a couple of reasons: the device was deleted from the UI, or you've added a new node to your Mesh.

The event is fired for each new node that is discovered.

The event looks as follows: -

event_type: linksys_velop_event
data:
  backhaul: {}
  connected_adapters: []
  model: MX42
  name: Utility
  parent_name: null
  serial: 123456789
  status: false
  unique_id: 80236f06-e622-faec-9410-e89f80603b3d
  mesh_device_id: f31f325891bc59506bdf98a54e23fcdd
  subtype: new_node
origin: LOCAL
time_fired: "2022-10-05T13:43:17.135224+00:00"
context:
  id: 01GEM65SCF8BVK3BEVFHXWS5F2
  parent_id: null
  user_id: null

new_primary_node

This event is fired when a new primary node is detected. The check for this is based on the serial number and is currently only found as part of SSDP discovery. If the serial numbers do not match, this event is fired and the unique_id of the integration instance is update.

This should stop the mesh being discovered again by SSDP when the primary node is changed.

event_type: linksys_velop_event
data:
  host: 192.168.1.254
  model: "velop ax4200 wifi 6 system"
  serial: 1234567890
  subtype: new_primary_node
origin: LOCAL
time_fired: "2022-10-05T13:43:17.135224+00:00"
context:
  id: 01GEM65SCF8BVK3BEVFHXWS5F2
  parent_id: null
  user_id: null

Device Triggers

All events are available in automations as device triggers on the Mesh device, as per the following screenshot.

Device Triggers

Services

The following services are available. Each service is described in metadata so paramters are described in the Home Assistant Services page.

All services require that you select the Mesh device that the request should be directed to. Other requirements by the services should be self-explanatory.

* these are considered long-running tasks. When the binary sensors spot these tasks are running an additional timer is set up that polls at intervals to get updates and updates the relevant attributes for that sensor.

^ these are deprecated services. A warning will be displayed in the HASS log when they are used. They are subject to removal at any time.

Setup

When setting up the integration you will be asked for the following information.

Initial Setup Screen

On successful set up the following screen will be seen detailing the Mesh device and the individual nodes found in the mesh.

Final Setup Screen

Configurable Options

It is possible to configure the following options for the integration.

Timers

Configure Timers

Device Trackers

Configure Device Trackers

UI Devices

A UI device is one which is available on the mesh and you would like to have further information available in Home Assistant. IT could be that you want to create automations based on a device signal strength, parent node or state (without using a device tracker).

Configure UI Devices

Advanced Options

This section is only available if "Advanced Mode" is enabled for the current user. See here.

Configure Advanced Options

Logging

Configure Logging

Troubleshooting

Debug Logging

This way of logging is most useful if there is an intermitent problem as it will continue logging until it is disabled again. If your intention is only to log a single request because the issue is repeatable then see here.

Debug logging can be enabled in Home Assistant using the logger integration see here.

logger:
  default: warning
  logs:
    custom_components.linksys_velop: debug
    pyvelop: debug

Diagnostics Integration

Starting with Home Assistant 2022.2 a new diagnostics integration can be used to provide troubleshooting for integrations. This integration supports that as of version 2021.1.3.

The highlighted area in the image below shows where the link for downloading diagnostics can be found.

Diagnostics link

Example output: -

Example Automations

Below are some example automations.

I'm aware some of these could be more generic or even done in a better way but these are for example purposes only.

Notify when a node goes offline or comes online ```yaml alias: 'Notify: Velop node online/offline' description: '' trigger: - platform: state entity_id: binary_sensor.velop_utility_status id: Node Online from: 'off' to: 'on' - platform: state entity_id: binary_sensor.velop_utility_status id: Node Offline from: 'on' to: 'off' condition: [] action: - choose: - conditions: - condition: trigger id: Node Online sequence: - service: persistent_notification.create data: message: Node is online - conditions: - condition: trigger id: Node Offline sequence: - service: persistent_notification.create data: message: Node is offline default: [] mode: single ```
Notify on events ```yaml alias: "Notify: Velop Information" description: "" trigger: - platform: event event_type: linksys_velop_event event_data: subtype: new_device id: Device Found - platform: event event_type: linksys_velop_event event_data: subtype: new_node id: Node Found - platform: event event_type: linksys_velop_event event_data: subtype: new_primary_node id: Primary Node Changed - platform: event event_type: linksys_velop_event event_data: subtype: logging_stopped id: Logging Stopped condition: [] action: - variables: title_prefix: "Linksys Velop - " - if: - condition: template value_template: "{{ trigger.id in [\"Logging Stopped\"] }}" then: - variables: notification_id: logging_stopped message: Logging has stopped for {{ trigger.event.data.get('name') }} - service: persistent_notification.create data: notification_id: "{{ notification_id }}" title: "{{ title_prefix }}{{ trigger.id }}" message: "{{ message }}" else: - variables: notification_id: >- {{ trigger.event.event_type }}_{{ trigger.event.data.get('unique_id') or trigger.event.data.get('serial') }} message: >- {% if trigger.event.data.get('name') is not none %} ## {{ trigger.event.data.name }} {% endif %} | | | | |---|---|---| {% if trigger.event.data.get('mesh_device_id') is not none %} |Mesh:| |{{ device_attr(trigger.event.data.mesh_device_id, 'name_by_user') or device_attr(trigger.event.data.mesh_device_id, 'name') }}| {% endif %} {% if trigger.event.data.get('parent_name') is not none %} |Parent:| |{{ trigger.event.data.parent_name }}| {% endif %} {% if trigger.event.data.get('host') is not none %} |Host:| |{{ trigger.event.data.host }}| {% endif %} {% if trigger.event.data.get('connected_adapters') is not none and trigger.event.data.get('connected_adapters') | count > 0 %} |Guest:| |{{ 'Yes' if trigger.event.data.connected_adapters[0].get('guest_network', False) is eq true else 'No' }}| |IP:| |{{ trigger.event.data.connected_adapters[0].get('ip', 'N/A') }}| |MAC:| |{{ trigger.event.data.connected_adapters[0].get('mac', 'N/A') }}| {% endif %} {% if trigger.event.data.get('description') is not none %} |Description:| |{{ trigger.event.data.description }}| {% endif %} {% if trigger.event.data.get('manufacturer') is not none %} |Manufacturer:| |{{ trigger.event.data.manufacturer }}| {% endif %} {% if trigger.event.data.get('model') is not none %} |Model:| |{{ trigger.event.data.model }}| {% endif %} {% if trigger.event.data.get('serial') is not none %} |Serial:| |{{ trigger.event.data.serial }}| {% endif %} {% if trigger.event.data.get('operating_system') is not none %} |Operating System:| |{{ trigger.event.data.operating_system }}| {% endif %} - service: persistent_notification.create data: notification_id: "{{ notification_id }}" title: "{{ title_prefix }}{{ trigger.id }}" message: "{{ message }}" mode: parallel ```