pyTelops 0.2.4__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. {pytelops-0.2.4 → pytelops-0.3.0}/PKG-INFO +4 -2
  2. {pytelops-0.2.4 → pytelops-0.3.0}/README.rst +7 -1
  3. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/changelog.rst +61 -0
  4. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/conf.py +1 -1
  5. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/index.rst +6 -0
  6. pytelops-0.3.0/docs/source/mcp.rst +175 -0
  7. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/troubleshooting.rst +110 -0
  8. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/__init__.py +1 -1
  9. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/camera.py +247 -28
  10. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/cli.py +72 -2
  11. pytelops-0.3.0/pyTelops/doctor.py +550 -0
  12. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/gui.py +11 -0
  13. pytelops-0.3.0/pyTelops/mcp/__init__.py +4 -0
  14. pytelops-0.3.0/pyTelops/mcp/artifacts.py +117 -0
  15. pytelops-0.3.0/pyTelops/mcp/server.py +607 -0
  16. pytelops-0.3.0/pyTelops/mcp/session.py +803 -0
  17. pytelops-0.3.0/pyTelops/mcp/sim.py +495 -0
  18. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/registers.py +2 -2
  19. {pytelops-0.2.4 → pytelops-0.3.0}/pyproject.toml +3 -2
  20. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_camera.py +346 -7
  21. pytelops-0.3.0/tests/test_cli.py +158 -0
  22. pytelops-0.3.0/tests/test_doctor.py +443 -0
  23. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_download_integrity.py +4 -3
  24. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_hardware.py +2 -0
  25. pytelops-0.3.0/tests/test_mcp_server.py +865 -0
  26. pytelops-0.2.4/tests/test_cli.py +0 -62
  27. {pytelops-0.2.4 → pytelops-0.3.0}/.gitignore +0 -0
  28. {pytelops-0.2.4 → pytelops-0.3.0}/AGENTS.md +0 -0
  29. {pytelops-0.2.4 → pytelops-0.3.0}/CONTRIBUTING.rst +0 -0
  30. {pytelops-0.2.4 → pytelops-0.3.0}/LICENSE +0 -0
  31. {pytelops-0.2.4 → pytelops-0.3.0}/PYPI_README.rst +0 -0
  32. {pytelops-0.2.4 → pytelops-0.3.0}/docs/requirements.txt +0 -0
  33. {pytelops-0.2.4 → pytelops-0.3.0}/docs/rtd_postbuild.py +0 -0
  34. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/_static/.gitkeep +0 -0
  35. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/_static/ai-buttons.css +0 -0
  36. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/_static/ai-buttons.js +0 -0
  37. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/_static/logo.png +0 -0
  38. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/calibration.rst +0 -0
  39. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/camera.rst +0 -0
  40. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/examples.rst +0 -0
  41. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/getting_started.rst +0 -0
  42. {pytelops-0.2.4 → pytelops-0.3.0}/docs/source/streaming_and_buffer.rst +0 -0
  43. {pytelops-0.2.4 → pytelops-0.3.0}/examples/01_connect_and_grab.py +0 -0
  44. {pytelops-0.2.4 → pytelops-0.3.0}/examples/02_continuous_live.py +0 -0
  45. {pytelops-0.2.4 → pytelops-0.3.0}/examples/03_buffer_record.py +0 -0
  46. {pytelops-0.2.4 → pytelops-0.3.0}/examples/04_calibration_load.py +0 -0
  47. {pytelops-0.2.4 → pytelops-0.3.0}/examples/05_external_trigger.py +0 -0
  48. {pytelops-0.2.4 → pytelops-0.3.0}/examples/06_force_ip.py +0 -0
  49. {pytelops-0.2.4 → pytelops-0.3.0}/examples/07_robust_download.py +0 -0
  50. {pytelops-0.2.4 → pytelops-0.3.0}/examples/08_pretrigger_software_moi.py +0 -0
  51. {pytelops-0.2.4 → pytelops-0.3.0}/examples/README.rst +0 -0
  52. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/connection.py +0 -0
  53. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/errors.py +0 -0
  54. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/header.py +0 -0
  55. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/provisioning.py +0 -0
  56. {pytelops-0.2.4 → pytelops-0.3.0}/pyTelops/py.typed +0 -0
  57. {pytelops-0.2.4 → pytelops-0.3.0}/requirements.dev.txt +0 -0
  58. {pytelops-0.2.4 → pytelops-0.3.0}/requirements.txt +0 -0
  59. {pytelops-0.2.4 → pytelops-0.3.0}/sync_version.py +0 -0
  60. {pytelops-0.2.4 → pytelops-0.3.0}/tests/conftest.py +0 -0
  61. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_connection.py +0 -0
  62. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_discovery_reachability.py +0 -0
  63. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_enum_resolution.py +0 -0
  64. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_header.py +0 -0
  65. {pytelops-0.2.4 → pytelops-0.3.0}/tests/test_registers.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pyTelops
