Skip to content

feat: drive a simulated firmware over tcp:// - #43

Merged
thetooler merged 2 commits into
mainfrom
feat/tcp-transport-v2
Oct 28, 2026
Merged

thetooler merged 2 commits into
mainfrom
feat/tcp-transport-v2

Conversation

@thetooler

Copy link
Copy Markdown
Contributor

Summary

  • Adds TcpTransport so port can name a network target (tcp://host:port, sim://host:port,
    or a bare host:port) and the SDK drives a firmware stand-in — a MuJoCo-backed simulation, or
    anything else speaking this protocol — with no change above the connection call.
  • Documents it in the READMEs and the examples guide, including what a simulated arm can and
    cannot validate.

This is not a second backend: frames, timing assumptions and error classes are copied from
SerialTransport, only the carrier changes (USB CDC → socket). connect() picks the carrier as
injected transport_factory → TCP-looking target → SerialTransport, so the existing
SerialTransport monkeypatch point that the offline tests rely on stays intact.

Zero new dependencies: stdlib socket / select only, pyserial remains the sole dependency.

Why the docs are in the same PR

The transport landed originally as code + tests only, so the only way to discover that port
takes a network target was to read transport_tcp.py. The docs cover the three accepted
spellings, that auto-discovery does not apply to a network target, and both failure modes
(unreachable endpoint at connect(), peer that closes the socket — both TransportError, never
a silently idle link).

Verification

  • Full suite: 733 passed, 22 skipped (PYTHONPATH=src python3 -m pytest).
  • tests/test_transport_tcp.py: 27 passed.
  • tests/test_doc_examples.py: 96 passed — the new python blocks in both READMEs are executed
    against the offline stub, so is_tcp_target() claims are checked, not just asserted in prose.
  • Serial paths are not misdetected: /dev/ttyACM0, COM5 and /dev/serial/by-id/usb-…:1 all
    return False; a real connect to a dead port raises
    TransportError: 连接 … 失败: [Errno 111] Connection refused.

Notes for review

  • Consolidates the old feat/tcp-transport worktree branch. Its other two commits (tool point
    offset, payload identification) had already been squash-merged as feat: control a tool point and identify the payload on the host #27 — their tree hash is
    identical — so only the TCP commit was carried over; merging that branch as-is would have
    produced five conflicts against changes it already contains.
  • Left undone deliberately: docs/DEVELOPER_GUIDE.md has no TCP section yet. Say the word and I
    will add one.

thetooler added 2 commits October 28, 2026 11:09
The SDK is a thin protocol layer, so pointing it at a socket is enough to run the
same script against a simulated arm -- as long as the bytes are identical.

- transport_tcp.py: TcpTransport with the same contract as SerialTransport
  (port string kept verbatim for connect() idempotency, half frames survive a
  timeout, timeout=0 means take what has arrived, a failed write raises so
  _CartPending still drops its token, peer close is a link failure instead of a
  silent timeout);
- arm.py: three-way dispatch in connect() -- injected factory first, then a
  tcp:// or host:port target, then SerialTransport unchanged. Deliberately not a
  make_transport() factory: tests/conftest.py injects by replacing the
  SerialTransport attribute, and a factory hides that point (344 errors).
- is_tcp_target() in transport.py, so serial callers pay nothing.
The transport landed with code and tests only, so the only way to discover that
`port` takes a network target was to read `transport_tcp.py`. Document the three
accepted spellings, that auto-discovery does not apply, and the two failure modes
(unreachable endpoint / peer closed), plus what a simulated arm can and cannot
validate in the examples.
@thetooler
thetooler merged commit 5f75768 into main Oct 28, 2026
2 checks passed
@thetooler
thetooler deleted the feat/tcp-transport-v2 branch October 28, 2026 03:37
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.3.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

@github-actions github-actions Bot added the released Shipped in a release label Oct 28, 2026
X-F-R pushed a commit that referenced this pull request Nov 2, 2026
#33 and #43 landed on main after this branch was opened: they added
tests/test_env_sh.py and tests/test_transport_tcp.py, and two new
references to tests/conftest.py. Delete the remaining tests so the
repository really has no suite, and point the two comments at
litearm.testing.FakeTransport instead.

Co-Authored-By: Claude Code <noreply@anthropic.com>
yang-dong-yd pushed a commit that referenced this pull request Nov 3, 2026
* test: remove the test suite and its CI gate

The owner removed tests/ from the repository. Drop the pytest config,
replace the CI test step with an install and import smoke check, and
update README, the developer guide and AGENTS.md so they no longer
promise a test suite.

* docs: drop stale test references and warn on save_params

The test suite is gone, so comments pointing at tests/... no longer resolve. Replace them with the behavior they described, or state that the check is now manual. AGENTS.md now points at the smoke check instead of a test suite.

Arm.save_params() carries an explicit warning: irreversible whole-sector flash write, requires the disabled state, and the erase window must not be interrupted. params.py, payload.py and load_tool() cross-reference it.

* test: remove tests added after the branch point

#33 and #43 landed on main after this branch was opened: they added
tests/test_env_sh.py and tests/test_transport_tcp.py, and two new
references to tests/conftest.py. Delete the remaining tests so the
repository really has no suite, and point the two comments at
litearm.testing.FakeTransport instead.

Co-Authored-By: Claude Code <noreply@anthropic.com>

* chore: drop the unused pytest dev extra

The repository no longer has a test suite, so `.[dev]` only pulled in
pytest for nothing. Remove the optional-dependencies block.

Co-Authored-By: Claude Code <noreply@anthropic.com>

---------

Co-authored-by: thetooler <wuruihao@nexform.tech>
Co-authored-by: YOLO-DT <3199429837@qq.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

released Shipped in a release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant