sdwire 0.3.1__tar.gz → 0.5.0__tar.gz

sdwire-0.5.0/.gitignore

@@ -0,0 +1,162 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

sdwire-0.5.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: sdwire
+Version: 0.5.0
+Summary: CLI application to interact with Badgerd SDWire devices
+Author-email: Talha Can Havadar <havadartalha@gmail.com>
+License-Expression: GPL-3.0-only
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <4,>=3.12
+Requires-Dist: click<9,>=8.1.7
+Requires-Dist: pyftdi<0.57,>=0.56.0
+Requires-Dist: pyusb<2,>=1.2.1
+Description-Content-Type: text/markdown
+
+# CLI for Badgerd SDWire Devices
+
+Application also supports legacy SDWireC and non-Badger'd sdwires as well as
+new Badgerd SDwire Gen2 devices.
+
+Please see below for usage:
+
+```
+❯ sdwire --help
+Usage: sdwire [OPTIONS] COMMAND [ARGS]...
+
+  SDWire CLI - Control SDWire devices from command line.
+
+Options:
+  --debug    Enable debug output
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+
+Commands:
+  block-dev  Print the block device path of the SD card, for use in scripts.
+  list       List all connected SDWire devices with their block device...
+  state      Query and display the state of all connected SDWire devices.
+  switch     dut/target => connects the sdcard interface to target device
+
+❯ sdwire switch --help
+Usage: sdwire switch [OPTIONS] COMMAND [ARGS]...
+
+  dut/target => connects the sdcard interface to target device
+
+  ts/host => connects the sdcard interface to host machine
+
+  off => disconnects the sdcard interface from both host and target
+
+Options:
+  -s, --serial TEXT  Serial number of the sdwire device, if there is only one
+                     sdwire connected then it will be used by default
+  --help             Show this message and exit.
+
+Commands:
+  dut     dut/target => connects the sdcard interface to target device
+  host    ts/host => connects the sdcard interface to host machine
+  off     off => disconnects the sdcard interface from both host and target
+  target  dut/target => connects the sdcard interface to target device
+  ts      ts/host => connects the sdcard interface to host machine
+```
+
+## Installing
+
+Using pip
+
+```
+pip install sdwire
+```
+
+Using apt
+
+```
+sudo add-apt-repository ppa:tchavadar/badgerd
+sudo apt install python3-sdwire
+```
+
+Using a container (podman)
+
+```
+podman pull ghcr.io/badger-embedded/sdwire-cli:latest
+# or build locally from the repository root
+podman build -t sdwire -f Containerfile .
+```
+
+## Running in a container
+
+The image's entrypoint is `sdwire`, so arguments are passed directly. The
+container needs access to the host USB devices (and block devices for
+`sdwire list`), the simplest way is `--privileged`:
+
+```
+podman run --rm --privileged ghcr.io/badger-embedded/sdwire-cli list
+podman run --rm --privileged ghcr.io/badger-embedded/sdwire-cli switch dut
+```
+
+Replace the image name with `sdwire` if you built it locally. A shell alias
+makes it feel like a native install:
+
+```
+alias sdwire='podman run --rm --privileged ghcr.io/badger-embedded/sdwire-cli'
+```
+
+> **udev rules are required on the host.** udev runs on the host, not in the
+> container, so install `udev/90-sdwire.rules` there for proper USB access and
+> SDWire3 power management (autosuspend):
+>
+> ```
+> sudo cp udev/90-sdwire.rules /etc/udev/rules.d/
+> sudo udevadm control --reload-rules && sudo udevadm trigger
+> ```
+>
+> Without them, USB access and card switching may fail with permission errors.
+
+## Listing SDWire Devices
+
+`sdwire list` command will search through usb devices connected to the system
+and prints out the list of gen2 and legacy devices.
+
+```
+❯ sdwire list
+Serial			Product Info
+sdwire_gen2_101		[SDWire-Gen2::Badgerd Technologies]
+bdgrd_sdwirec_522	[sd-wire::SRPOL]
+```
+
+## Switching SD Card Connection
+
+`sdwire switch` command switches the sd card connection to specified direction.
+If there is more than one sdwire connected to then you need specify which sdwire
+you want to alter with `--serial` or `-s` options.
+
+If there is only one sdwire connected then you dont need to specify the serial,
+it will pick the one connected automatically. See the examples below.
+
+```
+❯ sdwire list
+Serial			Product Info
+sdwire_gen2_101		[SDWire-Gen2::Badgerd Technologies]
+bdgrd_sdwirec_522	[sd-wire::SRPOL]
+
+❯ sdwire switch -s bdgrd_sdwirec_522 target
+
+❯ sdwire switch target
+Usage: sdwire switch [OPTIONS] COMMAND [ARGS]...
+Try 'sdwire switch --help' for help.
+
+Error: There is more then 1 sdwire device connected, please use --serial|-s to specify!
+
+❯ sdwire list
+Serial			Product Info
+bdgrd_sdwirec_522	[sd-wire::SRPOL]
+
+❯ sdwire switch host
+```
+
+## Getting the Block Device Path
+
+`sdwire block-dev` prints only the block device path of the SD card (e.g.
+`/dev/sdb`), so it can be used directly in scripts. Errors and warnings go to
+stderr, so stdout stays clean. Like `switch`, use `--serial`/`-s` when more than
+one sdwire is connected.
+
+```
+❯ sdwire switch -s bdgrd_sdwirec_522 host
+❯ sudo bmaptool copy disk.img "$(sdwire block-dev -s bdgrd_sdwirec_522)"
+```
+
+Right after `sdwire switch host` the block device needs a moment to become
+usable: SDWire3 re-enumerates (~2 s) and SDWireC needs the kernel to detect the
+card (up to ~2 s). `block-dev` waits up to 5 seconds for it. If the device
+reports target mode it fails immediately instead of waiting. On macOS, an
+existing disk node is assumed to be usable.
+
+| Exit code | Meaning                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| 0         | Path printed to stdout                                                     |
+| 1         | Device found but no usable block device (target mode, no SD card, timeout) |
+| 2         | No device, unknown serial, or more than one device without `--serial`      |
+
+```
+❯ sdwire switch target
+❯ sdwire block-dev
+Error: 20120501030900000.1 is in target mode, run 'sdwire switch host' first
+❯ echo $?
+1
+```
+
+### SDWire3 and Linux USB power management
+
+On Linux, the SDWire3 only hands the SD card to the target while the USB device
+is runtime-suspended. `sdwire switch target` enables this automatically
+(`power/autosuspend_delay_ms=0`, `power/control=auto`) and verifies that
+`power/runtime_status` becomes `suspended`; otherwise it exits with an error.
+Writing to sysfs requires root, or install `udev/90-sdwire.rules`, which applies
+the setting when the device is plugged in.
+
+To do it by hand (replace `2-8` with your device's sysfs name, e.g. `5-1`):
+
+```
+echo 0    | sudo tee /sys/bus/usb/devices/2-8/power/autosuspend_delay_ms
+echo auto | sudo tee /sys/bus/usb/devices/2-8/power/control
+```
+
+## Testing
+
+Unit tests: `uv run pytest tests`.
+
+End-to-end tests run the installed CLI against simulated devices (umockdev) or
+real hardware. See [tests/e2e/README.md](tests/e2e/README.md).

sdwire-0.5.0/README.md

@@ -0,0 +1,194 @@
+# CLI for Badgerd SDWire Devices
+
+Application also supports legacy SDWireC and non-Badger'd sdwires as well as
+new Badgerd SDwire Gen2 devices.
+
+Please see below for usage:
+
+```
+❯ sdwire --help
+Usage: sdwire [OPTIONS] COMMAND [ARGS]...
+
+  SDWire CLI - Control SDWire devices from command line.
+
+Options:
+  --debug    Enable debug output
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+
+Commands:
+  block-dev  Print the block device path of the SD card, for use in scripts.
+  list       List all connected SDWire devices with their block device...
+  state      Query and display the state of all connected SDWire devices.
+  switch     dut/target => connects the sdcard interface to target device
+
+❯ sdwire switch --help
+Usage: sdwire switch [OPTIONS] COMMAND [ARGS]...
+
+  dut/target => connects the sdcard interface to target device
+
+  ts/host => connects the sdcard interface to host machine
+
+  off => disconnects the sdcard interface from both host and target
+
+Options:
+  -s, --serial TEXT  Serial number of the sdwire device, if there is only one
+                     sdwire connected then it will be used by default
+  --help             Show this message and exit.
+
+Commands:
+  dut     dut/target => connects the sdcard interface to target device
+  host    ts/host => connects the sdcard interface to host machine
+  off     off => disconnects the sdcard interface from both host and target
+  target  dut/target => connects the sdcard interface to target device
+  ts      ts/host => connects the sdcard interface to host machine
+```
+
+## Installing
+
+Using pip
+
+```
+pip install sdwire
+```
+
+Using apt
+
+```
+sudo add-apt-repository ppa:tchavadar/badgerd
+sudo apt install python3-sdwire
+```
+
+Using a container (podman)
+
+```
+podman pull ghcr.io/badger-embedded/sdwire-cli:latest
+# or build locally from the repository root
+podman build -t sdwire -f Containerfile .
+```
+
+## Running in a container
+
+The image's entrypoint is `sdwire`, so arguments are passed directly. The
+container needs access to the host USB devices (and block devices for
+`sdwire list`), the simplest way is `--privileged`:
+
+```
+podman run --rm --privileged ghcr.io/badger-embedded/sdwire-cli list
+podman run --rm --privileged ghcr.io/badger-embedded/sdwire-cli switch dut
+```
+
+Replace the image name with `sdwire` if you built it locally. A shell alias
+makes it feel like a native install:
+
+```
+alias sdwire='podman run --rm --privileged ghcr.io/badger-embedded/sdwire-cli'
+```
+
+> **udev rules are required on the host.** udev runs on the host, not in the
+> container, so install `udev/90-sdwire.rules` there for proper USB access and
+> SDWire3 power management (autosuspend):
+>
+> ```
+> sudo cp udev/90-sdwire.rules /etc/udev/rules.d/
+> sudo udevadm control --reload-rules && sudo udevadm trigger
+> ```
+>
+> Without them, USB access and card switching may fail with permission errors.
+
+## Listing SDWire Devices
+
+`sdwire list` command will search through usb devices connected to the system
+and prints out the list of gen2 and legacy devices.
+
+```
+❯ sdwire list
+Serial			Product Info
+sdwire_gen2_101		[SDWire-Gen2::Badgerd Technologies]
+bdgrd_sdwirec_522	[sd-wire::SRPOL]
+```
+
+## Switching SD Card Connection
+
+`sdwire switch` command switches the sd card connection to specified direction.
+If there is more than one sdwire connected to then you need specify which sdwire
+you want to alter with `--serial` or `-s` options.
+
+If there is only one sdwire connected then you dont need to specify the serial,
+it will pick the one connected automatically. See the examples below.
+
+```
+❯ sdwire list
+Serial			Product Info
+sdwire_gen2_101		[SDWire-Gen2::Badgerd Technologies]
+bdgrd_sdwirec_522	[sd-wire::SRPOL]
+
+❯ sdwire switch -s bdgrd_sdwirec_522 target
+
+❯ sdwire switch target
+Usage: sdwire switch [OPTIONS] COMMAND [ARGS]...
+Try 'sdwire switch --help' for help.
+
+Error: There is more then 1 sdwire device connected, please use --serial|-s to specify!
+
+❯ sdwire list
+Serial			Product Info
+bdgrd_sdwirec_522	[sd-wire::SRPOL]
+
+❯ sdwire switch host
+```
+
+## Getting the Block Device Path
+
+`sdwire block-dev` prints only the block device path of the SD card (e.g.
+`/dev/sdb`), so it can be used directly in scripts. Errors and warnings go to
+stderr, so stdout stays clean. Like `switch`, use `--serial`/`-s` when more than
+one sdwire is connected.
+
+```
+❯ sdwire switch -s bdgrd_sdwirec_522 host
+❯ sudo bmaptool copy disk.img "$(sdwire block-dev -s bdgrd_sdwirec_522)"
+```
+
+Right after `sdwire switch host` the block device needs a moment to become
+usable: SDWire3 re-enumerates (~2 s) and SDWireC needs the kernel to detect the
+card (up to ~2 s). `block-dev` waits up to 5 seconds for it. If the device
+reports target mode it fails immediately instead of waiting. On macOS, an
+existing disk node is assumed to be usable.
+
+| Exit code | Meaning                                                                    |
+| --------- | -------------------------------------------------------------------------- |
+| 0         | Path printed to stdout                                                     |
+| 1         | Device found but no usable block device (target mode, no SD card, timeout) |
+| 2         | No device, unknown serial, or more than one device without `--serial`      |
+
+```
+❯ sdwire switch target
+❯ sdwire block-dev
+Error: 20120501030900000.1 is in target mode, run 'sdwire switch host' first
+❯ echo $?
+1
+```
+
+### SDWire3 and Linux USB power management
+
+On Linux, the SDWire3 only hands the SD card to the target while the USB device
+is runtime-suspended. `sdwire switch target` enables this automatically
+(`power/autosuspend_delay_ms=0`, `power/control=auto`) and verifies that
+`power/runtime_status` becomes `suspended`; otherwise it exits with an error.
+Writing to sysfs requires root, or install `udev/90-sdwire.rules`, which applies
+the setting when the device is plugged in.
+
+To do it by hand (replace `2-8` with your device's sysfs name, e.g. `5-1`):
+
+```
+echo 0    | sudo tee /sys/bus/usb/devices/2-8/power/autosuspend_delay_ms
+echo auto | sudo tee /sys/bus/usb/devices/2-8/power/control
+```
+
+## Testing
+
+Unit tests: `uv run pytest tests`.
+
+End-to-end tests run the installed CLI against simulated devices (umockdev) or
+real hardware. See [tests/e2e/README.md](tests/e2e/README.md).

sdwire-0.5.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "sdwire"
+version = "0.5.0"
+description = "CLI application to interact with Badgerd SDWire devices"
+authors = [{ name = "Talha Can Havadar", email = "havadartalha@gmail.com" }]
+requires-python = ">=3.12,<4"
+readme = "README.md"
+license = "GPL-3.0-only"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "click>=8.1.7,<9",
+    "pyusb>=1.2.1,<2",
+    "pyftdi>=0.56.0,<0.57",
+]
+
+[project.scripts]
+sdwire = "sdwire:main.main"
+
+[dependency-groups]
+dev = [
+    "black>=24.8.0,<25",
+    "pytest>=9.2.0,<10",
+]
+# harness of the end-to-end tests (tests/e2e), installed on its own in CI
+e2e = [
+    "pytest>=9.2.0,<10",
+    "pytest-timeout>=2.4.0,<3",
+    "syrupy>=6.1.1,<7",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["sdwire"]
+
+[tool.hatch.build.targets.wheel]
+include = ["sdwire"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

{sdwire-0.3.1 → sdwire-0.5.0}/sdwire/backend/block_device_utils.py

@@ -5,6 +5,7 @@ to their corresponding block device paths (e.g., /dev/sda on Linux, /dev/disk2 o
 It uses USB hierarchy and topology information for accurate device mapping.
 """
 
+import os
 import platform
 import logging
 import re
@@ -23,6 +24,43 @@ from sdwire.constants import (
 
 log = logging.getLogger(__name__)
 
+SYSFS_ROOT = "/sys"
+
+
+def _read_sysfs(path: str) -> Optional[str]:
+    try:
+        with open(path) as f:
+            return f.read().strip()
+    except OSError:
+        return None
+
+
+def _sysfs_block_dir(block_dev: str, sysfs_root: str) -> str:
+    return os.path.join(sysfs_root, "class", "block", os.path.basename(block_dev))
+
+
+def is_block_dev_usable(block_dev: str, sysfs_root: str = SYSFS_ROOT) -> bool:
+    """Return True when the block device has a medium and is ready for I/O.
+
+    Card readers (e.g. SDWireC) keep their block device while no medium is
+    present, reporting a size of 0. Uses sysfs only, so no permissions on the
+    device node are needed. Without sysfs (macOS) existence of the node is
+    the best available signal.
+    """
+    if not os.path.isdir(os.path.join(sysfs_root, "class", "block")):
+        return os.path.exists(block_dev)
+    base = _sysfs_block_dir(block_dev, sysfs_root)
+    size = _read_sysfs(os.path.join(base, "size"))
+    if not size or not size.isdigit() or int(size) == 0:
+        return False
+    state = _read_sysfs(os.path.join(base, "device", "state"))
+    return state in (None, "running")
+
+
+def is_block_dev_readonly(block_dev: str, sysfs_root: str = SYSFS_ROOT) -> bool:
+    base = _sysfs_block_dir(block_dev, sysfs_root)
+    return _read_sysfs(os.path.join(base, "ro")) == "1"
+
 
 def map_usb_device_to_block_device(usb_device: usb.core.Device) -> Optional[str]:
     """Map a USB device to its corresponding system block device path using USB hierarchy.