[speedtest] Binding for Ookla's Speedtest - Initial contribution

CODEOWNERS

@@ -321,6 +321,7 @@
 /bundles/org.openhab.binding.sonyaudio/ @freke
 /bundles/org.openhab.binding.sonyprojector/ @lolodomo
 /bundles/org.openhab.binding.souliss/ @lucacalcaterra @fazioa
+/bundles/org.openhab.binding.speedtest/ @MikeTheTux
 /bundles/org.openhab.binding.spotify/ @Hilbrand
 /bundles/org.openhab.binding.squeezebox/ @digitaldan @mhilbush
 /bundles/org.openhab.binding.surepetcare/ @renescherer @HerzScheisse

bom/openhab-addons/pom.xml

@@ -1601,6 +1601,11 @@
       <artifactId>org.openhab.binding.souliss</artifactId>
       <version>${project.version}</version>
     </dependency>
+    <dependency>
+      <groupId>org.openhab.addons.bundles</groupId>
+      <artifactId>org.openhab.binding.speedtest</artifactId>
+      <version>${project.version}</version>
+    </dependency>
     <dependency>
       <groupId>org.openhab.addons.bundles</groupId>
       <artifactId>org.openhab.binding.spotify</artifactId>

bundles/org.openhab.binding.speedtest/NOTICE

@@ -0,0 +1,13 @@
+This content is produced and maintained by the openHAB project.
+
+* Project home: https://www.openhab.org
+
+== Declared Project Licenses
+
+This program and the accompanying materials are made available under the terms
+of the Eclipse Public License 2.0 which is available at
+https://www.eclipse.org/legal/epl-2.0/.
+
+== Source Code
+
+https://github.com/openhab/openhab-addons

bundles/org.openhab.binding.speedtest/README.md

