webthing


Namewebthing JSON
Version 0.5.3 PyPI version JSON
download
home_pagehttps://github.com/mozilla-iot/webthing-python
SummaryHTTP Web Thing implementation
upload_time2018-04-16 14:21:03
maintainer
docs_urlNone
authorMozilla IoT
requires_python>=3.4, <4
licenseMPL-2.0
keywords mozilla iot web thing webthing
VCS
bugtrack_url
requirements eventemitter jsonschema tornado zeroconf
Travis-CI No Travis.
coveralls test coverage No coveralls.
            webthing
========

Implementation of an HTTP `Web Thing <https://iot.mozilla.org/wot/>`_. This library is compatible with Python 3.4+.

Installation
============

``webthing`` can be installed via ``pip``, as such:

.. code:: shell

  $ pip install webthing

Example
=======

In this example we will set up a dimmable light and a humidity sensor (both using fake data, of course). Both working examples can be found in `here <https://github.com/mozilla-iot/webthing-java/tree/master/src/main/java/org/mozilla/iot/webthing/example>`_.

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 `dimmableLight` 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.

* ``level``: 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:

.. code:: python

    light = Thing('My Lamp', 'dimmableLight', '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 how to turn the light on/off. For our purposes, we just want to log the new state if the light is switched on/off.

.. code:: python

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

The ``level`` 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 to std::out.

.. code:: python

  light.add_property(
      Property(
          light,
          'level',
          Value(0.0, lambda l: print('New light level is', l)),
          metadata={
              'type': 'number',
              'description': 'The level of light from 0-100',
              'minimum': 0,
              'maximum': 100,
          }))

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

.. code:: python

  # If adding more than one thing here, be sure to set the second
  # parameter to some string, which will be broadcast via mDNS.
  # In the single thing case, the thing's name will be broadcast.
  server = WebThingServer([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 can also return a level instead of just true/false) has two required properties (besides the name, type, and  optional description): ``on`` and ``level``. We want to monitor those properties and get notified if the value changes.

First we create a new Thing:

.. code:: python

  sensor = Thing('My Humidity Sensor',
                 'multiLevelSensor',
                 'A web connected humidity sensor')

Then we create and add the appropriate properties:

* ``on``: tells us whether the sensor is on (i.e. high), or off (i.e. low)

  .. code:: python

    sensor.add_property(
        Property(
            sensor,
            'on',
            Value(True),
            metadata={
                'type': 'boolean',
                'description': 'Whether the sensor is on',
            }))

* ``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 utilizing a **read-only** Value by omitting the ``value_forwarder`` parameter.

    .. code:: python

      level = Value(0.0);

      sensor.add_property(
          Property(
              sensor,
              'level',
              level,
              metadata={
                  'type': 'number',
                  'description': 'The current humidity in %',
                  'unit': '%',
              }))

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.

.. code:: python

  ioloop = tornado.ioloop.IOLoop.current()

  def update_level():
      while True:
          time.sleep(3)

          # Update the underlying value, which in turn notifies all listeners
          ioloop.add_callback(level.notify_of_external_update,
                              read_from_gpio())

  t = threading.Thread(target=update_level)
  t.daemon = True
  t.start()

This will update our ``Value`` object with the sensor readings via the ``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.



            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": ">=3.4, <4", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "mozilla iot web thing webthing", 
    "upload_time": "2018-04-16 14:21:03", 
    "requirements": [
        {
            "name": "eventemitter", 
            "specs": []
        }, 
        {
            "name": "jsonschema", 
            "specs": []
        }, 
        {
            "name": "tornado", 
            "specs": []
        }, 
        {
            "name": "zeroconf", 
            "specs": []
        }
    ], 
    "author": "Mozilla IoT", 
    "home_page": "https://github.com/mozilla-iot/webthing-python", 
    "github_user": "mozilla-iot", 
    "download_url": "https://pypi.python.org/packages/6f/d5/568fc0d2d84bd504c9d53ce70ac1f91f74b2906e73fa67c35da378d0f6ed/webthing-0.5.3.tar.gz", 
    "platform": "", 
    "version": "0.5.3", 
    "cheesecake_documentation_id": null, 
    "description": "webthing\n========\n\nImplementation of an HTTP `Web Thing <https://iot.mozilla.org/wot/>`_. This library is compatible with Python 3.4+.\n\nInstallation\n============\n\n``webthing`` can be installed via ``pip``, as such:\n\n.. code:: shell\n\n  $ pip install webthing\n\nExample\n=======\n\nIn this example we will set up a dimmable light and a humidity sensor (both using fake data, of course). Both working examples can be found in `here <https://github.com/mozilla-iot/webthing-java/tree/master/src/main/java/org/mozilla/iot/webthing/example>`_.\n\nDimmable Light\n--------------\n\nImagine 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 `dimmableLight` is required to expose two properties:\n\n* ``on``: the state of the light, whether it is turned on or off\n\n  - Setting this property via a ``PUT {\"on\": true/false}`` call to the REST API toggles the light.\n\n* ``level``: the brightness level of the light from 0-100%\n\n  - Setting this property via a PUT call to the REST API sets the brightness level of this light.\n\nFirst we create a new Thing:\n\n.. code:: python\n\n    light = Thing('My Lamp', 'dimmableLight', 'A web connected lamp')\n\nNow we can add the required properties.\n\nThe ``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 how to turn the light on/off. For our purposes, we just want to log the new state if the light is switched on/off.\n\n.. code:: python\n\n  light.add_property(\n      Property(\n          light,\n          'on',\n          Value(True, lambda v: print('On-State is now', v)),\n          metadata={\n              'type': 'boolean',\n              'description': 'Whether the lamp is turned on',\n          }))\n\nThe ``level`` 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 to std::out.\n\n.. code:: python\n\n  light.add_property(\n      Property(\n          light,\n          'level',\n          Value(0.0, lambda l: print('New light level is', l)),\n          metadata={\n              'type': 'number',\n              'description': 'The level of light from 0-100',\n              'minimum': 0,\n              'maximum': 100,\n          }))\n\nNow we can add our newly created thing to the server and start it:\n\n.. code:: python\n\n  # If adding more than one thing here, be sure to set the second\n  # parameter to some string, which will be broadcast via mDNS.\n  # In the single thing case, the thing's name will be broadcast.\n  server = WebThingServer([light], port=8888)\n\n  try:\n      server.start()\n  except KeyboardInterrupt:\n      server.stop()\n\nThis 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.\n\nSensor\n------\n\nLet's now also connect a humidity sensor to the server we set up for our light.\n\nA ``multiLevelSensor`` (a sensor that can also return a level instead of just true/false) has two required properties (besides the name, type, and  optional description): ``on`` and ``level``. We want to monitor those properties and get notified if the value changes.\n\nFirst we create a new Thing:\n\n.. code:: python\n\n  sensor = Thing('My Humidity Sensor',\n                 'multiLevelSensor',\n                 'A web connected humidity sensor')\n\nThen we create and add the appropriate properties:\n\n* ``on``: tells us whether the sensor is on (i.e. high), or off (i.e. low)\n\n  .. code:: python\n\n    sensor.add_property(\n        Property(\n            sensor,\n            'on',\n            Value(True),\n            metadata={\n                'type': 'boolean',\n                'description': 'Whether the sensor is on',\n            }))\n\n* ``level``: tells us what the sensor is actually reading\n\n  - 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 utilizing a **read-only** Value by omitting the ``value_forwarder`` parameter.\n\n    .. code:: python\n\n      level = Value(0.0);\n\n      sensor.add_property(\n          Property(\n              sensor,\n              'level',\n              level,\n              metadata={\n                  'type': 'number',\n                  'description': 'The current humidity in %',\n                  'unit': '%',\n              }))\n\nNow 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.\n\n.. code:: python\n\n  ioloop = tornado.ioloop.IOLoop.current()\n\n  def update_level():\n      while True:\n          time.sleep(3)\n\n          # Update the underlying value, which in turn notifies all listeners\n          ioloop.add_callback(level.notify_of_external_update,\n                              read_from_gpio())\n\n  t = threading.Thread(target=update_level)\n  t.daemon = True\n  t.start()\n\nThis will update our ``Value`` object with the sensor readings via the ``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.\n\n\n", 
    "lcname": "webthing", 
    "bugtrack_url": null, 
    "github": true, 
    "coveralls": false, 
    "name": "webthing", 
    "license": "MPL-2.0", 
    "travis_ci": false, 
    "github_project": "webthing-python", 
    "summary": "HTTP Web Thing implementation", 
    "split_keywords": [
        "mozilla", 
        "iot", 
        "web", 
        "thing", 
        "webthing"
    ], 
    "author_email": "iot@mozilla.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2018-04-16T14:21:01", 
            "comment_text": "", 
            "python_version": "py3", 
            "url": "https://pypi.python.org/packages/00/07/fae07d8346f69fe773aabe882d322dacbcceda6a01749481d83c85cc82c3/webthing-0.5.3-py3-none-any.whl", 
            "md5_digest": "da402f414289e5b3d19c0b13c4fc7c87", 
            "downloads": 0, 
            "filename": "webthing-0.5.3-py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "00/07/fae07d8346f69fe773aabe882d322dacbcceda6a01749481d83c85cc82c3/webthing-0.5.3-py3-none-any.whl", 
            "digests": {
                "sha256": "167ce0673df61e513186c48d5539bf23504816b0d0da61dd2ee2bc4dbf1a5ed9", 
                "md5": "da402f414289e5b3d19c0b13c4fc7c87"
            }, 
            "sha256_digest": "167ce0673df61e513186c48d5539bf23504816b0d0da61dd2ee2bc4dbf1a5ed9", 
            "size": 15802
        }, 
        {
            "has_sig": false, 
            "upload_time": "2018-04-16T14:21:03", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/6f/d5/568fc0d2d84bd504c9d53ce70ac1f91f74b2906e73fa67c35da378d0f6ed/webthing-0.5.3.tar.gz", 
            "md5_digest": "f8cb7edbeb6b3386c123e8aae52cf866", 
            "downloads": 0, 
            "filename": "webthing-0.5.3.tar.gz", 
            "packagetype": "sdist", 
            "path": "6f/d5/568fc0d2d84bd504c9d53ce70ac1f91f74b2906e73fa67c35da378d0f6ed/webthing-0.5.3.tar.gz", 
            "digests": {
                "sha256": "6b0d31b731a842affd358d2cf57a7a4dbc0b264cf973496a534918730c771164", 
                "md5": "f8cb7edbeb6b3386c123e8aae52cf866"
            }, 
            "sha256_digest": "6b0d31b731a842affd358d2cf57a7a4dbc0b264cf973496a534918730c771164", 
            "size": 16000
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}