smartcan — SmartCAN Pro Python SDK

Phase 1 SDK for talking to SmartCAN Pro over USB CDC or Wi-Fi HTTP. Single API; the transport is picked for you (or you can force one).

• Repository: https://github.com/ameriuse/smartcan-python-sdk
• Issues: https://github.com/ameriuse/smartcan-python-sdk/issues
• License: MIT

Install

pip install smartcan

Coming soon on PyPI. Until then, install from a GitHub release:

pip install https://github.com/ameriuse/smartcan-python-sdk/releases/download/v0.1.0/smartcan-0.1.0-py3-none-any.whl

Or clone and install from source — see "Developer install" below.

Python 3.11 / 3.12 only. Python 3.14 alpha segfaults on macOS — pinned out in pyproject.toml.

Usage

from smartcan import SmartCAN

dev = SmartCAN.auto()                    # USB if present, else Wi-Fi
print(dev.status())

for frame in dev.live(timeout=5):
    print(f"0x{frame.can_id:X}  {frame.dlc}  {frame.data.hex()}")

Force a transport:

dev = SmartCAN.from_usb("/dev/cu.usbserial-XXXX")
dev = SmartCAN.from_wifi("192.168.40.4")     # device's default Wi-Fi AP IP

CLI

smartcan status            # one-shot JSON status
smartcan live              # binary stream, prints a frame per line
smartcan start             # begin a logger session
smartcan stop              # end the logger session
smartcan discover          # scan USB + mDNS for nearby devices

Connection options apply to every subcommand except discover:

smartcan --port /dev/cu.usbserial-XXXX status
smartcan --ip   192.168.40.4              live --duration 5
smartcan --baud 460800                    live           # default

Phase 1 method matrix

What's implemented today:

Method	USB	Wi-Fi
ping()	✓	(uses /api/status as liveness)
version()	✓	from device_name field
status()	✓	✓
start() / stop()	✓	— (see Roadmap)
live() (binary)	✓	— (see Roadmap)

Typed errors: DeviceNotFound, UsbBusy, ProtocolError, Timeout (all subclass SmartCANError).

Roadmap

Not yet implemented. These methods raise NotImplementedError if called today; they'll land in v0.2:

• list_files() — list CAP files on the device's SD card.
• download_file(name, out_path) — download a CAP file.
• Wi-Fi live() / start() / stop() — same surface as USB, but over HTTP/SSE.

Why two transports

Wi-Fi is convenient for status checks and the existing browser UI. USB is required for ≥1000 fps live streaming because the firmware's WebServer doesn't push frames. The USB path uses a binary batch protocol (SCBF) at 460800 baud — the on-the-wire format is documented in docs/USB_PROTOCOL.md (shipped alongside SmartCAN firmware releases) for the on-the-wire format.

Verified throughput (Phase 1)

Bench: STM32H743 simulator looping CAP_009 (Toyota Sienna body bus, 26,456 records / 30 s ≈ 880 fps avg). 11 s sample:

host-side  : 9273 frames in 11.07 s = 837 fps
firmware Δ : 10267 in same window     = 927 fps   (matches the bus rate)
usb_dropped_frames  = 0
usb_dropped_batches = 0
ring_drops (logger) = 0

Zero drops at every layer. The 90 fps host/firmware gap is the short window between dev.status() calls and the iterator entering the binary-stream loop — it's sampling, not loss.

Troubleshooting

• DeviceNotFound: no SmartCAN device found — make sure your /dev/cu.usbserial-* (macOS) / /dev/ttyUSB* (Linux) / COM* (Windows) port is visible. Run smartcan discover to enumerate. Force-connect with SmartCAN.from_usb("<port>") if discovery misses it.
• Timeout: timed out waiting for ... response from device — the firmware may not be running a build with the USB CDC subsystem. Check the boot banner over a 460800-baud serial monitor for the line [USBCLI] task started on Core 1.
• live() yields 0 frames — confirm dev.status()['can_rx_count'] is rising (i.e. the bus is actually producing frames). The SDK doesn't synthesize.

Developer install (from source)

For SDK development against a local checkout:

git clone https://github.com/ameriuse/smartcan-python-sdk.git
cd smartcan-python-sdk
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e .

pyproject.toml, LICENSE, and CHANGELOG.md live alongside the smartcan/ package directory.

License

MIT — see LICENSE.