@@ -0,0 +1,118 @@
+# Speedtest Binding
+
+The Speedtest Binding can be used to perform a network speed test for your openHAB instance.
+It is based on the command line interface (CLI) version of Ookla's Speedtest (https://www.speedtest.net/apps/cli).
+
+The Ookla CLI Speedtest application MUST be installed on your openHAB instance when using the Speedtest Binding.
+
+## Why Ookla's Speedtest?
+
+Fully supported and maintained by Ookla with the latest Speedtest technology for best results:
+
+- Consistent measurement, even on high bandwidth
+- Consistent measurement, very much independent from the performance of the host system
+
+## What functionality does Ookla's Speedtest offer?
+
+The Speedtest Binding is using the following functionality, provided by Ookla's Speedtest:
+
+- Output of an accurate timestamp per measurement
+- Output of Ping time and Jitter
+- Output of Bandwidth, transferred Bytes and elapsed time for Down-/Upload
+- Output of the used interface with Internal/External IP, MAC Address and the Internet Service Provider (ISP)
+- Output of a result ID and a result URL
+- Output of the used Server and location the Speedtest was run against
+- Possibility to pre-select a server used for testing
+
+## What interfaces does the Speedtest Binding offer?
+
+The Speedtest Binding provides the Ookla's Speedtest functionality via the following openHAB interface:
+
+- Execute Speedtest time based or triggered
+- Provide results via openHAB Channels
+- List available Ookla Speedtest servers that can be used for testing (optional)
+
+## Ookla License and Privacy Terms
+
+When using this binding, you automatically accept the license and privacy terms of Ookla's Speedtest.
+You can find the latest version of those terms at the following webpages:
+
+- https://www.speedtest.net/about/eula
+- https://www.speedtest.net/about/terms
+- https://www.speedtest.net/about/privacy
+
+## Supported Things
+
+Speedtest thing.
+
+## Binding Configuration
+
+For this binding to work, you MUST install Ookla's Speedtest command line tool (`speedtest` or `speedtest.exe`).
+It will not work with other versions like `speedtest-cli` or other `speedtest` variants.
+
+To install Ookla's version of Speedtest, head to https://www.speedtest.net/apps/cli and follow the instructions for your Operating System.
+
+## Thing Configuration
+
+| Parameter         |  Description                                                                                                                 | Default |
+|-------------------|------------------------------------------------------------------------------------------------------------------------------|---------|
+| `refreshInterval` | How often to test network speed, in minutes                                                                                  | `60`    |
+| `execPath`        | The path of the Ookla Speedtest executable.<br/>Linux machines may leave this blank and it defaults to `/usr/bin/speedtest`. |         |
+| `serverID`        | Optional: A specific server that shall be used for testing. You can pick the server ID from the "Thing Properties".<br/>If this is left blank the best option will be selected by Ookla.          |         |
+
+The `refreshInterval` parameter can also be set to `0` which means "Do not test automatically".
+This can be used if you want to use the "Trigger Test" channel in order to test via rules, or an item instead.
+
+Ensure that the user that openHAB is running with, has the permissions to access and execute the executable.
+
+## Properties
+
+| Property            | Description                                                                                                |
+|---------------------|------------------------------------------------------------------------------------------------------------|
+| Server List 1...10  | A List of Ookla Speedtest servers that can be used in order to specify a specific server for the Speedtest.<br/>Configure the Server ID via the `serverID` Thing Configuration Parameter. |
+
+## Channels
+
+| Channel               | Type                      | Description                                                       |
+|-----------------------|---------------------------|-------------------------------------------------------------------|
+| `server`              | `String`                  | The remote server that the Speedtest was run against              |
+| `pingJitter`          | `Number:Time`             | Ping Jitter - the variation in the response time                  |
+| `pingLatency`         | `Number:Time`             | Ping Latency - the reaction time of your internet connection      |
+| `downloadBandwidth`   | `Number:DataTransferRate` | Download bandwidth, e.g. in Mbit/s                                |
+| `downloadBytes`       | `Number:DataAmount`       | Amount of data that was used for the last download bandwidth test |
+| `downloadElapsed`     | `Number:Time`             | Time spent for the last download bandwidth test                   |
+| `uploadBandwidth`     | `Number:DataTransferRate` | Upload bandwidth, e.g. in Mbit/s                                  |
+| `uploadBytes`         | `Number:DataAmount`       | Amount of data that was used for the last upload bandwidth test   |
+| `uploadElapsed`       | `Number:Time`             | Time spent for the last upload bandwidth test                     |
+| `isp`                 | `String`                  | Your Internet Service Provider (ISP) as calculated by Ookla       |
+| `interfaceInternalIp` | `String`                  | IP address of the internal interface that was used for the test   |
+| `interfaceExternalIp` | `String`                  | IP address of the external interface that was used for the test   |
+| `resultUrl`           | `String`                  | The URL to the Speedtest results in HTML on the Ookla webserver   |
+| `triggerTest`         | `Switch`                  | Trigger in order to run Speedtest manually                        |
+
+## Full Example
+
+### Thing File
+
+```java
+Thing   speedtest:speedtest:myspeedtest   "Ookla Speedtest"    [ execPath="/usr/bin/speedtest", refreshInterval=60 ]
+```
+
+### Item File
+
+```java
+String                    Speedtest_Server                "Server"                { channel="speedtest:speedtest:myspeedtest:server" }
+Number:Time               Speedtest_Ping_Jitter           "Ping Jitter"           { channel="speedtest:speedtest:myspeedtest:pingJitter" }
+Number:Time               Speedtest_Ping_Latency          "Ping Latency"          { channel="speedtest:speedtest:myspeedtest:pingLatency" }
+Number:DataTransferRate   Speedtest_Download_Bandwith     "Download Bandwith"     { channel="speedtest:speedtest:myspeedtest:downloadBandwidth" }
+Number:DataAmount         Speedtest_Download_Bytes        "Download Bytes"        { channel="speedtest:speedtest:myspeedtest:downloadBytes" }
+Number:Time               Speedtest_Download_Elapsed      "Download Elapsed"      { channel="speedtest:speedtest:myspeedtest:downloadElapsed" }
+Number:DataTransferRate   Speedtest_Upload_Bandwith       "Upload Bandwith"       { channel="speedtest:speedtest:myspeedtest:uploadBandwidth" }
+Number:DataAmount         Speedtest_Upload_Bytes          "Upload Bytes"          { channel="speedtest:speedtest:myspeedtest:uploadBytes" }
+Number:Time               Speedtest_Upload_Elapsed        "Upload Elapsed"        { channel="speedtest:speedtest:myspeedtest:uploadElapsed" }
+String                    Speedtest_ISP                   "ISP"                   { channel="speedtest:speedtest:myspeedtest:isp" }
+String                    Speedtest_Interface_InternalIP  "Internal IP Address"   { channel="speedtest:speedtest:myspeedtest:interfaceInternalIp" }
+String                    Speedtest_Interface_ExternalIP  "External IP Address"   { channel="speedtest:speedtest:myspeedtest:interfaceExternalIp" }
+String                    Speedtest_ResultURL             "Result URL"            { channel="speedtest:speedtest:myspeedtest:resultUrl" }
+Switch                    Speedtest_TriggerTest           "Trigger Test"          { channel="speedtest:speedtest:myspeedtest:triggerTest" }
+```

bundles/org.openhab.binding.speedtest/pom.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.openhab.addons.bundles</groupId>
+    <artifactId>org.openhab.addons.reactor.bundles</artifactId>
+    <version>4.0.0-SNAPSHOT</version>
+  </parent>
+
+  <artifactId>org.openhab.binding.speedtest</artifactId>
+
+  <name>openHAB Add-ons :: Bundles :: Speedtest Binding</name>
+
+</project>

