modpoll-wot 0.1.0a1__tar.gz

modpoll_wot-0.1.0a1/CONTRACT.md

@@ -0,0 +1,89 @@
+# Executable configuration contract 0.1 (preview)
+
+This is Modpoll's supported WoT TM/TD 1.1 subset for replacing CSV configuration.
+It is not a general WoT runtime. The Modbus binding document remains a draft:
+https://w3c.github.io/wot-binding-templates/bindings/protocols/modbus/.
+Its entity, address, quantity and byte/word-order vocabulary is reused. Ordered
+acquisition groups, offsets, precise decoding and multipliers are project extensions.
+They do not claim standard W3C acquisition or transformation semantics.
+
+Use `python -m modpoll_wot MODEL [--unit-id N]` to validate and inspect a
+model without opening a device connection. Schemas are bundled locally; the
+loader does not dereference contexts or remote schema dependencies. The official
+TD/TM schemas identify themselves as `1.1-12-March-2025` (Draft 7).
+
+| 1.x input | Contract 0.1 |
+| --- | --- |
+| device name | `title`, used verbatim as output device name |
+| Unit ID | Optional root modv:unitID default per file; explicit CLI overrides it; fallback 1; range 1–254 |
+| poll table | group `modv:entity`: Coil, DiscreteInput, InputRegister, HoldingRegister |
+| poll start/count | group `modv:address` / `modv:quantity`, literal PDU addresses |
+| poll endian | `modv:mostSignificantByte` and `modv:mostSignificantWord` booleans |
+| ref effective name | property key and member `modpoll:property` |
+| ref address | member `modpoll:offset`, relative to group start |
+| ref `address:bit` | member `modpoll:bit`, 0–15, register bool only |
+| ref dtype | member `modpoll:dataType` |
+| ref rw | standard property `readOnly` / `writeOnly`; neither means rw |
+| ref unit | standard property `unit` |
+| ref scale | member `modpoll:multiplier`, multiplication, never inferred division |
+
+The JSON root declares `modpoll:version: "0.1"` and `modpoll:acquisition`.
+Context aliases must match the supported project and draft Modbus namespaces;
+these are not arbitrary remotely resolved JSON-LD aliases. The project namespace
+documents contract 0.1 at https://top-maker.github.io/modpoll/vocab/wot-modbus.
+This is a project extension, not a W3C Modbus standard. Concrete TD Forms use `modbus+tcp` URLs. The Form's entity, operations,
+unit/address/quantity and declared payload/byte order must match the group/member.
+Explicit transport CLI options select the actual endpoint, allowing the same
+configuration to be tested through a proxy or alternate transport. Concrete TD
+Unit IDs must match `--unit-id`; unbound TMs can be instantiated with any supported ID.
+
+Register member offsets count 16-bit registers. Bit-table member offsets count
+eight-bit groups relative to poll start, preserving the old behavior; poll counts
+still specify physical bits. A final partial bit group is clipped by the executor.
+Bit tables support bool/bool8/bool16 and numeric/string payloads that fit complete
+requested bytes. Numeric assembly preserves v1 bit reversal within each byte; word
+order is ignored for bit-table numeric decoding as in v1. Register types are int/uint16/32/64, float16/32/64,
+bool/bool8/bool16 and stringN. String lengths count bytes, including odd lengths;
+spans must fit the declared block. A register bool with a bit selector is a scalar
+boolean; bool groups are arrays with boolean items. Strings cannot be multiplied.
+Float and fractional-multiplier outputs require a number property schema.
+
+Groups preserve order, boundaries and holes. Reads are limited to 125 registers
+or 2000 physical bits per request, within 0–65535. No coalescing takes place.
+Each property must have exactly one mapping. Distinct property aliases at the same backing address/bit are retained and
+decoded independently from one request.
+Overlapping views at distinct starting offsets remain explicit, independent values.
+Missing fields, unknown executable extension fields, invalid access, non-finite
+values/multipliers, duplicate JSON keys and invalid type combinations fail the
+whole file with source and field diagnostics. Inputs are bounded to 1 MiB and 64
+nested containers. Invalid files do not yield partially configured devices.
+
+DI/IR are read-only. The historical simulator CSV's rw flags for those tables are
+corrected to readOnly in the fixtures; no unsupported write capability is promised.
+The interpreter records access flags; raw MQTT write commands retain the 1.x raw
+address behavior. This milestone does not add property-based writes or inverse
+engineering-value transforms. Multipliers are retained as Decimal in the model
+but adapted to the existing float execution semantics. Int64 without a multiplier
+stays a Python integer. JSON/JavaScript consumers must still account for their own
+numeric precision limits.
+
+Inheritance, links, optional TM members, URI templates, root operation Forms,
+actions/events, unsupported Form terms and non-nosec security schemes are rejected.
+Model/TD schema validation does not prove that a stock WoT consumer will implement
+this acquisition extension or its transforms. In particular, a direct Modbus Form
+identifies raw device access; engineering-value interpretation requires the project
+transform metadata. No HTTP endpoint or cache service is declared.
+
+`examples/modsim.tm.json` is an authored mapping of `examples/modsim.csv`, retaining
+four groups and 37 properties; it is not generated from CSV at runtime.
+`examples/modsim.td.json` binds the same mapping to the documented local TCP
+endpoint. Their mappings are checked against the CSV in tests. Runtime equivalence
+checks additionally compare independently known initial values, complete JSON
+snapshots, rendered tables, and the exact four requests against modsim. Shared
+remote modsim state may have been written by others, so remote checks compare
+successive read-only snapshots rather than assuming fixed initial values.
+
+The shared interpreter is independently versioned and published as
+`modpoll-wot`. Application previews pin an exact registry version.
+Its schemas are bundled for offline use; new profile semantics require an
+explicit contract revision rather than silently changing contract 0.1.

