• Stars
    star
    177
  • Rank 215,985 (Top 5 %)
  • Language
    Python
  • License
    Mozilla Public Li...
  • Created over 6 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Python implementation of a Web Thing server

webthing

Implementation of an HTTP Web Thing. This library is compatible with Python 2.7 and 3.5+.

Installation

webthing can be installed via pip, as such:

$ pip install webthing

Running the Sample

$ wget https://raw.githubusercontent.com/WebThingsIO/webthing-python/master/example/single-thing.py
$ python3 single-thing.py

This starts a server and lets you search for it from your gateway through mDNS. To add it to your gateway, navigate to the Things page in the gateway's UI and click the + icon at the bottom right. If both are on the same network, the example thing will automatically appear.

Example Implementation

In this code-walkthrough we will set up a dimmable light and a humidity sensor (both using fake data, of course). Both working examples can be found in the examples directory.

Dimmable Light

Imagine you have a dimmable light that you want to expose via the web of things API. The light can be turned on/off and the brightness can be set from 0% to 100%. Besides the name, description, and type, a Light is required to expose two properties:

  • on: the state of the light, whether it is turned on or off
    • Setting this property via a PUT {"on": true/false} call to the REST API toggles the light.
  • brightness: the brightness level of the light from 0-100%
    • Setting this property via a PUT call to the REST API sets the brightness level of this light.

First we create a new Thing:

light = Thing(
    'urn:dev:ops:my-lamp-1234',
    'My Lamp',
    ['OnOffSwitch', 'Light'],
    'A web connected lamp'
)

Now we can add the required properties.

The on property reports and sets the on/off state of the light. For this, we need to have a Value object which holds the actual state and also a method to turn the light on/off. For our purposes, we just want to log the new state if the light is switched on/off.

light.add_property(
    Property(
        light,
        'on',
        Value(True, lambda v: print('On-State is now', v)),
        metadata={
            '@type': 'OnOffProperty',
            'title': 'On/Off',
            'type': 'boolean',
            'description': 'Whether the lamp is turned on',
        }))

The brightness property reports the brightness level of the light and sets the level. Like before, instead of actually setting the level of a light, we just log the level.

light.add_property(
    Property(
        light,
        'brightness',
        Value(50, lambda v: print('Brightness is now', v)),
        metadata={
            '@type': 'BrightnessProperty',
            'title': 'Brightness',
            'type': 'number',
            'description': 'The level of light from 0-100',
            'minimum': 0,
            'maximum': 100,
            'unit': 'percent',
        }))

Now we can add our newly created thing to the server and start it:

# If adding more than one thing, use MultipleThings() with a name.
# In the single thing case, the thing's name will be broadcast.
server = WebThingServer(SingleThing(light), port=8888)

try:
    server.start()
except KeyboardInterrupt:
    server.stop()

This will start the server, making the light available via the WoT REST API and announcing it as a discoverable resource on your local network via mDNS.

Sensor

Let's now also connect a humidity sensor to the server we set up for our light.

A MultiLevelSensor (a sensor that returns a level instead of just on/off) has one required property (besides the name, type, and optional description): level. We want to monitor this property and get notified if the value changes.

First we create a new Thing:

sensor = Thing(
    'urn:dev:ops:my-humidity-sensor-1234',
    'My Humidity Sensor',
     ['MultiLevelSensor'],
     'A web connected humidity sensor'
)

Then we create and add the appropriate property:

  • level: tells us what the sensor is actually reading

    • Contrary to the light, the value cannot be set via an API call, as it wouldn't make much sense, to SET what a sensor is reading. Therefore, we are creating a readOnly property.

      level = Value(0.0);
      
      sensor.add_property(
          Property(
              sensor,
              'level',
              level,
              metadata={
                  '@type': 'LevelProperty',
                  'title': 'Humidity',
                  'type': 'number',
                  'description': 'The current humidity in %',
                  'minimum': 0,
                  'maximum': 100,
                  'unit': 'percent',
                  'readOnly': True,
              }))

Now we have a sensor that constantly reports 0%. To make it usable, we need a thread or some kind of input when the sensor has a new reading available. For this purpose we start a thread that queries the physical sensor every few seconds. For our purposes, it just calls a fake method.

self.sensor_update_task = \
    get_event_loop().create_task(self.update_level())

async def update_level(self):
    try:
        while True:
            await sleep(3)
            new_level = self.read_from_gpio()
            logging.debug('setting new humidity level: %s', new_level)
            self.level.notify_of_external_update(new_level)
    except CancelledError:
        pass

This will update our Value object with the sensor readings via the self.level.notify_of_external_update(read_from_gpio()) call. The Value object now notifies the property and the thing that the value has changed, which in turn notifies all websocket listeners.

Adding to Gateway

To add your web thing to the WebThings Gateway, install the "Web Thing" add-on and follow the instructions here.

More Repositories

1

gateway

WebThings Gateway
TypeScript
2,599
star
2

wiki

Developer Wiki
Shell
291
star
3

webthing-node

Node.js implementation of a Web Thing server
TypeScript
232
star
4

webthing-rust

Rust implementation of a Web Thing server
Rust
206
star
5

webthing-arduino

Simple server for ESP8266, ESP32, Ethernet, or WiFi101-compatible boards compliant with Mozilla's proposed WoT API
C++
204
star
6

api

Web Thing API Specification
HTML
164
star
7

registration_server

The registration server for WebThings Gateway.
Rust
78
star
8

addon-list

List of installable add-ons for WebThings Gateway
Python
77
star
9

gateway-docker

Legacy docker image for WebThings Gateway - now moved to main gateway repo at https://github.com/WebThingsIO/gateway
Dockerfile
71
star
10

webthing-java

Java implementation of a Web Thing server
Java
51
star
11

webthing-upy

MicroPython implementation of a Web Thing server
Python
50
star
12

zigbee-adapter

Zigbee adapter add-on for WebThings Gateway
JavaScript
46
star
13

example-adapter

Example adapter add-on for WebThings Gateway
JavaScript
34
star
14

homekit-adapter

HomeKit device adapter for WebThings Gateway
JavaScript
22
star
15

thing-url-adapter

Proxy adapter for Web Thing API endpoints
JavaScript
22
star
16

philips-hue-adapter

WebThings Gateway Philips Hue Adapter
TypeScript
21
star
17

mozilla-iot.github.io

Mozilla IoT Website
SCSS
20
star
18

curl-examples

Examples of using the gateway API using curl
Shell
19
star
19

gateway-addon-python

Python bindings for developing add-ons for WebThings Gateway
Python
16
star
20

zwave-adapter

Z-Wave adapter add-on for WebThings Gateway
JavaScript
15
star
21

tplink-adapter

TP-Link Kasa smart plug/bulb adapter for WebThings Gateway
Python
15
star
22

gateway-addon-node

Node bindings for developing add-ons for WebThings Gateway
TypeScript
13
star
23

virtual-things-adapter

WebThings Gateway Virtual Things Adapter for experimenting with new thing types
JavaScript
12
star
24

onvif-adapter

ONVIF Profile S video camera adapter
JavaScript
10
star
25

voice-addon

Voice control add-on for WebThings Gateway
JavaScript
8
star
26

yeelight-adapter

Yeelight device adapter for WebThings Gateway
JavaScript
7
star
27

weather-adapter

Weather adapter for WebThings Gateway
JavaScript
7
star
28

lg-tv-adapter

LG webOS TV adapter for WebThings Gateway
JavaScript
7
star
29

serial-adapter

WebThings Gateway adapter for talking to serial-mcu based software through a serial port.
JavaScript
7
star
30

deconz-api

Talk to Zigbee devices using ConBee dongle or RaspBee HAT, modelled after xbee-api
JavaScript
7
star
31

gateway-deb

Debian package for running WebThings Gateway
Shell
6
star
32

things-controller

Things Controller
Java
6
star
33

roku-adapter

Roku adapter
JavaScript
6
star
34

mozgateway-alexa-skill