3
- Version: 0.2.4
3
+ Version: 0.3.0
4
4
  Summary: Pure-Python driver for Telops thermal cameras over GigE Vision
5
5
  Project-URL: Homepage, https://github.com/ladisk/pyTelops
6
6
  Project-URL: Documentation, https://pytelops.readthedocs.io
@@ -25,7 +25,7 @@ Classifier: Topic :: Scientific/Engineering :: Image Processing
25
25
  Classifier: Topic :: System :: Hardware :: Hardware Drivers
26
26
  Requires-Python: >=3.10
27
27
  Requires-Dist: numpy>=1.20
28
- Requires-Dist: pygigevision>=0.2.2
28
+ Requires-Dist: pygigevision>=0.3.0
29
29
  Requires-Dist: tqdm
30
30
  Provides-Extra: dev
31
31
  Requires-Dist: build; extra == 'dev'
@@ -42,6 +42,8 @@ Requires-Dist: wheel; extra == 'dev'
42
42
  Provides-Extra: gui
43
43
  Requires-Dist: matplotlib; extra == 'gui'
44
44
  Requires-Dist: pillow; extra == 'gui'
45
+ Provides-Extra: mcp
46
+ Requires-Dist: mcp<3,>=2.3; extra == 'mcp'
45
47
  Description-Content-Type: text/x-rst
46
48
 
47
49
  pyTelops
@@ -22,6 +22,11 @@ Pure-Python driver for `Telops <https://www.telops.com/>`_ thermal cameras
22
22
  over GigE Vision. No vendor SDK required; communicates directly via GVCP/GVSP
23
23
  protocols over UDP.
24
24
 
25
+ .. image:: hero.gif
26
+ :alt: pyTelops demo: discover and connect to the camera, open a live thermal
27
+ view with cam.live_view(), then record to the camera buffer and
28
+ download the frames
29
+
25
30
  pyTelops is built on `pyGigEVision <https://github.com/ladisk/pyGigEVision>`_,
26
31
  which provides the GigE Vision protocol layer (GVCP control and GVSP
27
32
  streaming). pyTelops adds the Telops-specific calibration, register map, and
@@ -41,7 +46,7 @@ Features
41
46
  - **Live streaming**: real-time frame acquisition
42
47
  - **Subwindow**: configurable resolution for higher frame rates
43
48
  - **Diagnostics**: 13 temperature sensors, NUC trigger, timestamps, voltage/current
44
- - **GUI viewer & CLI**: live thermal display, ``pytelops discover / grab / live``
49
+ - **GUI viewer & CLI**: live thermal display, ``pytelops discover / grab / live / doctor``
45
50
 
46
51
  Installation
47
52
  ------------
@@ -468,6 +473,7 @@ CLI
468
473
  pytelops discover # find cameras on the network
469
474
  pytelops info # show camera configuration
470
475
  pytelops grab -o frame.npy # grab a single frame
476
+ pytelops doctor # check host, network and camera state
471
477
  pytelops live # open live viewer
472
478
  pytelops setup # configure OS (firewall, MTU)
473
479
 
