Skip to main content

QNAP QSW smart home integration, free and open source

QNAP QSW integration for Gladys Assistant

QNAP QSW switches: ports, link speed, rates, temperature, fans, firmware, reboot.

View on GitHubAll integrations

QNAP QSW managed switches (QSW-M408, QSW-M2116 and the other QSW-M models running QSS) in Gladys, through the API of the local web interface of the switch. Handy to watch the network of the house: a port that drops, a link that falls back to 100 Mbit/s, a switch getting hot:

  • the switch becomes a Gladys device (Discovery tab): ports connected, temperature, fan 1 and fan 2 speeds (rpm, when the switch has them), receive and transmit rates of all ports together, uptime, firmware; and for each port: connected (yes / no), link speed (0 when nothing is plugged in), receive and transmit rates;
  • a Reboot the switch button, inactive until you allow it.

The rates are computed from the byte counters of two readings in a row (none at the first reading, none when the counters start again, after a reboot of the switch). The link aggregation groups (LACP) are not read, only the physical ports. PoE is not read: the library this integration follows does not read it, and its routes are not guessed. Unmanaged QSW switches have no interface and cannot be read.

This is not the integration of the QNAP NAS (QTS, QuTS hero): that one is another integration of the store.

This integration has never been tested with a real switch. This first version follows aioqsw, the library Home Assistant uses, and was tested against a fake switch only. Tell on the Gladys forum what works and what does not, with the model and the QSS version.

Unofficial integration, not affiliated with QNAP.

Before you start​

  1. The switch must be a managed QSW (with a web interface, QSS).
  2. Gladys needs an administration account of the web interface (admin by default). Its password is kept by Gladys in its database, never shown again, and sent only to the switch.
  3. Add one integration per switch.

Settings​

  • Address of the switch: its IP address or host name, as you type it to open its interface. HTTPS by default (port 443, or :port). If your switch serves its interface in plain HTTP only, type http:// before the address: the password (in base64, which anyone can read) then crosses your network readable by anyone on it.
  • User name, Password.
  • Certificate fingerprint (optional, HTTPS only): see below.
  • Refresh: 30 s, 1 min (default), 2 or 5 min. The test button, a save of the form and a restart of Gladys or of the container do not read sooner (the time of the last attempt is kept, written before the reading). A press on Reboot the switch makes one fresh read of its own, outside the refresh.
  • Allow rebooting the switch: off by default.

The HTTPS certificate​

The switch has a self-signed certificate, which no authority can vouch for. Gladys checks it by its SHA-256 fingerprint, right after the TLS handshake and before sending the password:

  • the field empty, at the first connection: Gladys writes the certificate met to its storage, then sends the password. If its storage cannot be read or written, nothing is learned and nothing is sent (the status shows the fingerprint met; the storage is read again every 10 s);
  • afterwards, another certificate stops everything (nothing is sent) and the status shows its fingerprint. Saving the form again changes nothing. If you replaced or reset the switch, type in Certificate fingerprint the fingerprint your browser shows for it (padlock, certificate, SHA-256): it becomes the trusted one.

The reboot​

The Reboot the switch button is a button, never a switch: a "turn everything off" of a voice assistant or a scene never reaches it. Every device plugged into the switch loses its network for 1 to 3 minutes. A press is refused, nothing sent, in these cases:

  • Allow rebooting the switch is off (checked again right before the request is written);
  • the configuration is incomplete, the login or the certificate was refused, another switch answers at the address, or Gladys is in a pause asked by the switch (HTTP 429 or 5xx);
  • a reboot was sent less than 10 minutes ago (kept across restarts), or this delay cannot be written to the storage of the integration (/data), or that storage cannot be read;
  • a reboot is already being sent, or a reading in progress does not end within 2.5 s of the press;
  • the switch does not answer the read made just before within 2.5 s, or another switch answers (another MAC), or its MAC cannot be read or was never read before at this address;
  • the request could not be written within 3.5 s of the press.

A press does not wait for the readings to come back after an outage: its own fresh read decides. When the request was written but the switch did not answer, Gladys says "sent, without an answer": the switch may be rebooting. For 5 minutes, a reading that fails says the switch is rebooting.

Failures​

  • Credentials refused (by the login page of the switch only): nothing is sent again until the user name or the password is saved again in the form (the password saved is then tried once, even the same one); the Test the connection button tries once more, when a reading is due (never sooner than the refresh after the last attempt). Gladys keeps an 8-bit marker of the refused password (shared by 1 password in 256, never the password) so that a restart does not try it again.
  • HTTP 429 or 5xx on the login, the board or the port status: a pause of every request (1 min to 6 h), kept across restarts. The other routes (rates, sensors, uptime, firmware) never pause nor stop the reading (a refused certificate or login aside, which stops everything wherever it is met): what they did not give this time is said in the status. One of them refusing the session (HTTP 401/403, an account without the right to it) opens no new session: it is asked again 1, 2, 4... readings later, at most an hour apart.
  • No answer: tried again after 1 minute or the refresh interval if longer, then twice as long each time, up to 30 minutes.
  • Another switch at the address (another MAC): nothing is published nor sent; save the form to take it as the new one.

Neither the password, nor the session token, nor the MAC address or the serial number are logged or published. The storage keeps the certificate fingerprint, the 8-bit marker above, and a salted hash of the MAC of the switch (not the MAC in clear).

Not done (yet)​

PoE (power per port), the link aggregation groups, the error counters, the firmware update check: say on the forum if you need one.

Configuration settings​

These are the settings QNAP QSW asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
How it workssectionNoGladys reads one QNAP QSW managed switch (QSW-M408, QSW-M2116 and the other QSW-M models running QSS) through the API of its local web interface, with an administration account. The switch becomes a device: ports connected, temperature, fan speeds, total receive and transmit rates, uptime, firmware, and for each port: connected, link speed, receive and transmit rates; plus a Reboot button, off unless you allow it below. PoE is not read (not in the reference library, not guessed). Unmanaged QSW switches have no interface and cannot be read. Add one integration per switch. This is not the QNAP NAS integration. Unofficial integration, not affiliated with QNAP.
Address of the switchstringYesThe IP address (or host name) of the switch on your local network, as you type it to open its web interface. HTTPS by default (certificate checked, see below). If the switch serves its interface in plain HTTP only, start the address with http:// : the password then crosses your network readable by anyone on it.
User namestringYesAn administration account of the web interface of the switch (admin by default on QSS).
PasswordsecretYesThe password of this account. Kept by Gladys in its database, never shown again, sent only to the switch (in HTTPS, on a connection whose certificate was checked first).
Certificate fingerprint (optional, HTTPS)stringNoThe switch has a self-signed HTTPS certificate. Empty: Gladys pins the certificate met at the first connection (written to its storage before the password is sent) and then refuses any other one, saying its fingerprint. To trust a new certificate (switch replaced or reset), or to pin it yourself, type its SHA-256 fingerprint here (as your browser shows it). Leave it empty with an http:// address.
RefreshselectYesHow often the switch is read. The test button, a save of the form or a restart do not read sooner; a press on Reboot makes one fresh read of its own.
CommandsectionNoReading only by default. The one command is the reboot, a button (never a switch: a "turn everything off" never reaches it), refused unless allowed here, at most one every 10 minutes. Every device plugged into the switch loses its network while it reboots (1 to 3 minutes).
Allow rebooting the switchbooleanNoOff: the Reboot button is refused and nothing is sent.

How to install QNAP QSW in Gladys​

  1. In Gladys, open Integrations: QNAP QSW appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-qnap-qsw:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-qnap-qsw.

QNAP QSW requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

QNAP QSW is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on