agmangas / wot-py

wotpy is an experimental asynchronous implementation of a W3C Web of Things runtime

wotpy

Introduction

wotpy is an experimental implementation of a W3C WoT Runtime and the W3C WoT Scripting API in Python.

Inspired by the exploratory implementations located in the thingweb GitHub page.

About the current version

The current version of the project has been updated in an effort to address stability and deprecation issues. The following changes have been made compared to version 0.16.0:

• The project has been updated to support Python 3.7 and above. All support for Python 2 has been dropped.
• The project has mostly dropped the Tornado coroutines syntax in favor of the async/await syntax.
• The project has removed the dependency from the hbmqtt package in favor of aiomqtt due to the deprecation of the former.

However, please note that there's still a significant pending issue. Although the project is currently in a reasonably stable state, it does not implement the current version of the W3C WoT specifications. Specifically, the version at the time of writing is based on the following outdated references:

• K. Kajimoto, M. Kovatsch, and U. Davuluru, ‘Web of Things (WoT) Architecture’, W3C, W3C First Public Working Draft, Sep. 2017. [Online]. Available: https://www.w3.org/TR/2017/WD-wot-architecture-20170914/
• Z. Kis, K. Nimura, D. Peintner, and J. Hund, ‘Web of Things (WoT) Scripting API’, W3C, W3C Working Draft, Nov. 2018. [Online]. Available: https://www.w3.org/TR/2018/WD-wot-scripting-api-20181129/
• S. Käbisch and T. Kamiya, ‘Web of Things (WoT) Thing Description’, W3C, W3C Working Draft, Oct. 2018. [Online]. Available: https://www.w3.org/TR/2018/WD-wot-thing-description-20181021/

ℹ️ It is in our plans to get wotpy up to speed with the latest version of the specifications. We don't have an ETA for this, but we will be working on it in the near future.

In summary, wotpy is mature enough to be used in projects; in fact, it is being used in production at CTIC. However, it is not an adequate representation of the current status of the W3C WoT. We greatly encourage you to check the Developer Resources section on the WoT website to find out about the current state of the art.

Features

The wotpy project provides fully functional implementations of four different protocol bindings: MQTT, HTTP, WebSockets, and CoAP. Moreover, it offers a discovery implementation based on Multicast DNS.

These bindings are built on top of the following dependencies, which are instrumental to the project:

Feature	Implementation based on
HTTP binding	tornadoweb/tornado
WebSockets binding	tornadoweb/tornado
CoAP binding	chrysn/aiocoap
MQTT binding	sbtinstruments/aiomqtt
mDNS discovery	jstasiak/python-zeroconf

Installation

pip install wotpy

Development

The development workflow of wotpy is based on Taskfile, so that's the first thing you need to install.

Then, to create a virtual environment under .venv, and install the project in development mode with all the test dependencies, run:

task venv

Some wotpy features (e.g., the CoAP binding) are not available outside of Linux. If you have Docker installed on your system and want to run the tests in a Linux environment easily, you can use the Docker-based test task:

$ PYTHON_TAG="3.9" task docker-tests
task: [test-broker] docker run -d -p 1883:1883 --name wotpy_test_broker eclipse-mosquitto:1.6

68bfef102faf3529427e5c7122f41d43490885c04f8a2d673a2c57b3afd68f72
task: [docker-tests] echo "⚙️ Running tests for Python 3.9..."
⚙️ Running tests for Python 3.9...
task: [docker-tests] /Users/agmangas/Documents/Projects/wot-py/pytest-docker.sh
Running python tests for version 3.9 with arguments "-v"
Creating temporary container volume
wotpy_tests_28b82c629b354b83a7fa22a9ed3d6dba
Running test container. Environment setup will take a while.
+ docker run --rm -it -v wotpy_tests_28b82c629b354b83a7fa22a9ed3d6dba:/app -e WOTPY_TESTS_MQTT_BROKER_URL=mqtt://172.16.102.196:1883 python:3.9 /bin/bash -c 'cd /app && pip install --quiet -U .[tests] && pytest -v'
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

[notice] A new release of pip is available: 23.0.1 -> 23.3.1
[notice] To update, run: pip install --upgrade pip
================================================================================================================================================== test session starts ===================================================================================================================================================
platform linux -- Python 3.9.18, pytest-7.4.2, pluggy-1.3.0 -- /usr/local/bin/python
cachedir: .pytest_cache
rootdir: /app
configfile: pytest.ini
plugins: asyncio-0.21.1, rerunfailures-10.3, Faker-13.16.0, cov-2.5.1
asyncio: mode=strict
collected 154 items

