Mozilla WebThings Binding

Development Add-ons
Tags: #<Tag:0x00007f6188cf7088>
#1

I am currently developing a binding to host openHAB things as WebThings (https://iot.mozilla.org/wot/#web-thing-description) so that they are accessible by other applications - mostly the Mozilla Gateway (https://iot.mozilla.org/). Furthermore, you can connect openHAB things and (Mozilla) WebThings to control each other.

Edit: It is now possible to auto-discover and manually import WebThings into openHAB and control them afterwards.

The binding uses the Java WebThing Framework (https://iot.mozilla.org/framework/) which currently offers no OSGi bundle. Therefore, i created the bundle myself based on the Jar on MVNRepository (https://mvnrepository.com/artifact/org.mozilla.iot/webthing/0.12.0).

From the ReadMe:

WebThings Binding

This binding can be used to:

  • Import WebThings and control them via openHAB

  • Host openHAB things as (Mozilla) WebThings.

  • Connect existing openHAB things to WebThings to control each other.

Example interaction: Link

!!! Work in progress !!!

Prerequisites

Copy the files from the dependencies folder and the binding into your addons folder

Supported Things

  • WebThings WebThing: Import and control a WebThing.

  • WebThings Server: Host your openHAB things as WebThings.

  • WebThings Connector: Connect openHAB things and WebThings.

Discovery

Automatically discovers:

  • WebThings from the Gateway based on binding configuration

  • WebThings from local WebThing Servers via mDNS

Binding Configuration

Configuration Parameters:

  1. Server URL of WebThing Server: Currently only Mozilla Gateways supported. This is used for by the WebThings Connector.

  2. Bearer token: Token for the Connector Things authorization. Can be generated in the Mozilla Gateway: Settings --> Developer --> Create local authorization

  3. OpenHAB IP and Port: OpenHAB instance to get necessary information from. Used for REST API calls.

  4. Match capabilities: If true the WebThing Server will try to add a @type to each WebThing to match Mozilla capabilities based on default tags - this may not always work flawlessly for all things. If set to false, all WebThings will appear as custom things.

Additional:

  1. Background Discovery: If true all WebThings from the selected Gateway will be automatically discovered, without the need to manually start a search (may generate a lot of inbox entries if many things exist)

  2. Operating system: Choose your installation (can be used as fallback option to import ThingUIDs for the WebThing Server)

  3. Custom path: Set a custom path in case your operating system is not listed or you use a non-standard userdata directory

Thing Configuration

WebThings WebThing

Configuration parameters:

  1. Link of WebThing: Link to WebThing to be imported

  2. Security Scheme: Security method to access the respective WebThing

  3. Security Token: Authorization token for “Bearer” authorization

  4. Import Token: If true the security token can be left blank and will be imported from the binding configuration


WebThings Server

Configuration parameters:

  1. Port of WebThing Server: Port to host your Webserver on. Multiple servers possible.

  2. Linked items: Choose whether to create a property for every channel of the openHAB thing or for every item linked to it. For linked items naming convention of simple linking is currently advised

  3. Host all things: Host all things (except things created by this binding) or only selected ones.

  4. Selected openHAB things: Choose openHAB things to host as WebThings (only if 3. = false).


WebThings Connector

Configuration parameters:

  1. ID of WebThing

  2. UID of openHAB thing

Channels

Thing channel type description
WebThing Automatic Automatic All channels will be automacially generated based on the WebThing properties

Thing channel type description
Server Port Number Port of WebThing Server
Server Hosted WebThings Text List of openHAB things hosted as WebThings

Thing channel type description
Connector Update Switch Can be used to restart the websocket (re-connect)
Connector ID String ID of WebThing
Connector UID String UID of openHAB thing

Example Use Cases

  1. Easily add real world objects to openHAB using any of the existing WebThing Frameworks (Node.js, Pytho, Java, Rust, C#, Go, …) without the need for a binding

  2. Single platform for multiple smart homes or smart home systems from one or multiple networks

  3. Remote access

  4. Sync openHAB instances

  5. Authorization concept (expose different WebThing Servers with selected things via reverse proxy)

Planned Updates

  • Resolve known issues

  • Support for more items types / properties

Known Issues

Issue Impact Status Workaround
Dependency incompatibility when REST API docs are installed Binding may not start Active Remove docs --> install binding --> install docs
First command for switch item / OnOff property gets send but not detected by gateway Command not properly received Active Send another command after initially connecting
Add webthing as internal dependency Dependencies need to be deployed manually Active Add lib directory (currently not compiling)
ItemStateChangeEvents for items with delimiters are not processed correctly Some items are not controllable Active Switch case for special items
WebThings can only be accessed via their index in list (e.g. localhost:8888/0) Removal of things from a WebThing Server will change the indices of the other things Active Create multiple servers so that changes to one do not affect all things
WebThings WebThing label & location can not be updated Things need to be re-created Active Set during creation
ConfigOptionProvider for WebThing Server may request the openHAB thing list before the API is ready Server may not be creatable Resolved Try to manually restart bundle, Re-compile without WebThingsConfigOptionProvider.java

Work in progress code can be found here: https://github.com/svensven94/openhab-addons/tree/webthings/bundles/org.openhab.binding.webthings

Lastly, the relevant GitHub issue can be found here: https://github.com/openhab/openhab-addons/issues/7009

edit: updated ReadMe and link

5 Likes
Mozilla Web of Things
#2

I updated the binding to support auto-discovery and manually importing WebThings into openHAB and control them afterwards.

Furthermore the internal structure got a major overhaul.

3 Likes
#3

This is great, I’m using openHAB at home and at the same time I like developing Mozilla WebThings. Until now there was no simple way to connect those WebThings directly to openHAB. I’ll give this a try, thanks for putting effort into this!

Is there a pre-build jar available for testing?

#4

I added a pre-build jar for testing. You can find it here.

Be aware that this is the barebones version of the binding, which only supports importing WebThings and not converting OH --> WoT (the reason for there being two version can be found in the issue on GitHub).

I will make a [WIP] pull request soon, so there should be an officially compiled version coming.

2 Likes
#5

Thanks for publishing the jar file! I’ve tested the binding, it’s exactly the functionality I’m searching for: Controlling WebThings via openHAB. Thanks for working on this!

In my case adding the add on (and dependencies) to the addons/ folder caused my openHAB installation to become unstable. Other functionality (REST API and Paper UI) became unresponsive, throwing HTTP 503 errors in a irregular but rising basis. Nevertheless I was able to find and add one of my WebThings (an Arduino RGB-Lamp). Interface was intuitive, so looks promising. I did not figure out how to control my device, but also did not invest much time. Maybe my self-implemented API is not fully conform to the standard or they just can’t be detected automatically.

I’m limited in time, but will keep a close eye on this and test new versions when they become available. Let me know if you’re interested in logs or anything. I’ve also subscribed to the GitHub issue.

1 Like
#6

There should not be special dependencies. What are the Things that you can create with the binding - only a WebThings WebThing or also Servers/Connectors? (maybe i provided the wrong JAR).

I made the observation that the WebSocket can break, when the request is not in a specific format. I tested the connection for WebThings imported from the Mozilla Gateway and the Java, NodeJS and Python Frameworks. Interestingly, the Gateway has slighlty different syntax than the Framework, so maybe it’s the same case for you self-implemented API. In that case, you should get an error in your logs and the Thing goes offline with a communication error.

You should be able to control your WebThing with normal openHAB items. Take a look at the channels the binding automatically creates for your imported thing and add respective items. Keep in mind that actions and events are not yet supported.

Edit: If desired I can provide screenshots/a video on how to use the binding.

#7

Yes this would be nice :wink: