ponkan-python 0.1.0__py3-none-any.whl
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.
- ponkan_python-0.1.0.dist-info/METADATA +157 -0
- ponkan_python-0.1.0.dist-info/RECORD +39 -0
- ponkan_python-0.1.0.dist-info/WHEEL +4 -0
- ponkan_python-0.1.0.dist-info/entry_points.txt +5 -0
- ponkan_python-0.1.0.dist-info/licenses/LICENSE +22 -0
- ponkan_python-0.1.0.dist-info/licenses/NOTICE.md +14 -0
- py3dscapture/__init__.py +36 -0
- py3dscapture/artifacts.py +66 -0
- py3dscapture/capture.py +599 -0
- py3dscapture/devices/__init__.py +1 -0
- py3dscapture/devices/n3dsxl_ftd3.py +238 -0
- py3dscapture/errors.py +120 -0
- py3dscapture/hardware_gate.py +143 -0
- py3dscapture/image/__init__.py +1 -0
- py3dscapture/image/frame.py +166 -0
- py3dscapture/protocol/__init__.py +1 -0
- py3dscapture/protocol/layout_3ds.py +60 -0
- py3dscapture/protocol/n3dsxl.py +249 -0
- py3dscapture/protocol/sizes.py +128 -0
- py3dscapture/py.typed +1 -0
- py3dscapture/streaming/__init__.py +1 -0
- py3dscapture/streaming/buffers.py +156 -0
- py3dscapture/streaming/engine.py +285 -0
- py3dscapture/streaming/policies.py +157 -0
- py3dscapture/streaming/stats.py +254 -0
- py3dscapture/tools/__init__.py +1 -0
- py3dscapture/tools/capture_raw.py +44 -0
- py3dscapture/tools/list_devices.py +68 -0
- py3dscapture/tools/raw_to_png.py +251 -0
- py3dscapture/tools/stream_n3dsxl.py +152 -0
- py3dscapture/transport/__init__.py +1 -0
- py3dscapture/transport/d3xx_backend.py +850 -0
- py3dscapture/transport/d3xx_native.py +268 -0
- py3dscapture/transport/d3xx_native_streaming.py +306 -0
- py3dscapture/transport/d3xx_streaming.py +202 -0
- py3dscapture/transport/ftd3_backend.py +275 -0
- py3dscapture/transport/ftd3_pipe.py +387 -0
- py3dscapture/transport/libusb_async.py +134 -0
- py3dscapture/transport/libusb_backend.py +357 -0
|
@@ -0,0 +1,850 @@
|
|
|
1
|
+
# ruff: noqa: N802
|
|
2
|
+
"""Optional FTDI D3XX backend boundary."""
|
|
3
|
+
|
|
4
|
+
import ctypes
|
|
5
|
+
from collections.abc import Iterator, Mapping
|
|
6
|
+
from contextlib import contextmanager
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from importlib import import_module
|
|
9
|
+
from types import ModuleType
|
|
10
|
+
from typing import Any, Literal, Protocol, cast
|
|
11
|
+
|
|
12
|
+
from py3dscapture.devices.n3dsxl_ftd3 import DeviceCandidate, classify_n3dsxl_device
|
|
13
|
+
from py3dscapture.errors import CaptureError, OptionalDependencyError
|
|
14
|
+
from py3dscapture.protocol.sizes import N3DSXL_VENDOR_ID
|
|
15
|
+
from py3dscapture.transport.libusb_backend import UsbDeviceInfo
|
|
16
|
+
|
|
17
|
+
FT_OK = 0
|
|
18
|
+
D3XX_OPEN_BY_SERIAL_NUMBER = 0x01
|
|
19
|
+
D3XX_OPEN_BY_INDEX = 0x10
|
|
20
|
+
D3XX_DEFAULT_TIMEOUT_MS = 500
|
|
21
|
+
PYD3XX_MODULE_NAMES = ("PyD3XX", "pyd3xx")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class D3xxBinding(Protocol):
|
|
25
|
+
"""Subset of the PyD3XX module needed for device enumeration and I/O.
|
|
26
|
+
|
|
27
|
+
The real package exposes module-level functions and factory classes. This
|
|
28
|
+
protocol describes only the calls used by ``D3xxBackend`` and ``D3xxHandle``.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
FT_Pipe: Any
|
|
32
|
+
FT_Buffer: Any
|
|
33
|
+
|
|
34
|
+
def FT_CreateDeviceInfoList(self) -> tuple[int, int]:
|
|
35
|
+
"""Return D3XX status and number of devices.
|
|
36
|
+
|
|
37
|
+
Returns:
|
|
38
|
+
``(status, count)`` where status must be ``FT_OK``.
|
|
39
|
+
"""
|
|
40
|
+
...
|
|
41
|
+
|
|
42
|
+
def FT_GetDeviceInfoDetail(self, index: int) -> tuple[int, object]:
|
|
43
|
+
"""Return D3XX status and one device information node.
|
|
44
|
+
|
|
45
|
+
Args:
|
|
46
|
+
index: Zero-based device index in the current D3XX device list.
|
|
47
|
+
|
|
48
|
+
Returns:
|
|
49
|
+
``(status, detail)`` where detail contains ID, description,
|
|
50
|
+
serial-number, and flag fields.
|
|
51
|
+
"""
|
|
52
|
+
...
|
|
53
|
+
|
|
54
|
+
def FT_Create(self, identifier: object, open_flag: int, device: object) -> int:
|
|
55
|
+
"""Open a D3XX device into an initialized FT_Device object.
|
|
56
|
+
|
|
57
|
+
Args:
|
|
58
|
+
identifier: Serial number or index used by the selected open flag.
|
|
59
|
+
open_flag: D3XX open mode such as serial-number or index.
|
|
60
|
+
device: Device detail object to initialize.
|
|
61
|
+
|
|
62
|
+
Returns:
|
|
63
|
+
D3XX status code.
|
|
64
|
+
"""
|
|
65
|
+
...
|
|
66
|
+
|
|
67
|
+
def FT_Close(self, device: object) -> int:
|
|
68
|
+
"""Close an opened D3XX device object.
|
|
69
|
+
|
|
70
|
+
Args:
|
|
71
|
+
device: Open D3XX device object.
|
|
72
|
+
|
|
73
|
+
Returns:
|
|
74
|
+
D3XX status code.
|
|
75
|
+
"""
|
|
76
|
+
...
|
|
77
|
+
|
|
78
|
+
def FT_AbortPipe(self, device: object, pipe: object) -> int:
|
|
79
|
+
"""Abort one D3XX native pipe.
|
|
80
|
+
|
|
81
|
+
Args:
|
|
82
|
+
device: Open D3XX device object.
|
|
83
|
+
pipe: D3XX pipe object with the selected pipe ID.
|
|
84
|
+
|
|
85
|
+
Returns:
|
|
86
|
+
D3XX status code.
|
|
87
|
+
"""
|
|
88
|
+
...
|
|
89
|
+
|
|
90
|
+
def FT_SetStreamPipe(
|
|
91
|
+
self,
|
|
92
|
+
device: object,
|
|
93
|
+
all_write_pipes: bool,
|
|
94
|
+
all_read_pipes: bool,
|
|
95
|
+
pipe: object,
|
|
96
|
+
stream_size: int,
|
|
97
|
+
) -> int:
|
|
98
|
+
"""Configure streaming for one D3XX native pipe.
|
|
99
|
+
|
|
100
|
+
Args:
|
|
101
|
+
device: Open D3XX device object.
|
|
102
|
+
all_write_pipes: Whether all write pipes should be affected.
|
|
103
|
+
all_read_pipes: Whether all read pipes should be affected.
|
|
104
|
+
pipe: D3XX pipe object with the selected pipe ID.
|
|
105
|
+
stream_size: Stream transfer size in bytes.
|
|
106
|
+
|
|
107
|
+
Returns:
|
|
108
|
+
D3XX status code.
|
|
109
|
+
"""
|
|
110
|
+
...
|
|
111
|
+
|
|
112
|
+
def FT_ReadPipe(
|
|
113
|
+
self,
|
|
114
|
+
device: object,
|
|
115
|
+
pipe: object,
|
|
116
|
+
buffer_length: int,
|
|
117
|
+
overlapped_timeout_ms: int,
|
|
118
|
+
) -> tuple[int, object, int]:
|
|
119
|
+
"""Read bytes from one D3XX native pipe.
|
|
120
|
+
|
|
121
|
+
Args:
|
|
122
|
+
device: Open D3XX device object.
|
|
123
|
+
pipe: D3XX pipe object with the selected pipe ID.
|
|
124
|
+
buffer_length: Maximum read length in bytes.
|
|
125
|
+
overlapped_timeout_ms: Read timeout in milliseconds.
|
|
126
|
+
|
|
127
|
+
Returns:
|
|
128
|
+
``(status, buffer, transferred)``.
|
|
129
|
+
"""
|
|
130
|
+
...
|
|
131
|
+
|
|
132
|
+
def FT_ReadPipeEx(
|
|
133
|
+
self,
|
|
134
|
+
device: object,
|
|
135
|
+
pipe: object,
|
|
136
|
+
buffer_length: int,
|
|
137
|
+
overlapped_timeout_ms: int,
|
|
138
|
+
) -> tuple[int, object, int]:
|
|
139
|
+
"""Read bytes from one D3XX native stream pipe.
|
|
140
|
+
|
|
141
|
+
Args:
|
|
142
|
+
device: Open D3XX device object.
|
|
143
|
+
pipe: D3XX pipe object with the selected pipe ID.
|
|
144
|
+
buffer_length: Maximum read length in bytes.
|
|
145
|
+
overlapped_timeout_ms: Read timeout in milliseconds.
|
|
146
|
+
|
|
147
|
+
Returns:
|
|
148
|
+
``(status, buffer, transferred)``.
|
|
149
|
+
"""
|
|
150
|
+
...
|
|
151
|
+
|
|
152
|
+
def FT_WritePipe(
|
|
153
|
+
self,
|
|
154
|
+
device: object,
|
|
155
|
+
pipe: object,
|
|
156
|
+
buffer: object,
|
|
157
|
+
buffer_length: int,
|
|
158
|
+
overlapped_timeout_ms: int,
|
|
159
|
+
) -> tuple[int, int]:
|
|
160
|
+
"""Write bytes to one D3XX native pipe.
|
|
161
|
+
|
|
162
|
+
Args:
|
|
163
|
+
device: Open D3XX device object.
|
|
164
|
+
pipe: D3XX pipe object with the selected pipe ID.
|
|
165
|
+
buffer: D3XX buffer object containing payload bytes.
|
|
166
|
+
buffer_length: Number of bytes to write.
|
|
167
|
+
overlapped_timeout_ms: Write timeout in milliseconds.
|
|
168
|
+
|
|
169
|
+
Returns:
|
|
170
|
+
``(status, transferred)``.
|
|
171
|
+
"""
|
|
172
|
+
...
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
class D3xxBackendError(CaptureError):
|
|
176
|
+
"""Raised when a D3XX API call fails or returns unsupported data.
|
|
177
|
+
|
|
178
|
+
Attributes:
|
|
179
|
+
function: D3XX function or parser step associated with the failure.
|
|
180
|
+
status: Optional native status code.
|
|
181
|
+
field_name: Optional detail field that was missing or invalid.
|
|
182
|
+
"""
|
|
183
|
+
|
|
184
|
+
def __init__(
|
|
185
|
+
self,
|
|
186
|
+
function: str,
|
|
187
|
+
status: int | None = None,
|
|
188
|
+
*,
|
|
189
|
+
field_name: str | None = None,
|
|
190
|
+
) -> None:
|
|
191
|
+
"""Create a structured D3XX backend failure.
|
|
192
|
+
|
|
193
|
+
Args:
|
|
194
|
+
function: D3XX function or parser step associated with the failure.
|
|
195
|
+
status: Optional native status code.
|
|
196
|
+
field_name: Optional detail field that was missing or invalid.
|
|
197
|
+
"""
|
|
198
|
+
message = _d3xx_error_message(function, status, field_name)
|
|
199
|
+
super().__init__(message)
|
|
200
|
+
self.function = function
|
|
201
|
+
self.status = status
|
|
202
|
+
self.field_name = field_name
|
|
203
|
+
|
|
204
|
+
@classmethod
|
|
205
|
+
def missing_field(cls, field_name: str) -> "D3xxBackendError":
|
|
206
|
+
"""Create an error for an unsupported D3XX detail shape.
|
|
207
|
+
|
|
208
|
+
Args:
|
|
209
|
+
field_name: Required field that was not present.
|
|
210
|
+
|
|
211
|
+
Returns:
|
|
212
|
+
Structured backend error.
|
|
213
|
+
"""
|
|
214
|
+
return cls("missing field", field_name=field_name)
|
|
215
|
+
|
|
216
|
+
@classmethod
|
|
217
|
+
def invalid_integer(cls, field_name: str) -> "D3xxBackendError":
|
|
218
|
+
"""Create an error for an integer field that cannot be parsed.
|
|
219
|
+
|
|
220
|
+
Args:
|
|
221
|
+
field_name: Integer field that could not be converted.
|
|
222
|
+
|
|
223
|
+
Returns:
|
|
224
|
+
Structured backend error.
|
|
225
|
+
"""
|
|
226
|
+
return cls("invalid integer", field_name=field_name)
|
|
227
|
+
|
|
228
|
+
@classmethod
|
|
229
|
+
def invalid_candidate(cls) -> "D3xxBackendError":
|
|
230
|
+
"""Create an error for an unsupported D3XX candidate object.
|
|
231
|
+
|
|
232
|
+
Returns:
|
|
233
|
+
Structured backend error for a wrong candidate type.
|
|
234
|
+
"""
|
|
235
|
+
return cls("invalid candidate")
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
@dataclass(frozen=True, slots=True)
|
|
239
|
+
class D3xxDeviceInfo:
|
|
240
|
+
"""D3XX listing information normalized for N3DSXL classification.
|
|
241
|
+
|
|
242
|
+
Attributes:
|
|
243
|
+
index: Zero-based D3XX device index.
|
|
244
|
+
usb_info: USB identity reconstructed from D3XX detail fields.
|
|
245
|
+
flags: Optional D3XX flags field.
|
|
246
|
+
device_id: Raw D3XX device ID containing VID/PID information.
|
|
247
|
+
"""
|
|
248
|
+
|
|
249
|
+
index: int
|
|
250
|
+
usb_info: UsbDeviceInfo
|
|
251
|
+
flags: int | None
|
|
252
|
+
device_id: int
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
@dataclass(frozen=True, slots=True)
|
|
256
|
+
class D3xxDeviceCandidate:
|
|
257
|
+
"""N3DSXL candidate found through the D3XX driver backend.
|
|
258
|
+
|
|
259
|
+
Attributes:
|
|
260
|
+
candidate: Accepted N3DSXL candidate after USB identity classification.
|
|
261
|
+
index: Zero-based D3XX device index.
|
|
262
|
+
flags: Optional D3XX flags field.
|
|
263
|
+
device_id: Raw D3XX device ID containing VID/PID information.
|
|
264
|
+
backend_kind: Normalized backend label for metadata.
|
|
265
|
+
"""
|
|
266
|
+
|
|
267
|
+
candidate: DeviceCandidate
|
|
268
|
+
index: int
|
|
269
|
+
flags: int | None
|
|
270
|
+
device_id: int
|
|
271
|
+
backend_kind: str = "d3xx"
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
class D3xxHandle:
|
|
275
|
+
"""Opened D3XX handle with idempotent close.
|
|
276
|
+
|
|
277
|
+
The handle implements the pipe operations expected by ``N3DSXLProtocol`` and
|
|
278
|
+
records which pipes were configured for stream reads.
|
|
279
|
+
"""
|
|
280
|
+
|
|
281
|
+
backend_kind: Literal["d3xx"] = "d3xx"
|
|
282
|
+
|
|
283
|
+
def __init__(
|
|
284
|
+
self,
|
|
285
|
+
binding: D3xxBinding,
|
|
286
|
+
device: object,
|
|
287
|
+
candidate: DeviceCandidate,
|
|
288
|
+
d3xx_candidate: D3xxDeviceCandidate | None = None,
|
|
289
|
+
) -> None:
|
|
290
|
+
"""Create a handle from an opened PyD3XX device detail object.
|
|
291
|
+
|
|
292
|
+
Args:
|
|
293
|
+
binding: PyD3XX-compatible module binding.
|
|
294
|
+
device: Open D3XX device detail object.
|
|
295
|
+
candidate: Accepted N3DSXL candidate for metadata.
|
|
296
|
+
d3xx_candidate: Original D3XX candidate, required for reconnect.
|
|
297
|
+
"""
|
|
298
|
+
self._binding = binding
|
|
299
|
+
self._device = device
|
|
300
|
+
self.candidate = candidate
|
|
301
|
+
self._d3xx_candidate = d3xx_candidate
|
|
302
|
+
self._closed = False
|
|
303
|
+
self._stream_pipes: set[int] = set()
|
|
304
|
+
|
|
305
|
+
def close(self) -> None:
|
|
306
|
+
"""Close the D3XX device handle.
|
|
307
|
+
|
|
308
|
+
The method is idempotent after the first successful or attempted close.
|
|
309
|
+
|
|
310
|
+
Raises:
|
|
311
|
+
D3xxBackendError: ``FT_Close`` returns a non-OK status.
|
|
312
|
+
"""
|
|
313
|
+
if self._closed:
|
|
314
|
+
return
|
|
315
|
+
try:
|
|
316
|
+
_check_status("FT_Close", self._binding.FT_Close(self._device))
|
|
317
|
+
finally:
|
|
318
|
+
self._closed = True
|
|
319
|
+
|
|
320
|
+
def abort_pipe(self, pipe: int) -> None:
|
|
321
|
+
"""Abort one D3XX native pipe.
|
|
322
|
+
|
|
323
|
+
Args:
|
|
324
|
+
pipe: D3XX pipe ID.
|
|
325
|
+
|
|
326
|
+
Raises:
|
|
327
|
+
D3xxBackendError: ``FT_AbortPipe`` fails.
|
|
328
|
+
"""
|
|
329
|
+
pipe_object = _pipe_from_id(self._binding, pipe)
|
|
330
|
+
_check_status("FT_AbortPipe", self._binding.FT_AbortPipe(self._device, pipe_object))
|
|
331
|
+
|
|
332
|
+
def create_pipe(self) -> None:
|
|
333
|
+
"""Keep protocol compatibility with the shared FTD3 transport surface.
|
|
334
|
+
|
|
335
|
+
The D3XX native API does not need the libusb command-pipe create
|
|
336
|
+
payload, so this operation is intentionally a no-op.
|
|
337
|
+
"""
|
|
338
|
+
|
|
339
|
+
def reconnect_after_drain(self) -> None:
|
|
340
|
+
"""Close and reopen after the initial drain, matching cc3dsfs' D3XX path.
|
|
341
|
+
|
|
342
|
+
Raises:
|
|
343
|
+
D3xxBackendError: The handle lacks original candidate metadata, or
|
|
344
|
+
the D3XX detail lookup/open call fails.
|
|
345
|
+
"""
|
|
346
|
+
if self._d3xx_candidate is None:
|
|
347
|
+
raise D3xxBackendError.invalid_candidate()
|
|
348
|
+
self.close()
|
|
349
|
+
_, detail = _status_and_value(
|
|
350
|
+
"FT_GetDeviceInfoDetail",
|
|
351
|
+
self._binding.FT_GetDeviceInfoDetail(self._d3xx_candidate.index),
|
|
352
|
+
)
|
|
353
|
+
_check_status(
|
|
354
|
+
"FT_Create",
|
|
355
|
+
self._binding.FT_Create(
|
|
356
|
+
_open_identifier(self._d3xx_candidate),
|
|
357
|
+
_open_flag(self._d3xx_candidate),
|
|
358
|
+
detail,
|
|
359
|
+
),
|
|
360
|
+
)
|
|
361
|
+
self._device = detail
|
|
362
|
+
self._closed = False
|
|
363
|
+
|
|
364
|
+
def set_stream_pipe(self, pipe: int, length: int) -> None:
|
|
365
|
+
"""Configure one D3XX native stream pipe.
|
|
366
|
+
|
|
367
|
+
Args:
|
|
368
|
+
pipe: D3XX pipe ID to configure.
|
|
369
|
+
length: Stream transfer length in bytes.
|
|
370
|
+
|
|
371
|
+
Raises:
|
|
372
|
+
D3xxBackendError: ``FT_SetStreamPipe`` fails.
|
|
373
|
+
"""
|
|
374
|
+
pipe_object = _pipe_from_id(self._binding, pipe)
|
|
375
|
+
_check_status(
|
|
376
|
+
"FT_SetStreamPipe",
|
|
377
|
+
self._binding.FT_SetStreamPipe(
|
|
378
|
+
self._device,
|
|
379
|
+
False,
|
|
380
|
+
False,
|
|
381
|
+
pipe_object,
|
|
382
|
+
length,
|
|
383
|
+
),
|
|
384
|
+
)
|
|
385
|
+
self._stream_pipes.add(pipe)
|
|
386
|
+
|
|
387
|
+
def pyd3xx_native_dll(self) -> object | None:
|
|
388
|
+
"""Return the loaded PyD3XX DLL object for explicit native adapters.
|
|
389
|
+
|
|
390
|
+
The fast-path backend uses this through ``D3xxNativeApi`` so PyD3XX
|
|
391
|
+
private module details do not leak into the streaming backend itself.
|
|
392
|
+
"""
|
|
393
|
+
return _pyd3xx_dll(self._binding)
|
|
394
|
+
|
|
395
|
+
def pyd3xx_native_handle(self) -> object:
|
|
396
|
+
"""Return the native D3XX handle object for explicit native adapters.
|
|
397
|
+
|
|
398
|
+
Raises:
|
|
399
|
+
D3xxBackendError: The underlying PyD3XX device does not expose a
|
|
400
|
+
native handle.
|
|
401
|
+
"""
|
|
402
|
+
return _device_handle(self._device)
|
|
403
|
+
|
|
404
|
+
def read_pipe(
|
|
405
|
+
self,
|
|
406
|
+
pipe: int,
|
|
407
|
+
length: int,
|
|
408
|
+
timeout_ms: int = D3XX_DEFAULT_TIMEOUT_MS,
|
|
409
|
+
) -> bytes:
|
|
410
|
+
"""Read bytes from one D3XX native pipe.
|
|
411
|
+
|
|
412
|
+
Args:
|
|
413
|
+
pipe: D3XX pipe ID to read.
|
|
414
|
+
length: Maximum number of bytes to read.
|
|
415
|
+
timeout_ms: Read timeout in milliseconds.
|
|
416
|
+
|
|
417
|
+
Returns:
|
|
418
|
+
Bytes read from the native D3XX pipe.
|
|
419
|
+
|
|
420
|
+
Raises:
|
|
421
|
+
D3xxBackendError: The D3XX read call fails or returns unsupported
|
|
422
|
+
buffer metadata.
|
|
423
|
+
"""
|
|
424
|
+
if pipe in self._stream_pipes:
|
|
425
|
+
return self._read_stream_pipe(pipe, length, timeout_ms)
|
|
426
|
+
direct = _direct_read_pipe(self._binding, self._device, pipe, length, timeout_ms)
|
|
427
|
+
if direct is not None:
|
|
428
|
+
return direct
|
|
429
|
+
pipe_object = _pipe_from_id(self._binding, pipe)
|
|
430
|
+
result = self._binding.FT_ReadPipe(self._device, pipe_object, length, timeout_ms)
|
|
431
|
+
status, buffer, transferred = _status_buffer_and_transferred("FT_ReadPipe", result)
|
|
432
|
+
_check_status("FT_ReadPipe", status)
|
|
433
|
+
return bytes(_buffer_value(buffer)[:transferred])
|
|
434
|
+
|
|
435
|
+
def _read_stream_pipe(self, pipe: int, length: int, timeout_ms: int) -> bytes:
|
|
436
|
+
direct = _direct_read_pipe_ex(self._binding, self._device, pipe, length, timeout_ms)
|
|
437
|
+
if direct is not None:
|
|
438
|
+
return direct
|
|
439
|
+
pipe_object = _pipe_from_id(self._binding, pipe)
|
|
440
|
+
result = self._binding.FT_ReadPipeEx(self._device, pipe_object, length, timeout_ms)
|
|
441
|
+
status, buffer, transferred = _status_buffer_and_transferred("FT_ReadPipeEx", result)
|
|
442
|
+
_check_status("FT_ReadPipeEx", status)
|
|
443
|
+
return bytes(_buffer_value(buffer)[:transferred])
|
|
444
|
+
|
|
445
|
+
def write_pipe(
|
|
446
|
+
self,
|
|
447
|
+
pipe: int,
|
|
448
|
+
payload: bytes,
|
|
449
|
+
timeout_ms: int = D3XX_DEFAULT_TIMEOUT_MS,
|
|
450
|
+
) -> int:
|
|
451
|
+
"""Write bytes to one D3XX native pipe.
|
|
452
|
+
|
|
453
|
+
Args:
|
|
454
|
+
pipe: D3XX pipe ID to write.
|
|
455
|
+
payload: Bytes to transfer.
|
|
456
|
+
timeout_ms: Write timeout in milliseconds.
|
|
457
|
+
|
|
458
|
+
Returns:
|
|
459
|
+
Number of bytes transferred.
|
|
460
|
+
|
|
461
|
+
Raises:
|
|
462
|
+
D3xxBackendError: The D3XX write call fails.
|
|
463
|
+
"""
|
|
464
|
+
direct = _direct_write_pipe(self._binding, self._device, pipe, payload, timeout_ms)
|
|
465
|
+
if direct is not None:
|
|
466
|
+
return direct
|
|
467
|
+
pipe_object = _pipe_from_id(self._binding, pipe)
|
|
468
|
+
buffer = _buffer_from_bytes(self._binding, payload)
|
|
469
|
+
status, transferred = _status_and_transferred(
|
|
470
|
+
"FT_WritePipe",
|
|
471
|
+
self._binding.FT_WritePipe(
|
|
472
|
+
self._device,
|
|
473
|
+
pipe_object,
|
|
474
|
+
buffer,
|
|
475
|
+
len(payload),
|
|
476
|
+
timeout_ms,
|
|
477
|
+
),
|
|
478
|
+
)
|
|
479
|
+
_check_status("FT_WritePipe", status)
|
|
480
|
+
return transferred
|
|
481
|
+
|
|
482
|
+
|
|
483
|
+
def load_pyd3xx_binding() -> D3xxBinding:
|
|
484
|
+
"""Import the optional PyD3XX module.
|
|
485
|
+
|
|
486
|
+
Returns:
|
|
487
|
+
Imported module cast to the D3XX binding protocol.
|
|
488
|
+
|
|
489
|
+
Raises:
|
|
490
|
+
OptionalDependencyError: Neither supported PyD3XX module name can be
|
|
491
|
+
imported.
|
|
492
|
+
"""
|
|
493
|
+
for module_name in PYD3XX_MODULE_NAMES:
|
|
494
|
+
try:
|
|
495
|
+
return cast("D3xxBinding", import_module(module_name))
|
|
496
|
+
except ImportError:
|
|
497
|
+
continue
|
|
498
|
+
raise OptionalDependencyError("PyD3XX", "d3xx")
|
|
499
|
+
|
|
500
|
+
|
|
501
|
+
class D3xxBackend:
|
|
502
|
+
"""FTDI D3XX-backed device enumeration.
|
|
503
|
+
|
|
504
|
+
This backend is used as a fallback when libusb cannot open an otherwise
|
|
505
|
+
accepted N3DSXL because the installed Windows driver belongs to D3XX.
|
|
506
|
+
"""
|
|
507
|
+
|
|
508
|
+
def __init__(self, binding: D3xxBinding | None = None) -> None:
|
|
509
|
+
"""Create a backend using an injected or optional PyD3XX binding.
|
|
510
|
+
|
|
511
|
+
Args:
|
|
512
|
+
binding: Optional test or real PyD3XX binding. When omitted, the
|
|
513
|
+
optional dependency is imported lazily.
|
|
514
|
+
|
|
515
|
+
Raises:
|
|
516
|
+
OptionalDependencyError: ``binding`` is omitted and PyD3XX is not
|
|
517
|
+
installed.
|
|
518
|
+
"""
|
|
519
|
+
self._binding = binding or load_pyd3xx_binding()
|
|
520
|
+
|
|
521
|
+
def iter_devices(self) -> tuple[D3xxDeviceInfo, ...]:
|
|
522
|
+
"""Return D3XX devices visible through the binding.
|
|
523
|
+
|
|
524
|
+
Returns:
|
|
525
|
+
Tuple of normalized D3XX device information.
|
|
526
|
+
|
|
527
|
+
Raises:
|
|
528
|
+
D3xxBackendError: The binding returns a non-OK status or an
|
|
529
|
+
unsupported detail shape.
|
|
530
|
+
"""
|
|
531
|
+
_, count = _status_and_value(
|
|
532
|
+
"FT_CreateDeviceInfoList",
|
|
533
|
+
self._binding.FT_CreateDeviceInfoList(),
|
|
534
|
+
)
|
|
535
|
+
devices: list[D3xxDeviceInfo] = []
|
|
536
|
+
for index in range(_int_from_object("FT_CreateDeviceInfoList.count", count)):
|
|
537
|
+
_, detail = _status_and_value(
|
|
538
|
+
"FT_GetDeviceInfoDetail",
|
|
539
|
+
self._binding.FT_GetDeviceInfoDetail(index),
|
|
540
|
+
)
|
|
541
|
+
devices.append(_device_info_from_detail(index=index, detail=detail))
|
|
542
|
+
return tuple(devices)
|
|
543
|
+
|
|
544
|
+
def iter_device_candidates(self) -> tuple[D3xxDeviceCandidate, ...]:
|
|
545
|
+
"""Return N3DSXL candidates visible through the D3XX backend.
|
|
546
|
+
|
|
547
|
+
Returns:
|
|
548
|
+
D3XX devices that pass the same N3DSXL classification policy as the
|
|
549
|
+
libusb path.
|
|
550
|
+
"""
|
|
551
|
+
candidates: list[D3xxDeviceCandidate] = []
|
|
552
|
+
for device in self.iter_devices():
|
|
553
|
+
classified = classify_n3dsxl_device(device.usb_info)
|
|
554
|
+
if isinstance(classified, DeviceCandidate):
|
|
555
|
+
candidates.append(
|
|
556
|
+
D3xxDeviceCandidate(
|
|
557
|
+
candidate=classified,
|
|
558
|
+
index=device.index,
|
|
559
|
+
flags=device.flags,
|
|
560
|
+
device_id=device.device_id,
|
|
561
|
+
)
|
|
562
|
+
)
|
|
563
|
+
return tuple(candidates)
|
|
564
|
+
|
|
565
|
+
def open(self, candidate: object) -> D3xxHandle:
|
|
566
|
+
"""Open one D3XX candidate and return a closeable handle.
|
|
567
|
+
|
|
568
|
+
Args:
|
|
569
|
+
candidate: ``D3xxDeviceCandidate`` returned by this backend.
|
|
570
|
+
|
|
571
|
+
Returns:
|
|
572
|
+
Open D3XX handle compatible with the N3DSXL protocol pipe surface.
|
|
573
|
+
|
|
574
|
+
Raises:
|
|
575
|
+
D3xxBackendError: The candidate type is unsupported, or the D3XX
|
|
576
|
+
detail lookup/open call fails.
|
|
577
|
+
"""
|
|
578
|
+
if not isinstance(candidate, D3xxDeviceCandidate):
|
|
579
|
+
raise D3xxBackendError.invalid_candidate()
|
|
580
|
+
_, detail = _status_and_value(
|
|
581
|
+
"FT_GetDeviceInfoDetail",
|
|
582
|
+
self._binding.FT_GetDeviceInfoDetail(candidate.index),
|
|
583
|
+
)
|
|
584
|
+
_check_status(
|
|
585
|
+
"FT_Create",
|
|
586
|
+
self._binding.FT_Create(
|
|
587
|
+
_open_identifier(candidate),
|
|
588
|
+
_open_flag(candidate),
|
|
589
|
+
detail,
|
|
590
|
+
),
|
|
591
|
+
)
|
|
592
|
+
return D3xxHandle(
|
|
593
|
+
binding=self._binding,
|
|
594
|
+
device=detail,
|
|
595
|
+
candidate=candidate.candidate,
|
|
596
|
+
d3xx_candidate=candidate,
|
|
597
|
+
)
|
|
598
|
+
|
|
599
|
+
|
|
600
|
+
def _device_info_from_detail(*, index: int, detail: object) -> D3xxDeviceInfo:
|
|
601
|
+
device_id = _int_from_object("FT_GetDeviceInfoDetail.ID", _field(detail, "ID"))
|
|
602
|
+
vendor_id, product_id = _vid_pid_from_device_id(device_id)
|
|
603
|
+
usb_info = UsbDeviceInfo(
|
|
604
|
+
bus_number=None,
|
|
605
|
+
address=None,
|
|
606
|
+
vendor_id=vendor_id,
|
|
607
|
+
product_id=product_id,
|
|
608
|
+
product_string=_optional_text(_field(detail, "Description")),
|
|
609
|
+
serial_number=_optional_text(_field(detail, "SerialNumber")),
|
|
610
|
+
)
|
|
611
|
+
flags = _optional_int(_field(detail, "Flags"))
|
|
612
|
+
return D3xxDeviceInfo(index=index, usb_info=usb_info, flags=flags, device_id=device_id)
|
|
613
|
+
|
|
614
|
+
|
|
615
|
+
def _open_identifier(candidate: D3xxDeviceCandidate) -> object:
|
|
616
|
+
serial_number = candidate.candidate.info.serial_number
|
|
617
|
+
if serial_number is not None:
|
|
618
|
+
return serial_number
|
|
619
|
+
return candidate.index
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
def _open_flag(candidate: D3xxDeviceCandidate) -> int:
|
|
623
|
+
if candidate.candidate.info.serial_number is not None:
|
|
624
|
+
return D3XX_OPEN_BY_SERIAL_NUMBER
|
|
625
|
+
return D3XX_OPEN_BY_INDEX
|
|
626
|
+
|
|
627
|
+
|
|
628
|
+
def _status_and_value(function: str, result: object) -> tuple[int, object]:
|
|
629
|
+
if not isinstance(result, tuple) or len(result) < 2:
|
|
630
|
+
raise D3xxBackendError(function)
|
|
631
|
+
status = _int_from_object(f"{function}.status", result[0])
|
|
632
|
+
if status != FT_OK:
|
|
633
|
+
raise D3xxBackendError(function, status)
|
|
634
|
+
return status, result[1]
|
|
635
|
+
|
|
636
|
+
|
|
637
|
+
def _check_status(function: str, status: object) -> None:
|
|
638
|
+
value = _int_from_object(f"{function}.status", status)
|
|
639
|
+
if value != FT_OK:
|
|
640
|
+
raise D3xxBackendError(function, value)
|
|
641
|
+
|
|
642
|
+
|
|
643
|
+
def _status_buffer_and_transferred(function: str, result: object) -> tuple[int, object, int]:
|
|
644
|
+
if not isinstance(result, tuple) or len(result) < 3:
|
|
645
|
+
raise D3xxBackendError(function)
|
|
646
|
+
return (
|
|
647
|
+
_int_from_object(f"{function}.status", result[0]),
|
|
648
|
+
result[1],
|
|
649
|
+
_int_from_object(f"{function}.transferred", result[2]),
|
|
650
|
+
)
|
|
651
|
+
|
|
652
|
+
|
|
653
|
+
def _status_and_transferred(function: str, result: object) -> tuple[int, int]:
|
|
654
|
+
if not isinstance(result, tuple) or len(result) < 2:
|
|
655
|
+
raise D3xxBackendError(function)
|
|
656
|
+
return (
|
|
657
|
+
_int_from_object(f"{function}.status", result[0]),
|
|
658
|
+
_int_from_object(f"{function}.transferred", result[1]),
|
|
659
|
+
)
|
|
660
|
+
|
|
661
|
+
|
|
662
|
+
def _pipe_from_id(binding: D3xxBinding, pipe: int) -> object:
|
|
663
|
+
pipe_type = binding.FT_Pipe
|
|
664
|
+
pipe_object = pipe_type()
|
|
665
|
+
pipe_object.PipeID = pipe
|
|
666
|
+
pipe_object._PipeID = pipe
|
|
667
|
+
return pipe_object
|
|
668
|
+
|
|
669
|
+
|
|
670
|
+
def _buffer_from_bytes(binding: D3xxBinding, payload: bytes) -> object:
|
|
671
|
+
buffer_type = binding.FT_Buffer
|
|
672
|
+
return buffer_type.from_bytes(payload)
|
|
673
|
+
|
|
674
|
+
|
|
675
|
+
def _buffer_value(buffer: object) -> bytearray:
|
|
676
|
+
value_method = cast("Any", buffer).Value
|
|
677
|
+
if not callable(value_method):
|
|
678
|
+
raise D3xxBackendError("FT_Buffer.Value")
|
|
679
|
+
value = value_method()
|
|
680
|
+
if isinstance(value, bytearray):
|
|
681
|
+
return value
|
|
682
|
+
if isinstance(value, bytes):
|
|
683
|
+
return bytearray(value)
|
|
684
|
+
raise D3xxBackendError("FT_Buffer.Value")
|
|
685
|
+
|
|
686
|
+
|
|
687
|
+
def _direct_write_pipe(
|
|
688
|
+
binding: D3xxBinding,
|
|
689
|
+
device: object,
|
|
690
|
+
pipe: int,
|
|
691
|
+
payload: bytes,
|
|
692
|
+
timeout_ms: int,
|
|
693
|
+
) -> int | None:
|
|
694
|
+
dll = _pyd3xx_dll(binding)
|
|
695
|
+
if dll is None:
|
|
696
|
+
return None
|
|
697
|
+
dll = cast("Any", dll)
|
|
698
|
+
buffer = ctypes.create_string_buffer(payload, len(payload))
|
|
699
|
+
transferred = ctypes.c_ulong(0)
|
|
700
|
+
handle = _device_handle(device)
|
|
701
|
+
with _pipe_timeout(dll, handle, pipe, timeout_ms):
|
|
702
|
+
status = dll.FT_WritePipe(
|
|
703
|
+
handle,
|
|
704
|
+
ctypes.c_ubyte(pipe),
|
|
705
|
+
buffer,
|
|
706
|
+
ctypes.c_ulong(len(payload)),
|
|
707
|
+
ctypes.byref(transferred),
|
|
708
|
+
None,
|
|
709
|
+
)
|
|
710
|
+
_check_status("FT_WritePipe", status)
|
|
711
|
+
return int(transferred.value)
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
def _direct_read_pipe(
|
|
715
|
+
binding: D3xxBinding,
|
|
716
|
+
device: object,
|
|
717
|
+
pipe: int,
|
|
718
|
+
length: int,
|
|
719
|
+
timeout_ms: int,
|
|
720
|
+
) -> bytes | None:
|
|
721
|
+
dll = _pyd3xx_dll(binding)
|
|
722
|
+
if dll is None:
|
|
723
|
+
return None
|
|
724
|
+
dll = cast("Any", dll)
|
|
725
|
+
buffer = ctypes.create_string_buffer(length)
|
|
726
|
+
transferred = ctypes.c_ulong(0)
|
|
727
|
+
handle = _device_handle(device)
|
|
728
|
+
with _pipe_timeout(dll, handle, pipe, timeout_ms):
|
|
729
|
+
status = dll.FT_ReadPipe(
|
|
730
|
+
handle,
|
|
731
|
+
ctypes.c_ubyte(pipe),
|
|
732
|
+
buffer,
|
|
733
|
+
ctypes.c_ulong(length),
|
|
734
|
+
ctypes.byref(transferred),
|
|
735
|
+
None,
|
|
736
|
+
)
|
|
737
|
+
_check_status("FT_ReadPipe", status)
|
|
738
|
+
return bytes(buffer.raw[: transferred.value])
|
|
739
|
+
|
|
740
|
+
|
|
741
|
+
def _direct_read_pipe_ex(
|
|
742
|
+
binding: D3xxBinding,
|
|
743
|
+
device: object,
|
|
744
|
+
pipe: int,
|
|
745
|
+
length: int,
|
|
746
|
+
timeout_ms: int,
|
|
747
|
+
) -> bytes | None:
|
|
748
|
+
dll = _pyd3xx_dll(binding)
|
|
749
|
+
if dll is None:
|
|
750
|
+
return None
|
|
751
|
+
dll = cast("Any", dll)
|
|
752
|
+
buffer = ctypes.create_string_buffer(length)
|
|
753
|
+
transferred = ctypes.c_ulong(0)
|
|
754
|
+
handle = _device_handle(device)
|
|
755
|
+
with _pipe_timeout(dll, handle, pipe, timeout_ms):
|
|
756
|
+
status = dll.FT_ReadPipeEx(
|
|
757
|
+
handle,
|
|
758
|
+
ctypes.c_ubyte(pipe),
|
|
759
|
+
buffer,
|
|
760
|
+
ctypes.c_ulong(length),
|
|
761
|
+
ctypes.byref(transferred),
|
|
762
|
+
None,
|
|
763
|
+
)
|
|
764
|
+
_check_status("FT_ReadPipeEx", status)
|
|
765
|
+
return bytes(buffer.raw[: transferred.value])
|
|
766
|
+
|
|
767
|
+
|
|
768
|
+
@contextmanager
|
|
769
|
+
def _pipe_timeout(dll: object, handle: object, pipe: int, timeout_ms: int) -> Iterator[None]:
|
|
770
|
+
dll = cast("Any", dll)
|
|
771
|
+
old_timeout_ms = ctypes.c_ulong(0)
|
|
772
|
+
status = dll.FT_GetPipeTimeout(handle, ctypes.c_ubyte(pipe), ctypes.byref(old_timeout_ms))
|
|
773
|
+
_check_status("FT_GetPipeTimeout", status)
|
|
774
|
+
status = dll.FT_SetPipeTimeout(handle, ctypes.c_ubyte(pipe), ctypes.c_ulong(timeout_ms))
|
|
775
|
+
_check_status("FT_SetPipeTimeout", status)
|
|
776
|
+
try:
|
|
777
|
+
yield
|
|
778
|
+
finally:
|
|
779
|
+
status = dll.FT_SetPipeTimeout(handle, ctypes.c_ubyte(pipe), old_timeout_ms)
|
|
780
|
+
_check_status("FT_SetPipeTimeout", status)
|
|
781
|
+
|
|
782
|
+
|
|
783
|
+
def _pyd3xx_dll(binding: D3xxBinding) -> object | None:
|
|
784
|
+
if not isinstance(binding, ModuleType):
|
|
785
|
+
return None
|
|
786
|
+
try:
|
|
787
|
+
implementation = import_module("PyD3XX.PyD3XX")
|
|
788
|
+
except ImportError:
|
|
789
|
+
return None
|
|
790
|
+
return getattr(implementation, "_DLL", None)
|
|
791
|
+
|
|
792
|
+
|
|
793
|
+
def _device_handle(device: object) -> object:
|
|
794
|
+
try:
|
|
795
|
+
return cast("Any", device)._Handle
|
|
796
|
+
except AttributeError as exc:
|
|
797
|
+
raise D3xxBackendError.missing_field("_Handle") from exc
|
|
798
|
+
|
|
799
|
+
|
|
800
|
+
def _field(target: object, name: str) -> object:
|
|
801
|
+
if isinstance(target, Mapping):
|
|
802
|
+
mapping = cast("Mapping[str, object]", target)
|
|
803
|
+
if name in mapping:
|
|
804
|
+
return mapping[name]
|
|
805
|
+
raise D3xxBackendError.missing_field(name)
|
|
806
|
+
try:
|
|
807
|
+
return getattr(target, name)
|
|
808
|
+
except AttributeError as exc:
|
|
809
|
+
raise D3xxBackendError.missing_field(name) from exc
|
|
810
|
+
|
|
811
|
+
|
|
812
|
+
def _vid_pid_from_device_id(device_id: int) -> tuple[int, int]:
|
|
813
|
+
high = (device_id >> 16) & 0xFFFF
|
|
814
|
+
low = device_id & 0xFFFF
|
|
815
|
+
if high == N3DSXL_VENDOR_ID:
|
|
816
|
+
return high, low
|
|
817
|
+
if low == N3DSXL_VENDOR_ID:
|
|
818
|
+
return low, high
|
|
819
|
+
return high, low
|
|
820
|
+
|
|
821
|
+
|
|
822
|
+
def _optional_text(value: object) -> str | None:
|
|
823
|
+
if value is None:
|
|
824
|
+
return None
|
|
825
|
+
text = str(value)
|
|
826
|
+
if text == "":
|
|
827
|
+
return None
|
|
828
|
+
return text
|
|
829
|
+
|
|
830
|
+
|
|
831
|
+
def _optional_int(value: object) -> int | None:
|
|
832
|
+
if value is None:
|
|
833
|
+
return None
|
|
834
|
+
return _int_from_object("optional int", value)
|
|
835
|
+
|
|
836
|
+
|
|
837
|
+
def _int_from_object(field_name: str, value: object) -> int:
|
|
838
|
+
if isinstance(value, int):
|
|
839
|
+
return value
|
|
840
|
+
if isinstance(value, str | bytes | bytearray):
|
|
841
|
+
return int(value)
|
|
842
|
+
raise D3xxBackendError.invalid_integer(field_name)
|
|
843
|
+
|
|
844
|
+
|
|
845
|
+
def _d3xx_error_message(function: str, status: int | None, field_name: str | None) -> str:
|
|
846
|
+
if field_name is not None:
|
|
847
|
+
return f"{function}: {field_name}"
|
|
848
|
+
if status is None:
|
|
849
|
+
return function
|
|
850
|
+
return f"{function} failed with status {status}"
|