@@ -1,6 +1,67 @@
1
1
  Changelog
2
2
  =========
3
3
 
4
+ Version 0.3.0
5
+ -------------
6
+
7
+ - **Added:** ``pytelops doctor`` checks the host, network, and camera in one
8
+ command and prints a fix for each problem. It is read-only by default.
9
+ ``--stream`` tests frame delivery, ``--json`` prints one JSON object, and the
10
+ exit code is 0 (ok), 1 (warning), or 2 (failure).
11
+ - **Added:** ``pytelops mcp`` starts a Model Context Protocol server, so an AI
12
+ assistant such as Claude Code can connect to the camera, change settings,
13
+ grab frames, and record and download buffer sequences. Install it with
14
+ ``pip install "pyTelops[mcp]"``. ``--simulate`` runs it without a camera.
15
+ See :doc:`mcp`.
16
+ - **Added:** ``Camera.connect(force_control=False)`` raises ``GVCPError`` at
17
+ once on ``ACCESS_DENIED``. The default ``True`` still waits up to 15 s for a
18
+ stale control lock to expire.
19
+ - **Added:** ``grab()``, ``acquire()`` and the live viewer now warn when the
20
+ camera reports acquiring but sends no frames. The warning uses the stream
21
+ statistics of pyGigEVision 0.3 to tell a camera that sends no data from
22
+ packet loss, and points to the troubleshooting page. These changes help
23
+ diagnose issue #28. They do not fix its root cause.
24
+ - **Changed:** pyTelops now needs pyGigEVision 0.3.0 or later and uses only its
25
+ public API.
26
+ - **Changed:** ``Camera.write_register()`` now refuses to write the stream
27
+ packet size register while acquisition is running. Such a write can leave
28
+ the stream channel unusable until a power cycle (issue #28).
29
+ - **Fixed:** ``roi_offset`` failed with ``GVCPError`` (GENERIC_ERROR) on
30
+ the offset write, for example ``cam.roi_offset = (0, 0)`` after
31
+ connect to a camera already at full frame (issue #29). The setter now writes
32
+ only the offsets that change. If a write still fails because CenterImage is
33
+ on, the error says so. If the camera also locks CenterImage on
34
+ (``LockedCenterImage``, new constant ``REG_LOCKED_CENTER_IMAGE``), the error
35
+ says that the window is always centered and the offsets cannot be set. The
36
+ LADISK FAST M3k has this lock.
37
+ - **Fixed:** ``start_stream()`` now raises a ``GVCPError`` with a clear
38
+ message when the camera rejects the packet size. The message says whether
39
+ the camera is still acquiring from an earlier session or needs a power
40
+ cycle (issue #28).
41
+ - **Fixed:** a script that ends without ``disconnect()`` now releases the
42
+ camera at exit. ``pytelops live`` also handles SIGTERM and SIGHUP, so a
43
+ killed viewer stops acquisition before it exits.
44
+
45
+ Version 0.2.5
46
+ -------------
47
+
48
+ - **Fixed:** ``grab()`` and ``acquire()`` could return a frame left over from a
49
+ previous session, still sitting in the GVSP receiver's queue. Right after a
50
+ setting change, such as switching ``calibration_mode``, the first grab or two
51
+ came back captured under the old setting (issue #21). Both methods now
52
+ discard queued and buffered residue before waiting for a frame: a full
53
+ receiver flush when the stream was not already running, or a non-blocking
54
+ drain of the output queue when it was.
55
+ - **Fixed:** ``Camera.temperature`` and ``info["temperature_c"]`` always read
56
+ 0.0 (issue #20). They read address 0xE970, which the camera's GenICam XML
57
+ defines as the external fan speed mode, not a temperature. Both now return
58
+ the detector temperature, the same as ``sensor_temperature("sensor")``. The
59
+ wrong ``registers.REG_DEVICE_TEMPERATURE`` constant is removed; use
60
+ ``REG_DEVICE_TEMPERATURE_SELECTOR`` and ``REG_DEVICE_TEMPERATURE_READOUT``.
61
+ - **Fixed:** ``diagnostics()`` reported the mainboard temperature as 0.0 on the
62
+ TS-IR, which has no mainboard sensor. A readout of exactly 0.0 now maps to
63
+ ``None``, like other unsupported locations.
64
+
4
65
  Version 0.2.4
5
66
  -------------
6
67
 
@@ -10,7 +10,7 @@ sys.path.insert(0, os.path.abspath("../.."))
10
10
  project = "pyTelops"
11
11
  author = "Jaša Šonc, Janko Slavič"
12
12
  copyright = "2026, Jaša Šonc and Ladisk group, University of Ljubljana"
13
- release = "0.2.4"
13
+ release = "0.3.0"
14
14
  # -- General configuration ---------------------------------------------------
15
15
  extensions = [
16
16
  "sphinx.ext.autodoc",
@@ -6,6 +6,11 @@ over GigE Vision. No vendor SDK required: pyTelops speaks the GVCP and GVSP
6
6
  protocols directly over UDP, on top of `pyGigEVision
7
7
  <https://github.com/ladisk/pyGigEVision>`_.
8
8
 
9
+ .. image:: ../../hero.gif
10
+ :alt: pyTelops demo: discover and connect to the camera, open a live thermal
11
+ view with cam.live_view(), then record to the camera buffer and
12
+ download the frames
13
+
9
14
  Quickstart
10
15
  ----------
11
16
 
@@ -30,6 +35,7 @@ Contents
30
35
  camera
31
36
  calibration
32
37
  streaming_and_buffer
38
+ mcp
33
39
  examples
34
40
  troubleshooting
35
41
  changelog
@@ -0,0 +1,175 @@
1
+ MCP server
2
+ ==========
3
+
4
+ ``pytelops mcp`` runs a Model Context Protocol (MCP) server for the camera.
5
+ An AI assistant such as Claude Code can then connect to the camera, change
6
+ settings, grab frames, and record and download buffer sequences.
7
+ The server talks over stdio. It controls one camera.
8
+
9
+ Install
10
+ -------
11
+
12
+ Install the ``mcp`` extra:
13
+
14
+ .. code-block:: bash
15
+
16
+ pip install "pyTelops[mcp]"
17
+
18
+ The extra needs the official ``mcp`` package, version 2.3 or later.
19
+
20
+ Set up Claude Code
21
+ ------------------
22
+
23
+ Register the server and choose a data folder:
24
+
25
+ .. code-block:: bash
26
+
27
+ claude mcp add telops -- pytelops mcp --data-dir ~/takes/telops
28
+
29
+ The default data folder is ``./pytelops-data``. The server creates it when it
30
+ saves the first file. The server finds the camera by network discovery at each
31
+ connect. Other MCP clients use the same command.
32
+
33
+ Tools
34
+ -----
35
+
36
+ .. list-table::
37
+ :header-rows: 1
38
+ :widths: 24 76
39
+
40
+ * - Tool
41
+ - Action
42
+ * - ``camera_doctor``
43
+ - Check host, network, and camera. ``stream=true`` also tests frame delivery. It needs the camera disconnected.
44
+ * - ``camera_connect``
45
+ - Find and connect to the camera. Runs as a job. Optional ``ip``.
46
+ * - ``camera_disconnect``
47
+ - Disconnect and release control.
48
+ * - ``camera_status``
49
+ - Connection, settings, sensor temperature, buffer state, and current job.
50
+ * - ``camera_configure``
51
+ - Set only the given fields: size, offset, integration time, frame rate, calibration mode. Returns the actual values and any clamps.
52
+ * - ``camera_grab``
53
+ - Grab 1 to 500 frames. Saves ``.npy``, a PNG preview, and JSON. Returns statistics and the preview image.
54
+ * - ``buffer_record``
55
+ - Record into the camera memory. Runs as a job. Refuses if the memory holds recordings.
56
+ * - ``buffer_download``
57
+ - Download one recorded sequence to a raw ``.npy`` file. Runs as a job.
58
+ * - ``buffer_clear``
59
+ - Delete all recordings in the camera memory. Needs ``confirm=true``.
60
+ * - ``camera_nuc``
61
+ - Run a non-uniformity correction. Needs ``confirm=true``. Takes up to 60 s.
62
+ * - ``job_status``
63
+ - State, progress, message, and result or error of a job.
64
+ * - ``job_cancel``
65
+ - Ask a job to stop.
66
+
67
+ Jobs and polling
68
+ ----------------
69
+
70
+ Connect, record, and download can take minutes. They run as jobs in a
71
+ background thread. The tool returns a ``job_id`` at once.
72
+
73
+ Poll ``job_status`` with that ``job_id``. The state is ``running``, ``done``,
74
+ ``failed``, or ``cancelled``. A finished job holds a ``result`` or an ``error``.
75
+
76
+ Only one job runs at a time. While a job runs, other camera tools refuse and
77
+ name the running job. ``job_status``, ``job_cancel``, and ``camera_status``
78
+ still work.
79
+
80
+ ``camera_status`` does not read the camera during a job. Some buffer reads
81
+ write camera registers. The tool returns the snapshot from the last finished
82
+ call and sets ``live`` to ``false``.
83
+
84
+ ``job_cancel`` stops a job at its next check:
85
+
86
+ - Record stops within about 0.5 s and stops the acquisition.
87
+ - Download stops after the current slice of up to 1000 frames.
88
+ - Connect stops during the cooldown wait, within about 3 s.
89
+
90
+ ``camera_connect`` returns the result at once if the camera is ready. If the
91
+ camera is still cooling, the tool returns a job. A cold camera can need up to
92
+ 10 minutes.
93
+
94
+ Data layout
95
+ -----------
96
+
97
+ .. code-block:: text
98
+
99
+ <data dir>/
100
+ grabs/
101
+ grab_20261118_101500.npy frames, shape (N, H, W)
102
+ grab_20261118_101500.png preview of the first frame
103
+ grab_20261118_101500.json settings and statistics
104
+ downloads/
105
+ download_20261118_102000.npy uint16, shape (N, H+2, W)
106
+ download_20261118_102000.json metadata
107
+
108
+ Names come from the time in UTC. Use the ``name`` argument to choose a name.
109
+ A name can hold letters, digits, ``.``, ``_``, and ``-``. The server never
110
+ overwrites a file.
111
+
112
+ A download keeps the two header rows of each frame and the raw uint16 values.
113
+ The server writes the file slice by slice. The JSON file shows ``complete``,
114
+ ``state``, ``frames_written``, and ``integrity_ok``. If a download is
115
+ cancelled or fails, the ``.npy`` file is partial. Frames after
116
+ ``frames_written`` are zeros.
117
+
118
+ ``integrity_ok`` is ``false`` if frames are missing, if any frame ID differs from the requested
119
+ range, or if the driver counted out-of-order or strided frames. Download the sequence again in that case.
120
+
121
+ Convert a download to Celsius
122
+ -----------------------------
123
+
124
+ Each frame carries its own conversion data in the header rows. In RT mode
125
+ (``calibration_mode`` 2), convert each frame:
126
+
127
+ .. code-block:: python
128
+
129
+ import numpy as np
130
+ from pyTelops import parse_header
131
+
132
+ raw = np.load("downloads/rec1.npy", mmap_mode="r")
133
+ frame = np.asarray(raw[0])
134
+ h = parse_header(frame)
135
+ celsius = frame[2:].astype(np.float32) * 2.0**h.data_exp + h.data_offset - 273.15
136
+
137
+ In NUC and RAW modes, ``data_exp`` and ``data_offset`` are zero. The values
138
+ are counts. The JSON ``header`` block holds the values of the first frame.
139
+ Read the header of each frame if the integration time or the calibration
140
+ changed during the recording.
141
+
142
+ Safety rules
143
+ ------------
144
+
145
+ - ``buffer_clear`` and ``camera_nuc`` do nothing without ``confirm=true``. The
146
+ assistant must ask you first.
147
+ - For a ``black_body`` NUC, put a uniform black body or a lens cap in front of
148
+ the lens before you confirm.
149
+ - ``buffer_record`` refuses to run while the camera memory holds recordings.
150
+ Download them, then call ``buffer_clear`` with ``confirm=true``.
151
+ - Buffer mode stays on after a recording. ``camera_grab`` and ``camera_configure``
152
+ turn it off. If the memory still holds recordings, they refuse. Download and clear first.
153
+ - Only one client controls the camera. If another program holds it, connect
154
+ fails with ``ACCESS_DENIED``. Close the other program and try again. A lock
155
+ from a crashed session expires after about 15 s.
156
+ - Do not use the Telops software, ``pytelops live``, or a Python session at
157
+ the same time.
158
+ - If registers stay locked or frames stop, power-cycle the camera.
159
+ - The server stops the running job and disconnects when the client closes
160
+ stdin or when the process gets SIGINT or SIGTERM.
161
+
162
+ The server never writes to stdout, because stdout carries the protocol.
163
+ Driver messages go to stderr.
164
+
165
+ Simulate mode
166
+ -------------
167
+
168
+ Start the server with ``--simulate`` to test without a camera:
169
+
170
+ .. code-block:: bash
171
+
172
+ pytelops mcp --simulate --data-dir /tmp/telops-sim
173
+
174
+ The simulated camera makes synthetic frames with header rows. It supports all
175
+ tools. Frame IDs start at 1000, as on the real camera.
@@ -4,6 +4,45 @@ Troubleshooting
4
4
  Symptoms, causes, and fixes for the most common issues you may
5
5
  encounter while using pyTelops.
6
6
 
7
+ Run ``pytelops doctor`` first
8
+ -----------------------------
9
+
10
+ Run this command first in every camera session. It prints one line per
11
+ check and tells you the fix for each problem.
12
+
13
+ .. code-block:: bash
14
+
15
+ pytelops doctor
16
+ pytelops doctor --json
17
+ pytelops doctor --ip 169.254.1.10 --stream --frames 50
18
+
19
+ The command is read-only by default. It does not take control of the camera.
20
+ It checks:
21
+
22
+ - USB and Ethernet adapters: driver, USB ID, carrier, MTU, known bad adapters.
23
+ - ``net.core.rmem_max`` (Linux).
24
+ - Camera discovery, and whether the OS routes the camera IP through the
25
+ adapter that found it.
26
+ - Camera state, read without control: TDC status, readiness, stream
27
+ channel, and whether another application holds control.
28
+ - The ARP entry for the camera (Linux).
29
+
30
+ Add ``--stream`` to connect and receive ``--frames`` frames (default 20). This
31
+ changes camera state. The command connects, applies the pyTelops defaults,
32
+ runs free-run acquisition, restores the packet size and delay registers, and
33
+ disconnects. It counts incomplete frames and gaps in the block IDs. It is
34
+ skipped when trigger mode is on or the memory buffer is in use.
35
+
36
+ Add ``--json`` for scripts and agents. The command prints one JSON object
37
+ with ``summary`` (counts per status), ``problems`` (every warning and
38
+ failure), and ``camera`` (IP, MAC, model, serial, firmware, TDC flags).
39
+
40
+ Exit codes:
41
+
42
+ - ``0``: all checks are ``ok`` or ``skip``.
43
+ - ``1``: at least one warning.
44
+ - ``2``: at least one failure.
45
+
7
46
  Camera not found on ``discover()`` / ``connect()``
8
47
  --------------------------------------------------
9
48
 
@@ -72,6 +111,53 @@ After ``force_ip`` returns, allow about a second for the camera to apply
72
111
  the new address before calling ``discover()`` again. Choose an address on
73
112
  one of your host NIC subnets so the re-discovered result is reachable.
74
113
 
114
+ Linux USB Ethernet adapters
115
+ ---------------------------
116
+
117
+ Some USB Ethernet adapters cause discovery or stream problems on Linux.
118
+
119
+ **ASIX AX88179 (0b95:1790).** After a replug, the adapter often comes up on
120
+ the generic ``cdc_ncm`` driver. Use the vendor driver ``ax88179_178a``. To
121
+ switch by hand, select USB configuration 1:
122
+
123
+ .. code-block:: bash
124
+
125
+ echo 1 | sudo tee /sys/bus/usb/devices/<port>/bConfigurationValue
126
+
127
+ Find ``<port>`` with ``lsusb -t`` or in ``/sys/bus/usb/devices``.
128
+
129
+ With the vendor driver, ARP to the camera only resolved in promiscuous mode.
130
+ Enable it:
131
+
132
+ .. code-block:: bash
133
+
134
+ sudo ip link set <iface> promisc on
135
+
136
+ To do both steps at each plug-in, install this udev rule:
137
+
138
+ .. code-block:: bash
139
+
140
+ sudo tee /etc/udev/rules.d/90-pytelops-usb-ethernet.rules >/dev/null <<'RULES'
141
+ # ASIX AX88179: vendor driver (configuration 1), not cdc_ncm
142
+ ACTION=="add", SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTR{idVendor}=="0b95", ATTR{idProduct}=="1790", ATTR{bConfigurationValue}!="1", ATTR{bConfigurationValue}="1"
143
+ # ASIX AX88179: promiscuous mode, needed for ARP to the camera
144
+ ACTION=="add", SUBSYSTEM=="net", DRIVERS=="ax88179_178a", RUN+="/usr/bin/ip link set dev $name promisc on"
145
+ RULES
146
+ sudo udevadm control --reload
147
+
148
+ Then replug the adapter. Check with ``lsusb -t`` (``Driver=ax88179_178a``)
149
+ and ``ip link show <iface>`` (``PROMISC``).
150
+
151
+ **TP-Link USB 3.0 adapter (2357:0601, RTL8153, driver r8152).** This adapter
152
+ dropped most stream packets and reset in a loop. The resets stopped when USB
153
+ link power management (LPM) was off. Add this kernel parameter:
154
+
155
+ .. code-block:: text
156
+
157
+ usbcore.quirks=0bda:0411:k,2357:0601:k
158
+
159
+ Do not use this adapter for streaming.
160
+
75
161
  ``ACCESS_DENIED`` on reconnect
76
162
  ------------------------------
77
163
 
@@ -87,6 +173,30 @@ heartbeat timeout expires.
87
173
  camera and auto-recovers once the heartbeat timeout elapses. If it
88
174
  takes longer, power-cycle the camera.
89
175
 
176
+ Camera acquires but sends no data
177
+ ---------------------------------
178
+
179
+ **Symptom:** The TDC status shows that acquisition has started. GVCP
180
+ commands work. ``grab()`` returns ``None`` or the live viewer stays empty.
181
+ pyTelops warns that the camera reports acquiring but no complete frame
182
+ arrived, and that no stream packet arrived.
183
+
184
+ If the warning says that stream packets arrive, the cause is packet loss, not
185
+ a dead stream channel. See the next section.
186
+
187
+ **Cause:** Not confirmed. It was seen after sessions that ended abruptly,
188
+ and with a faulty Ethernet adapter or driver. The stream channel of the camera
189
+ then possibly stays in a bad state.
190
+
191
+ **Fix:**
192
+
193
+ 1. Stop the program.
194
+ 2. Power-cycle the camera.
195
+ 3. Run ``discover()`` again.
196
+
197
+ The link-local IP address of the camera can change after a power cycle. Use
198
+ discovery. Do not reuse the old address.
199
+
90
200
  Live streaming: ``packets unrecoverable`` warnings
91
201
  --------------------------------------------------
92
202
 
@@ -18,7 +18,7 @@ Usage::
18
18
 
19
19
  from __future__ import annotations
20
20
 
21
- __version__ = "0.2.4"
21
+ __version__ = "0.3.0"
22
22
  from pyGigEVision import GVCPClient, GVCPError
23
23
 
24
24
  from .camera import Camera, discover