bundles/org.openhab.binding.speedtest/src/main/feature/feature.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<features name="org.openhab.binding.speedtest-${project.version}" xmlns="http://karaf.apache.org/xmlns/features/v1.4.0">
+	<repository>mvn:org.openhab.core.features.karaf/org.openhab.core.features.karaf.openhab-core/${ohc.version}/xml/features</repository>
+
+	<feature name="openhab-binding-speedtest" description="Speedtest Binding" version="${project.version}">
+		<feature>openhab-runtime-base</feature>
+		<bundle start-level="80">mvn:org.openhab.addons.bundles/org.openhab.binding.speedtest/${project.version}</bundle>
+	</feature>
+</features>

bundles/org.openhab.binding.speedtest/src/main/java/org/openhab/binding/speedtest/internal/SpeedtestBindingConstants.java

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) 2010-2023 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+package org.openhab.binding.speedtest.internal;
+
+import java.util.Set;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.core.thing.ThingTypeUID;
+
+/**
+ * The {@link SpeedtestBindingConstants} class defines common constants, which are
+ * used across the whole binding.
+ *
+ * @author Brian Homeyer - Initial contribution
+ */
+@NonNullByDefault
+public class SpeedtestBindingConstants {
+
+    private static final String BINDING_ID = "speedtest";
+
+    // List of all Thing Type UIDs
+    public static final ThingTypeUID THING_TYPE_SPEEDTEST = new ThingTypeUID(BINDING_ID, "speedtest");
+
+    // Config
+    public static final String REFRESH_INTERVAL = "refreshInterval";
+    public static final String EXEC_PATH = "execPath";
+    public static final String SPEEDTEST_VERSION = "speedTestVersion";
+    public static final String SERVER_ID = "serverID";
+
+    // Channels
+    public static final String SERVER = "server";
+    public static final String PING_JITTER = "pingJitter";
+    public static final String PING_LATENCY = "pingLatency";
+    public static final String DOWNLOAD_BANDWIDTH = "downloadBandwidth";
+    public static final String DOWNLOAD_BYTES = "downloadBytes";
+    public static final String DOWNLOAD_ELAPSED = "downloadElapsed";
+    public static final String UPLOAD_BANDWIDTH = "uploadBandwidth";
+    public static final String UPLOAD_BYTES = "uploadBytes";
+    public static final String UPLOAD_ELAPSED = "uploadElapsed";
+    public static final String ISP = "isp";
+    public static final String INTERFACE_INTERNALIP = "interfaceInternalIp";
+    public static final String INTERFACE_EXTERNALIP = "interfaceExternalIp";
+    public static final String RESULT_URL = "resultUrl";
+    public static final String TRIGGER_TEST = "triggerTest";
+
+    public static final String PROPERTY_SERVER_LIST1 = "Server List 1";
+    public static final String PROPERTY_SERVER_LIST2 = "Server List 2";
+    public static final String PROPERTY_SERVER_LIST3 = "Server List 3";
+    public static final String PROPERTY_SERVER_LIST4 = "Server List 4";
+    public static final String PROPERTY_SERVER_LIST5 = "Server List 5";
+    public static final String PROPERTY_SERVER_LIST6 = "Server List 6";
+    public static final String PROPERTY_SERVER_LIST7 = "Server List 7";
+    public static final String PROPERTY_SERVER_LIST8 = "Server List 8";
+    public static final String PROPERTY_SERVER_LIST9 = "Server List 9";
+    public static final String PROPERTY_SERVER_LIST10 = "Server List 10";
+
+    public static final Set<String> SUPPORTED_CHANNEL_IDS = Set.of(SERVER, PING_JITTER, PING_LATENCY,
+            DOWNLOAD_BANDWIDTH, DOWNLOAD_BYTES, DOWNLOAD_ELAPSED, UPLOAD_BANDWIDTH, UPLOAD_BYTES, UPLOAD_ELAPSED, ISP,
+            INTERFACE_INTERNALIP, INTERFACE_EXTERNALIP, RESULT_URL);
+}

bundles/org.openhab.binding.speedtest/src/main/java/org/openhab/binding/speedtest/internal/SpeedtestConfiguration.java

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2010-2023 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+package org.openhab.binding.speedtest.internal;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
+/**
+ * The {@link SpeedtestConfiguration} class contains fields mapping thing configuration parameters.
+ *
+ * @author Brian Homeyer - Initial contribution
+ */
+@NonNullByDefault
+public class SpeedtestConfiguration {
+    public int refreshInterval = 60;
+    public String execPath = "";
+    public String serverID = "";
+    public String speedTestVersion = "";
+}