/thing-description` by the server,
+ and the `ClientFactory` subsribes to the `Thing Description` and constructs the `ObjectProxy`.
-!!! Note
-
- Only one protocol is allowed per client.
+ MQTT currently supports only events and properties that publish change events.
### read and write properties
@@ -108,10 +113,7 @@ One can also use `invoke_action` to invoke an action by name
### oneway scheduling
-`oneway` scheduling do not fetch return value and exceptions that might occur while executing a property or an action.
-The server schedules the operation and returns an empty response to the client, allowing it to process further logic.
-It is possible to set a property, set multiple or all properties or invoke an action in
-oneway. Other operations are not supported.
+`oneway` scheduling do not fetch return value and exceptions that might occur while executing a property or an action. The server schedules the operation and returns an empty response to the client, allowing it to process further logic. It is possible to set a property, set multiple or all properties or invoke an action in oneway. Other operations are not supported.
```py title="oneway=True" linenums="1"
--8<-- "docs/beginners-guide/code/object_proxy/sync.py:79:103"
@@ -119,12 +121,11 @@ oneway. Other operations are not supported.
Simply provide the keyword argument `oneway=True` to the operation method.
-Importantly, one cannot have an action argument or a property on the server named `oneway` as it is a
-reserved keyword argument to such methods on the client. At least they become inaccessible on the `ObjectProxy`.
+`oneway` must be always specified as a keyword argument. Due to this reason, one cannot have an action argument or a property on the server named `oneway` as it is a reserved keyword argument to such methods on the client. At least they become inaccessible on the `ObjectProxy`.
### no-block scheduling
-`noblock` allows scheduling a property or action but collecting the reply later:
+`noblock` allows scheduling a property or action and collecting the reply later:
```py title="noblock=True" linenums="1"
--8<-- "docs/beginners-guide/code/object_proxy/sync.py:107:139"
@@ -156,7 +157,7 @@ Simply prefix `async_` to the method name, like `async_read_property`, `async_wr
There is no support for dot operator based access for asyncio. One may also note that `async` operations
do not change the nature of the execution on the server side.
`asyncio` on `ObjectProxy` is purely a client-side non-blocking network call, so that one can
-simultaneously perform other async operations while the client is waiting for the network operation to complete.
+simultaneously perform other async operations while the client is waiting for said network operation to complete.
!!! Note
@@ -214,15 +215,14 @@ Once again, to customize callback scheduling, see [events section](./events.md#s
##### foreign attributes on client
-Normally, there cannot be user defined attributes on the `ObjectProxy` as the attributes on the client
-must mimic the available properties, actions and events on the server. An accidental setting of an unknown
-property must raise an `AttributeError` when not found on the server, instead of silently going through and setting
-said property on the client object itself:
+Normally, there cannot be user defined attributes on the `ObjectProxy` as the attributes on the client must mimic the available properties, actions and events on the server. An accidental setting of an unknown property must raise an `AttributeError`, when not found on the server, instead of silently setting said property on the client itself:
```py title="foreign attributes raise AttributeError" linenums="1"
--8<-- "docs/beginners-guide/code/object_proxy/customizations.py:3:7"
```
+The requirement for this behaviour is due to python's duck typing. If one intends to set a property named `foo`, and instead types it as `fooo` (misspelt), it is better to raise an error instead of silently setting a new attribute `fooo` on the client.
+
One can overcome this by setting `allow_foreign_attributes` to `True`:
```py title="foreign attributes allowed" linenums="1"
@@ -236,15 +236,13 @@ For invoking any operation (say property read/write & action call), two types of
- `invokation_timeout` - the amount of time the server has to wait for an operation to be scheduled
- `execution_timeout` - the amount of time the server has to complete the operation once scheduled
-When the `invokation_timeout` expires, the operation is guaranteed to be never scheduled. When the `execution_timeout` expires, the operation is scheduled but returns without the expected response. In both cases, a `TimeoutError` is raised on the client side specifying the timeout type. If an operation is scheduled but not completed within the `execution_timeout`, the server may still complete the operation and there can be unknown side effects or client does not know about it.
+When the `invokation_timeout` expires, the operation is guaranteed to be never executed. When the `execution_timeout` expires, the operation is scheduled but returns without the expected response. In both cases, a `TimeoutError` is raised on the client specifying the timeout type. If an operation is scheduled but not completed within the `execution_timeout`, the server may still complete the operation but client does not know about it.
```py title="timeout specification" linenums="1"
--8<-- "docs/beginners-guide/code/object_proxy/customizations.py:29:36"
```
-!!! Note
-
- Currently only a global specification is supported. In future, one may be able to specify timeouts per operation.
+> Currently only a global customization of these values are supported. In future, one may be able to specify timeouts per operation.
#### Remote Access to Logger
diff --git a/docs/index.md b/docs/index.md
index eef96fa..27d0cb4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,11 +5,11 @@ description: hololinked introduces SCADA & IoT systems to beginners
# hololinked - Pythonic Object-Oriented Supervisory Control & Data Acquisition / Internet of Things
-`hololinked` is a beginner-friendly pythonic tool suited for instrumentation control and data acquisition over network (IoT & SCADA).
+`hololinked` is a beginner-friendly, extensible pythonic tool suited for instrumentation control and data acquisition over network (IoT & SCADA).
As a novice, you have a requirement to control and capture data from your hardware, say in your electronics or science lab, and you want to show the data in a dashboard, provide a PyQt GUI or run automated scripts, `hololinked` can help. Even for isolated desktop applications or a small setup without networking, one can still separate the concerns of the tools that interact with the hardware & the hardware itself.
-If you are a web developer or an industry professional looking for a web standards compatible (high-speed) IoT runtime, `hololinked` can be a decent choice. By conforming to [W3C Web of Things](https://www.w3.org/WoT/), one can expect a consistent API and flexible bidirectional message flow to interact with your devices, irrespective of the underlying protocol. Currently HTTP, MQTT & ZMQ are supported.
+If you are a web developer or an industry professional looking for a web standards compatible, interoperable (high-speed) IoT runtime, `hololinked` can be a decent choice. By conforming to [W3C Web of Things](https://www.w3.org/WoT/), one can expect a consistent API and flexible bidirectional message flow to interact with your devices, irrespective of the underlying protocol. Currently HTTP, MQTT & ZMQ are supported.
This implementation is based on RPC, built ground-up in python keeping both the latest web technologies and python principles in mind.
@@ -67,7 +67,7 @@ Each device, or **Thing**, is modeled in software with:
- **Actions**: Methods that command the hardware to perform operations.
- _Oscilloscope_ - connect/disconnect hardware
- - _Camera_ - start/stop measurement or video capture
+ - _Camera_ - snap image or start/stop video capture
- _DC Power Supply_ - execute control routines (e.g., closed-loop control)
- **Events**: Asynchronous messages or data streams to clients (e.g., alarms, measured values)
@@ -82,12 +82,27 @@ This separation is independent of:
- data serialization or binary representation (JSON, MessagePack, Pickle etc.)
- security or access control mechanisms (JWT, Basic Auth, OAuth etc.)
-The `Thing` object represents the physical device and is modeled as a class, encapsulating its properties, actions, and events as its attributes & methods. Additionally, **state machines** can constrain property and action execution:
+The `Thing` object (as in OOP) represents the physical device and is modeled as a class, encapsulating its properties, actions, and events as its attributes & methods.
+
+Additionally, **state machines** can constrain property and action execution:
- _Oscilloscope_ - Cannot start a new measurement while one is ongoing
- _Camera_ - Cannot change exposure time while capturing video
---
-> **Ready to get started?**
-> See the [Handbook](beginners-guide/articles/servers) section for concepts and code example and the [Examples Repository](https://github.com/hololinked-dev/examples) section for hardware-specific implementations.
+!!! tip "Ready to get started?"
+ Please see:
+
+ - [Handbook](beginners-guide/articles/servers) section for concepts
+ - Code example and the [Examples Repository](https://github.com/hololinked-dev/examples) section for hardware-specific implementations
+ - Online (live) examples listed on the [project website](https://hololinked.dev)
+
+ Office hours are available on request for any formal or informal discussions, help with implementation or just to say hi:
+
+ - Every Wednesday 4-6PM CET/CEST
+ - Every Friday 9-10AM CET/CEST, 4-5PM CET/CEST
+
+ Please email to info@hololinked.dev. You can also ask questions in the [discord group](https://discord.com/invite/kEz87zqQXh) (currently no participants).
+
+
diff --git a/docs/introduction/contributing.md b/docs/introduction/contributing.md
index 4220495..1dde945 100644
--- a/docs/introduction/contributing.md
+++ b/docs/introduction/contributing.md
@@ -25,51 +25,43 @@ For good first issues, visit repository wise:
- [control panel](https://github.com/hololinked-dev/thing-control-panel/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
- [documentation](https://github.com/hololinked-dev/docs-v2/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
- [additional/new projects](https://github.com/hololinked-dev/.github/issues)
-- [website](https://github.com/hololinked-dev/website/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
-- [kubernetes](https://github.com/hololinked-dev/vps-kubernetes-cluster/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22)
Our [contribution guidelines](https://github.com/hololinked-dev/hololinked/blob/main/CONTRIBUTING.md) may also help. There are also [weekly office hours](https://github.com/hololinked-dev#monthly-meetings) & [discord group](https://discord.com/invite/kEz87zqQXh) (currently no participants).
+> Please do note that we are only looking for code contributions that can enfore code ownership and integrating contributors that can understand the codebase, not AI automated PRs. All solutions anybody can automate can also be automated by us, so, this is not the purpose of accepting contributions.
+
## Setup Development Environment
One can setup a development environment with [uv](https://docs.astral.sh/uv/) as follows:
-1. Install uv if you don't have it already: https://docs.astral.sh/uv/getting-started/installation/
+1. Install uv if you don't have it already: [uv docs](https://docs.astral.sh/uv/getting-started/installation/)
2. Create and activate a virtual environment:
-
```bash
-uv venv venv
-source venv/bin/activate # On Windows: venv\Scripts\activate
+uv venv
+source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
3. Install the package in development mode with all dependencies:
-
```bash
-uv pip install -e .
+uv sync
+# or
+uv sync --no-install-project
uv pip install -e ".[dev,test]"
```
## Running Tests
-To run the tests with uv:
-
-In linux:
-
+To run unit and integration tests:
```bash
-uv run --active coverage run -m unittest discover -s tests -p 'test_*.py'
-uv run --active coverage report -m
+pytest -s -v tests
```
-In windows:
-
-```bash
-python -m unittest
-```
+You might need docker daemon for running some tests (currently `test_16_protocols_mqtt`).
## Pre-commit Hooks
-You can use pre-commit hooks to ensure code quality before committing changes, and be sure that certain pipeline checks will pass.
+You can use pre-commit hooks to ensure code quality before committing changes, and be ensured that certain pipeline checks will pass.
```bash
python -m pip install pre-commit
@@ -77,9 +69,9 @@ pre-commit install
pre-commit run --all-files
```
-Currently ruff, bandit and gitleaks are configured to run as pre-commit hooks.
+Currently `ruff`, `bandit` and `gitleaks` are configured to run as pre-commit hooks.
-To skip pre-commit hooks use:
+Precommit hooks are optional. To skip them, use:
```bash
git commit --no-verify -m "Your commit message"
diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md
index 86da95a..4fbada0 100644
--- a/docs/introduction/installation.md
+++ b/docs/introduction/installation.md
@@ -2,16 +2,22 @@
From pip:
- pip install hololinked
+```sh
+pip install hololinked
+```
From conda:
- conda install -c conda-forge hololinked
+```sh
+pip install aiomqtt
+conda install -c conda-forge hololinked
+```
One may also clone it from github & install directly (in develop mode):
```sh
-git clone https://github.com/hololinked-dev/hololinked.git
+git clone --no-recurse-submodules https://github.com/hololinked-dev/hololinked.git
+# the submodules can be quite hefty and are not necessary
cd hololinked
pip install -e .
```
@@ -19,7 +25,7 @@ pip install -e .
With `uv`:
```sh
-git clone https://github.com/hololinked-dev/hololinked.git
+git clone --no-recurse-submodules https://github.com/hololinked-dev/hololinked.git
cd hololinked
uv venv
source .venv/bin/activate # for Linux/Mac
diff --git a/docs/introduction/resources.md b/docs/introduction/resources.md
index f8894c0..5217cf5 100644
--- a/docs/introduction/resources.md
+++ b/docs/introduction/resources.md
@@ -7,7 +7,7 @@ Check out:
| Repository | URL | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| examples | [GitHub](https://github.com/hololinked-dev/examples.git) | repository containing example code discussed in this documentation |
-| control panel | [Website](https://control-panel.hololinked.dev) [GitHub](https://github.com/hololinked-dev/thing-control-panel.git) | GUI to view your devices' properties, actions, and events |
-| Infrastructure Components | [GitHub](https://github.com/hololinked-dev/daq-system-infrastructure.git) | Databases, MQTT broker (Identity System in the future), based on docker |
+| control panel | [Website](https://control-panel.hololinked.dev) [GitHub](https://github.com/hololinked-dev/thing-control-panel.git) | GUI to view and interact with your devices' properties, actions, and events |
+| Infrastructure Components | [GitHub](https://github.com/hololinked-dev/daq-system-infrastructure.git) | Databases, MQTT broker, Identity System (Keycloak), based on docker |
| Eclipse ThingWeb | [GitHub](https://github.com/eclipse-thingweb/node-wot) | javascript implementation of the W3C Web of Things (WoT) standard, for example, to use as HTTP clients |
| TD Editor | [Website](https://eclipse.github.io/editdor/) [GitHub](https://github.com/eclipse/editdor) | GUI to create and edit Thing Descriptions (TD) |
diff --git a/docs/introduction/use-cases.md b/docs/introduction/use-cases.md
index edcb643..c5b1a78 100644
--- a/docs/introduction/use-cases.md
+++ b/docs/introduction/use-cases.md
@@ -3,47 +3,39 @@
| Protocol |
Plausible Use Cases |
Operations |
+ Underlying Implementation |
Security |
| HTTP |
Web Apps |
-
- readproperty,
- writeproperty,
- observeproperty,
- unobserveproperty,
- invokeaction,
- subscribeevent,
- unsubscribeevent,
- readmultipleproperties,
- writemultipleproperties,
- readallproperties,
- writeallproperties
- properties and actions can be operated in a oneway and no-block manner (issue and query later format) as well
+ |
+ Properties,
Actions,
Events
+ |
+
+ tornado
|
username-password,
device API key,
IP filter,
- OAuth2 OIDC (experimental)
+ OAuth2 OIDC
|
| ZMQ TCP |
- Networked Control Systems, subnet protected containerized apps like in Kubernetes |
-
- username-password planned,
- device API key planned
+ | Networked Control Systems, devices in protected networks, containerized apps like in Kubernetes |
+
+ Properties,
Actions,
Events
+ |
+ pyzmq |
+
+ planned, likely may take upto end of 2026, please use HTTP if needed. Its not slow.
|
| ZMQ IPC |
- Desktop Applications, Python Dashboards without exposing device API directly on network |
-
- username-password planned,
- device API key planned
- |
+ Desktop Applications, Python Dashboards without exposing device API directly on network (streamlit, dash, panel etc.) |
| ZMQ INPROC |
@@ -57,15 +49,15 @@
| MQTT |
- Reliable pub-sub & incorporating into existing systems that use MQTT for
lightweight messaging
+ Reliable pub-sub & incorporating into existing systems that use MQTT for lightweight messaging
|
-
- observeproperty,
- unobserveproperty,
- subscribeevent,
- unsubscribeevent
+ |
+ Properties that emit change events,
plain Events
|
-
+ |
+ aiomqtt/Eclipse Paho
+ |
+
username-password,
TLS with client certificates (you set this up in the broker anyway)
|
@@ -73,17 +65,26 @@
| MQTT with websockets |
- Reliable pub-sub for web applications, planned for March 2026 release.
+ planned for April/May 2026 release.
|
+
+
- observeproperty,
- unobserveproperty,
- subscribeevent,
- unsubscribeevent
+ CoAP
+ CoAP Websockets
+ CoAP UDP
|
- username-password,
- TLS with client certificates (you set this up in the broker anyway)
+ Planned, April 2026.
+ |
+
+ Will be updated
+ |
+
+ aiocoap
+ |
+
+ Will be updated
|
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index 600823f..69e9596 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -126,12 +126,4 @@
/* Optional polish */
.md-nav__link--active { font-weight: 700; } /* make current item pop */
-.md-nav__link code { font-family: inherit; } /* keep code fragments consistent in TOCs */
-
-/* Compact footer navigation (prev/next links) */
-.md-footer__inner {
- padding-top: 0rem;
- padding-bottom: 0rem;
- max-height: 60px;
-}
-
+.md-nav__link code { font-family: inherit; } /* keep code fragments consistent in TOCs */
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index caf418d..1b4afa4 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,10 +8,10 @@ nav:
- Home:
- Introduction: index.md
- Installation: introduction/installation.md
+ - Protocol Use Cases: introduction/use-cases.md
- Resources: introduction/resources.md
- Contributing: introduction/contributing.md
- License: introduction/license.md
- - Protocol Use Cases: introduction/use-cases.md
- Security Scan Overview: introduction/security-scanning.md
- Handbook:
- Expose Python Objects: beginners-guide/articles/servers.md
@@ -79,13 +79,16 @@ nav:
- Clients:
- ClientFactory: api-reference/clients/base.md
- ObjectProxy: api-reference/clients/object-proxy.md
- # Security
- Abstractions:
- ConsumedThingAction: api-reference/clients/bases/cta.md
- ConsumedThingProperty: api-reference/clients/bases/ctp.md
- ConsumedThingEvent: api-reference/clients/bases/cte.md
- SSE: api-reference/clients/bases/sse.md
- Utils: api-reference/clients/bases/utils.md
+ - Security:
+ - Basic: api-reference/clients/security/basic.md
+ - API Key: api-reference/clients/security/apikey.md
+ - OIDC Direct Access Grant: api-reference/clients/security/oidc.md
- Servers:
- HTTP: api-reference/protocols/http/index.md
- ZMQ: api-reference/protocols/zmq/index.md
@@ -104,6 +107,9 @@ nav:
- EventAffordance: api-reference/td/interaction_affordance/event_affordance.md
- DataSchema: api-reference/td/data_schema.md
- Thing Model: api-reference/td/tm.md
+ - Form: api-reference/td/form.md
+ - Metadata: api-reference/td/metadata.md
+ - Security Definitions: api-reference/td/security.md
- Bases:
- Schema: api-reference/td/bases/schema.md
# Examples
@@ -271,11 +277,12 @@ extra:
name: sponsor
copyright: >
- © BSD-3-Clause license, hololinked contributors. This website was written by humans, except API reference
- which can contain automated content. Leave us a star on
+
+ © BSD-3-Clause license, hololinked contributors. Leave us a star on
GitHub
if you find this project useful!
This website uses anonymized privacy friendly GDPR compliant cookie-less analytics.
+