tests/codecs/test_json.py::test_json_codec PASSED [  0%]
tests/protocols/test_protocols.py::test_all_protocols_combined PASSED [  1%]

[...]

================================================================================================================================== 148 passed, 6 skipped, 1 warning in 60.70s (0:01:00) ==================================================================================================================================
+ set +x
wotpy_tests_28b82c629b354b83a7fa22a9ed3d6dba
task: [docker-tests] echo "✅ Tests for Python 3.9 completed successfully"
✅ Tests for Python 3.9 completed successfully

An MQTT broker is needed as a dependency for the MQTT binding tests. The task will automatically create a new container based on the eclipse-mosquitto image and expose the broker port to the host. The WOTPY_TESTS_MQTT_BROKER_URL environment variable will be set to the broker URL.

wot-py's Issues

Observable properties behavior

node-wot:

The change event for an observable property is emitted only if the new value differs from the previous one.

---

wot-py:

The change event for an observable property is always emitted regardless of the value.

Support for `securityDefinitions`

According to the Thing Description specification it is possible to create a set of security definitions under securityDefinitions field and refer to them in the security field. However, this kind of TD is not currently supported by wot-py, although it is absolutely valid TD.

Dropping support for Python 2.7

As Python 2.7 is now EOL, it should be considered to drop both the support and the testing in the CI for this version. This should make the code easier to maintain and further develop as dependencies like six could be removed.

readOnly properties are not initializable

node-wot approach:

1. Create a readOnly property.
2. Make it changeable from the creator Thing but keep it read-only for all the clients.
3. Initialize it with thing.writeProperty.

---

wot-py approach:

1. Create a readOnly property.
2. And now the property is read-only for everyone, even the creator Thing, which makes it not initializable as well.

title is ignored in TD

The title field is ignored in the generated Thing Description.

op field type

According to the Thing Description specification, the type of the op field is a string or an array of strings.
However, currently, wot-py considers it as a string only.

Trailing slashes in URLs

I've found an issue while working on #11.
Any URL with a trailing slash leads to 404 Not Found.
However, http://127.0.0.1:9090/my-thing and http://127.0.0.1:9090/my-thing/ must be the same URL.

This can lead to incompatibility issues with node-wot as well.

Create Thing Description from Thing Model

Hello.

I'm taking a look into your W3C Web of Things implementation in Python.

Is it with the current state of the implementation possible to create a Thing Description from various Thing Models?

W3C WoT Compliance

I suggest using this issue to keep track of all the work being done to make the library compliant with the W3C WoT specifications.

@agmangas Could you please create a list of current blocking issues so that I can start working on some of them? (And other people or you might take the others)

We can link all the blockers and todos here and finally start working on bringing the library up to the specs! 😊

uriVariables are ignored in property and action affordances

According to the Thing Description specification, it should be possible to read/write properties and invoke actions using uriVariables but, currently, they are ignored in both affordances.

action invocation result

node-wot approach:

Direct result of an action is returned when invoking an action.

---

wot-py approach:

Invocation id is returned when invoking an action. Direct result of an action should be fetched from a separate endpoint.

Wrappers for value and input

node-wot approach:

The body of a request is already considered as a new value when writing to a property. It is also possible to wrap it around {"value": ...value...} and node-wot will unwrap that. But the first way is preferred.

The body of a request is already considered as an input when invoking an action. It is not possible to wrap it around {"input": ...input...}.

---

wot-py approach:

It is mandatory to wrap property values with {"value": ...value...} and action inputs with {"input": ...input...}.

Thing URL

node-wot approach:

Create Thing and expose it within the following URL:
scheme://ip-address:port/thing-title, e.g.
http://127.0.0.1:8080/Smart-Coffee-Machine
which looks pretty concise.

---

wot-py approach:

Create Thing and expose it within the following URL:
scheme://hostname.domain:port/thing-id+uuid(derived from TD), e.g.
http://my-hostname.my-domain:9090/urn-dev-wot-example-coffee-machine-97e83de1-f5c9-a4a0-23b6-be918d3a22ca
which is imho too long and quite overwhelmed.