modpoll_wot-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021-2024, Ying Shaodong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modpoll_wot-0.1.0a1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.1
+Name: modpoll-wot
+Version: 0.1.0a1
+Summary: WoT Modbus configuration interpreter for Modpoll
+Home-page: https://github.com/top-maker/modpoll
+License: MIT
+Author: Ying Shaodong
+Author-email: helloysd@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: jsonschema (>=4.18,<5)
+Requires-Dist: referencing (>=0.28.4,<1)
+Project-URL: Documentation, https://top-maker.github.io/modpoll/v2/
+Project-URL: Repository, https://github.com/top-maker/modpoll
+Description-Content-Type: text/markdown
+
+# modpoll-wot (experimental)
+
+An independently versioned TM/TD configuration interpreter for Modpoll and future
+compatible consumers. No Modbus execution, scheduler or MQTT service is included.
+
+```sh
+pip install modpoll-wot==0.1.0a1
+python -m modpoll_wot meter.tm.json
+```
+See CONTRACT.md for the executable 0.1 subset and 1.x field mapping.
+
+The loader validates bundled W3C TM/TD 1.1 schemas, the project extension
+schema, and acquisition semantics. It does not execute Modbus requests.
+
+```python
+from modpoll_wot.loading import load_model
+model = load_model("examples/modsim.tm.json", kind="tm", unit_id=1)
+```
+
+The application adapter is connected to the existing Modpoll poll/decode/output engine. Run checks from the repository root:
+
+```sh
+PYTHONPATH=packages/modpoll-wot python -m unittest discover -s packages/modpoll-wot/tests
+```
+
+The bundled W3C schemas identify themselves as 1.1-12-March-2025, retrieved from
+https://www.w3.org/2022/wot/td-schema/v1.1 and
+https://www.w3.org/2022/wot/tm-schema/v1.1. Standard validation does not
+establish device correctness.
+

modpoll_wot-0.1.0a1/README.md

@@ -0,0 +1,29 @@
+# modpoll-wot (experimental)
+
+An independently versioned TM/TD configuration interpreter for Modpoll and future
+compatible consumers. No Modbus execution, scheduler or MQTT service is included.
+
+```sh
+pip install modpoll-wot==0.1.0a1
+python -m modpoll_wot meter.tm.json
+```
+See CONTRACT.md for the executable 0.1 subset and 1.x field mapping.
+
+The loader validates bundled W3C TM/TD 1.1 schemas, the project extension
+schema, and acquisition semantics. It does not execute Modbus requests.
+
+```python
+from modpoll_wot.loading import load_model
+model = load_model("examples/modsim.tm.json", kind="tm", unit_id=1)
+```
+
+The application adapter is connected to the existing Modpoll poll/decode/output engine. Run checks from the repository root:
+
+```sh
+PYTHONPATH=packages/modpoll-wot python -m unittest discover -s packages/modpoll-wot/tests
+```
+
+The bundled W3C schemas identify themselves as 1.1-12-March-2025, retrieved from
+https://www.w3.org/2022/wot/td-schema/v1.1 and
+https://www.w3.org/2022/wot/tm-schema/v1.1. Standard validation does not
+establish device correctness.

