Home Assistant integration for the Linksys Velop Wi-Fi system.
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.
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).
- Mesh: the mesh is the network itself and refers to anything that is not attributed to a single node or device in the network.
- Node: a node is a device that helps to form the mesh.
- Device: a device is an endpoint that connects to the mesh network. Think of these as the endpoint devices, such as a laptop, phone or tablet.
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.
- Device: Blocked Times
- Times of the week that are blocked
- Device: Guest Network
- Device: Reserved IP
- Device: Connected
- Mesh: Channel Scanning
- Mesh: Client Steering (disabled by default)
- Mesh: DHCP Server (disabled by default)
- Mesh: Express Forwarding (disabled by default)
- Mesh: HomeKit Integration Paired (disabled by default)
- Mesh: MAC Filtering (disabled by default)
- mode, address list
- Mesh: Node Steering (disabled by default)
- Mesh: SIP (disabled by default)
- Mesh: Speedtest state
- Mesh: UPnP (disabled by default)
- Mesh: UPnP Allow Users to Configure (disabled by default)
- Mesh: UPnP Allow Users to Disable Internet (disabled by default)
- Mesh: WAN Status
- IP, DNS, MAC
- Node: Status
- IP, MAC, guest network
- Node: Update Available (only if HASS < 2022.4.0)
- Device: Delete
- Mesh: Check for Updates
- Mesh: Reboot the Whole Mesh (see Configurable Options -> Advanced Options)
- Mesh: Start Channel Scanning (interval: 40s)
- Mesh: Start Speedtest (interval: 1s)
- Node: Reboot
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 theMesh: Reboot the Whole Mesh
button.
These are selectable and are presented as part of the configuration at both install time and from reconfiguring the integration.
- Mesh: Devices (disabled by default)
- Once a device is selected (assuming a temporary device is not being used for display) the attributes will be updated to reflect the following: connected adapters, description, manufacturer, model, name, operating_system, parent name, serial, status and unique_id
- Device: Blocked Sites
- list of sites blocked
- Device: Description
- Device: Friendly Signal Strength
- Device: ID
- Device: IP
- Device: IPv6
- Device: MAC
- Device: Manufacturer
- Device: Model
- Device: Name
- Device: Operating System
- Device: Parent
- Device: Serial
- Device: Signal Strength (i.e., RSSI)
- Device: UI Type (The
entity_picture
attribute will be set ifnode_images
are configured, see here) - Mesh: DHCP Reservations (disabled by default)
- list of DHCP reservations on the mesh
- Mesh: Number of Offline Devices
- list of device objects containing names and unique ID of devices that are offline
- Mesh: Number of Online Devices
- list of device objects containing names, unique IDs, IP addresses, adapter types and guest network state for the online devices
- Mesh: Number of Guest Devices (disabled by default)
- list of device names, IP addresses, adapter types etc
- Mesh: Speedtest Download Bandwidth (disabled by default)
- Mesh: Speedtest Last Run (disabled by default)
- Mesh: Speedtest Latency (disabled by default)
- Mesh: Speedtest Progress (disabled by default), e.g. Detecting server, Checking latency
- Mesh: Speedtest Result (disabled by default)
- Mesh: Speedtest Upload Bandwidth (disabled by default)
- Mesh: Number of Available Storage Partitions (disabled by default)
- list of the available partitions including the following information: IP, label, available Kb, used Kb, used %age and last checked time
- Mesh: WAN IP
- Node: Number of Connected Devices
- list of names, IP addresses, type of connection and guest network state for the connected devices
- Node: Backhaul Friendly Signal Strength (only if not the primary node and using a wireless backhaul)
- Node: Backhaul Last Checked (only if not the primary node) (disabled by default)
- Node: Backhaul Signal Strength (only if not the primary node and using a wireless backhaul)
- Node: Backhaul Speed (only if not the primary node)
- Node: Backhaul Type (only if not the primary node)
- Node: Current Firmware Version (only if HASS < 2022.4.0)
- Node: Image (disabled by default. Only available if
node_images
are configured, see here) - Node: Last Update Check (disabled by default)
- Node: Model Number (The
entity_picture
attribute will be set ifnode_images
are configured, see here) - Node: Newest Firmware Version (only if HASS < 2022.4.0)
- Node: Parent Name (only if the node is not the primary)
- IP address of the parent
- Node: Serial Number
- Node: Type of Node, e.g. Primary Secondary
- Device: Internet Access
- Mesh: Guest Wi-Fi state
- list of guest networks available
- Mesh: HomeKit Integration
- Mesh: Parental Control state
- list of the rules being applied
- Mesh: WPS
- Node: Firmware update available.
- includes current and latest firmware versions
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.
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
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
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
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
All events are available in automations as device triggers on the Mesh device, as per the following screenshot.
The following services are available. Each service is described in metadata so paramters are described in the Home Assistant Services page.
- Check for Updates ^ - check if there are firmware updates for the nodes.
- Control Internet Access for a Device - allow/block access to the Internet for a device.
- Delete Device - delete a device from the Mesh device list.
- Execute Speedtest *^ - carry out a Speedtest from the Primary node.
- Reboot Node - reboot the given node.
- Rename Device - rename the given device in the Mesh device list.
- Set Device Parental Controls - set the times a device is blocked from using the Internet.
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.
When setting up the integration you will be asked for the following information.
Primary node address
: must be the node classed as the primary nodePassword
: the password you would use to log in to the router. This may not be the same as the password for the application or web UI if you use the Linksys cloud service.
On successful set up the following screen will be seen detailing the Mesh device and the individual nodes found in the mesh.
It is possible to configure the following options for the integration.
Scan Interval
: the frequency of updates for the sensors, default30s
Device Tracker Interval
: the frequency of updates for the device trackers, default10s
Consider Home Period
: the time to wait before considering a device away after it notifies of becoming disconnected, default180s
Response Timeout
: the number of seconds to wait for a response from an individual request to the API
Available devices
: a multi-select list of the devices found on the mesh. This list excludes any device which doesn't have a name - typically displayed in the official interfaces asNetwork Device
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
).
Available devices
: a multi-select list of the devices found on the mesh. This list excludes any device which doesn't have a name - typically displayed in the official interfaces asNetwork Device
This section is only available if "Advanced Mode" is enabled for the current user. See here.
Velop image path
: the path to the folder location containing the images to use for integration purposes. This is currently used for to set the entity picture for various entities. It relies on thehttp
integration from HASS, details of which can be found here, and more specifically here for the path to place the files in.Use a temporary device for select entity details
: creates a placeholder device that will be populated with the details of the device selected in the select entity. Theselect
entity will no longer have the details populated to its attributes.Allow rebooting the Mesh
: creates a button on the Mesh entity that allows rebooting the whole mesh.
Logging options
- includes the following: --
Include the serial number in debug logs
: setting this will make the serial number of the primary node appear in the debug logs. This will be useful if there a multiple instances of the integration configured. -
Include query responses in logs
: setting this will cause the debug logs to include the responses to the queries. This could drastically increase the size of your logs depending on the number of devices you have connected to the mesh.N.B. there is no redaction on the responses as much of the response will be required for troubleshooting. Using diagnostics a pre-processed and redacted version can be downloaded for the mesh or a node.
-
Logging mode
- this setting has no effect if logging for the integration is configured inconfiguration.yaml
and is only available if thelogger
integration is enabled inconfiguration.yaml
.off
: disable debug loggingSingle poll
: only enable debug logging for a single poll requesting information from the Mesh.
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
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.
Example output: -
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
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
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