This page is part of archived documentation for openHAB 4.1. Go to the current stable version

# 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 (opens new window)).

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:

# 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 (opens new window) 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.
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".
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.
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
timestamp DateTime Timestamp of the Speedtest run
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
resultImage Image The Speedtest results as image
triggerTest Switch Trigger in order to run Speedtest manually

# Full Example

# Thing File

Thing   speedtest:speedtest:myspeedtest   "Ookla Speedtest"    [ execPath="/usr/bin/speedtest", refreshInterval=60 ]

# Item File

String                    Speedtest_Server                "Server"                { channel="speedtest:speedtest:myspeedtest:server" }
DateTime                  Speedtest_Timestamp             "Timestamp"             { channel="speedtest:speedtest:myspeedtest:timestamp" }
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" }
Image                     Speedtest_ResultImage           "Result Image"          { channel="speedtest:speedtest:myspeedtest:resultImage" }
Switch                    Speedtest_TriggerTest           "Trigger Test"          { channel="speedtest:speedtest:myspeedtest:triggerTest" }