2021-04-11 19:47:27 +02:00
# WebThing Binding
2023-04-11 12:54:54 +02:00
The WebThing binding supports an interface to smart home device supporting the Web Thing API.
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
The [Web Thing API ](https://iot.mozilla.org/wot/ ) describes an open and generic standard to discover and link smart home devices
like motion sensors, web-connected displays or awning controls. Devices implementing the Web Thing standard can be integrated
2021-04-11 19:47:27 +02:00
into smart home systems such as openHAB to monitor and control them.
2023-04-11 12:54:54 +02:00
These days, the Web Thing API is primarily used by makers to provide a common API to their physical devices.
For instance, the Web Thing API has been used by makers to provide an open way to control [LEDs on an ESP8266 board ](https://github.com/WebThingsIO/webthing-arduino )
2021-04-11 19:47:27 +02:00
or to monitor [a PIR motion sensor on Raspberry Pi ](https://pypi.org/project/pi-pir-webthing/ ).
## Supported Things
2023-04-11 12:54:54 +02:00
As a generic solution, the WebThing binding does not depend on specific devices. All devices implementing the Web Thing API should be accessible.
2021-04-11 19:47:27 +02:00
## Discovery
Once the binding is activated all reachable **WebThing devices will be detected automatically** (via mDNS).
## Binding Configuration
No binding configuration required.
## Thing Configuration
2023-04-11 12:54:54 +02:00
| Parameter | Description | Required |
2021-04-11 19:47:27 +02:00
|----------|--------|-------------|
| webThingURI | the URI of the WebThing | true |
2023-04-11 12:54:54 +02:00
Due to the discovery support, **no manual Thing configuration is required** in general. However, under certain circumstances textual
2021-04-11 19:47:27 +02:00
Thing configuration may be preferred. In this case, the webThingURI has to be configured as shown in the webthing.things file below:
2023-04-11 12:54:54 +02:00
```java
2021-04-11 19:47:27 +02:00
Thing webthing:generic:motionsensor [ webThingURI="http://192.168.1.27:9496/" ]
```
## Channels
2023-04-11 12:54:54 +02:00
The supported channels depend on the WebThing device that is connected. Each mappable **WebThing property will be mapped to a dedicated channel, automatically** . For instance, to support the _motion property_ of a Motion-Sensor WebThing, a dedicated _motion channel_ will be created, automatically.
2021-04-11 19:47:27 +02:00
| Thing | channel | type | description |
|--------|----------|--------|------------------------------|
| WebThing | Automatic | Automatic | All channels will be generated automatically based on the detected WebThing properties |
## Full Example
2023-04-11 12:54:54 +02:00
In the example below WebThings provided by the [Internet Monitor Service ](https://pypi.org/project/internet-monitor-webthing/ ) will be connected.
This service does not require specific hardware or devices. To connect the WebThings, the service has to be installed inside your local network.
2021-04-11 19:47:27 +02:00
2024-09-28 17:46:53 +02:00
### Thing
2021-04-11 19:47:27 +02:00
After installing the WebThing binding you should find the WebThings of your network in the things section of your openHAB administration interface as shown below.
2023-04-11 12:54:54 +02:00
![discovery picture ](doc/discovery.png )
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
Here, the WebThings provided by the _Internet Monitor Service_ : the _Internet Connectivity_ WebThing as well as the
_Internet Speed Monitor_ WebThing have been discovered. To add a WebThing as an openHAB Thing click the 'Add as Thing' button.
![discovery picture ](doc/speedmonitor.png )
2021-04-11 19:47:27 +02:00
2024-09-28 17:46:53 +02:00
Alternatively, you may add the WebThing as an openHAB Thing by using a webthing.thing file that has to be located inside the things folder.
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
```java
2021-04-11 19:47:27 +02:00
Thing webthing:generic:speedmonitor [ webThingURI="http://192.168.1.27:9496/0" ]
```
2023-04-11 12:54:54 +02:00
Please consider that the _Internet Monitor Service_ in this example supports two WebThings. Both WebThings are bound on the
same hostname and port. However, the WebThing URI path of the speed monitor ends with '/0'. In contrast,
the connectivity WebThing URI path ends with '/1' in this example.
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
Due to the fact that the WebThing API is based on web technologies, you can validate the WebThing description by opening the WebThing uri in a browser.
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
![webthing picture ](doc/webthing_description.png )
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
### Items
The _Internet Speed Monitor_ WebThing used in this example supports properties such as _downloadspeed_ , _uploadspeed_ or _ping_ .
For each property of the WebThing a dedicated openHAB channel will be created, automatically. The channelUID such
as _webthing:generic:speedmonitor:uploadspeed_ is the combination of the thingUID _webthing:generic_ and the
WebThing property name _uploadspeed_ .
![channels picture ](doc/channels.png )
2021-04-11 19:47:27 +02:00
These channels may be linked via the channels tab of the graphical user interface or manually via a webthing.items file as shown below
2023-04-11 12:54:54 +02:00
```java
2021-04-11 19:47:27 +02:00
Number uploadSpeed "uploadspeed speed [%.0f]" {channel="webthing:generic:speedmonitor:uploadspeed"}
Number downloadSpeed "download speed [%.0f]" {channel="webthing:generic:speedmonitor:downloadspeed"}
```
2023-04-11 12:54:54 +02:00
2021-04-11 19:47:27 +02:00
### Sitemap
2023-04-11 12:54:54 +02:00
To add the newly linked WebThing items to the sitemap you place a sitemap file such as the internetmonitor.sitemap file shown below
2021-04-11 19:47:27 +02:00
2023-04-11 12:54:54 +02:00
```perl
2021-04-11 19:47:27 +02:00
sitemap internetmonitor label="Internet Speed Monitor" {
2024-09-28 17:46:53 +02:00
Text item=uploadSpeed
Text item=downloadSpeed
2021-04-11 19:47:27 +02:00
}
```
2023-04-11 12:54:54 +02:00
![sitemap picture ](doc/sitemap.png )