# hololinked - Pythonic Object-Oriented Supervisory Control & Data Acquisition / Internet of Things
### Description
`hololinked` is a beginner-friendly server side pythonic tool suited for instrumentation control and data acquisition over network, especially with HTTP. If you have a requirement to control and capture data from your hardware/instrumentation, show the data in a browser/dashboard, provide a GUI or run automated scripts, `hololinked` can help. Even for isolated applications or a small lab setup without networking concepts, one can still separate the concerns of the tools that interact with the hardware & the hardware itself.
For those that understand, this package is a ZMQ/HTTP-RPC.
[](https://hololinked.readthedocs.io/en/latest/?badge=latest) [](https://pypi.org/project/hololinked/) [](https://anaconda.org/conda-forge/hololinked)
[](https://codecov.io/gh/VigneshVSV/hololinked)
<br>
[](mailto:vignesh.vaidyanathan@hololinked.dev) [](https://hololinked.dev/contact)
<br>
[](https://pypistats.org/packages/hololinked)
[](https://anaconda.org/conda-forge/hololinked)
### To Install
From pip - ``pip install hololinked``
From conda - `conda install -c conda-forge hololinked`
Or, clone the repository (main branch for latest codebase) and install `pip install .` / `pip install -e .`. The conda env ``hololinked.yml`` can also help to setup all dependencies.
### Usage/Quickstart
`hololinked` is compatible with the [Web of Things](https://www.w3.org/WoT/) recommended pattern for developing hardware/instrumentation control software.
Each device or thing can be controlled systematically when their design in software is segregated into properties, actions and events. In object oriented terms:
- the hardware is (generally) represented by a class
- properties are validated get-set attributes of the class which may be used to model settings, hold captured/computed data or generic network accessible quantities
- actions are methods which issue commands like connect/disconnect, execute a control routine, start/stop measurement, or run arbitray python logic
- events can asynchronously communicate/push (arbitrary) data to a client (say, a GUI), like alarm messages, streaming measured quantities etc.
In this package, the base class which enables this classification is the `Thing` class. Any class that inherits the `Thing` class
can instantiate properties, actions and events which become visible to a client in this segragated manner. For example, consider an optical spectrometer, the following code is possible:
> This is a fairly mid-level intro focussed on HTTP. If you are beginner or looking for ZMQ which can be used with no networking knowledge, check [How-To](https://hololinked.readthedocs.io/en/latest/howto/index.html)
#### Import Statements
```python
from hololinked.server import Thing, Property, action, Event
from hololinked.server.properties import String, Integer, Number, List
from seabreeze.spectrometers import Spectrometer # device driver
```
#### Definition of one's own hardware controlling class
subclass from Thing class to "make a network accessible Thing":
```python
class OceanOpticsSpectrometer(Thing):
"""
OceanOptics spectrometers using seabreeze library. Device is identified by serial number.
"""
```
#### Instantiating properties
Say, we wish to make device serial number, integration time and the captured intensity as properties. There are certain predefined properties available like `String`, `Number`, `Boolean` etc.
or one may define one's own. To create properties:
```python
class OceanOpticsSpectrometer(Thing):
"""class doc"""
serial_number = String(default=None, allow_None=True, URL_path='/serial-number',
doc="serial number of the spectrometer to connect/or connected",
http_method=("GET", "PUT"))
# GET and PUT is default for reading and writing the property respectively.
# So you can leave it out, especially if you are going to use ZMQ and dont understand HTTP
integration_time = Number(default=1000, bounds=(0.001, None), crop_to_bounds=True,
URL_path='/integration-time',
doc="integration time of measurement in milliseconds")
intensity = List(default=None, allow_None=True,
doc="captured intensity", readonly=True,
fget=lambda self: self._intensity)
def __init__(self, instance_name, serial_number, **kwargs):
super().__init__(instance_name=instance_name, serial_number=serial_number, **kwargs)
```
> There is an ongoing work to remove HTTP API from the property API and completely move them to the HTTP server
In non-expert terms, properties look like class attributes however their data containers are instantiated at object instance level by default.
For example, the `integration_time` property defined above as `Number`, whenever set/written, will be validated as a float or int, cropped to bounds and assigned as an attribute to each instance of the `OceanOpticsSpectrometer` class with an internally generated name. It is not necessary to know this internally generated name as the property value can be accessed again in any python logic, say, `print(self.integration_time)`.
To overload the get-set (or read-write) of properties, one may do the following:
```python
class OceanOpticsSpectrometer(Thing):
integration_time = Number(default=1000, bounds=(0.001, None), crop_to_bounds=True,
URL_path='/integration-time',
doc="integration time of measurement in milliseconds")
@integration_time.setter # by default called on http PUT method
def apply_integration_time(self, value : float):
self.device.integration_time_micros(int(value*1000))
self._integration_time = int(value)
@integration_time.getter # by default called on http GET method
def get_integration_time(self) -> float:
try:
return self._integration_time
except AttributeError:
return self.properties["integration_time"].default
```
In this case, instead of generating a data container with an internal name, the setter method is called when `integration_time` property is set/written. One might add the hardware device driver logic here (say, supplied by the manufacturer) or a protocol that talks directly to the device to apply the property onto the device. In the above example, there is not a way provided by the device driver library to read the value from the device, so we store it in a variable after applying it and supply the variable back to the getter method. Normally, one would also want the getter to read from the device directly.
Those familiar with Web of Things (WoT) terminology may note that these properties generate the property affordance. An example for `integration_time` is as follows:
```JSON
"integration_time": {
"title": "integration_time",
"description": "integration time of measurement in milliseconds",
"type": "number",
"forms": [{
"href": "https://example.com/spectrometer/integration-time",
"op": "readproperty",
"htv:methodName": "GET",
"contentType": "application/json"
},{
"href": "https://example.com/spectrometer/integration-time",
"op": "writeproperty",
"htv:methodName": "PUT",
"contentType": "application/json"
}
],
"minimum": 0.001
},
```
If you are <span style="text-decoration: underline">not familiar</span> with Web of Things or the term "property affordance", consider the above JSON as a description of
what the property represents and how to interact with it from somewhere else. Such a JSON is both human-readable, yet consumable by any application that may use the property, say a client provider to create a client object to interact with the property or a GUI application to autogenerate a suitable input field for this property.
For example, the Eclipse ThingWeb [node-wot](https://github.com/eclipse-thingweb/node-wot) supports this feature to produce a HTTP(s) client that can issue `readProperty("integration_time")` and `writeProperty("integration_time", 1000)` to read and write this property.
The URL path segment `../spectrometer/..` in href field is taken from the `instance_name` which was specified in the `__init__`.
This is a mandatory key word argument to the parent class `Thing` to generate a unique name/id for the instance. One should use URI compatible strings.
#### Specify methods as actions
decorate with `action` decorator on a python method to claim it as a network accessible method:
```python
class OceanOpticsSpectrometer(Thing):
@action(URL_path='/connect', http_method="POST") # POST is default for actions
def connect(self, serial_number = None):
"""connect to spectrometer with given serial number"""
if serial_number is not None:
self.serial_number = serial_number
self.device = Spectrometer.from_serial_number(self.serial_number)
self._wavelengths = self.device.wavelengths().tolist()
# So you can leave it out, especially if you are going to use ZMQ and dont understand HTTP
@action()
def disconnect(self):
"""disconnect from the spectrometer"""
self.device.close()
```
Methods that are neither decorated with action decorator nor acting as getters-setters of properties remain as plain python methods and are **not** accessible on the network.
In WoT Terminology, again, such a method becomes specified as an action affordance (or a description of what the action represents
and how to interact with it):
```JSON
"connect": {
"title": "connect",
"description": "connect to spectrometer with given serial number",
"forms": [
{
"href": "https://example.com/spectrometer/connect",
"op": "invokeaction",
"htv:methodName": "POST",
"contentType": "application/json"
}
],
"input": {
"type": "object",
"properties": {
"serial_number": {
"type": "string"
}
},
"additionalProperties": false
}
},
```
> input and output schema ("input" field above which describes the argument type `serial_number`) are optional and will be discussed in docs
#### Defining and pushing events
create a named event using `Event` object that can push any arbitrary data:
```python
class OceanOpticsSpectrometer(Thing):
# only GET HTTP method possible for events
intensity_measurement_event = Event(name='intensity-measurement-event',
URL_path='/intensity/measurement-event',
doc="""event generated on measurement of intensity,
max 30 per second even if measurement is faster.""",
schema=intensity_event_schema)
# schema is optional and will be discussed later,
# assume the intensity_event_schema variable is valid
def capture(self): # not an action, but a plain python method
self._run = True
last_time = time.time()
while self._run:
self._intensity = self.device.intensities(
correct_dark_counts=False,
correct_nonlinearity=False
)
curtime = datetime.datetime.now()
measurement_timestamp = curtime.strftime('%d.%m.%Y %H:%M:%S.') + '{:03d}'.format(
int(curtime.microsecond /1000))
if time.time() - last_time > 0.033: # restrict speed to avoid overloading
self.intensity_measurement_event.push({
"timestamp" : measurement_timestamp,
"value" : self._intensity.tolist()
})
last_time = time.time()
@action(URL_path='/acquisition/start', http_method="POST")
def start_acquisition(self):
if self._acquisition_thread is not None and self._acquisition_thread.is_alive():
return
self._acquisition_thread = threading.Thread(target=self.capture)
self._acquisition_thread.start()
@action(URL_path='/acquisition/stop', http_method="POST")
def stop_acquisition(self):
self._run = False
```
Events can stream live data without polling or push data to a client whose generation in time is uncontrollable.
In WoT Terminology, such an event becomes specified as an event affordance (or a description of
what the event represents and how to subscribe to it) with subprotocol SSE (HTTP-SSE):
```JSON
"intensity_measurement_event": {
"title": "intensity-measurement-event",
"description": "event generated on measurement of intensity, max 30 per second even if measurement is faster.",
"forms": [
{
"href": "https://example.com/spectrometer/intensity/measurement-event",
"subprotocol": "sse",
"op": "subscribeevent",
"htv:methodName": "GET",
"contentType": "text/plain"
}
],
"data": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"type": "number"
}
},
"timestamp": {
"type": "string"
}
}
}
}
```
> data schema ("data" field above which describes the event payload) are optional and discussed later
Events follow a pub-sub model with '1 publisher to N subscribers' per `Event` object, both through ZMQ and HTTP SSE.
To start the Thing, a configurable HTTP Server is already available (from `hololinked.server.HTTPServer`) which redirects HTTP requests to the object:
```python
import ssl, os, logging
from multiprocessing import Process
from hololinked.server import HTTPServer
if __name__ == '__main__':
ssl_context = ssl.SSLContext(protocol = ssl.PROTOCOL_TLS)
ssl_context.load_cert_chain(f'assets{os.sep}security{os.sep}certificate.pem',
keyfile = f'assets{os.sep}security{os.sep}key.pem')
O = OceanOpticsSpectrometer(
instance_name='spectrometer',
serial_number='S14155',
log_level=logging.DEBUG
)
O.run_with_http_server(ssl_context=ssl_context)
# or O.run(zmq_protocols='IPC') - interprocess communication and no HTTP
# or O.run(zmq_protocols=['IPC', 'TCP'], tcp_socket_address='tcp://*:9999')
# both interprocess communication & TCP, no HTTP
```
> There is an ongoing work to remove HTTP API from the API of all of properties, actions and events and completely move them to the HTTP server for a more accurate syntax. The functionality will not change though.
Here one can see the use of `instance_name` and why it turns up in the URL path. See the detailed example of the above code [here](https://gitlab.com/hololinked-examples/oceanoptics-spectrometer/-/blob/simple/oceanoptics_spectrometer/device.py?ref_type=heads).
##### NOTE - The package is under active development. Contributors welcome, please check CONTRIBUTING.md and the open issues. Some issues can also be independently dealt without much knowledge of this package.
- [example repository](https://github.com/VigneshVSV/hololinked-examples) - detailed examples for both clients and servers
- [helper GUI](https://github.com/VigneshVSV/thing-control-panel) - view & interact with your object's actions, properties and events.
See a list of currently supported possibilities while using this package [below](#currently-supported).
> You may use a script deployment/automation tool to remote stop and start servers, in an attempt to remotely control your hardware scripts.
### Looking for sponsorships
Kindly read my message [in my README](https://github.com/VigneshVSV#sponsor)
### A little more about Usage
One may use the HTTP API according to one's beliefs (including letting the package auto-generate it), but it is mainly intended for web development and cross platform clients
like the interoperable [node-wot](https://github.com/eclipse-thingweb/node-wot) HTTP(s) client. If your plan is to develop a truly networked system, it is recommended to learn more and
se [Thing Descriptions](https://www.w3.org/TR/wot-thing-description11) to describe your hardware. A Thing Description will be automatically generated if absent as shown in JSON examples above or can be supplied manually. The default end point to
fetch thing descriptions are: <br> `http(s)://<host name>/<instance name of the thing>/resources/wot-td`
If there are errors in generation of Thing Description
(mostly due to JSON non-complaint types), one could use: <br> `http(s)://<host name>/<instance name of the thing>/resources/wot-td?ignore_errors=true`
(client docs will be updated here next)
### Currently Supported
- control method execution and property write with a custom finite state machine.
- database (Postgres, MySQL, SQLite - based on SQLAlchemy) support for storing and loading properties when the object dies and restarts.
- auto-generate Thing Description for Web of Things applications.
- use serializer of your choice (except for HTTP) - MessagePack, JSON, pickle etc. & extend serialization to suit your requirement. HTTP Server will support only JSON serializer to maintain comptibility with Javascript (MessagePack may be added later). Default is JSON serializer based on msgspec.
- asyncio compatible - async RPC server event-loop and async HTTP Server - write methods in async
- choose from multiple ZeroMQ transport methods which offers some possibilities like the following without changing the code:
- expose only a dashboard or web page on the network without exposing the hardware itself
- run direct ZMQ-TCP server without HTTP details
- serve multiple objects with the same HTTP server, run HTTP Server & python object in separate processes or the same process
Again, please check examples or the code for explanations. Documentation is being activety improved.
### Currently being worked
- unit tests coverage
- separation of HTTP protocol specification like URL path and HTTP verbs from the API of properties, actions and events and move their customization completely to the HTTP server
- serve multiple things with the same server (unfortunately due to a small oversight it is currently somewhat difficult for end user to serve multiple things with the same server, although its possible. This will be fixed.)
- improving accuracy of Thing Descriptions
- cookie credentials for authentication - as a workaround until credentials are supported, use `allowed_clients` argument on HTTP server which restricts access based on remote IP supplied with the HTTP headers. This wont still help you in public networks or modified/non-standard HTTP clients.
Raw data
{
"_id": null,
"home_page": "https://hololinked.readthedocs.io/en/latest/index.html",
"name": "hololinked",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "data-acquisition, zmq-rpc, SCADA/IoT, Web of Things",
"author": "Vignesh Vaidyanathan",
"author_email": "vignesh.vaidyanathan@hololinked.dev",
"download_url": "https://files.pythonhosted.org/packages/96/16/8e3133899d8f54f226ee6b148d4addafd2ae1f2d7e5c2ecc0ba4da273276/hololinked-0.2.7.tar.gz",
"platform": null,
"description": "# hololinked - Pythonic Object-Oriented Supervisory Control & Data Acquisition / Internet of Things\n\n### Description\n\n`hololinked` is a beginner-friendly server side pythonic tool suited for instrumentation control and data acquisition over network, especially with HTTP. If you have a requirement to control and capture data from your hardware/instrumentation, show the data in a browser/dashboard, provide a GUI or run automated scripts, `hololinked` can help. Even for isolated applications or a small lab setup without networking concepts, one can still separate the concerns of the tools that interact with the hardware & the hardware itself.\n\nFor those that understand, this package is a ZMQ/HTTP-RPC.\n \n[](https://hololinked.readthedocs.io/en/latest/?badge=latest) [](https://pypi.org/project/hololinked/) [](https://anaconda.org/conda-forge/hololinked)\n[](https://codecov.io/gh/VigneshVSV/hololinked) \n<br>\n[](mailto:vignesh.vaidyanathan@hololinked.dev) [](https://hololinked.dev/contact)\n<br>\n[](https://pypistats.org/packages/hololinked)\n[](https://anaconda.org/conda-forge/hololinked)\n\n### To Install\n\nFrom pip - ``pip install hololinked`` \nFrom conda - `conda install -c conda-forge hololinked`\n\nOr, clone the repository (main branch for latest codebase) and install `pip install .` / `pip install -e .`. The conda env ``hololinked.yml`` can also help to setup all dependencies. \n\n### Usage/Quickstart\n\n`hololinked` is compatible with the [Web of Things](https://www.w3.org/WoT/) recommended pattern for developing hardware/instrumentation control software. \nEach device or thing can be controlled systematically when their design in software is segregated into properties, actions and events. In object oriented terms:\n- the hardware is (generally) represented by a class \n- properties are validated get-set attributes of the class which may be used to model settings, hold captured/computed data or generic network accessible quantities\n- actions are methods which issue commands like connect/disconnect, execute a control routine, start/stop measurement, or run arbitray python logic\n- events can asynchronously communicate/push (arbitrary) data to a client (say, a GUI), like alarm messages, streaming measured quantities etc.\n\nIn this package, the base class which enables this classification is the `Thing` class. Any class that inherits the `Thing` class \ncan instantiate properties, actions and events which become visible to a client in this segragated manner. For example, consider an optical spectrometer, the following code is possible:\n\n> This is a fairly mid-level intro focussed on HTTP. If you are beginner or looking for ZMQ which can be used with no networking knowledge, check [How-To](https://hololinked.readthedocs.io/en/latest/howto/index.html)\n\n#### Import Statements\n\n```python\n\nfrom hololinked.server import Thing, Property, action, Event\nfrom hololinked.server.properties import String, Integer, Number, List\nfrom seabreeze.spectrometers import Spectrometer # device driver\n```\n\n#### Definition of one's own hardware controlling class\n\nsubclass from Thing class to \"make a network accessible Thing\":\n\n```python \nclass OceanOpticsSpectrometer(Thing):\n \"\"\"\n OceanOptics spectrometers using seabreeze library. Device is identified by serial number. \n \"\"\"\n \n```\n\n#### Instantiating properties\n\nSay, we wish to make device serial number, integration time and the captured intensity as properties. There are certain predefined properties available like `String`, `Number`, `Boolean` etc. \nor one may define one's own. To create properties:\n\n```python\n\nclass OceanOpticsSpectrometer(Thing):\n \"\"\"class doc\"\"\"\n \n serial_number = String(default=None, allow_None=True, URL_path='/serial-number', \n doc=\"serial number of the spectrometer to connect/or connected\",\n http_method=(\"GET\", \"PUT\"))\n # GET and PUT is default for reading and writing the property respectively.\n # So you can leave it out, especially if you are going to use ZMQ and dont understand HTTP\n\n integration_time = Number(default=1000, bounds=(0.001, None), crop_to_bounds=True, \n URL_path='/integration-time', \n doc=\"integration time of measurement in milliseconds\")\n\n intensity = List(default=None, allow_None=True, \n doc=\"captured intensity\", readonly=True, \n fget=lambda self: self._intensity) \n\n def __init__(self, instance_name, serial_number, **kwargs):\n super().__init__(instance_name=instance_name, serial_number=serial_number, **kwargs)\n\n```\n> There is an ongoing work to remove HTTP API from the property API and completely move them to the HTTP server\n\nIn non-expert terms, properties look like class attributes however their data containers are instantiated at object instance level by default.\nFor example, the `integration_time` property defined above as `Number`, whenever set/written, will be validated as a float or int, cropped to bounds and assigned as an attribute to each instance of the `OceanOpticsSpectrometer` class with an internally generated name. It is not necessary to know this internally generated name as the property value can be accessed again in any python logic, say, `print(self.integration_time)`. \n\nTo overload the get-set (or read-write) of properties, one may do the following:\n```python\nclass OceanOpticsSpectrometer(Thing):\n\n integration_time = Number(default=1000, bounds=(0.001, None), crop_to_bounds=True, \n URL_path='/integration-time', \n doc=\"integration time of measurement in milliseconds\")\n\n @integration_time.setter # by default called on http PUT method\n def apply_integration_time(self, value : float):\n self.device.integration_time_micros(int(value*1000))\n self._integration_time = int(value) \n \n @integration_time.getter # by default called on http GET method\n def get_integration_time(self) -> float:\n try:\n return self._integration_time\n except AttributeError:\n return self.properties[\"integration_time\"].default \n\n```\n\nIn this case, instead of generating a data container with an internal name, the setter method is called when `integration_time` property is set/written. One might add the hardware device driver logic here (say, supplied by the manufacturer) or a protocol that talks directly to the device to apply the property onto the device. In the above example, there is not a way provided by the device driver library to read the value from the device, so we store it in a variable after applying it and supply the variable back to the getter method. Normally, one would also want the getter to read from the device directly.\n \nThose familiar with Web of Things (WoT) terminology may note that these properties generate the property affordance. An example for `integration_time` is as follows:\n\n```JSON\n\"integration_time\": {\n \"title\": \"integration_time\",\n \"description\": \"integration time of measurement in milliseconds\",\n \"type\": \"number\",\n \"forms\": [{\n \"href\": \"https://example.com/spectrometer/integration-time\",\n \"op\": \"readproperty\",\n \"htv:methodName\": \"GET\",\n \"contentType\": \"application/json\"\n },{\n \"href\": \"https://example.com/spectrometer/integration-time\",\n \"op\": \"writeproperty\",\n \"htv:methodName\": \"PUT\",\n \"contentType\": \"application/json\"\n }\n ],\n \"minimum\": 0.001\n},\n```\nIf you are <span style=\"text-decoration: underline\">not familiar</span> with Web of Things or the term \"property affordance\", consider the above JSON as a description of \nwhat the property represents and how to interact with it from somewhere else. Such a JSON is both human-readable, yet consumable by any application that may use the property, say a client provider to create a client object to interact with the property or a GUI application to autogenerate a suitable input field for this property. \nFor example, the Eclipse ThingWeb [node-wot](https://github.com/eclipse-thingweb/node-wot) supports this feature to produce a HTTP(s) client that can issue `readProperty(\"integration_time\")` and `writeProperty(\"integration_time\", 1000)` to read and write this property.\n\nThe URL path segment `../spectrometer/..` in href field is taken from the `instance_name` which was specified in the `__init__`. \nThis is a mandatory key word argument to the parent class `Thing` to generate a unique name/id for the instance. One should use URI compatible strings.\n\n#### Specify methods as actions\n\ndecorate with `action` decorator on a python method to claim it as a network accessible method:\n\n```python\n\nclass OceanOpticsSpectrometer(Thing):\n\n @action(URL_path='/connect', http_method=\"POST\") # POST is default for actions\n def connect(self, serial_number = None):\n \"\"\"connect to spectrometer with given serial number\"\"\"\n if serial_number is not None:\n self.serial_number = serial_number\n self.device = Spectrometer.from_serial_number(self.serial_number)\n self._wavelengths = self.device.wavelengths().tolist()\n\n # So you can leave it out, especially if you are going to use ZMQ and dont understand HTTP\n @action()\n def disconnect(self):\n \"\"\"disconnect from the spectrometer\"\"\"\n self.device.close()\n \n```\n\nMethods that are neither decorated with action decorator nor acting as getters-setters of properties remain as plain python methods and are **not** accessible on the network.\n\nIn WoT Terminology, again, such a method becomes specified as an action affordance (or a description of what the action represents\nand how to interact with it):\n\n```JSON\n\"connect\": {\n \"title\": \"connect\",\n \"description\": \"connect to spectrometer with given serial number\",\n \"forms\": [\n {\n \"href\": \"https://example.com/spectrometer/connect\",\n \"op\": \"invokeaction\",\n \"htv:methodName\": \"POST\",\n \"contentType\": \"application/json\"\n }\n ],\n \"input\": {\n \"type\": \"object\",\n \"properties\": {\n \"serial_number\": {\n \"type\": \"string\"\n }\n },\n \"additionalProperties\": false\n }\n},\n```\n> input and output schema (\"input\" field above which describes the argument type `serial_number`) are optional and will be discussed in docs\n\n#### Defining and pushing events\n\ncreate a named event using `Event` object that can push any arbitrary data:\n\n```python\nclass OceanOpticsSpectrometer(Thing):\n\n # only GET HTTP method possible for events\n intensity_measurement_event = Event(name='intensity-measurement-event', \n URL_path='/intensity/measurement-event',\n doc=\"\"\"event generated on measurement of intensity, \n max 30 per second even if measurement is faster.\"\"\",\n schema=intensity_event_schema) \n # schema is optional and will be discussed later,\n # assume the intensity_event_schema variable is valid\n \n def capture(self): # not an action, but a plain python method\n self._run = True \n last_time = time.time()\n while self._run:\n self._intensity = self.device.intensities(\n correct_dark_counts=False,\n correct_nonlinearity=False\n )\n curtime = datetime.datetime.now()\n measurement_timestamp = curtime.strftime('%d.%m.%Y %H:%M:%S.') + '{:03d}'.format(\n int(curtime.microsecond /1000))\n if time.time() - last_time > 0.033: # restrict speed to avoid overloading\n self.intensity_measurement_event.push({\n \"timestamp\" : measurement_timestamp, \n \"value\" : self._intensity.tolist()\n })\n last_time = time.time()\n\n @action(URL_path='/acquisition/start', http_method=\"POST\")\n def start_acquisition(self):\n if self._acquisition_thread is not None and self._acquisition_thread.is_alive():\n return\n self._acquisition_thread = threading.Thread(target=self.capture) \n self._acquisition_thread.start()\n\n @action(URL_path='/acquisition/stop', http_method=\"POST\")\n def stop_acquisition(self):\n self._run = False \n```\nEvents can stream live data without polling or push data to a client whose generation in time is uncontrollable. \n\nIn WoT Terminology, such an event becomes specified as an event affordance (or a description of \nwhat the event represents and how to subscribe to it) with subprotocol SSE (HTTP-SSE):\n\n```JSON\n\"intensity_measurement_event\": {\n \"title\": \"intensity-measurement-event\",\n \"description\": \"event generated on measurement of intensity, max 30 per second even if measurement is faster.\",\n \"forms\": [\n {\n \"href\": \"https://example.com/spectrometer/intensity/measurement-event\",\n \"subprotocol\": \"sse\",\n \"op\": \"subscribeevent\",\n \"htv:methodName\": \"GET\",\n \"contentType\": \"text/plain\"\n }\n ],\n \"data\": {\n \"type\": \"object\",\n \"properties\": {\n \"value\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"number\"\n }\n },\n \"timestamp\": {\n \"type\": \"string\"\n }\n }\n }\n}\n```\n> data schema (\"data\" field above which describes the event payload) are optional and discussed later\n\nEvents follow a pub-sub model with '1 publisher to N subscribers' per `Event` object, both through ZMQ and HTTP SSE. \n\nTo start the Thing, a configurable HTTP Server is already available (from `hololinked.server.HTTPServer`) which redirects HTTP requests to the object:\n\n```python\nimport ssl, os, logging\nfrom multiprocessing import Process\nfrom hololinked.server import HTTPServer\n\nif __name__ == '__main__':\n ssl_context = ssl.SSLContext(protocol = ssl.PROTOCOL_TLS)\n ssl_context.load_cert_chain(f'assets{os.sep}security{os.sep}certificate.pem',\n keyfile = f'assets{os.sep}security{os.sep}key.pem')\n \n O = OceanOpticsSpectrometer(\n instance_name='spectrometer',\n serial_number='S14155',\n log_level=logging.DEBUG\n )\n O.run_with_http_server(ssl_context=ssl_context)\n # or O.run(zmq_protocols='IPC') - interprocess communication and no HTTP\n # or O.run(zmq_protocols=['IPC', 'TCP'], tcp_socket_address='tcp://*:9999')\n # both interprocess communication & TCP, no HTTP \n```\n> There is an ongoing work to remove HTTP API from the API of all of properties, actions and events and completely move them to the HTTP server for a more accurate syntax. The functionality will not change though.\n\nHere one can see the use of `instance_name` and why it turns up in the URL path. See the detailed example of the above code [here](https://gitlab.com/hololinked-examples/oceanoptics-spectrometer/-/blob/simple/oceanoptics_spectrometer/device.py?ref_type=heads). \n\n##### NOTE - The package is under active development. Contributors welcome, please check CONTRIBUTING.md and the open issues. Some issues can also be independently dealt without much knowledge of this package. \n\n- [example repository](https://github.com/VigneshVSV/hololinked-examples) - detailed examples for both clients and servers\n- [helper GUI](https://github.com/VigneshVSV/thing-control-panel) - view & interact with your object's actions, properties and events. \n \nSee a list of currently supported possibilities while using this package [below](#currently-supported). \n\n> You may use a script deployment/automation tool to remote stop and start servers, in an attempt to remotely control your hardware scripts. \n\n### Looking for sponsorships\n\nKindly read my message [in my README](https://github.com/VigneshVSV#sponsor)\n\n### A little more about Usage\n\nOne may use the HTTP API according to one's beliefs (including letting the package auto-generate it), but it is mainly intended for web development and cross platform clients \nlike the interoperable [node-wot](https://github.com/eclipse-thingweb/node-wot) HTTP(s) client. If your plan is to develop a truly networked system, it is recommended to learn more and \nse [Thing Descriptions](https://www.w3.org/TR/wot-thing-description11) to describe your hardware. A Thing Description will be automatically generated if absent as shown in JSON examples above or can be supplied manually. The default end point to \nfetch thing descriptions are: <br> `http(s)://<host name>/<instance name of the thing>/resources/wot-td`\nIf there are errors in generation of Thing Description\n(mostly due to JSON non-complaint types), one could use: <br> `http(s)://<host name>/<instance name of the thing>/resources/wot-td?ignore_errors=true`\n\n(client docs will be updated here next)\n\n### Currently Supported\n\n- control method execution and property write with a custom finite state machine.\n- database (Postgres, MySQL, SQLite - based on SQLAlchemy) support for storing and loading properties when the object dies and restarts. \n- auto-generate Thing Description for Web of Things applications. \n- use serializer of your choice (except for HTTP) - MessagePack, JSON, pickle etc. & extend serialization to suit your requirement. HTTP Server will support only JSON serializer to maintain comptibility with Javascript (MessagePack may be added later). Default is JSON serializer based on msgspec.\n- asyncio compatible - async RPC server event-loop and async HTTP Server - write methods in async \n- choose from multiple ZeroMQ transport methods which offers some possibilities like the following without changing the code:\n - expose only a dashboard or web page on the network without exposing the hardware itself\n - run direct ZMQ-TCP server without HTTP details\n - serve multiple objects with the same HTTP server, run HTTP Server & python object in separate processes or the same process\n \nAgain, please check examples or the code for explanations. Documentation is being activety improved. \n\n### Currently being worked\n\n- unit tests coverage\n- separation of HTTP protocol specification like URL path and HTTP verbs from the API of properties, actions and events and move their customization completely to the HTTP server \n- serve multiple things with the same server (unfortunately due to a small oversight it is currently somewhat difficult for end user to serve multiple things with the same server, although its possible. This will be fixed.)\n- improving accuracy of Thing Descriptions \n- cookie credentials for authentication - as a workaround until credentials are supported, use `allowed_clients` argument on HTTP server which restricts access based on remote IP supplied with the HTTP headers. This wont still help you in public networks or modified/non-standard HTTP clients.\n\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A ZMQ-based Object Oriented RPC tool-kit for instrument control/data acquisition or controlling generic python objects.",
"version": "0.2.7",
"project_urls": {
"Homepage": "https://hololinked.readthedocs.io/en/latest/index.html"
},
"split_keywords": [
"data-acquisition",
" zmq-rpc",
" scada/iot",
" web of things"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2ef7f578ea17672211dd5bf8ae78baddbeb82382bb3abced93ffcc55823ebdcc",
"md5": "6a880773a775853b3fdaa9e48095696a",
"sha256": "93a37b8aeef044c2292cd6936e6fa67ae2e9fe520bf69c5480b4f26918f123a3"
},
"downloads": -1,
"filename": "hololinked-0.2.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6a880773a775853b3fdaa9e48095696a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 194414,
"upload_time": "2024-10-24T12:41:27",
"upload_time_iso_8601": "2024-10-24T12:41:27.088677Z",
"url": "https://files.pythonhosted.org/packages/2e/f7/f578ea17672211dd5bf8ae78baddbeb82382bb3abced93ffcc55823ebdcc/hololinked-0.2.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96168e3133899d8f54f226ee6b148d4addafd2ae1f2d7e5c2ecc0ba4da273276",
"md5": "91a67caf3ff4b91df1321fa24a418dfb",
"sha256": "1381b790544acddcb2354f9b2ed581ed765a0b2a62a0ccc38309a0443125b37a"
},
"downloads": -1,
"filename": "hololinked-0.2.7.tar.gz",
"has_sig": false,
"md5_digest": "91a67caf3ff4b91df1321fa24a418dfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 192086,
"upload_time": "2024-10-24T12:41:28",
"upload_time_iso_8601": "2024-10-24T12:41:28.550984Z",
"url": "https://files.pythonhosted.org/packages/96/16/8e3133899d8f54f226ee6b148d4addafd2ae1f2d7e5c2ecc0ba4da273276/hololinked-0.2.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-24 12:41:28",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hololinked"
}
JSON