diff options
Diffstat (limited to 'python-thingserver.spec')
| -rw-r--r-- | python-thingserver.spec | 686 |
1 files changed, 686 insertions, 0 deletions
diff --git a/python-thingserver.spec b/python-thingserver.spec new file mode 100644 index 0000000..b51eedd --- /dev/null +++ b/python-thingserver.spec @@ -0,0 +1,686 @@ +%global _empty_manifest_terminate_build 0 +Name: python-thingserver +Version: 0.2.1 +Release: 1 +Summary: HTTP Web Thing implementation +License: MPL-2.0 +URL: https://pypi.org/project/thingserver/ +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/ca/a2/bd310d3920dde3267092a6302bf6802c6b6d95985d087b6d60c16dbc07ea/thingserver-0.2.1.tar.gz +BuildArch: noarch + +Requires: python3-ifaddr +Requires: python3-pyee +Requires: python3-jsonschema +Requires: python3-tornado +Requires: python3-zeroconf + +%description +# Thing Server + +[](https://github.com/labthings/) +[](https://pypi.org/project/thingserver/) +[](https://github.com/psf/black) +[](https://riot.im/app/#/room/#labthings:matrix.org) + + +Implementation of an HTTP [Web Thing](https://iot.mozilla.org/wot/). +This library is compatible with Python 3.5+. + +## Installation + +`thingserver` can be installed via `pip`, as such: + +``` {.sourceCode .shell} +$ pip install thingserver +``` + +## Example Implementation + +In this code-walkthrough we will set up a dimmable light and a humidity +sensor (both using fake data, of course). + +### 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: + +``` {.sourceCode .python} +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. + +``` {.sourceCode .python} +light.add_property( + Property( + light, + 'on', + Value(True, None, lambda x: print(x)), + 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. + +``` {.sourceCode .python} +light.add_property( + Property( + light, + 'brightness', + Value(50, None, lambda x: print(x)), + 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: + +``` {.sourceCode .python} +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 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: + +``` {.sourceCode .python} +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. + +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. + +``` {.sourceCode .python} +sensor.add_property( + Property( + sensor, + 'level', + Value(None, self.read_from_gpio, None), + metadata={ + '@type': 'LevelProperty', + 'title': 'Humidity', + 'type': 'number', + 'description': 'The current humidity in %', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + 'readOnly': True, + })) +``` + +In this example, we pass a readproperty method that will read and return +the sensor value every time it is requested. + +Alternatively, we can create a thread that queries the physical sensor +every few seconds. We first remove the readproperty argument from our +Property. + +``` {.sourceCode .python} +sensor.add_property( + Property( + sensor, + 'level', + Value(0.0), + metadata={ + '@type': 'LevelProperty', + 'title': 'Humidity', + 'type': 'number', + 'description': 'The current humidity in %', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + 'readOnly': True, + })) +``` + +We then create our looping function to periodically query the sensor and +set the property value. + +``` {.sourceCode .python} +self.sensor_update_task = \ + get_event_loop().create_task(self.update_level()) + +async def update_level(self): + try: + while True: + await sleep(3) + sensor.properties["level"].value.set(self.read_from_gpio()) + logging.debug('setting new humidity level: %s', new_level) + except CancelledError: + pass +``` + +This will update our `Value` object with the sensor readings via the +`sensor.properties["level"].value.set(self.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](https://github.com/mozilla-iot/thing-url-adapter#readme). + + +%package -n python3-thingserver +Summary: HTTP Web Thing implementation +Provides: python-thingserver +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-thingserver +# Thing Server + +[](https://github.com/labthings/) +[](https://pypi.org/project/thingserver/) +[](https://github.com/psf/black) +[](https://riot.im/app/#/room/#labthings:matrix.org) + + +Implementation of an HTTP [Web Thing](https://iot.mozilla.org/wot/). +This library is compatible with Python 3.5+. + +## Installation + +`thingserver` can be installed via `pip`, as such: + +``` {.sourceCode .shell} +$ pip install thingserver +``` + +## Example Implementation + +In this code-walkthrough we will set up a dimmable light and a humidity +sensor (both using fake data, of course). + +### 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: + +``` {.sourceCode .python} +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. + +``` {.sourceCode .python} +light.add_property( + Property( + light, + 'on', + Value(True, None, lambda x: print(x)), + 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. + +``` {.sourceCode .python} +light.add_property( + Property( + light, + 'brightness', + Value(50, None, lambda x: print(x)), + 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: + +``` {.sourceCode .python} +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 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: + +``` {.sourceCode .python} +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. + +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. + +``` {.sourceCode .python} +sensor.add_property( + Property( + sensor, + 'level', + Value(None, self.read_from_gpio, None), + metadata={ + '@type': 'LevelProperty', + 'title': 'Humidity', + 'type': 'number', + 'description': 'The current humidity in %', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + 'readOnly': True, + })) +``` + +In this example, we pass a readproperty method that will read and return +the sensor value every time it is requested. + +Alternatively, we can create a thread that queries the physical sensor +every few seconds. We first remove the readproperty argument from our +Property. + +``` {.sourceCode .python} +sensor.add_property( + Property( + sensor, + 'level', + Value(0.0), + metadata={ + '@type': 'LevelProperty', + 'title': 'Humidity', + 'type': 'number', + 'description': 'The current humidity in %', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + 'readOnly': True, + })) +``` + +We then create our looping function to periodically query the sensor and +set the property value. + +``` {.sourceCode .python} +self.sensor_update_task = \ + get_event_loop().create_task(self.update_level()) + +async def update_level(self): + try: + while True: + await sleep(3) + sensor.properties["level"].value.set(self.read_from_gpio()) + logging.debug('setting new humidity level: %s', new_level) + except CancelledError: + pass +``` + +This will update our `Value` object with the sensor readings via the +`sensor.properties["level"].value.set(self.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](https://github.com/mozilla-iot/thing-url-adapter#readme). + + +%package help +Summary: Development documents and examples for thingserver +Provides: python3-thingserver-doc +%description help +# Thing Server + +[](https://github.com/labthings/) +[](https://pypi.org/project/thingserver/) +[](https://github.com/psf/black) +[](https://riot.im/app/#/room/#labthings:matrix.org) + + +Implementation of an HTTP [Web Thing](https://iot.mozilla.org/wot/). +This library is compatible with Python 3.5+. + +## Installation + +`thingserver` can be installed via `pip`, as such: + +``` {.sourceCode .shell} +$ pip install thingserver +``` + +## Example Implementation + +In this code-walkthrough we will set up a dimmable light and a humidity +sensor (both using fake data, of course). + +### 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: + +``` {.sourceCode .python} +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. + +``` {.sourceCode .python} +light.add_property( + Property( + light, + 'on', + Value(True, None, lambda x: print(x)), + 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. + +``` {.sourceCode .python} +light.add_property( + Property( + light, + 'brightness', + Value(50, None, lambda x: print(x)), + 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: + +``` {.sourceCode .python} +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 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: + +``` {.sourceCode .python} +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. + +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. + +``` {.sourceCode .python} +sensor.add_property( + Property( + sensor, + 'level', + Value(None, self.read_from_gpio, None), + metadata={ + '@type': 'LevelProperty', + 'title': 'Humidity', + 'type': 'number', + 'description': 'The current humidity in %', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + 'readOnly': True, + })) +``` + +In this example, we pass a readproperty method that will read and return +the sensor value every time it is requested. + +Alternatively, we can create a thread that queries the physical sensor +every few seconds. We first remove the readproperty argument from our +Property. + +``` {.sourceCode .python} +sensor.add_property( + Property( + sensor, + 'level', + Value(0.0), + metadata={ + '@type': 'LevelProperty', + 'title': 'Humidity', + 'type': 'number', + 'description': 'The current humidity in %', + 'minimum': 0, + 'maximum': 100, + 'unit': 'percent', + 'readOnly': True, + })) +``` + +We then create our looping function to periodically query the sensor and +set the property value. + +``` {.sourceCode .python} +self.sensor_update_task = \ + get_event_loop().create_task(self.update_level()) + +async def update_level(self): + try: + while True: + await sleep(3) + sensor.properties["level"].value.set(self.read_from_gpio()) + logging.debug('setting new humidity level: %s', new_level) + except CancelledError: + pass +``` + +This will update our `Value` object with the sensor readings via the +`sensor.properties["level"].value.set(self.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](https://github.com/mozilla-iot/thing-url-adapter#readme). + + +%prep +%autosetup -n thingserver-0.2.1 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-thingserver -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Thu Mar 09 2023 Python_Bot <Python_Bot@openeuler.org> - 0.2.1-1 +- Package Spec generated |