ikalogic-scanastudio 0.2.1__tar.gz

ikalogic_scanastudio-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) IKALOGIC S.A.S.
+
+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.

ikalogic_scanastudio-0.2.1/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: ikalogic-scanastudio
+Version: 0.2.1
+Summary: Python SDK for ScanaStudio v6 logic analysers and pattern generators
+Keywords: scanastudio,ikalogic,logic-analyzer,protocol-decoder,pattern-generator,instrumentation,sdk,api
+Author: IKALOGIC
+Author-email: IKALOGIC <contact@ikalogic.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.7
+Requires-Dist: websockets>=13.0
+Requires-Python: >=3.10
+Project-URL: Documentation, https://www.ikalogic.com/kb/scanastudio-api/
+Project-URL: Homepage, https://www.ikalogic.com/logic-analyzers/
+Project-URL: Repository, https://github.com/ikalogic/scanastudio-v6
+Description-Content-Type: text/markdown
+
+# ikalogic-scanastudio
+
+Python SDK for [ScanaStudio v6](https://www.ikalogic.com/logic-analyzers/), the
+software behind Ikalogic logic analysers and pattern generators.
+
+ScanaStudio runs a server that owns the devices and speaks one WebSocket
+protocol. The interface is a client of that protocol, and so is this package —
+so everything you can do in the application, you can do from a script: capture,
+decode, measure, generate patterns and export.
+
+```sh
+pip install ikalogic-scanastudio
+```
+
+## Capture and decode
+
+```python
+from ikalogic_scanastudio import ScanaStudio, Trigger
+
+with ScanaStudio.connect() as server:
+    workspace = server.create("se254")  # a demo device: no hardware needed
+
+    workspace.capture.run(
+        samples=1_000_000,
+        sample_rate=25_000_000,
+        trigger=Trigger.rising(channel=0, position=0.1),
+    )
+
+    i2c = workspace.decoders.add(
+        "i2c.js",
+        {"ch_scl": workspace.channel("I2C SCL"), "ch_sda": workspace.channel("I2C SDA")},
+        wait=True,
+    )
+    for packet in i2c.packets():
+        print(f"{workspace.capture.seconds(packet.start):.6f}s  {packet.title}: {packet.content}")
+
+    workspace.export_csv("packets.csv", source="packets", instances=[i2c.instance_id])
+```
+
+`server.create` takes a demo key such as `se254`, or `hw:<serial>` for real
+hardware; `server.devices()` lists both. `server.open` takes the path of a
+`.scana` instead, and `server.attach` joins a workspace already running.
+
+⚠️ A demo device generates pseudo-random noise, not protocol traffic. It runs
+the whole path — capture, decode, measure, export — which is what makes it
+useful for writing and testing a script without hardware, but a decoder run on
+it finds structure by chance.
+
+## Read the raw signal
+
+```python
+for edge in workspace.data.transitions(channel=0):
+    print(edge.sample, edge.level)
+```
+
+The iterator pages for you, however long the capture. The first edge it yields
+is the level in force where you started reading, so a window describes itself.
+
+## Find out what a decoder takes
+
+```python
+for option in workspace.decoders.options("i2c.js"):
+    print(option)
+# ch_sda: SDA Channel (ch_selector) = None
+# address_format [Advanced options]: Address display format (combo)
+#     one of ['HEX', 'Binary', 'Decimal'] = 'HEX'
+```
+
+Pass those by id or by caption, as Python values — a channel number, a combo
+entry by name, a flag as `True`. Anything left out keeps the script's default.
+
+## Leave a capture running
+
+The server owns the workspace, so disconnecting destroys nothing. Start a long
+acquisition, go away, and come back to it:
+
+```python
+with ScanaStudio.connect() as server:
+    workspace = server.create("hw:SP259-000123")
+    workspace.capture.start(samples=2_000_000_000)
+    print("running as workspace", workspace.id)
+
+# later, from anywhere
+with ScanaStudio.connect("ws://bench.local:4911") as server:
+    for session in server.workspaces():
+        print(session.workspace_id, session.device_name, session.state)
+    workspace = server.attach(session.workspace_id)
+    workspace.capture.wait()
+```
+
+⚠️ A server listening beyond loopback has **no authentication**: whoever reaches
+the port has the devices.
+
+## What is where
+
+| | |
+|---|---|
+| `server.devices()`, `server.workspaces()` | what you can open, and what is already open |
+| `server.capabilities(device)` | the rates, depths and thresholds it offers |
+| `server.scripts` | the decoder library, which belongs to the server |
+| `workspace.capture` | arming, running and waiting |
+| `workspace.data` | raw edges, packets, items, hex |
+| `workspace.decoders` | attaching and configuring decoders |
+| `workspace.markers` | time markers |
+| `workspace.measures` | measurements between two markers |
+| `workspace.pattern` | the pattern generator |
+| `workspace.events` | everything the server pushes |
+
+## Versions
+
+This SDK speaks protocol 7. `ScanaStudio.connect` refuses a server that speaks
+another, since a mismatch means one of the two needs updating. The protocol
+itself is documented in
+[`api/schema/protocol.md`](https://github.com/ikalogic/scanastudio-v6/blob/main/api/schema/protocol.md).
+
+MIT licensed.

ikalogic_scanastudio-0.2.1/README.md

@@ -0,0 +1,116 @@
+# ikalogic-scanastudio
+
+Python SDK for [ScanaStudio v6](https://www.ikalogic.com/logic-analyzers/), the
+software behind Ikalogic logic analysers and pattern generators.
+
+ScanaStudio runs a server that owns the devices and speaks one WebSocket
+protocol. The interface is a client of that protocol, and so is this package —
+so everything you can do in the application, you can do from a script: capture,
+decode, measure, generate patterns and export.
+
+```sh
+pip install ikalogic-scanastudio
+```
+
+## Capture and decode
+
+```python
+from ikalogic_scanastudio import ScanaStudio, Trigger
+
+with ScanaStudio.connect() as server:
+    workspace = server.create("se254")  # a demo device: no hardware needed
+
+    workspace.capture.run(
+        samples=1_000_000,
+        sample_rate=25_000_000,
+        trigger=Trigger.rising(channel=0, position=0.1),
+    )
+
+    i2c = workspace.decoders.add(
+        "i2c.js",
+        {"ch_scl": workspace.channel("I2C SCL"), "ch_sda": workspace.channel("I2C SDA")},
+        wait=True,
+    )
+    for packet in i2c.packets():
+        print(f"{workspace.capture.seconds(packet.start):.6f}s  {packet.title}: {packet.content}")
+
+    workspace.export_csv("packets.csv", source="packets", instances=[i2c.instance_id])
+```
+
+`server.create` takes a demo key such as `se254`, or `hw:<serial>` for real
+hardware; `server.devices()` lists both. `server.open` takes the path of a
+`.scana` instead, and `server.attach` joins a workspace already running.
+
+⚠️ A demo device generates pseudo-random noise, not protocol traffic. It runs
+the whole path — capture, decode, measure, export — which is what makes it
+useful for writing and testing a script without hardware, but a decoder run on
+it finds structure by chance.
+
+## Read the raw signal
+
+```python
+for edge in workspace.data.transitions(channel=0):
+    print(edge.sample, edge.level)
+```
+
+The iterator pages for you, however long the capture. The first edge it yields
+is the level in force where you started reading, so a window describes itself.
+
+## Find out what a decoder takes
+
+```python
+for option in workspace.decoders.options("i2c.js"):
+    print(option)
+# ch_sda: SDA Channel (ch_selector) = None
+# address_format [Advanced options]: Address display format (combo)
+#     one of ['HEX', 'Binary', 'Decimal'] = 'HEX'
+```
+
+Pass those by id or by caption, as Python values — a channel number, a combo
+entry by name, a flag as `True`. Anything left out keeps the script's default.
+
+## Leave a capture running
+
+The server owns the workspace, so disconnecting destroys nothing. Start a long
+acquisition, go away, and come back to it:
+
+```python
+with ScanaStudio.connect() as server:
+    workspace = server.create("hw:SP259-000123")
+    workspace.capture.start(samples=2_000_000_000)
+    print("running as workspace", workspace.id)
+
+# later, from anywhere
+with ScanaStudio.connect("ws://bench.local:4911") as server:
+    for session in server.workspaces():
+        print(session.workspace_id, session.device_name, session.state)
+    workspace = server.attach(session.workspace_id)
+    workspace.capture.wait()
+```
+
+⚠️ A server listening beyond loopback has **no authentication**: whoever reaches
+the port has the devices.
+
+## What is where
+
+| | |
+|---|---|
+| `server.devices()`, `server.workspaces()` | what you can open, and what is already open |
+| `server.capabilities(device)` | the rates, depths and thresholds it offers |
+| `server.scripts` | the decoder library, which belongs to the server |
+| `workspace.capture` | arming, running and waiting |
+| `workspace.data` | raw edges, packets, items, hex |
+| `workspace.decoders` | attaching and configuring decoders |
+| `workspace.markers` | time markers |
+| `workspace.measures` | measurements between two markers |
+| `workspace.pattern` | the pattern generator |
+| `workspace.events` | everything the server pushes |
+
+## Versions
+
+This SDK speaks protocol 7. `ScanaStudio.connect` refuses a server that speaks
+another, since a mismatch means one of the two needs updating. The protocol
+itself is documented in
+[`api/schema/protocol.md`](https://github.com/ikalogic/scanastudio-v6/blob/main/api/schema/protocol.md).
+
+MIT licensed.

ikalogic_scanastudio-0.2.1/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "ikalogic-scanastudio"
+version = "0.2.1"
+description = "Python SDK for ScanaStudio v6 logic analysers and pattern generators"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "IKALOGIC", email = "contact@ikalogic.com" }]
+keywords = [
+  "scanastudio",
+  "ikalogic",
+  "logic-analyzer",
+  "protocol-decoder",
+  "pattern-generator",
+  "instrumentation",
+  "sdk",
+  "api",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Manufacturing",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Embedded Systems",
+  "Topic :: Scientific/Engineering",
+  "Typing :: Typed",
+]
+requires-python = ">=3.10"
+dependencies = [
+  "pydantic>=2.7",
+  "websockets>=13.0",
+]
+
+[project.urls]
+Homepage = "https://www.ikalogic.com/logic-analyzers/"
+Documentation = "https://www.ikalogic.com/kb/scanastudio-api/"
+Repository = "https://github.com/ikalogic/scanastudio-v6"
+
+[dependency-groups]
+dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6"]
+
+[build-system]
+requires = ["uv_build>=0.5,<0.9"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "ikalogic_scanastudio"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+# Generated: it mirrors the Rust contract, and reformatting it would fight the
+# staleness check that keeps the two in step.
+extend-exclude = ["src/ikalogic_scanastudio/_generated"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+# Generated, and it mirrors the Rust contract rather than Python taste.
+"src/ikalogic_scanastudio/_generated/*" = ["E501"]
+
+[tool.mypy]
+plugins = ["pydantic.mypy"]
+python_version = "3.10"
+strict = true
+files = ["src/ikalogic_scanastudio"]
+
+[[tool.mypy.overrides]]
+module = "ikalogic_scanastudio._generated.*"
+disallow_untyped_defs = false

ikalogic_scanastudio-0.2.1/src/ikalogic_scanastudio/__init__.py

@@ -0,0 +1,121 @@
+"""Python SDK for ScanaStudio v6.
+
+The server owns the workspaces and speaks one WebSocket protocol; this package
+is a typed client for it. Everything the ScanaStudio interface can do, a script
+can do here — capture, decode, measure, generate patterns and export.
+
+    from ikalogic_scanastudio import ScanaStudio, Trigger
+
+    with ScanaStudio.connect() as server:
+        workspace = server.create("se254")
+        workspace.capture.run(
+            samples=1_000_000,
+            sample_rate=25_000_000,
+            trigger=Trigger.rising(channel=0),
+        )
+        i2c = workspace.decoders.add(
+            "i2c.js",
+            {"ch_scl": workspace.channel("I2C SCL"), "ch_sda": workspace.channel("I2C SDA")},
+            wait=True,
+        )
+        for packet in i2c.packets():
+            print(packet.start, packet.title, packet.content)
+"""
+
+from ._core.errors import (
+    Busy,
+    ConnectionClosed,
+    IoError,
+    ProtocolError,
+    Refused,
+    ScanaStudioError,
+    Timeout,
+    VersionMismatch,
+)
+from ._core.frames import Edge, HexByte, HexPage, Item
+from ._core.gui import Option, UnknownOption
+from ._core.state import RUNNING_STATES
+from ._generated.protocol import (
+    PROTOCOL_VERSION,
+    CapabilitiesEvent,
+    ChannelDesc,
+    HexByteDesc,
+    ItemRowDesc,
+    MarkerDesc,
+    MeasureDesc,
+    PacketDesc,
+    RowFilter,
+    ScriptDesc,
+    TriggerRequest,
+    WorkspaceDesc,
+)
+from .capture import DEFAULT_WAIT, CaptureApi
+from .client import DEFAULT_URL, SUPPORTED_PROTOCOLS, Device, ScanaStudio, ServerInfo
+from .data import EDGE_PAGE, PAGE, DataApi
+from .decoders import Decoder, DecodersApi, ScriptError
+from .events import EventsApi
+from .export import DEFAULT_IO_WAIT, EXPORT_SOURCES
+from .markers import MarkersApi
+from .measures import MEASURE_KINDS, MeasuresApi
+from .patterns import PatternApi
+from .scripts import ScriptOpError, ScriptsApi
+from .trigger import SEQUENCES, Trigger, step
+from .workspace import Workspace
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_URL",
+    "DEFAULT_WAIT",
+    "EDGE_PAGE",
+    "DEFAULT_IO_WAIT",
+    "EXPORT_SOURCES",
+    "MEASURE_KINDS",
+    "PAGE",
+    "PROTOCOL_VERSION",
+    "RUNNING_STATES",
+    "SEQUENCES",
+    "SUPPORTED_PROTOCOLS",
+    "Busy",
+    "CapabilitiesEvent",
+    "CaptureApi",
+    "ChannelDesc",
+    "ConnectionClosed",
+    "DataApi",
+    "Decoder",
+    "DecodersApi",
+    "Device",
+    "Edge",
+    "EventsApi",
+    "HexByte",
+    "HexByteDesc",
+    "HexPage",
+    "IoError",
+    "Item",
+    "ItemRowDesc",
+    "MarkerDesc",
+    "MarkersApi",
+    "MeasuresApi",
+    "MeasureDesc",
+    "Option",
+    "PacketDesc",
+    "PatternApi",
+    "ProtocolError",
+    "Refused",
+    "RowFilter",
+    "ScanaStudio",
+    "ScanaStudioError",
+    "ScriptDesc",
+    "ScriptError",
+    "ScriptOpError",
+    "ScriptsApi",
+    "ServerInfo",
+    "Timeout",
+    "Trigger",
+    "TriggerRequest",
+    "UnknownOption",
+    "VersionMismatch",
+    "Workspace",
+    "WorkspaceDesc",
+    "step",
+]

ikalogic_scanastudio-0.2.1/src/ikalogic_scanastudio/_core/errors.py

@@ -0,0 +1,68 @@
+"""What the SDK raises, and why."""
+
+from __future__ import annotations
+
+
+class ScanaStudioError(Exception):
+    """Base of every error this package raises."""
+
+
+class ConnectionClosed(ScanaStudioError):
+    """The server went away while a request was in flight.
+
+    A workspace survives a disconnect: reconnect and attach to its id to pick
+    up where the capture got to.
+    """
+
+
+class ProtocolError(ScanaStudioError):
+    """The server refused a command.
+
+    Attributes:
+        code: Stable and matchable — ``bad_message`` or ``no_workspace``.
+        message: A sentence written by the server, to show as is.
+    """
+
+    def __init__(self, code: str, message: str):
+        super().__init__(f"{message} ({code})")
+        self.code = code
+        self.message = message
+
+
+class Timeout(ScanaStudioError):
+    """No answer arrived in time.
+
+    The server drops nothing it can read, so this usually means the operation
+    is still running rather than lost. Raise the timeout, or wait on the event
+    the operation reports through.
+    """
+
+
+class VersionMismatch(ScanaStudioError):
+    """The server speaks a protocol this SDK does not.
+
+    Attributes:
+        spoken: The protocol version the server announced.
+        supported: The versions this SDK knows.
+    """
+
+    def __init__(self, spoken: int, supported: tuple[int, ...]):
+        listed = ", ".join(str(v) for v in supported)
+        super().__init__(
+            f"the server speaks protocol {spoken}, this SDK speaks {listed}. "
+            "Update whichever is older."
+        )
+        self.spoken = spoken
+        self.supported = supported
+
+
+class IoError(ScanaStudioError):
+    """A save, load or export failed, with the server's own reason."""
+
+
+class Refused(ScanaStudioError):
+    """The server declined to start an acquisition, with its written reason."""
+
+
+class Busy(ScanaStudioError):
+    """The workspace is frozen by a running export, so the command was refused."""

ikalogic_scanastudio-0.2.1/src/ikalogic_scanastudio/_core/frames.py

@@ -0,0 +1,135 @@
+"""Binary frames. They carry the bulk data JSON would make expensive, and their
+layouts live in `api/schema/protocol.md`."""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+from typing import NamedTuple
+
+from .._generated.protocol import BINARY_FRAME_MAGIC
+
+_HEADER = struct.Struct("<II")
+
+
+class FrameHeader(NamedTuple):
+    request_id: int
+    body: bytes
+
+
+def read_header(frame: bytes) -> FrameHeader | None:
+    """Splits `[magic u32 LE][id u32 LE]` off a frame, or None if it is not one."""
+    if len(frame) < _HEADER.size:
+        return None
+    magic, request_id = _HEADER.unpack_from(frame, 0)
+    if magic != BINARY_FRAME_MAGIC:
+        return None
+    return FrameHeader(request_id, frame[_HEADER.size :])
+
+
+class Edge(NamedTuple):
+    """One transition: the channel holds `level` from `sample` until the next."""
+
+    sample: int
+    level: int
+
+
+_EDGE = struct.Struct("<qB")
+
+
+def read_transitions(body: bytes) -> list[Edge]:
+    """`[n u32 LE]` then n × `[sample i64 LE][level u8]`."""
+    (count,) = struct.unpack_from("<I", body, 0)
+    at = 4
+    edges = []
+    for _ in range(count):
+        sample, level = _EDGE.unpack_from(body, at)
+        edges.append(Edge(sample, level))
+        at += _EDGE.size
+    return edges
+
+
+@dataclass(frozen=True)
+class Item:
+    """One decoded item, as the script emitted it."""
+
+    channel: int
+    start: int
+    end: int
+    emphasis: int
+    contents: list[str]
+    """Longest first: a renderer picks the one that fits the width it has."""
+
+
+def read_items(body: bytes) -> list[Item]:
+    """Item records, then the string table their content indices point into."""
+    (count,) = struct.unpack_from("<I", body, 0)
+    at = 4
+    raw: list[tuple[int, int, int, int, list[int]]] = []
+    for _ in range(count):
+        channel, emphasis, n_contents = struct.unpack_from("<HBB", body, at)
+        at += 4
+        start, end = struct.unpack_from("<qq", body, at)
+        at += 16
+        indices = list(struct.unpack_from(f"<{n_contents}I", body, at))
+        at += 4 * n_contents
+        raw.append((channel, emphasis, start, end, indices))
+
+    (n_strings,) = struct.unpack_from("<I", body, at)
+    at += 4
+    table: list[str] = []
+    for _ in range(n_strings):
+        (length,) = struct.unpack_from("<I", body, at)
+        at += 4
+        table.append(body[at : at + length].decode("utf-8", "replace"))
+        at += length
+
+    return [
+        Item(
+            channel=channel,
+            start=start,
+            end=end,
+            emphasis=emphasis,
+            contents=[table[i] for i in indices if i < len(table)],
+        )
+        for channel, emphasis, start, end, indices in raw
+    ]
+
+
+@dataclass(frozen=True)
+class HexByte:
+    """One byte of a decoder's hex view, with the samples it spans."""
+
+    channel: int
+    value: int
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class HexPage:
+    """A page of the hex view, and the generation it belongs to.
+
+    The store is append-only between clears, so a client pulls only the tail.
+    A `generation` that moved means the store was cleared: drop what you cached
+    and start again from offset 0.
+    """
+
+    generation: int
+    total: int
+    bytes: list[HexByte]
+
+
+_HEX = struct.Struct("<HBqq")
+
+
+def read_hex_page(body: bytes) -> HexPage:
+    """`[generation u32][total u32][n u32]` then n × `[ch u16][byte u8][start i64][end i64]`."""
+    generation, total, count = struct.unpack_from("<III", body, 0)
+    at = 12
+    out = []
+    for _ in range(count):
+        channel, value, start, end = _HEX.unpack_from(body, at)
+        out.append(HexByte(channel, value, start, end))
+        at += _HEX.size
+    return HexPage(generation, total, out)