Alexa Skill to interact with Mozilla WebThings Gateway
Python
6
star
35

rpi-image-builder

Builds gate files needed to create a Raspberry Pi image
Shell
6
star
36

intent-parser

Intent Parser for the Mozilla WebThings Gateway
Python
5
star
37

schemas

A Web of Things schema repository
HTML
5
star
38

zigbee-zdo

Module for parsing and building Zigbee ZDO frames for use with xbee-api or deconz-api
JavaScript
5
star
39

android-app

A Web of Things client for Android
Kotlin
5
star
40

gpio-adapter

GPIO adapter add-on for WebThings Gateway
JavaScript
5
star
41

gateway-addon-ipc-schema

JSON-Schema for add-on IPC messages
Python
5
star
42

meross-adapter

Meross smart device adapter for WebThings Gateway
Python
4
star
43

webthing-tester

Web Thing test script
Python
4
star
44

tapo-adapter

TP-Link Tapo smart plug adapter for WebThings Gateway
Python
4
star
45

tunnelclient-rs

A Rust client library for the DNS/pagekite tunnel
Rust
4
star
46

node-mozilla-iot-gateway

gateway package for OpenWRT
Makefile
3
star
47

serial-mcu

MCU side code which talks with the serial-adapter
C++
3
star
48

registration-server-docker

Docker image for WebThingsIO/registration_server
Dockerfile
3
star
49

twilio-adapter

Simple adapter exposing the texting part of the Twilio API to the WebThings Gateway
JavaScript
3
star
50

sengled-adapter

Sengled Wi-Fi smart bulb adapter for WebThings Gateway
Python
3
star
51

wake-on-lan-adapter

Wake-on-LAN adapter for WebThings gateway.
JavaScript
3
star
52

email-sender-adapter

Simple SMTP-based email sending adapter for the WebThings Gateway
JavaScript
3
star
53

crateway

Rust
3
star
54

gateway-package-turris-omnia

WebThings gateway package for theTurris Omnia
Makefile
2
star
55

le-store-certbot

Mozilla IoT's fork of le-store-certbot
JavaScript
2
star
56

device-compat

Hardware compatibility data for WebThings Gateway
JavaScript
2
star
57

cli

Command line tools for working with things
Python
2
star
58

wot-adapter

Proxy adapter for W3C compliant WoT devices
TypeScript
2
star
59

gateway-ipc-types-rust

Rust
2
star
60

pulse-adapter

Adapter which can create pulse devices.
JavaScript
2
star
61

le-challenge-dns

Mozilla's iot fork of le-challenge-dns to issue certificates automatically
JavaScript
2
star
62

example-extension

Example extension add-on for WebThings Gateway
JavaScript
2
star
63

http-on-off-wifi101

Simple HTTP server which turns an LED on or off
C++
2
star
64

gotify-notifier

Simple notifier which uses a self-hosted Gotify server.
JavaScript
2
star
65

things-browser

Things Browser
1
star
66

webthingsio.github.io

HTML
1
star
67

webhook-events

JavaScript
1
star
68

scene-control-adapter

WebThings Gateway add-on to emulate scenes
JavaScript
1
star
69

earthquake-monitor-adapter

Earthquake monitor for WebThings Gateway
Python
1
star
70

tide-calendar-adapter

Tide calendar for WebThings Gateway
Python
1
star
71

mailchimp-proxy

Python
1
star
72

speed-test-adapter

Internet speed test adapter for WebThings Gateway
Python
1
star
73

gateway-package-docker

Docker images for creating the gateway .ipk files for OpenWRT
Dockerfile
1
star
74

example-notifier

Example notifier add-on for WebThings Gateway
JavaScript
1
star
75

eufy-adapter

Eufy smart plug/bulb adapter for WebThings Gateway
Python
1
star
76

etekcity-adapter

Etekcity smart plug/switch adapter for WebThings Gateway
Python
1
star
77

xctu-logdump

Parses an XCTU log file
JavaScript
1
star
78

gateway-aur

AUR package for running WebThings Gateway
Shell
1
star