Fix linux-att adapter wiring + V5X pagination & tolerant ACK waits

[d-roman-halliday]

Replacement for #24. The earlier PR predated 1424fe3 linux bearer problem #23 on master and shipped a parallel linux_l2cap_client.py adapter (~1042 LoC). That parallel adapter is no longer the right shape: upstream's linux_att.py already takes the same architectural approach, so this PR keeps your code in place and instead fixes the wiring bugs that prevented it from working on at least one Linux host. The #25 host-side mitigations from #24 are preserved.

I'll close #24 after this one is in your review queue.

Commits

1. eddd640 Fix linux-att adapter wiring so it can actually connect on Linux

On Ubuntu 6.17 / BlueZ 5.83 / Python 3.12 (MXW01) master (post 1424fe3/d28d937/b8d38a5) silently fell back to Bleak — i.e. the very BR/EDR-misroute path the linux-att workaround was added to bypass (#23). Three bugs:

1. Tuple/string mismatch. The shared _FallbackSocket iterates over (address, channel) tuples and passes the same tuple to every backend it owns. _LinuxAttSocket.connect() was typed as (address: str) and crashed on tuple.replace() inside address normalisation. Unpack the tuple before use; the RFCOMM channel is meaningless for an LE L2CAP/ATT socket so we discard it.
2. EINPROGRESS not handled. _open_att_socket previously called sock.settimeout(timeout) before the L2CAP connect, which puts the socket in non-blocking mode. The raw libc.connect() then returns -1 / EINPROGRESS instead of blocking. The old code raised that as a fatal error. Now we either select+SO_ERROR (when the caller already set a timeout), or use a blocking connect and apply the timeout afterwards.
3. Non-blocking L2CAP connect hangs. Even after the select+SO_ERROR fix, the AF_BLUETOOTH/L2CAP kernel path on this host never marked the socket writable, and the select() would time out after 30 s for a peer the blocking-mode equivalent connects to in <1 s. Switch to blocking mode for the connect itself, then settimeout() for subsequent read/writes.

Regression test for #1 in tests/test_bluetooth_adapter_fallback.py. #2 and #3 are exercised by the hardware Lorem-ipsum print below — unit tests for them would require faking ctypes.CDLL and are fragile relative to the underlying syscall behaviour.

2. 59bc714 Add per-job-rows pagination and tolerant V5X command-ack waits

For #25. Two host-side mitigations that don't unlock the firmware ceiling but improve the failure mode:

• Pagination in PrintJobBuilder. New env var TIMINI_PRINT_MAX_JOB_ROWS (default 0 = no split). When set, any rendered page raster taller than the limit is split vertically into sub-rasters and built as separate V5X sessions (A7 / A2 / A9 / bulk / AD), one per ProtocolStep.SEND so the runtime can pace them across one connection.
• Tolerant runtime ACK waits in printing/runtime/v5x.py. _wait_for_start_ready already logged-and-continued on a missing 0xAA; _wait_for_command_ack did not. With pagination on, the second sub-job's 0xA7 ACK is preemptively consumed by a between-segments 0xA6 idle re-identification — so seg2's ACK never arrives and the wait raised an empty asyncio.TimeoutError that bubbled out as Error: BLE write failed: with no detail. Now caught and log-and-continued, mirroring the existing tolerance for 0xAA.

10 new pagination unit tests in tests/test_builder_pagination.py. Updated tests/test_bleak_transport_session.py::test_v5x_timeout_clears_pending_handshake_state to assert the new "send completes, state still cleared" behaviour rather than the old "raise".

Test plan

• python -m unittest discover -s tests -p 'test_*.py' — 360/360 pass on this branch.
• Live MXW01 (v1.9.3.1.2) on Linux + BlueZ:
  • BLE connect via linux-att succeeds in <1 s (Linux direct ATT connected: address_type=1 mtu_payload=509 services=4).
  • Short text print: clean run, 0xA9 status 0x0000.
  • Lorem-ipsum repro at TIMINI_BLE_BULK_DELAY_MS=30 (equivalent to b8d38a5's bulk pacing on MTU-512 V5X): host-side ACKs clean (0xA9 status 0x0000, no 0xAA fc 20 73-style distress bytes). Physical print still truncates at ~"ex ea commodo" (~37 %), confirming the residual constraint is in MXW01 firmware/render pipeline and not host-side. Documented in V5X firmware variants have a per-job row ceiling; long jobs truncate mid-row silently (MXW01 v1.9.3.1.2) #25.
• CI on Linux x86_64/arm64, Windows, macOS arm64/intel (will run on push).

Residual firmware constraint (for #25 reviewers)

Strongest hypothesis from the test sequence: MXW01 v1.9.3.1.2 has a per-power-cycle render budget (~200–300 rows of 384 px) rather than a per-job one. Once consumed, subsequent jobs are accepted at the protocol layer but produce no physical output. Pagination + tolerant acks make the failure mode graceful (the host doesn't abort, the printer doesn't cascade-fail subsequent jobs), but unlocking the ceiling needs firmware-side cooperation we don't have.

Note on local BlueZ state during verification

On this host the linux-att L2CAP path occasionally hangs at connect-time when BlueZ has a stale entry for the device (e.g. after a failed connect via the dbus path). Running bluetoothctl remove <addr> clears that cleanly. Not an issue caused by this PR — but worth flagging since the symptom (silent connect timeout) is easy to mistake for the original #23 bug.

[Dejniel]

@d-roman-halliday I cherry-picked the Linux ATT wiring commit from this PR onto master as 94abaeb, with you preserved as the commit author. Thanks for tracking that down.

I am not merging the whole PR as-is because the second commit mixes the Linux ATT fix with #25 pagination / tolerant V5X ACK behavior. For future PRs, please keep one behavioral layer per PR; it makes it much easier for me to merge your work directly.

Can you clarify whether the second commit changes anything observable for #25 on current master, beyond making the host continue/log instead of aborting? From your notes it looks like the physical truncation still happens, so I would rather keep that as a separate, explicitly modeled MXW01/V5X firmware issue unless it actually improves the printed output.

[d-roman-halliday]

Following up on the #25 retest above: truncation isn't reproducing on current master against the MXW01 anymore (full numbers in #25 comment). The pagination half of this PR is therefore optional.

[Dejniel]

Thanks again for the PR and the hardware testing.

I cherry-picked the Linux ATT wiring fix onto master as 94abaeb, preserving you as the commit author. Since #23 and #25 are now fixed on current master, and the pagination/tolerant-ACK part is optional rather than needed right now, I'm closing this PR without merging the rest.

If the stale BlueZ cache behavior keeps happening, please open a separate issue for it so we can track that independently.