modpoll_wot-0.1.0a1/modpoll_wot/__init__.py

@@ -0,0 +1,18 @@
+"""Modpoll's versioned executable subset of WoT TM/TD and Modbus metadata."""
+
+from .acquisition import AcquisitionError, Group, Member, parse_acquisition
+from .loading import Model, load_model, loads_model, parse_model
+from .validation import ModelValidationError, validate_standard
+
+__all__ = [
+    "AcquisitionError",
+    "Group",
+    "Member",
+    "Model",
+    "ModelValidationError",
+    "parse_acquisition",
+    "load_model",
+    "loads_model",
+    "parse_model",
+    "validate_standard",
+]

modpoll_wot-0.1.0a1/modpoll_wot/__main__.py

@@ -0,0 +1,35 @@
+"""Validate a concrete executable TM/TD without contacting a device."""
+
+import argparse
+import json
+import sys
+
+from . import AcquisitionError, load_model
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("model")
+    parser.add_argument("--unit-id", type=int, default=None)
+    args = parser.parse_args()
+    try:
+        model = load_model(args.model, unit_id=args.unit_id)
+    except AcquisitionError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(
+        json.dumps(
+            {
+                "title": model.title,
+                "kind": model.kind,
+                "unit_id": model.unit_id,
+                "groups": len(model.groups),
+                "properties": sum(len(g.members) for g in model.groups),
+            }
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

modpoll_wot-0.1.0a1/modpoll_wot/acquisition.py

@@ -0,0 +1,185 @@
+"""Version 0.1 acquisition semantics, independent of Modbus transport."""
+
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+import re
+import math
+
+
+class AcquisitionError(ValueError):
+    """Invalid or unsupported executable configuration."""
+
+
+ENTITIES = {
+    "Coil": "coil",
+    "DiscreteInput": "discrete_input",
+    "InputRegister": "input_register",
+    "HoldingRegister": "holding_register",
+}
+WIDTHS = {
+    "int16": 1,
+    "uint16": 1,
+    "float16": 1,
+    "int32": 2,
+    "uint32": 2,
+    "float32": 2,
+    "int64": 4,
+    "uint64": 4,
+    "float64": 4,
+    "bool": 1,
+    "bool8": 1,
+    "bool16": 2,
+}
+
+
+@dataclass(frozen=True)
+class Member:
+    property: str
+    offset: int
+    data_type: str
+    bit: int | None = None
+    multiplier: Decimal | None = None
+    readable: bool = True
+    writable: bool = False
+    unit: str | None = None
+
+    @property
+    def width(self):
+        return type_width(self.data_type)
+
+    @property
+    def bit_group_width(self):
+        return type_width(self.data_type, bit_table=True)
+
+
+@dataclass(frozen=True)
+class Group:
+    table: str
+    start: int
+    quantity: int
+    byte_order: str
+    members: tuple[Member, ...]
+
+
+def type_width(dtype, *, bit_table=False):
+    if dtype in WIDTHS:
+        width = WIDTHS[dtype]
+        return width * 2 if bit_table and not dtype.startswith("bool") else width
+    if re.fullmatch(r"string[1-9][0-9]{0,3}", dtype):
+        length = int(dtype[6:])
+        return length if bit_table else (length + 1) // 2
+    raise AcquisitionError(f"unsupported data type: {dtype}")
+
+
+def _schema_type(prop, dtype, bit, multiplier, path):
+    actual = prop.get("type")
+    if dtype.startswith("string"):
+        valid = actual == "string"
+        if multiplier is not None:
+            raise AcquisitionError(f"{path}: strings cannot have a multiplier")
+    elif dtype.startswith("bool"):
+        valid = (
+            actual == "boolean"
+            if bit is not None
+            else (
+                actual == "array"
+                and isinstance(prop.get("items"), dict)
+                and prop["items"].get("type") == "boolean"
+            )
+        )
+        if multiplier is not None:
+            raise AcquisitionError(f"{path}: bit values cannot have a multiplier")
+    else:
+        valid = actual in ("integer", "number")
+        if dtype.startswith("float") or (
+            multiplier is not None and multiplier != multiplier.to_integral_value()
+        ):
+            valid = actual == "number"
+    if not valid:
+        raise AcquisitionError(
+            f"{path}: property type disagrees with decoded type/transform"
+        )
+
+
+def parse_acquisition(document) -> tuple[Group, ...]:
+    """Apply cross-field checks after structural schema validation."""
+    # Also validate here so callers cannot bypass structural validation.
+    from .validation import validate_extension
+
+    validate_extension(document)
+    properties = document.get("properties", {})
+    if not isinstance(properties, dict) or not properties:
+        raise AcquisitionError("/properties: expected nonempty object")
+    result, seen = [], set()
+    for i, group in enumerate(document["modpoll:acquisition"]):
+        path = f"/modpoll:acquisition/{i}"
+        table = ENTITIES[group["modv:entity"]]
+        bits = table in ("coil", "discrete_input")
+        start, count = group["modv:address"], group["modv:quantity"]
+        if count > (2000 if bits else 125) or start + count > 65536:
+            raise AcquisitionError(f"{path}: invalid Modbus range")
+        byte_order = (
+            ("BE" if group["modv:mostSignificantByte"] else "LE")
+            + "_"
+            + ("BE" if group["modv:mostSignificantWord"] else "LE")
+        )
+        members = []
+        for j, member in enumerate(group["modpoll:members"]):
+            mp = f"{path}/modpoll:members/{j}"
+            name = member["modpoll:property"]
+            if name not in properties or name in seen:
+                raise AcquisitionError(f"{mp}: unknown or duplicate property {name!r}")
+            prop = properties[name]
+            if not isinstance(prop, dict):
+                raise AcquisitionError(f"{mp}: expected property schema")
+            dtype, offset = member["modpoll:dataType"], member["modpoll:offset"]
+            width = type_width(dtype, bit_table=bits)
+            # 1.x bit table references count eight-bit groups, not physical bits.
+            limit = (count + 7) // 8 if bits else count
+            if offset + width > limit or (
+                bits and not dtype.startswith("bool") and (offset + width) * 8 > count
+            ):
+                raise AcquisitionError(f"{mp}: member outside group")
+            bit = member.get("modpoll:bit")
+            if bit is not None and (bits or dtype != "bool"):
+                raise AcquisitionError(
+                    f"{mp}: register bit selector requires register bool"
+                )
+            for flag in ("readOnly", "writeOnly"):
+                if flag in prop and type(prop[flag]) is not bool:
+                    raise AcquisitionError(f"{mp}: invalid {flag}")
+            if prop.get("readOnly") and prop.get("writeOnly"):
+                raise AcquisitionError(f"{mp}: conflicting access flags")
+            readable, writable = not prop.get("writeOnly", False), not prop.get(
+                "readOnly", False
+            )
+            if table in ("discrete_input", "input_register") and writable:
+                raise AcquisitionError(f"{mp}: read-only table requires readOnly")
+            multiplier = None
+            if "modpoll:multiplier" in member:
+                try:
+                    multiplier = Decimal(str(member["modpoll:multiplier"]))
+                except InvalidOperation as exc:
+                    raise AcquisitionError(f"{mp}: invalid multiplier") from exc
+                if not multiplier.is_finite() or not math.isfinite(float(multiplier)):
+                    raise AcquisitionError(f"{mp}: non-finite multiplier")
+            _schema_type(prop, dtype, bit, multiplier, mp)
+            members.append(
+                Member(
+                    name,
+                    offset,
+                    dtype,
+                    bit,
+                    multiplier,
+                    readable,
+                    writable,
+                    prop.get("unit"),
+                )
+            )
+            seen.add(name)
+        result.append(Group(table, start, count, byte_order, tuple(members)))
+    if seen != properties.keys():
+        raise AcquisitionError(
+            "/properties: every property must have an acquisition member"
+        )
+    return tuple(result)

modpoll_wot-0.1.0a1/modpoll_wot/forms.py

@@ -0,0 +1,145 @@
+"""Check any declared Modbus Forms against the acquisition mapping."""
+
+from urllib.parse import parse_qs, urlsplit
+
+from .acquisition import AcquisitionError, ENTITIES
+
+
+def validate_forms(document, groups, unit_id, kind):
+    endpoint = None
+    for group in groups:
+        entity = next(key for key, value in ENTITIES.items() if value == group.table)
+        for member in group.members:
+            forms = document["properties"][member.property].get("forms", [])
+            for form in forms:
+                path = f"/properties/{member.property}/forms"
+                if any(key.startswith("modpoll:") for key in form):
+                    raise AcquisitionError(
+                        f"{path}: unsupported project Form extension"
+                    )
+                if form.get("modv:entity") != entity:
+                    raise AcquisitionError(f"{path}: expected modv:entity {entity}")
+                if "modv:function" in form or "modv:zeroBasedAddressing" in form:
+                    raise AcquisitionError(
+                        f"{path}: function overrides and deprecated addressing are unsupported"
+                    )
+                for term, expected in (
+                    ("modv:mostSignificantByte", group.byte_order[:2] == "BE"),
+                    ("modv:mostSignificantWord", group.byte_order[-2:] == "BE"),
+                ):
+                    if term in form and (
+                        type(form[term]) is not bool or form[term] != expected
+                    ):
+                        raise AcquisitionError(
+                            f"{path}: byte order disagrees with group"
+                        )
+                allowed = (["readproperty"] if member.readable else []) + (
+                    ["writeproperty"] if member.writable else []
+                )
+                ops = form.get("op", allowed)
+                if isinstance(ops, str):
+                    ops = [ops]
+                if not ops or any(op not in allowed for op in ops):
+                    raise AcquisitionError(
+                        f"{path}: operation disagrees with property access"
+                    )
+                expected_type = {
+                    "uint16": "xsd:unsignedShort",
+                    "int16": "xsd:short",
+                    "uint32": "xsd:unsignedInt",
+                    "int32": "xsd:int",
+                    "uint64": "xsd:unsignedLong",
+                    "int64": "xsd:long",
+                    "float32": "xsd:float",
+                    "float64": "xsd:double",
+                }.get(member.data_type)
+                if member.data_type.startswith("string"):
+                    expected_type = "xsd:string"
+                elif member.data_type.startswith("bool"):
+                    expected_type = (
+                        "xsd:unsignedShort" if member.bit is not None else "xsd:boolean"
+                    )
+                if "modv:type" in form and (
+                    expected_type is None or form["modv:type"] != expected_type
+                ):
+                    raise AcquisitionError(
+                        f"{path}: modv:type disagrees with decoding type"
+                    )
+                supported = {
+                    "modv:entity",
+                    "modv:address",
+                    "modv:unitID",
+                    "modv:quantity",
+                    "modv:mostSignificantByte",
+                    "modv:mostSignificantWord",
+                    "modv:type",
+                }
+                if any(
+                    key.startswith("modv:") and key not in supported for key in form
+                ):
+                    raise AcquisitionError(f"{path}: unsupported Modbus form term")
+                if (
+                    form.get("contentType", "application/octet-stream")
+                    != "application/octet-stream"
+                ):
+                    raise AcquisitionError(f"{path}: unsupported content type")
+                href = form.get("href")
+                if href is None and kind == "tm":
+                    continue
+                if not isinstance(href, str):
+                    raise AcquisitionError(f"{path}: missing href")
+                if "://" not in href:
+                    base = document.get("base", "")
+                    href = base.rstrip("/") + "/" + href
+                try:
+                    url = urlsplit(href)
+                    parts = url.path.strip("/").split("/")
+                    query = parse_qs(
+                        url.query, strict_parsing=True, keep_blank_values=True
+                    )
+                    actual_unit, address = map(int, parts)
+                    quantity = int(query.get("quantity", ["1"])[0])
+                    if set(query) - {"quantity"} or len(query.get("quantity", [])) > 1:
+                        raise ValueError("unsupported query")
+                    remote = (url.hostname, url.port or 502)
+                    if (
+                        url.scheme != "modbus+tcp"
+                        or not remote[0]
+                        or url.username
+                        or url.password
+                        or url.fragment
+                    ):
+                        raise ValueError("invalid Modbus TCP URL")
+                except (TypeError, ValueError) as exc:
+                    raise AcquisitionError(f"{path}: invalid Modbus TCP href") from exc
+                for term, value in (
+                    ("modv:address", address),
+                    ("modv:quantity", quantity),
+                    ("modv:unitID", actual_unit),
+                ):
+                    if term in form and (
+                        type(form[term]) is not int or form[term] != value
+                    ):
+                        raise AcquisitionError(
+                            f"{path}: Modbus URL term disagrees with href"
+                        )
+                bit_table = group.table in ("coil", "discrete_input")
+                expected_address = group.start + member.offset * (8 if bit_table else 1)
+                expected_quantity = (
+                    min(member.bit_group_width * 8, group.quantity - member.offset * 8)
+                    if bit_table
+                    else member.width
+                )
+                if (actual_unit, address, quantity) != (
+                    unit_id,
+                    expected_address,
+                    expected_quantity,
+                ):
+                    raise AcquisitionError(
+                        f"{path}: href disagrees with group/member or Unit ID"
+                    )
+                if endpoint is not None and endpoint != remote:
+                    raise AcquisitionError(
+                        f"{path}: multiple endpoints in one device are unsupported"
+                    )
+                endpoint = remote