From 9a372b7d9b6242d32c5b45f414d46daf19890593 Mon Sep 17 00:00:00 2001 From: Paul Wallrabe Date: Tue, 8 Apr 2025 11:08:08 +0200 Subject: [PATCH] inverse symlinks to fix hatchling --- __templates__/create_driver.sh | 32 +- __templates__/driver/pyproject.toml.tmpl | 2 +- docs/source/api-reference/drivers/can.md | 34 +- .../source/api-reference/drivers/corellium.md | 73 +---- docs/source/api-reference/drivers/dutlink.md | 26 +- docs/source/api-reference/drivers/flashers.md | 305 +----------------- docs/source/api-reference/drivers/http.md | 26 +- docs/source/api-reference/drivers/index.md | 43 +-- docs/source/api-reference/drivers/network.md | 49 +-- docs/source/api-reference/drivers/opendal.md | 75 +---- docs/source/api-reference/drivers/power.md | 26 +- docs/source/api-reference/drivers/probe-rs.md | 63 +--- docs/source/api-reference/drivers/pyserial.md | 82 +---- docs/source/api-reference/drivers/qemu.md | 26 +- .../api-reference/drivers/raspberrypi.md | 26 +- docs/source/api-reference/drivers/sdwire.md | 36 +-- docs/source/api-reference/drivers/shell.md | 64 +--- docs/source/api-reference/drivers/snmp.md | 73 +---- docs/source/api-reference/drivers/tftp.md | 76 +---- docs/source/api-reference/drivers/uboot.md | 32 +- .../source/api-reference/drivers/ustreamer.md | 34 +- docs/source/api-reference/drivers/yepkit.md | 81 +---- packages/jumpstarter-driver-can/README.md | 34 +- .../jumpstarter-driver-corellium/README.md | 73 ++++- packages/jumpstarter-driver-dutlink/README.md | 26 +- .../jumpstarter-driver-flashers/README.md | 304 ++++++++++++++++- packages/jumpstarter-driver-http/README.md | 26 +- packages/jumpstarter-driver-network/README.md | 49 ++- packages/jumpstarter-driver-opendal/README.md | 75 ++++- packages/jumpstarter-driver-power/README.md | 26 +- .../jumpstarter-driver-probe-rs/README.md | 63 +++- .../jumpstarter-driver-pyserial/README.md | 82 ++++- packages/jumpstarter-driver-qemu/README.md | 26 +- .../jumpstarter-driver-raspberrypi/README.md | 26 +- packages/jumpstarter-driver-sdwire/README.md | 36 ++- packages/jumpstarter-driver-shell/README.md | 64 +++- packages/jumpstarter-driver-snmp/README.md | 73 ++++- packages/jumpstarter-driver-tftp/README.md | 76 ++++- packages/jumpstarter-driver-uboot/README.md | 32 +- .../jumpstarter-driver-ustreamer/README.md | 34 +- packages/jumpstarter-driver-yepkit/README.md | 81 ++++- 41 files changed, 1245 insertions(+), 1245 deletions(-) mode change 100644 => 120000 docs/source/api-reference/drivers/can.md mode change 100644 => 120000 docs/source/api-reference/drivers/corellium.md mode change 100644 => 120000 docs/source/api-reference/drivers/dutlink.md mode change 100644 => 120000 docs/source/api-reference/drivers/flashers.md mode change 100644 => 120000 docs/source/api-reference/drivers/http.md mode change 100644 => 120000 docs/source/api-reference/drivers/network.md mode change 100644 => 120000 docs/source/api-reference/drivers/opendal.md mode change 100644 => 120000 docs/source/api-reference/drivers/power.md mode change 100644 => 120000 docs/source/api-reference/drivers/probe-rs.md mode change 100644 => 120000 docs/source/api-reference/drivers/pyserial.md mode change 100644 => 120000 docs/source/api-reference/drivers/qemu.md mode change 100644 => 120000 docs/source/api-reference/drivers/raspberrypi.md mode change 100644 => 120000 docs/source/api-reference/drivers/sdwire.md mode change 100644 => 120000 docs/source/api-reference/drivers/shell.md mode change 100644 => 120000 docs/source/api-reference/drivers/snmp.md mode change 100644 => 120000 docs/source/api-reference/drivers/tftp.md mode change 100644 => 120000 docs/source/api-reference/drivers/uboot.md mode change 100644 => 120000 docs/source/api-reference/drivers/ustreamer.md mode change 100644 => 120000 docs/source/api-reference/drivers/yepkit.md mode change 120000 => 100644 packages/jumpstarter-driver-can/README.md mode change 120000 => 100644 packages/jumpstarter-driver-corellium/README.md mode change 120000 => 100644 packages/jumpstarter-driver-dutlink/README.md mode change 120000 => 100644 packages/jumpstarter-driver-flashers/README.md mode change 120000 => 100644 packages/jumpstarter-driver-http/README.md mode change 120000 => 100644 packages/jumpstarter-driver-network/README.md mode change 120000 => 100644 packages/jumpstarter-driver-opendal/README.md mode change 120000 => 100644 packages/jumpstarter-driver-power/README.md mode change 120000 => 100644 packages/jumpstarter-driver-probe-rs/README.md mode change 120000 => 100644 packages/jumpstarter-driver-pyserial/README.md mode change 120000 => 100644 packages/jumpstarter-driver-qemu/README.md mode change 120000 => 100644 packages/jumpstarter-driver-raspberrypi/README.md mode change 120000 => 100644 packages/jumpstarter-driver-sdwire/README.md mode change 120000 => 100644 packages/jumpstarter-driver-shell/README.md mode change 120000 => 100644 packages/jumpstarter-driver-snmp/README.md mode change 120000 => 100644 packages/jumpstarter-driver-tftp/README.md mode change 120000 => 100644 packages/jumpstarter-driver-uboot/README.md mode change 120000 => 100644 packages/jumpstarter-driver-ustreamer/README.md mode change 120000 => 100644 packages/jumpstarter-driver-yepkit/README.md diff --git a/__templates__/create_driver.sh b/__templates__/create_driver.sh index 9e1b00341..4c399d70c 100755 --- a/__templates__/create_driver.sh +++ b/__templates__/create_driver.sh @@ -27,14 +27,14 @@ MODULE_DIRECTORY=${DRIVER_DIRECTORY}/jumpstarter_driver_${DRIVER_NAME} mkdir -p ${MODULE_DIRECTORY} mkdir -p ${DRIVER_DIRECTORY}/examples -# Create documentation file +# Define paths DOCS_DIRECTORY=docs/source/api-reference/drivers DOC_FILE=${DOCS_DIRECTORY}/${DRIVER_NAME}.md +README_FILE=${DRIVER_DIRECTORY}/README.md -# Create initial documentation file if it doesn't exist -if [ ! -f "${DOC_FILE}" ]; then - echo "Creating initial documentation file: ${DOC_FILE}" - cat > "${DOC_FILE}" << 'EOF' +# Create README.md file with initial documentation +echo "Creating README.md file: ${README_FILE}" +cat > "${README_FILE}" << 'EOF' # ${DRIVER_CLASS} Driver `jumpstarter-driver-${DRIVER_NAME}` provides functionality for interacting with ${DRIVER_NAME} devices. @@ -61,11 +61,17 @@ interfaces: Add API documentation here. EOF - # Need to expand variables after EOF to prevent early expansion - sed -i "s/\${DRIVER_CLASS}/${DRIVER_CLASS}/g; s/\${DRIVER_NAME}/${DRIVER_NAME}/g" "${DOC_FILE}" - echo "Documentation file content:" - cat "${DOC_FILE}" -fi +# Need to expand variables after EOF to prevent early expansion +sed -i "s/\${DRIVER_CLASS}/${DRIVER_CLASS}/g; s/\${DRIVER_NAME}/${DRIVER_NAME}/g" "${README_FILE}" +echo "README.md file content:" +cat "${README_FILE}" + +# Create symlink from documentation directory to README.md +mkdir -p ${DOCS_DIRECTORY} +echo "Creating symlink to README.md file" +rel_path=$(realpath --relative-to="${DOCS_DIRECTORY}" "${README_FILE}") +ln -sf "${rel_path}" "${DOC_FILE}" +echo "Created symlink: ${DOC_FILE} -> ${rel_path}" for f in __init__.py client.py driver_test.py driver.py; do echo "Creating: ${MODULE_DIRECTORY}/${f}" @@ -76,9 +82,3 @@ for f in .gitignore pyproject.toml examples/exporter.yaml; do echo "Creating: ${DRIVER_DIRECTORY}/${f}" envsubst < __templates__/driver/${f}.tmpl > ${DRIVER_DIRECTORY}/${f} done - -# Create symlink to documentation file instead of README.md -echo "Creating symlink to documentation file" -rel_path=$(realpath --relative-to="${DRIVER_DIRECTORY}" "${DOC_FILE}") -ln -sf "${rel_path}" "${DRIVER_DIRECTORY}/README.md" -echo "Created symlink: ${DRIVER_DIRECTORY}/README.md -> ${rel_path}" diff --git a/__templates__/driver/pyproject.toml.tmpl b/__templates__/driver/pyproject.toml.tmpl index 13a5cbbc4..8721aced4 100644 --- a/__templates__/driver/pyproject.toml.tmpl +++ b/__templates__/driver/pyproject.toml.tmpl @@ -3,7 +3,7 @@ name = "jumpstarter-driver-${DRIVER_NAME}" dynamic = ["version", "urls"] description = "Add your description here" readme = "README.md" -license = "Apache-2.0" +license = "Apache-2.0" authors = [ { name = "${AUTHOR_NAME}", email = "${AUTHOR_EMAIL}" } ] diff --git a/docs/source/api-reference/drivers/can.md b/docs/source/api-reference/drivers/can.md deleted file mode 100644 index 571fdcfdd..000000000 --- a/docs/source/api-reference/drivers/can.md +++ /dev/null @@ -1,33 +0,0 @@ -# CAN driver - -`jumpstarter-driver-can` provides functionality for interacting with CAN bus connections. - -## Installation - -```bash -pip install jumpstarter-driver-can -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - can: - driver: jumpstarter_driver_can.CANDriver - parameters: - # Add required parameters here -``` - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_can.client.CanClient() - :members: -``` - -```{eval-rst} -.. autoclass:: jumpstarter_driver_can.client.IsoTpClient() - :members: -``` diff --git a/docs/source/api-reference/drivers/can.md b/docs/source/api-reference/drivers/can.md new file mode 120000 index 000000000..a30c88701 --- /dev/null +++ b/docs/source/api-reference/drivers/can.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-can/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/corellium.md b/docs/source/api-reference/drivers/corellium.md deleted file mode 100644 index f6abaa972..000000000 --- a/docs/source/api-reference/drivers/corellium.md +++ /dev/null @@ -1,72 +0,0 @@ -# Corellium Driver - -`jumpstarter-driver-corellium` provides functionality for interacting with [Corellium](https://corellium.com) virtualization platform. - -## Installation - -```bash -pip install jumpstarter-driver-corellium -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - corellium: - driver: jumpstarter_driver_corellium.driver.Corellium - parameters: - project_id: "778f00af-5e9b-40e6-8e7f-c4f14b632e9c" - device_name: "jmp-rd1ae" - device_flavor: "kronos" - # Optional parameters - # device_os: "1.0" - # device_build: "Critical Application Monitor (Baremetal)" -``` - -## API Reference - -For more examples, check the [examples folder](./examples). - -### ExporterConfig Example - -You can run an exporter by running: `jmp exporter shell -c $file`: - -```yml -apiVersion: jumpstarter.dev/v1alpha1 -kind: ExporterConfig -# endpoint and token are intentionally left empty -metadata: - namespace: default - name: corellium-demo -endpoint: "" -token: "" -export: - rd1ae: - type: jumpstarter_driver_corellium.driver.Corellium - config: - project_id: "778f00af-5e9b-40e6-8e7f-c4f14b632e9c" - device_name: "jmp-rd1ae" - device_flavor: "kronos" -``` - -```yml -apiVersion: jumpstarter.dev/v1alpha1 -kind: ExporterConfig -# endpoint and token are intentionally left empty -metadata: - namespace: default - name: corellium-demo -endpoint: "" -token: "" -export: - rd1ae: - type: jumpstarter_driver_corellium.driver.Corellium - config: - project_id: "778f00af-5e9b-40e6-8e7f-c4f14b632e9c" - device_name: "jmp-rd1ae" - device_flavor: "kronos" - device_os: "1.0" - device_build: "Critical Application Monitor (Baremetal)" -``` diff --git a/docs/source/api-reference/drivers/corellium.md b/docs/source/api-reference/drivers/corellium.md new file mode 120000 index 000000000..f9d1f64cd --- /dev/null +++ b/docs/source/api-reference/drivers/corellium.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-corellium/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/dutlink.md b/docs/source/api-reference/drivers/dutlink.md deleted file mode 100644 index a8cd77c0e..000000000 --- a/docs/source/api-reference/drivers/dutlink.md +++ /dev/null @@ -1,25 +0,0 @@ -# DUT Link driver - -`jumpstarter-driver-dutlink` provides functionality for interacting with DUT Link devices. - -## Installation - -```bash -pip install jumpstarter-driver-dutlink -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - dutlink: - driver: jumpstarter_driver_dutlink.DUTLinkDriver - parameters: - # Add required parameters here -``` - -## API Reference - -Add API documentation here. diff --git a/docs/source/api-reference/drivers/dutlink.md b/docs/source/api-reference/drivers/dutlink.md new file mode 120000 index 000000000..1bd2fa127 --- /dev/null +++ b/docs/source/api-reference/drivers/dutlink.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-dutlink/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/flashers.md b/docs/source/api-reference/drivers/flashers.md deleted file mode 100644 index 959a3c8b5..000000000 --- a/docs/source/api-reference/drivers/flashers.md +++ /dev/null @@ -1,304 +0,0 @@ -# Flashers - -The flasher drivers are used to flash images to DUTs via network, typically -using TFTP and HTTP. It is designed to interact with the target bootloader and -busybox shell to flash the DUT. - -All flasher drivers inherit from the -`jumpstarter_driver_flashers.driver.BaseFlasher` class, referencing their own -bundle of binary artifacts necessary to flash the DUT, like kernel/initram/dtbs. -See the [bundle](#oci-bundles) section for more details. - -## Available drivers and bundles - -| Driver | Bundle | -| --------------- | ------------------------------------------------------------ | -| TIJ784S4Flasher | quay.io/jumpstarter-dev/jumpstarter-flasher-ti-j784s4:latest | - - -## Driver configuration -**driver**: `jumpstarter_driver_flashers.driver.${DRIVER}` - -```yaml -export: - storage: - type: "jumpstarter_driver_flashers.driver.TIJ784S4Flasher" - children: - serial: - ref: "serial" - power: - ref: "power" - serial: - type: "jumpstarter_driver_pyserial.driver.PySerial" - config: - url: "/dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_112214101760A-if00-port0" - baudrate: 115200 - power: - type: jumpstarter_driver_yepkit.driver.Ykush - config: - serial: "YK112233" - port: "1" -``` - -flasher drivers require four children drivers: | Child Driver | Description | -Auto-created | | ------------ | ---------------------------------------------------------------------------------- -| ------------ | | serial | To communicate with the DUT via serial and -drive the bootloader and busybox shell | No | | power | To -power on and off the DUT | -No | | tftp | To serve binaries via TFTP | Yes | | -http | To serve the images via HTTP | Yes | - -In the above example we provide the serial and power children by -[reference](./proxy.md), so those remain also available on the root of the -exporter. - -The power driver is used to control power cycling of the DUT, and the serial -interface is used to communicate with the DUT bootloader via serial. TFTP and -HTTP servers are used to serve images to the DUT bootloader and busybox shell. - -### Config parameters - -| Parameter | Description | Type | Required | Default | -| -------------- | ------------------------------------------ | ---- | -------- | ---------------------------- | -| flasher_bundle | The OCI bundle to use for the flasher | str | yes | | -| cache_dir | The directory to cache the images | str | no | /var/lib/jumpstarter/flasher | -| tftp_dir | The directory to serve the images via TFTP | str | no | /var/lib/tftpboot | -| http_dir | The directory to serve the images via HTTP | str | no | /var/www/html | - - -## BaseFlasher API - -The `BaseFlasher` class provides a set of methods to flash the DUT, -```{eval-rst} -.. autoclass:: jumpstarter_driver_flashers.client.BaseFlasherClient() - :members: flash, busybox_shell, bootloader_shell, use_dtb, use_initram, use_kernel -``` - -## CLI - -The flasher driver provides a CLI to perform flashing, access to busybox shell -and uboot. - - -```bash -$ jmp shell -l board=ti-03 -INFO:jumpstarter.client.lease:Created lease request for labels {'board': 'ti-03'} for 0:30:00 -jumpstarter ⚡remote ➤ j storage -Usage: j storage [OPTIONS] COMMAND [ARGS]... - - Software-defined flasher interface - -Options: - --help Show this message and exit. - -Commands: - bootloader-shell Start a uboot/bootloader interactive console - busybox-shell Start a busybox shell - flash Flash image to DUT from file - -``` - -### flash -```bash -Usage: j storage flash [OPTIONS] FILE - - Flash image to DUT from file - -Options: - --partition TEXT - --os-image-checksum TEXT SHA256 checksum of OS image (direct value) - --os-image-checksum-file FILE File containing SHA256 checksum of OS image - --force-exporter-http Force use of exporter HTTP - --force-flash-bundle TEXT Force use of a specific flasher OCI bundle - --console-debug Enable console debug mode - --help Show this message and exit. -``` - -Example: -``` -jumpstarter ⚡remote ➤ j storage flash https://autosd.sig.centos.org/AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz -BaseFlasherClient - INFO - Writing image to storage in the background: /AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz -BaseFlasherClient - INFO - Setting up flasher bundle files in exporter -BaseFlasherClient - INFO - Writing image from storage, with metadata: md5=None,size=592736176 etag="23546fb0-63045567a5b80" -SNMPServerClient - INFO - Starting power cycle sequence -SNMPServerClient - INFO - Waiting 2 seconds... -SNMPServerClient - INFO - Power cycle sequence complete -BaseFlasherClient - INFO - Waiting for U-Boot prompt... -BaseFlasherClient - INFO - Running DHCP to obtain network configuration... -BaseFlasherClient - INFO - Running command: dhcp -BaseFlasherClient - INFO - Running command: printenv netmask -BaseFlasherClient - INFO - discovered dhcp details: DhcpInfo(ip_address='x.x.x.x', gateway='x.x.x.x', netmask='255.255.255.0') -BaseFlasherClient - INFO - Image written to storage: /AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz -BaseFlasherClient - INFO - Running command: setenv serverip 'x.x.x.x' -BaseFlasherClient - INFO - Running command: tftpboot 0x82000000 J784S4XEVM.flasher.img -BaseFlasherClient - INFO - Running command: tftpboot 0x84000000 k3-j784s4-evm.dtb -BaseFlasherClient - INFO - Running boot command: booti 0x82000000 - 0x84000000 -BaseFlasherClient - INFO - Using target block device: /dev/mmcblk1 -BaseFlasherClient - INFO - Running preflash command: dd if=/dev/zero of=/dev/mmcblk0 bs=512 count=34 -BaseFlasherClient - INFO - Running preflash command: dd if=/dev/zero of=/dev/mmcblk1 bs=512 count=34 -BaseFlasherClient - INFO - Waiting until the http image preparation in storage is completed -BaseFlasherClient - INFO - Flash progress: 25.00 MB, Speed: 15.78 MB/s -... -... -BaseFlasherClient - INFO - Flash progress: 5086.12 MB, Speed: 13.77 MB/s -BaseFlasherClient - INFO - Flash progress: 5102.94 MB, Speed: 12.93 MB/s -BaseFlasherClient - INFO - Flushing buffers -BaseFlasherClient - INFO - Flashing completed in 7:26 -BaseFlasherClient - INFO - Powering off target -``` - -### bootloader-shell -```bash -Usage: j storage bootloader-shell [OPTIONS] - - Start a uboot/bootloader interactive console - -Options: - --console-debug Enable console debug mode - --help Show this message and exit. -``` - -Example -``` -jumpstarter ⚡remote ➤ j storage bootloader-shell -BaseFlasherClient - INFO - Setting up flasher bundle files in exporter -SNMPServerClient - INFO - Starting power cycle sequence -SNMPServerClient - INFO - Waiting 2 seconds... -SNMPServerClient - INFO - Power cycle sequence complete -BaseFlasherClient - INFO - Waiting for U-Boot prompt... -=> version -U-Boot 2024.01-rc3 (Jan 09 2024 - 00:00:00 +0000) - -gcc (GCC) 11.4.1 20231218 (Red Hat 11.4.1-3) -GNU ld version 2.35.2-42.el9 -``` -### busybox-shell -```bash -Usage: j storage busybox-shell [OPTIONS] - - Start a busybox interactive console - -Options: - --console-debug Enable console debug mode - --help Show this message and exit. -``` - -Example -``` -jumpstarter ⚡remote ➤ j storage busybox-shell -BaseFlasherClient - INFO - Setting up flasher bundle files in exporter -SNMPServerClient - INFO - Starting power cycle sequence -SNMPServerClient - INFO - Waiting 2 seconds... -SNMPServerClient - INFO - Power cycle sequence complete -BaseFlasherClient - INFO - Waiting for U-Boot prompt... -BaseFlasherClient - INFO - Running DHCP to obtain network configuration... -BaseFlasherClient - INFO - Running command: dhcp -BaseFlasherClient - INFO - Running command: printenv netmask -BaseFlasherClient - INFO - discovered dhcp details: DhcpInfo(ip_address='10.26.28.138', gateway='10.26.28.254', netmask='255.255.255.0') -BaseFlasherClient - INFO - Running command: setenv serverip '10.26.28.62' -BaseFlasherClient - INFO - Running command: tftpboot 0x82000000 J784S4XEVM.flasher.img -BaseFlasherClient - INFO - Running command: tftpboot 0x84000000 k3-j784s4-evm.dtb -BaseFlasherClient - INFO - Running boot command: booti 0x82000000 - 0x84000000 -# uname -a -Linux buildroot 6.1.46-dirty #2 SMP PREEMPT Thu Mar 14 14:37:01 UTC 2024 aarch64 GNU/Linux -# -``` - -## Examples - -Flash the device with a specific image -```python -flasherclient.flash("/path/to/image.raw.xz") -``` - -Flash the device with a specific image from a remote URL -```python -flasherclient.flash("https://autosd.sig.centos.org/AutoSD-9/nightly/TI/auto-osbuild-j784s4evm-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz") -``` - -Flash into a specific partition -```python -flasherclient.flash("/path/to/image.raw.xz", partition="emmc") -``` - - -## Examples of utility consoles - -In addition to the flashing mechanisms, the flasher drivers also provide a way -to access the DUT bootloader and busybox shell for convenience and debugging, -when using the `busybox_shell` and `bootloader_shell` methods the embedded http -and tftp servers will be online and serving the images from the flasher bundle. - -Get the busybox shell on the device -```python -with flasherclient.busybox_shell() as serial: - serial.send("ls -la\n") - serial.expect("#") - print(serial.before) -``` - -Get the bootloader shell on the device -```python -with flasherclient.bootloader_shell() as serial: - serial.send("version\n") - serial.expect("=>") - print(serial.before) -``` - -# oci-bundles -The flasher drivers require some artifacts and basic information about the -target device to operate. To make this easy to distribute and use, we use OCI -bundles to package the artifacts and metadata. - -The bundle is a container that uses [oras](https://oras.land/) to transport the -artifacts and metadata. It is a container that contains the following: -- `manifest.yaml`: The manifest file that describes the bundle -- `data/*`: The artifacts, including kernel, initram, dtbs, etc. - -## The format of the manifest is as follows: - -```{literalinclude} ../../../../packages/jumpstarter-driver-flashers/oci_bundles/test/manifest.yaml -:language: yaml -``` -## Table with the spec fields of the manifest: -| Field | Description | Default | -| -------------------- | -------------------------------------------------------------------------- | ------- | -| `manufacturer` | Name of the device manufacturer | | -| `link` | URL to device documentation or manufacturer website | | -| `bootcmd` | Command used to boot the device (e.g. booti, bootz) | | -| `default_target` | Default target device to flash to if none specified | | -| `targets` | Map of target names to device paths | | -| `login.type` | Type of login shell | busybox | -| `login.login_prompt` | Expected login prompt string | login: | -| `login.username` | Username to log in with, leave empty if not needed | | -| `login.password` | Password for login, leave empty if not needed | | -| `login.prompt` | Shell prompt after successful login | # | -| `preflash_commands` | List of commands to run before flashing, useful to clear boot entries, etc | | -| `kernel.file` | Path to kernel image within bundle | -| `kernel.address` | Memory address to load kernel to | | -| `initram.file` | Path to initramfs within bundle (if any) | | -| `initram.address` | Memory address to load initramfs to (if any) | | -| `dtb.default` | Default DTB variant to use | | -| `dtb.address` | Memory address to load DTB to | | -| `dtb.variants` | Map of DTB variant names to files | - - -## Examples - -An example bundle for the TI J784S4XEVM looks like this: - -```{literalinclude} ../../../../packages/jumpstarter-driver-flashers/oci_bundles/ti_j784s4xevm/manifest.yaml -:language: yaml -``` - -You can find a script to build and push a bundle to a registry here: -[oci_bundles](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-flashers/oci_bundles) - diff --git a/docs/source/api-reference/drivers/flashers.md b/docs/source/api-reference/drivers/flashers.md new file mode 120000 index 000000000..fb286a1a9 --- /dev/null +++ b/docs/source/api-reference/drivers/flashers.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-flashers/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/http.md b/docs/source/api-reference/drivers/http.md deleted file mode 100644 index 4a05aa647..000000000 --- a/docs/source/api-reference/drivers/http.md +++ /dev/null @@ -1,25 +0,0 @@ -# HTTP driver - -`jumpstarter-driver-http` provides functionality for HTTP communication. - -## Installation - -```bash -pip install jumpstarter-driver-http -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - http: - driver: jumpstarter_driver_http.HTTPDriver - parameters: - # Add required parameters here -``` - -## API Reference - -Add API documentation here. diff --git a/docs/source/api-reference/drivers/http.md b/docs/source/api-reference/drivers/http.md new file mode 120000 index 000000000..41d9e15d8 --- /dev/null +++ b/docs/source/api-reference/drivers/http.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-http/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/index.md b/docs/source/api-reference/drivers/index.md index 0347ee0d2..e3e28ac50 100644 --- a/docs/source/api-reference/drivers/index.md +++ b/docs/source/api-reference/drivers/index.md @@ -9,50 +9,51 @@ Jumpstarter includes several types of drivers organized by their primary functio ### System Control Drivers Drivers that control the power state and basic operation of devices: -* **[Power](/api-reference/drivers/power.md)** (`jumpstarter-driver-power`) - Power control for devices -* **[Raspberry Pi](/api-reference/drivers/raspberrypi.md)** (`jumpstarter-driver-raspberrypi`) - Raspberry Pi hardware control -* **[Yepkit](/api-reference/drivers/yepkit.md)** (`jumpstarter-driver-yepkit`) - Yepkit hardware control -* **[DUT Link](/api-reference/drivers/dutlink.md)** (`jumpstarter-driver-dutlink`) - [DUT Link Board](https://github.com/jumpstarter-dev/dutlink-board) hardware control +* **[Power](power.md)** (`jumpstarter-driver-power`) - Power control for devices +* **[Raspberry Pi](raspberrypi.md)** (`jumpstarter-driver-raspberrypi`) - Raspberry Pi hardware control +* **[Yepkit](yepkit.md)** (`jumpstarter-driver-yepkit`) - Yepkit hardware control +* **[DUT Link](dutlink.md)** (`jumpstarter-driver-dutlink`) - [DUT Link Board](https://github.com/jumpstarter-dev/dutlink-board) hardware control ### Communication Drivers Drivers that provide various communication interfaces: -* **[CAN](/api-reference/drivers/can.md)** (`jumpstarter-driver-can`) - Controller Area Network communication -* **[D-Bus](/api-reference/drivers/dbus.md)** (`jumpstarter-driver-dbus`) - D-Bus message system interface -* **[HTTP](/api-reference/drivers/http.md)** (`jumpstarter-driver-http`) - HTTP communication -* **[Network](/api-reference/drivers/network.md)** (`jumpstarter-driver-network`) - Network interfaces and configuration -* **[Proxy](/api-reference/drivers/proxy.md)** (`jumpstarter-driver-proxy`) - Network proxy functionality -* **[PySerial](/api-reference/drivers/pyserial.md)** (`jumpstarter-driver-pyserial`) - Serial port communication -* **[SNMP](/api-reference/drivers/snmp.md)** (`jumpstarter-driver-snmp`) - Simple Network Management Protocol -* **[TFTP](/api-reference/drivers/tftp.md)** (`jumpstarter-driver-tftp`) - Trivial File Transfer Protocol +* **[CAN](can.md)** (`jumpstarter-driver-can`) - Controller Area Network communication +* **[D-Bus](dbus.md)** (`jumpstarter-driver-dbus`) - D-Bus message system interface +* **[HTTP](http.md)** (`jumpstarter-driver-http`) - HTTP communication +* **[Network](network.md)** (`jumpstarter-driver-network`) - Network interfaces and configuration +* **[Proxy](proxy.md)** (`jumpstarter-driver-proxy`) - Network proxy functionality +* **[PySerial](pyserial.md)** (`jumpstarter-driver-pyserial`) - Serial port communication +* **[SNMP](snmp.md)** (`jumpstarter-driver-snmp`) - Simple Network Management Protocol +* **[TFTP](tftp.md)** (`jumpstarter-driver-tftp`) - Trivial File Transfer Protocol ### Storage and Data Drivers Drivers that control storage devices and manage data: -* **[OpenDAL](/api-reference/drivers/opendal.md)** (`jumpstarter-driver-opendal`) - Open Data Access Layer -* **[SD Wire](/api-reference/drivers/sdwire.md)** (`jumpstarter-driver-sdwire`) - SD card switching utilities +* **[OpenDAL](opendal.md)** (`jumpstarter-driver-opendal`) - Open Data Access Layer +* **[SD Wire](sdwire.md)** (`jumpstarter-driver-sdwire`) - SD card switching utilities ### Media Drivers Drivers that handle media streams: -* **[UStreamer](/api-reference/drivers/ustreamer.md)** (`jumpstarter-driver-ustreamer`) - Video streaming functionality +* **[UStreamer](ustreamer.md)** (`jumpstarter-driver-ustreamer`) - Video streaming functionality ### Debug and Programming Drivers Drivers for debugging and programming devices: -* **[Flashers](/api-reference/drivers/flashers.md)** (`jumpstarter-driver-flashers`) - Flash memory programming tools -* **[Probe-RS](/api-reference/drivers/probe-rs.md)** (`jumpstarter-driver-probe-rs`) - Debugging probe support -* **[QEMU](/api-reference/drivers/qemu.md)** (`jumpstarter-driver-qemu`) - QEMU virtualization platform -* **[Corellium](/api-reference/drivers/corellium.md)** (`jumpstarter-driver-corellium`) - Corellium virtualization platform -* **[U-Boot](/api-reference/drivers/uboot.md)** (`jumpstarter-driver-uboot`) - Universal Bootloader interface +* **[Flashers](flashers.md)** (`jumpstarter-driver-flashers`) - Flash memory programming tools +* **[Probe-RS](probe-rs.md)** (`jumpstarter-driver-probe-rs`) - Debugging probe support +* **[QEMU](qemu.md)** (`jumpstarter-driver-qemu`) - QEMU virtualization platform +* **[Corellium](corellium.md)** (`jumpstarter-driver-corellium`) - Corellium virtualization platform +* **[U-Boot](uboot.md)** (`jumpstarter-driver-uboot`) - Universal Bootloader interface ### Utility Drivers General-purpose utility drivers: -* **[Shell](/api-reference/drivers/shell.md)** (`jumpstarter-driver-shell`) - Shell command execution +* **[Shell](shell.md)** (`jumpstarter-driver-shell`) - Shell command execution ```{toctree} :hidden: +:sorted: can.md corellium.md dbus.md diff --git a/docs/source/api-reference/drivers/network.md b/docs/source/api-reference/drivers/network.md deleted file mode 100644 index a138f832b..000000000 --- a/docs/source/api-reference/drivers/network.md +++ /dev/null @@ -1,48 +0,0 @@ -# Network drivers - -`jumpstarter-driver-network` provides functionality for interacting with network servers and connections. - -## Installation - -```bash -pip install jumpstarter-driver-network -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - network: - driver: jumpstarter_driver_network.NetworkDriver - parameters: - # Add required parameters here -``` - -## API Reference - -Network driver classes: - -```{eval-rst} -.. autoclass:: jumpstarter_driver_network.driver.TcpNetwork() -``` - -```{eval-rst} -.. autoclass:: jumpstarter_driver_network.driver.UdpNetwork() -``` - -```{eval-rst} -.. autoclass:: jumpstarter_driver_network.driver.UnixNetwork() -``` - -```{eval-rst} -.. autoclass:: jumpstarter_driver_network.driver.EchoNetwork() -``` - -Client API: - -```{eval-rst} -.. autoclass:: jumpstarter_driver_network.client.NetworkClient() - :members: -``` diff --git a/docs/source/api-reference/drivers/network.md b/docs/source/api-reference/drivers/network.md new file mode 120000 index 000000000..5289129ef --- /dev/null +++ b/docs/source/api-reference/drivers/network.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-network/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/opendal.md b/docs/source/api-reference/drivers/opendal.md deleted file mode 100644 index 192cb30ec..000000000 --- a/docs/source/api-reference/drivers/opendal.md +++ /dev/null @@ -1,74 +0,0 @@ -# OpenDAL driver - -`jumpstarter-driver-opendal` provides functionality for interacting with storages attached to the exporter. - -## Installation - -```bash -pip install jumpstarter-driver-opendal -``` - -## Configuration - -Example configuration: - -```{literalinclude} opendal.yaml -:language: yaml -``` - -## API Reference - -### Examples - -```{doctest} ->>> from tempfile import NamedTemporaryFile ->>> opendal.create_dir("test/directory/") ->>> opendal.write_bytes("test/directory/file", b"hello") ->>> assert opendal.hash("test/directory/file", "md5") == "5d41402abc4b2a76b9719d911017c592" ->>> opendal.remove_all("test/") -``` - -```{testsetup} * -from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance -from jumpstarter.common.utils import serve - -instance = serve( - ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/opendal.yaml" -).instantiate()) - -opendal = instance.__enter__() -``` - -```{testcleanup} * -instance.__exit__(None, None, None) -``` - -### Client API - -```{eval-rst} -.. autoclass:: jumpstarter_driver_opendal.client.OpendalClient() - :members: - -.. autoclass:: jumpstarter_driver_opendal.client.OpendalFile() - :members: - -.. autoclass:: jumpstarter_driver_opendal.common.Metadata() - :members: - :undoc-members: - :exclude-members: model_config - -.. autoclass:: jumpstarter_driver_opendal.common.EntryMode() - :members: - :undoc-members: - :exclude-members: model_config - -.. autoclass:: jumpstarter_driver_opendal.common.PresignedRequest() - :members: - :undoc-members: - :exclude-members: model_config - -.. autoclass:: jumpstarter_driver_opendal.common.Capability() - :members: - :undoc-members: - :exclude-members: model_config -``` diff --git a/docs/source/api-reference/drivers/opendal.md b/docs/source/api-reference/drivers/opendal.md new file mode 120000 index 000000000..18cc8250f --- /dev/null +++ b/docs/source/api-reference/drivers/opendal.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-opendal/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/power.md b/docs/source/api-reference/drivers/power.md deleted file mode 100644 index 1b440dbb5..000000000 --- a/docs/source/api-reference/drivers/power.md +++ /dev/null @@ -1,25 +0,0 @@ -# Power driver - -`jumpstarter-driver-power` provides functionality for interacting with power control devices. - -## Installation - -```bash -pip install jumpstarter-driver-power -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - power: - driver: jumpstarter_driver_power.PowerDriver - parameters: - # Add required parameters here -``` - -## API Reference - -Add API documentation here. diff --git a/docs/source/api-reference/drivers/power.md b/docs/source/api-reference/drivers/power.md new file mode 120000 index 000000000..68fc38a36 --- /dev/null +++ b/docs/source/api-reference/drivers/power.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-power/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/probe-rs.md b/docs/source/api-reference/drivers/probe-rs.md deleted file mode 100644 index 1b757704e..000000000 --- a/docs/source/api-reference/drivers/probe-rs.md +++ /dev/null @@ -1,62 +0,0 @@ -# probe-rs driver - -`jumpstarter-driver-probe-rs` provides functionality for remote debugging and flashing of embedded devices using the [probe-rs](https://probe.rs) tools. - -## Installation - -```bash -pip install jumpstarter-driver-probe-rs -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - probe: - driver: jumpstarter_driver_probe_rs.driver.ProbeRs - parameters: - probe: "2e8a:000c:5798DE5E500ACB60" - probe_rs_path: "/home/majopela/.cargo/bin/probe-rs" - chip: "RP2350" - protocol: "swd" - connect_under_reset: false -``` - -### Config parameters - -| Parameter | Description | Type | Required | Default | -| ------------------- | -------------------------------------------------------------- | --------------- | -------- | -------- | -| probe | The probe id, can be in VID:PID format or VID:PID:SERIALNUMBER | str | no | | -| probe_rs_path | The path to the probe-rs binary | str | no | probe-rs | -| chip | The target chip | str | no | | -| protocol | The target protocol | "swd" or "jtag" | no | | -| connect_under_reset | Connect to the target while asserting reset | bool | no | false | - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_probe_rs.client.ProbeRsClient() - :members: -``` - -### CLI - -The probe driver client comes with a CLI tool that can be used to interact with the target device. -``` -jumpstarter ⚡ local ➤ j probe -Usage: j probe [OPTIONS] COMMAND [ARGS]... - - probe-rs client - -Options: - --help Show this message and exit. - -Commands: - download Download a file to the target - erase Erase the target, this is a slow operation. - info Get target information - read read from target memory - reset Reset the target -``` \ No newline at end of file diff --git a/docs/source/api-reference/drivers/probe-rs.md b/docs/source/api-reference/drivers/probe-rs.md new file mode 120000 index 000000000..b16d5cb8c --- /dev/null +++ b/docs/source/api-reference/drivers/probe-rs.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-probe-rs/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/pyserial.md b/docs/source/api-reference/drivers/pyserial.md deleted file mode 100644 index 42ea3adbd..000000000 --- a/docs/source/api-reference/drivers/pyserial.md +++ /dev/null @@ -1,81 +0,0 @@ -# PySerial driver - -`jumpstarter-driver-pyserial` provides functionality for serial port communication. - -## Installation - -```bash -pip install jumpstarter-driver-pyserial -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - serial: - driver: jumpstarter_driver_pyserial.driver.PySerial - parameters: - url: "/dev/ttyUSB0" - baudrate: 115200 -``` - -### Config parameters - -| Parameter | Description | Type | Required | Default | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------- | ------- | -| url | The serial port to connect to, in [pyserial format](https://pyserial.readthedocs.io/en/latest/url_handlers.html) | str | yes | | -| baudrate | The baudrate to use for the serial connection | int | no | 115200 | -| check_existing | Check if the serial port exists during exporter initialization, disable if you are connecting to a dynamically created port (i.e. USB from your DUT) | bool | no | True | - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_pyserial.client.PySerialClient() - :members: pexpect, open, stream, open_stream, close -``` - -### Examples - -Using expect with a context manager -```{testcode} -with pyserialclient.pexpect() as session: - session.sendline("Hello, world!") - session.expect("Hello, world!") -``` - -Using expect without a context manager -```{testcode} -session = pyserialclient.open() -session.sendline("Hello, world!") -session.expect("Hello, world!") -pyserialclient.close() -``` - -Using a simple BlockingStream with a context manager -```{testcode} -with pyserialclient.stream() as stream: - stream.send(b"Hello, world!") - data = stream.receive() -``` - -Using a simple BlockingStream without a context manager -```{testcode} -stream = pyserialclient.open_stream() -stream.send(b"Hello, world!") -data = stream.receive() -``` - -```{testsetup} * -from jumpstarter_driver_pyserial.driver import PySerial -from jumpstarter.common.utils import serve - -instance = serve(PySerial(url="loop://")) - -pyserialclient = instance.__enter__() -``` - -```{testcleanup} * -instance.__exit__(None, None, None) -``` diff --git a/docs/source/api-reference/drivers/pyserial.md b/docs/source/api-reference/drivers/pyserial.md new file mode 120000 index 000000000..5d36bff85 --- /dev/null +++ b/docs/source/api-reference/drivers/pyserial.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-pyserial/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/qemu.md b/docs/source/api-reference/drivers/qemu.md deleted file mode 100644 index dce106570..000000000 --- a/docs/source/api-reference/drivers/qemu.md +++ /dev/null @@ -1,25 +0,0 @@ -# QEMU driver - -`jumpstarter-driver-qemu` provides functionality for interacting with QEMU virtualization platform. - -## Installation - -```bash -pip install jumpstarter-driver-qemu -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - qemu: - driver: jumpstarter_driver_qemu.QEMUDriver - parameters: - # Add required parameters here -``` - -## API Reference - -Add API documentation here. diff --git a/docs/source/api-reference/drivers/qemu.md b/docs/source/api-reference/drivers/qemu.md new file mode 120000 index 000000000..857cc7465 --- /dev/null +++ b/docs/source/api-reference/drivers/qemu.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-qemu/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/raspberrypi.md b/docs/source/api-reference/drivers/raspberrypi.md deleted file mode 100644 index 185d0faf2..000000000 --- a/docs/source/api-reference/drivers/raspberrypi.md +++ /dev/null @@ -1,25 +0,0 @@ -# Raspberry Pi driver - -`jumpstarter-driver-raspberrypi` provides functionality for interacting with Raspberry Pi devices. - -## Installation - -```bash -pip install jumpstarter-driver-raspberrypi -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - raspberrypi: - driver: jumpstarter_driver_raspberrypi.RaspberryPiDriver - parameters: - # Add required parameters here -``` - -## API Reference - -Add API documentation here. diff --git a/docs/source/api-reference/drivers/raspberrypi.md b/docs/source/api-reference/drivers/raspberrypi.md new file mode 120000 index 000000000..407825680 --- /dev/null +++ b/docs/source/api-reference/drivers/raspberrypi.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-raspberrypi/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/sdwire.md b/docs/source/api-reference/drivers/sdwire.md deleted file mode 100644 index dfb6c2e43..000000000 --- a/docs/source/api-reference/drivers/sdwire.md +++ /dev/null @@ -1,35 +0,0 @@ -# SDWire driver - -`jumpstarter-driver-sdwire` provides functionality for using the SDWire storage multiplexer. This device multiplexes an SD card between the DUT and the exporter host. - -## Installation - -```bash -pip install jumpstarter-driver-sdwire -``` - -## Configuration - -Example configuration: - -```{literalinclude} sdwire.yaml -:language: yaml -``` - -```{doctest} -:hide: ->>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance ->>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/sdwire.yaml").instantiate() -Traceback (most recent call last): -... -FileNotFoundError: failed to find sd-wire device -``` - -## API Reference - -The SDWire driver implements the `StorageMuxClient` class, which is a generic storage class. - -```{eval-rst} -.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClient() - :members: -``` diff --git a/docs/source/api-reference/drivers/sdwire.md b/docs/source/api-reference/drivers/sdwire.md new file mode 120000 index 000000000..b28d5d1ed --- /dev/null +++ b/docs/source/api-reference/drivers/sdwire.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-sdwire/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/shell.md b/docs/source/api-reference/drivers/shell.md deleted file mode 100644 index 827add1de..000000000 --- a/docs/source/api-reference/drivers/shell.md +++ /dev/null @@ -1,63 +0,0 @@ -# Shell driver - -`jumpstarter-driver-shell` provides functionality for shell command execution. - -## Installation - -```bash -pip install jumpstarter-driver-shell -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - shell: - driver: jumpstarter_driver_shell.driver.Shell - parameters: - methods: - ls: "ls" - method2: "echo 'Hello World 2'" - #multi line method - method3: | - echo 'Hello World $1' - echo 'Hello World $2' - env_var: "echo $1,$2,$ENV_VAR" - # optional parameters - cwd: "/tmp" - log_level: "INFO" - shell: - - "/bin/bash" - - "-c" -``` - -## API Reference - -Assuming the exporter driver is configured as in the example above, the client methods will be generated dynamically, and they will be available as follows: - -```{eval-rst} -.. autoclass:: jumpstarter_driver_shell.client.ShellClient - :members: - -.. function:: ls() - :noindex: - - :returns: A tuple(stdout, stderr, return_code) - -.. function:: method2() - :noindex: - - :returns: A tuple(stdout, stderr, return_code) - -.. function:: method3(arg1, arg2) - :noindex: - - :returns: A tuple(stdout, stderr, return_code) - -.. function:: env_var(arg1, arg2, ENV_VAR="value") - :noindex: - - :returns: A tuple(stdout, stderr, return_code) -``` diff --git a/docs/source/api-reference/drivers/shell.md b/docs/source/api-reference/drivers/shell.md new file mode 120000 index 000000000..5bb1ea648 --- /dev/null +++ b/docs/source/api-reference/drivers/shell.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-shell/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/snmp.md b/docs/source/api-reference/drivers/snmp.md deleted file mode 100644 index 71756d5c6..000000000 --- a/docs/source/api-reference/drivers/snmp.md +++ /dev/null @@ -1,72 +0,0 @@ -# SNMP driver - -`jumpstarter-driver-snmp` provides functionality for controlling power via SNMP-enabled PDUs (Power Distribution Units). - -## Installation - -```bash -pip install jumpstarter-driver-snmp -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - power: - driver: jumpstarter_driver_snmp.driver.SNMPServer - parameters: - host: "pdu.mgmt.com" - user: "labuser" - plug: 32 - port: 161 - oid: "1.3.6.1.4.1.13742.6.4.1.2.1.2.1" - auth_protocol: "NONE" - auth_key: null - priv_protocol: "NONE" - priv_key: null - timeout: 5.0 -``` - -### Config parameters - -| Parameter | Description | Type | Required | Default | -| ------------- | --------------------------------------------------- | ----- | -------- | --------------------------------- | -| host | Hostname or IP address of the SNMP-enabled PDU | str | yes | | -| user | SNMP v3 username | str | yes | | -| plug | PDU outlet number to control | int | yes | | -| port | SNMP port number | int | no | 161 | -| oid | Base OID for power control | str | no | "1.3.6.1.4.1.13742.6.4.1.2.1.2.1" | -| auth_protocol | Authentication protocol ("NONE", "MD5", "SHA") | str | no | "NONE" | -| auth_key | Authentication key when auth_protocol is not "NONE" | str | no | null | -| priv_protocol | Privacy protocol ("NONE", "DES", "AES") | str | no | "NONE" | -| priv_key | Privacy key when priv_protocol is not "NONE" | str | no | null | -| timeout | SNMP timeout in seconds | float | no | 5.0 | - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_snmp.client.SNMPServerClient() - :members: - :show-inheritance: -``` - -### Examples - -Power cycling a device: -```python -snmp_client.cycle(wait=3) -``` - -Basic power control: -```python -snmp_client.off() -snmp_client.on() -``` - -Using the CLI: -```bash -j power on -j power off -j power cycle --wait 3 diff --git a/docs/source/api-reference/drivers/snmp.md b/docs/source/api-reference/drivers/snmp.md new file mode 120000 index 000000000..f794c7298 --- /dev/null +++ b/docs/source/api-reference/drivers/snmp.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-snmp/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/tftp.md b/docs/source/api-reference/drivers/tftp.md deleted file mode 100644 index 9dd891a3a..000000000 --- a/docs/source/api-reference/drivers/tftp.md +++ /dev/null @@ -1,75 +0,0 @@ -# TFTP driver - -`jumpstarter-driver-tftp` provides functionality for a read-only TFTP server that can be used to serve files. - -## Installation - -```bash -pip install jumpstarter-driver-tftp -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - tftp: - driver: jumpstarter_driver_tftp.driver.Tftp - parameters: - root_dir: /var/lib/tftpboot # Directory to serve files from - host: 192.168.1.100 # Host IP to bind to (optional) - port: 69 # Port to listen on (optional) -``` - -### Config parameters - -| Parameter | Description | Type | Required | Default | -| --------- | ---------------------------------- | ---- | -------- | ------------------- | -| root_dir | Root directory for the TFTP server | str | no | "/var/lib/tftpboot" | -| host | IP address to bind the server to | str | no | auto-detect | -| port | Port number to listen on | int | no | 69 | - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_tftp.client.TftpServerClient() - :members: - :show-inheritance: -``` - -### Exception Classes - -```{eval-rst} -.. autoclass:: jumpstarter_driver_tftp.driver.TftpError - :members: - :show-inheritance: - -.. autoclass:: jumpstarter_driver_tftp.driver.ServerNotRunning - :members: - :show-inheritance: -``` - -### Examples - -```{doctest} ->>> import tempfile ->>> import os ->>> from jumpstarter_driver_tftp.driver import Tftp ->>> from jumpstarter.common.utils import serve ->>> with tempfile.TemporaryDirectory() as tmp_dir: -... # Create a test file -... test_file = os.path.join(tmp_dir, "test.txt") -... with open(test_file, "w") as f: -... _ = f.write("hello") -... -... # Start TFTP server -... with serve(Tftp(root_dir=tmp_dir, host="127.0.0.1", port=6969)) as tftp: -... tftp.start() -... -... # List files -... files = list(tftp.storage.list("/")) -... assert "test.txt" in files -... -... tftp.stop() -``` diff --git a/docs/source/api-reference/drivers/tftp.md b/docs/source/api-reference/drivers/tftp.md new file mode 120000 index 000000000..2677379ea --- /dev/null +++ b/docs/source/api-reference/drivers/tftp.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-tftp/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/uboot.md b/docs/source/api-reference/drivers/uboot.md deleted file mode 100644 index 346cf4939..000000000 --- a/docs/source/api-reference/drivers/uboot.md +++ /dev/null @@ -1,31 +0,0 @@ -# U-Boot driver - -`jumpstarter-driver-uboot` provides functionality for interacting with the U-Boot bootloader. This driver does not interact with the DUT directly, instead it should be configured with backing power and serial drivers. - -## Installation - -```bash -pip install jumpstarter-driver-uboot -``` - -## Configuration - -Example configuration: - -```{literalinclude} uboot.yaml -:language: yaml -``` - -```{doctest} -:hide: ->>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance ->>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/uboot.yaml").instantiate() -UbootConsole(...) -``` - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_uboot.client.UbootConsoleClient() - :members: -``` diff --git a/docs/source/api-reference/drivers/uboot.md b/docs/source/api-reference/drivers/uboot.md new file mode 120000 index 000000000..4f03c7ce7 --- /dev/null +++ b/docs/source/api-reference/drivers/uboot.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-uboot/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/ustreamer.md b/docs/source/api-reference/drivers/ustreamer.md deleted file mode 100644 index e4eaa7c0f..000000000 --- a/docs/source/api-reference/drivers/ustreamer.md +++ /dev/null @@ -1,33 +0,0 @@ -# Ustreamer driver - -`jumpstarter-driver-ustreamer` provides functionality for using the ustreamer video streaming server driven by the jumpstarter exporter. This driver takes a video device and exposes both snapshot and streaming interfaces. - -## Installation - -```bash -pip install jumpstarter-driver-ustreamer -``` - -## Configuration - -Example configuration: - -```{literalinclude} ustreamer.yaml -:language: yaml -``` - -```{doctest} -:hide: ->>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance ->>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/ustreamer.yaml").instantiate() -Traceback (most recent call last): -... -io.UnsupportedOperation: fileno -``` - -## API Reference - -```{eval-rst} -.. autoclass:: jumpstarter_driver_ustreamer.client.UStreamerClient() - :members: -``` diff --git a/docs/source/api-reference/drivers/ustreamer.md b/docs/source/api-reference/drivers/ustreamer.md new file mode 120000 index 000000000..79751a6e2 --- /dev/null +++ b/docs/source/api-reference/drivers/ustreamer.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-ustreamer/README.md \ No newline at end of file diff --git a/docs/source/api-reference/drivers/yepkit.md b/docs/source/api-reference/drivers/yepkit.md deleted file mode 100644 index d23b9c9de..000000000 --- a/docs/source/api-reference/drivers/yepkit.md +++ /dev/null @@ -1,80 +0,0 @@ -# Yepkit driver - -`jumpstarter-driver-yepkit` provides functionality for interacting with Yepkit products. - -## Installation - -```bash -pip install jumpstarter-driver-yepkit -``` - -## Configuration - -Example configuration: - -```yaml -interfaces: - power: - driver: jumpstarter_driver_yepkit.driver.Ykush - parameters: - serial: "YK25838" - port: "1" - - power2: - driver: jumpstarter_driver_yepkit.driver.Ykush - parameters: - serial: "YK25838" - port: "2" -``` - -### Config parameters - -| Parameter | Description | Type | Required | Default | -| --------- | ----------------------------------------------------------------- | ---- | -------- | ------- | -| serial | The serial number of the ykush hub, empty means auto-detection | no | None | | -| port | The port number to be managed, "0", "1", "2", "a" which means all | str | yes | "a" | - -## API Reference - -The yepkit ykush driver provides a `PowerClient` with the following API: - -```{eval-rst} -.. autoclass:: jumpstarter_driver_power.client.PowerClient() - :members: on, off -``` - -### Examples - -Powering on and off a device -```{testcode} -:skipif: True -client.power.on() -time.sleep(1) -client.power.off() -``` - -### CLI access - -```bash -$ sudo ~/.cargo/bin/uv run jmp shell --exporter-config ./packages/jumpstarter-driver-yepkit/examples/exporter.yaml -WARNING:Ykush:No serial number provided for ykush, using the first one found: YK25838 -INFO:Ykush:Power OFF for Ykush YK25838 on port 1 -INFO:Ykush:Power OFF for Ykush YK25838 on port 2 - -$$ j -Usage: j [OPTIONS] COMMAND [ARGS]... - - Generic composite device - -Options: - --help Show this message and exit. - -Commands: - power Generic power - power2 Generic power - -$$ j power on -INFO:Ykush:Power ON for Ykush YK25838 on port 1 - -$$ exit -``` diff --git a/docs/source/api-reference/drivers/yepkit.md b/docs/source/api-reference/drivers/yepkit.md new file mode 120000 index 000000000..0741324ab --- /dev/null +++ b/docs/source/api-reference/drivers/yepkit.md @@ -0,0 +1 @@ +../../../../packages/jumpstarter-driver-yepkit/README.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-can/README.md b/packages/jumpstarter-driver-can/README.md deleted file mode 120000 index fafef5ecc..000000000 --- a/packages/jumpstarter-driver-can/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/can.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-can/README.md b/packages/jumpstarter-driver-can/README.md new file mode 100644 index 000000000..571fdcfdd --- /dev/null +++ b/packages/jumpstarter-driver-can/README.md @@ -0,0 +1,33 @@ +# CAN driver + +`jumpstarter-driver-can` provides functionality for interacting with CAN bus connections. + +## Installation + +```bash +pip install jumpstarter-driver-can +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + can: + driver: jumpstarter_driver_can.CANDriver + parameters: + # Add required parameters here +``` + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_can.client.CanClient() + :members: +``` + +```{eval-rst} +.. autoclass:: jumpstarter_driver_can.client.IsoTpClient() + :members: +``` diff --git a/packages/jumpstarter-driver-corellium/README.md b/packages/jumpstarter-driver-corellium/README.md deleted file mode 120000 index 029ae3f31..000000000 --- a/packages/jumpstarter-driver-corellium/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/corellium.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-corellium/README.md b/packages/jumpstarter-driver-corellium/README.md new file mode 100644 index 000000000..0303b325d --- /dev/null +++ b/packages/jumpstarter-driver-corellium/README.md @@ -0,0 +1,72 @@ +# Corellium Driver + +`jumpstarter-driver-corellium` provides functionality for interacting with [Corellium](https://corellium.com) virtualization platform. + +## Installation + +```bash +pip install jumpstarter-driver-corellium +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + corellium: + driver: jumpstarter_driver_corellium.driver.Corellium + parameters: + project_id: "778f00af-5e9b-40e6-8e7f-c4f14b632e9c" + device_name: "jmp-rd1ae" + device_flavor: "kronos" + # Optional parameters + # device_os: "1.0" + # device_build: "Critical Application Monitor (Baremetal)" +``` + +## API Reference + +For more examples, check the [examples folder](./examples). + +### ExporterConfig Example + +You can run an exporter by running: `jmp exporter shell -c $file`: + +```yaml +apiVersion: jumpstarter.dev/v1alpha1 +kind: ExporterConfig +# endpoint and token are intentionally left empty +metadata: + namespace: default + name: corellium-demo +endpoint: "" +token: "" +export: + rd1ae: + type: jumpstarter_driver_corellium.driver.Corellium + config: + project_id: "778f00af-5e9b-40e6-8e7f-c4f14b632e9c" + device_name: "jmp-rd1ae" + device_flavor: "kronos" +``` + +```yaml +apiVersion: jumpstarter.dev/v1alpha1 +kind: ExporterConfig +# endpoint and token are intentionally left empty +metadata: + namespace: default + name: corellium-demo +endpoint: "" +token: "" +export: + rd1ae: + type: jumpstarter_driver_corellium.driver.Corellium + config: + project_id: "778f00af-5e9b-40e6-8e7f-c4f14b632e9c" + device_name: "jmp-rd1ae" + device_flavor: "kronos" + device_os: "1.0" + device_build: "Critical Application Monitor (Baremetal)" +``` diff --git a/packages/jumpstarter-driver-dutlink/README.md b/packages/jumpstarter-driver-dutlink/README.md deleted file mode 120000 index 9ee53b2fb..000000000 --- a/packages/jumpstarter-driver-dutlink/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/dutlink.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-dutlink/README.md b/packages/jumpstarter-driver-dutlink/README.md new file mode 100644 index 000000000..a8cd77c0e --- /dev/null +++ b/packages/jumpstarter-driver-dutlink/README.md @@ -0,0 +1,25 @@ +# DUT Link driver + +`jumpstarter-driver-dutlink` provides functionality for interacting with DUT Link devices. + +## Installation + +```bash +pip install jumpstarter-driver-dutlink +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + dutlink: + driver: jumpstarter_driver_dutlink.DUTLinkDriver + parameters: + # Add required parameters here +``` + +## API Reference + +Add API documentation here. diff --git a/packages/jumpstarter-driver-flashers/README.md b/packages/jumpstarter-driver-flashers/README.md deleted file mode 120000 index 4e9252d5f..000000000 --- a/packages/jumpstarter-driver-flashers/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/flashers.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-flashers/README.md b/packages/jumpstarter-driver-flashers/README.md new file mode 100644 index 000000000..526a583f7 --- /dev/null +++ b/packages/jumpstarter-driver-flashers/README.md @@ -0,0 +1,303 @@ +# Flashers + +The flasher drivers are used to flash images to DUTs via network, typically +using TFTP and HTTP. It is designed to interact with the target bootloader and +busybox shell to flash the DUT. + +All flasher drivers inherit from the +`jumpstarter_driver_flashers.driver.BaseFlasher` class, referencing their own +bundle of binary artifacts necessary to flash the DUT, like kernel/initram/dtbs. +See the [bundle](#oci-bundles) section for more details. + +## Available drivers and bundles + +| Driver | Bundle | +| --------------- | ------------------------------------------------------------ | +| TIJ784S4Flasher | quay.io/jumpstarter-dev/jumpstarter-flasher-ti-j784s4:latest | + + +## Driver configuration +**driver**: `jumpstarter_driver_flashers.driver.${DRIVER}` + +```yaml +export: + storage: + type: "jumpstarter_driver_flashers.driver.TIJ784S4Flasher" + children: + serial: + ref: "serial" + power: + ref: "power" + serial: + type: "jumpstarter_driver_pyserial.driver.PySerial" + config: + url: "/dev/serial/by-id/usb-FTDI_USB__-__Serial_Converter_112214101760A-if00-port0" + baudrate: 115200 + power: + type: jumpstarter_driver_yepkit.driver.Ykush + config: + serial: "YK112233" + port: "1" +``` + +flasher drivers require four children drivers: | Child Driver | Description | +Auto-created | | ------------ | +--------------------------------------------------------------------------------- +| ------------ | | serial | To communicate with the DUT via serial and +drive the bootloader and busybox shell | No | | power | To +power on and off the DUT | +No | | tftp | To serve binaries via TFTP | Yes | | +http | To serve the images via HTTP | Yes | + +In the above example we provide the serial and power children by +[reference](./proxy.md), so those remain also available on the root of the +exporter. + +The power driver is used to control power cycling of the DUT, and the serial +interface is used to communicate with the DUT bootloader via serial. TFTP and +HTTP servers are used to serve images to the DUT bootloader and busybox shell. + +### Config parameters + +| Parameter | Description | Type | Required | Default | +| -------------- | ------------------------------------------ | ---- | -------- | ---------------------------- | +| flasher_bundle | The OCI bundle to use for the flasher | str | yes | | +| cache_dir | The directory to cache the images | str | no | /var/lib/jumpstarter/flasher | +| tftp_dir | The directory to serve the images via TFTP | str | no | /var/lib/tftpboot | +| http_dir | The directory to serve the images via HTTP | str | no | /var/www/html | + + +## BaseFlasher API + +The `BaseFlasher` class provides a set of methods to flash the DUT, +```{eval-rst} +.. autoclass:: jumpstarter_driver_flashers.client.BaseFlasherClient() + :members: flash, busybox_shell, bootloader_shell, use_dtb, use_initram, use_kernel +``` + +## CLI + +The flasher driver provides a CLI to perform flashing, access to busybox shell +and uboot. + + +```bash +$ jmp shell -l board=ti-03 +INFO:jumpstarter.client.lease:Created lease request for labels {'board': 'ti-03'} for 0:30:00 +jumpstarter ⚡remote ➤ j storage +Usage: j storage [OPTIONS] COMMAND [ARGS]... + + Software-defined flasher interface + +Options: + --help Show this message and exit. + +Commands: + bootloader-shell Start a uboot/bootloader interactive console + busybox-shell Start a busybox shell + flash Flash image to DUT from file + +``` + +### flash +```bash +Usage: j storage flash [OPTIONS] FILE + + Flash image to DUT from file + +Options: + --partition TEXT + --os-image-checksum TEXT SHA256 checksum of OS image (direct value) + --os-image-checksum-file FILE File containing SHA256 checksum of OS image + --force-exporter-http Force use of exporter HTTP + --force-flash-bundle TEXT Force use of a specific flasher OCI bundle + --console-debug Enable console debug mode + --help Show this message and exit. +``` + +Example: +``` +jumpstarter ⚡remote ➤ j storage flash https://autosd.sig.centos.org/AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz +BaseFlasherClient - INFO - Writing image to storage in the background: /AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz +BaseFlasherClient - INFO - Setting up flasher bundle files in exporter +BaseFlasherClient - INFO - Writing image from storage, with metadata: md5=None,size=592736176 etag="23546fb0-63045567a5b80" +SNMPServerClient - INFO - Starting power cycle sequence +SNMPServerClient - INFO - Waiting 2 seconds... +SNMPServerClient - INFO - Power cycle sequence complete +BaseFlasherClient - INFO - Waiting for U-Boot prompt... +BaseFlasherClient - INFO - Running DHCP to obtain network configuration... +BaseFlasherClient - INFO - Running command: dhcp +BaseFlasherClient - INFO - Running command: printenv netmask +BaseFlasherClient - INFO - discovered dhcp details: DhcpInfo(ip_address='x.x.x.x', gateway='x.x.x.x', netmask='255.255.255.0') +BaseFlasherClient - INFO - Image written to storage: /AutoSD-9/nightly/TI/auto-osbuild-am69sk-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz +BaseFlasherClient - INFO - Running command: setenv serverip 'x.x.x.x' +BaseFlasherClient - INFO - Running command: tftpboot 0x82000000 J784S4XEVM.flasher.img +BaseFlasherClient - INFO - Running command: tftpboot 0x84000000 k3-j784s4-evm.dtb +BaseFlasherClient - INFO - Running boot command: booti 0x82000000 - 0x84000000 +BaseFlasherClient - INFO - Using target block device: /dev/mmcblk1 +BaseFlasherClient - INFO - Running preflash command: dd if=/dev/zero of=/dev/mmcblk0 bs=512 count=34 +BaseFlasherClient - INFO - Running preflash command: dd if=/dev/zero of=/dev/mmcblk1 bs=512 count=34 +BaseFlasherClient - INFO - Waiting until the http image preparation in storage is completed +BaseFlasherClient - INFO - Flash progress: 25.00 MB, Speed: 15.78 MB/s +... +... +BaseFlasherClient - INFO - Flash progress: 5086.12 MB, Speed: 13.77 MB/s +BaseFlasherClient - INFO - Flash progress: 5102.94 MB, Speed: 12.93 MB/s +BaseFlasherClient - INFO - Flushing buffers +BaseFlasherClient - INFO - Flashing completed in 7:26 +BaseFlasherClient - INFO - Powering off target +``` + +### bootloader-shell +```bash +Usage: j storage bootloader-shell [OPTIONS] + + Start a uboot/bootloader interactive console + +Options: + --console-debug Enable console debug mode + --help Show this message and exit. +``` + +Example +``` +jumpstarter ⚡remote ➤ j storage bootloader-shell +BaseFlasherClient - INFO - Setting up flasher bundle files in exporter +SNMPServerClient - INFO - Starting power cycle sequence +SNMPServerClient - INFO - Waiting 2 seconds... +SNMPServerClient - INFO - Power cycle sequence complete +BaseFlasherClient - INFO - Waiting for U-Boot prompt... +=> version +U-Boot 2024.01-rc3 (Jan 09 2024 - 00:00:00 +0000) + +gcc (GCC) 11.4.1 20231218 (Red Hat 11.4.1-3) +GNU ld version 2.35.2-42.el9 +``` +### busybox-shell +```bash +Usage: j storage busybox-shell [OPTIONS] + + Start a busybox interactive console + +Options: + --console-debug Enable console debug mode + --help Show this message and exit. +``` + +Example +``` +jumpstarter ⚡remote ➤ j storage busybox-shell +BaseFlasherClient - INFO - Setting up flasher bundle files in exporter +SNMPServerClient - INFO - Starting power cycle sequence +SNMPServerClient - INFO - Waiting 2 seconds... +SNMPServerClient - INFO - Power cycle sequence complete +BaseFlasherClient - INFO - Waiting for U-Boot prompt... +BaseFlasherClient - INFO - Running DHCP to obtain network configuration... +BaseFlasherClient - INFO - Running command: dhcp +BaseFlasherClient - INFO - Running command: printenv netmask +BaseFlasherClient - INFO - discovered dhcp details: DhcpInfo(ip_address='10.26.28.138', gateway='10.26.28.254', netmask='255.255.255.0') +BaseFlasherClient - INFO - Running command: setenv serverip '10.26.28.62' +BaseFlasherClient - INFO - Running command: tftpboot 0x82000000 J784S4XEVM.flasher.img +BaseFlasherClient - INFO - Running command: tftpboot 0x84000000 k3-j784s4-evm.dtb +BaseFlasherClient - INFO - Running boot command: booti 0x82000000 - 0x84000000 +# uname -a +Linux buildroot 6.1.46-dirty #2 SMP PREEMPT Thu Mar 14 14:37:01 UTC 2024 aarch64 GNU/Linux +# +``` + +## Examples + +Flash the device with a specific image +```python +flasherclient.flash("/path/to/image.raw.xz") +``` + +Flash the device with a specific image from a remote URL +```python +flasherclient.flash("https://autosd.sig.centos.org/AutoSD-9/nightly/TI/auto-osbuild-j784s4evm-autosd9-qa-regular-aarch64-1716106242.66b4d866.raw.xz") +``` + +Flash into a specific partition +```python +flasherclient.flash("/path/to/image.raw.xz", partition="emmc") +``` + + +## Examples of utility consoles + +In addition to the flashing mechanisms, the flasher drivers also provide a way +to access the DUT bootloader and busybox shell for convenience and debugging, +when using the `busybox_shell` and `bootloader_shell` methods the embedded http +and tftp servers will be online and serving the images from the flasher bundle. + +Get the busybox shell on the device +```python +with flasherclient.busybox_shell() as serial: + serial.send("ls -la\n") + serial.expect("#") + print(serial.before) +``` + +Get the bootloader shell on the device +```python +with flasherclient.bootloader_shell() as serial: + serial.send("version\n") + serial.expect("=>") + print(serial.before) +``` + +# oci-bundles +The flasher drivers require some artifacts and basic information about the +target device to operate. To make this easy to distribute and use, we use OCI +bundles to package the artifacts and metadata. + +The bundle is a container that uses [oras](https://oras.land/) to transport the +artifacts and metadata. It is a container that contains the following: +- `manifest.yaml`: The manifest file that describes the bundle +- `data/*`: The artifacts, including kernel, initram, dtbs, etc. + +## The format of the manifest is as follows: + +```{literalinclude} ../../../../packages/jumpstarter-driver-flashers/oci_bundles/test/manifest.yaml +:language: yaml +``` +## Table with the spec fields of the manifest: +| Field | Description | Default | +| -------------------- | -------------------------------------------------------------------------- | ------- | +| `manufacturer` | Name of the device manufacturer | | +| `link` | URL to device documentation or manufacturer website | | +| `bootcmd` | Command used to boot the device (e.g. booti, bootz) | | +| `default_target` | Default target device to flash to if none specified | | +| `targets` | Map of target names to device paths | | +| `login.type` | Type of login shell | busybox | +| `login.login_prompt` | Expected login prompt string | login: | +| `login.username` | Username to log in with, leave empty if not needed | | +| `login.password` | Password for login, leave empty if not needed | | +| `login.prompt` | Shell prompt after successful login | # | +| `preflash_commands` | List of commands to run before flashing, useful to clear boot entries, etc | | +| `kernel.file` | Path to kernel image within bundle | +| `kernel.address` | Memory address to load kernel to | | +| `initram.file` | Path to initramfs within bundle (if any) | | +| `initram.address` | Memory address to load initramfs to (if any) | | +| `dtb.default` | Default DTB variant to use | | +| `dtb.address` | Memory address to load DTB to | | +| `dtb.variants` | Map of DTB variant names to files | + + +## Examples + +An example bundle for the TI J784S4XEVM looks like this: + +```{literalinclude} ../../../../packages/jumpstarter-driver-flashers/oci_bundles/ti_j784s4xevm/manifest.yaml +:language: yaml +``` + +You can find a script to build and push a bundle to a registry here: +[oci_bundles](https://github.com/jumpstarter-dev/jumpstarter/tree/main/packages/jumpstarter-driver-flashers/oci_bundles) diff --git a/packages/jumpstarter-driver-http/README.md b/packages/jumpstarter-driver-http/README.md deleted file mode 120000 index 506f7c7a1..000000000 --- a/packages/jumpstarter-driver-http/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/http.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-http/README.md b/packages/jumpstarter-driver-http/README.md new file mode 100644 index 000000000..4a05aa647 --- /dev/null +++ b/packages/jumpstarter-driver-http/README.md @@ -0,0 +1,25 @@ +# HTTP driver + +`jumpstarter-driver-http` provides functionality for HTTP communication. + +## Installation + +```bash +pip install jumpstarter-driver-http +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + http: + driver: jumpstarter_driver_http.HTTPDriver + parameters: + # Add required parameters here +``` + +## API Reference + +Add API documentation here. diff --git a/packages/jumpstarter-driver-network/README.md b/packages/jumpstarter-driver-network/README.md deleted file mode 120000 index 1fadbf0b8..000000000 --- a/packages/jumpstarter-driver-network/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/network.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-network/README.md b/packages/jumpstarter-driver-network/README.md new file mode 100644 index 000000000..a138f832b --- /dev/null +++ b/packages/jumpstarter-driver-network/README.md @@ -0,0 +1,48 @@ +# Network drivers + +`jumpstarter-driver-network` provides functionality for interacting with network servers and connections. + +## Installation + +```bash +pip install jumpstarter-driver-network +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + network: + driver: jumpstarter_driver_network.NetworkDriver + parameters: + # Add required parameters here +``` + +## API Reference + +Network driver classes: + +```{eval-rst} +.. autoclass:: jumpstarter_driver_network.driver.TcpNetwork() +``` + +```{eval-rst} +.. autoclass:: jumpstarter_driver_network.driver.UdpNetwork() +``` + +```{eval-rst} +.. autoclass:: jumpstarter_driver_network.driver.UnixNetwork() +``` + +```{eval-rst} +.. autoclass:: jumpstarter_driver_network.driver.EchoNetwork() +``` + +Client API: + +```{eval-rst} +.. autoclass:: jumpstarter_driver_network.client.NetworkClient() + :members: +``` diff --git a/packages/jumpstarter-driver-opendal/README.md b/packages/jumpstarter-driver-opendal/README.md deleted file mode 120000 index fceb20ea0..000000000 --- a/packages/jumpstarter-driver-opendal/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/opendal.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-opendal/README.md b/packages/jumpstarter-driver-opendal/README.md new file mode 100644 index 000000000..192cb30ec --- /dev/null +++ b/packages/jumpstarter-driver-opendal/README.md @@ -0,0 +1,74 @@ +# OpenDAL driver + +`jumpstarter-driver-opendal` provides functionality for interacting with storages attached to the exporter. + +## Installation + +```bash +pip install jumpstarter-driver-opendal +``` + +## Configuration + +Example configuration: + +```{literalinclude} opendal.yaml +:language: yaml +``` + +## API Reference + +### Examples + +```{doctest} +>>> from tempfile import NamedTemporaryFile +>>> opendal.create_dir("test/directory/") +>>> opendal.write_bytes("test/directory/file", b"hello") +>>> assert opendal.hash("test/directory/file", "md5") == "5d41402abc4b2a76b9719d911017c592" +>>> opendal.remove_all("test/") +``` + +```{testsetup} * +from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance +from jumpstarter.common.utils import serve + +instance = serve( + ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/opendal.yaml" +).instantiate()) + +opendal = instance.__enter__() +``` + +```{testcleanup} * +instance.__exit__(None, None, None) +``` + +### Client API + +```{eval-rst} +.. autoclass:: jumpstarter_driver_opendal.client.OpendalClient() + :members: + +.. autoclass:: jumpstarter_driver_opendal.client.OpendalFile() + :members: + +.. autoclass:: jumpstarter_driver_opendal.common.Metadata() + :members: + :undoc-members: + :exclude-members: model_config + +.. autoclass:: jumpstarter_driver_opendal.common.EntryMode() + :members: + :undoc-members: + :exclude-members: model_config + +.. autoclass:: jumpstarter_driver_opendal.common.PresignedRequest() + :members: + :undoc-members: + :exclude-members: model_config + +.. autoclass:: jumpstarter_driver_opendal.common.Capability() + :members: + :undoc-members: + :exclude-members: model_config +``` diff --git a/packages/jumpstarter-driver-power/README.md b/packages/jumpstarter-driver-power/README.md deleted file mode 120000 index 856571961..000000000 --- a/packages/jumpstarter-driver-power/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/power.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-power/README.md b/packages/jumpstarter-driver-power/README.md new file mode 100644 index 000000000..1b440dbb5 --- /dev/null +++ b/packages/jumpstarter-driver-power/README.md @@ -0,0 +1,25 @@ +# Power driver + +`jumpstarter-driver-power` provides functionality for interacting with power control devices. + +## Installation + +```bash +pip install jumpstarter-driver-power +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + power: + driver: jumpstarter_driver_power.PowerDriver + parameters: + # Add required parameters here +``` + +## API Reference + +Add API documentation here. diff --git a/packages/jumpstarter-driver-probe-rs/README.md b/packages/jumpstarter-driver-probe-rs/README.md deleted file mode 120000 index 0b947ea42..000000000 --- a/packages/jumpstarter-driver-probe-rs/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/probe-rs.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-probe-rs/README.md b/packages/jumpstarter-driver-probe-rs/README.md new file mode 100644 index 000000000..00fc5acfb --- /dev/null +++ b/packages/jumpstarter-driver-probe-rs/README.md @@ -0,0 +1,62 @@ +# probe-rs driver + +`jumpstarter-driver-probe-rs` provides functionality for remote debugging and flashing of embedded devices using the [probe-rs](https://probe.rs) tools. + +## Installation + +```bash +pip install jumpstarter-driver-probe-rs +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + probe: + driver: jumpstarter_driver_probe_rs.driver.ProbeRs + parameters: + probe: "2e8a:000c:5798DE5E500ACB60" + probe_rs_path: "/home/majopela/.cargo/bin/probe-rs" + chip: "RP2350" + protocol: "swd" + connect_under_reset: false +``` + +### Config parameters + +| Parameter | Description | Type | Required | Default | +| ------------------- | -------------------------------------------------------------- | --------------- | -------- | -------- | +| probe | The probe id, can be in VID:PID format or VID:PID:SERIALNUMBER | str | no | | +| probe_rs_path | The path to the probe-rs binary | str | no | probe-rs | +| chip | The target chip | str | no | | +| protocol | The target protocol | "swd" or "jtag" | no | | +| connect_under_reset | Connect to the target while asserting reset | bool | no | false | + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_probe_rs.client.ProbeRsClient() + :members: +``` + +### CLI + +The probe driver client comes with a CLI tool that can be used to interact with the target device. +``` +jumpstarter ⚡ local ➤ j probe +Usage: j probe [OPTIONS] COMMAND [ARGS]... + + probe-rs client + +Options: + --help Show this message and exit. + +Commands: + download Download a file to the target + erase Erase the target, this is a slow operation. + info Get target information + read read from target memory + reset Reset the target +``` diff --git a/packages/jumpstarter-driver-pyserial/README.md b/packages/jumpstarter-driver-pyserial/README.md deleted file mode 120000 index 6f47a99ad..000000000 --- a/packages/jumpstarter-driver-pyserial/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/pyserial.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-pyserial/README.md b/packages/jumpstarter-driver-pyserial/README.md new file mode 100644 index 000000000..42ea3adbd --- /dev/null +++ b/packages/jumpstarter-driver-pyserial/README.md @@ -0,0 +1,81 @@ +# PySerial driver + +`jumpstarter-driver-pyserial` provides functionality for serial port communication. + +## Installation + +```bash +pip install jumpstarter-driver-pyserial +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + serial: + driver: jumpstarter_driver_pyserial.driver.PySerial + parameters: + url: "/dev/ttyUSB0" + baudrate: 115200 +``` + +### Config parameters + +| Parameter | Description | Type | Required | Default | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------- | ------- | +| url | The serial port to connect to, in [pyserial format](https://pyserial.readthedocs.io/en/latest/url_handlers.html) | str | yes | | +| baudrate | The baudrate to use for the serial connection | int | no | 115200 | +| check_existing | Check if the serial port exists during exporter initialization, disable if you are connecting to a dynamically created port (i.e. USB from your DUT) | bool | no | True | + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_pyserial.client.PySerialClient() + :members: pexpect, open, stream, open_stream, close +``` + +### Examples + +Using expect with a context manager +```{testcode} +with pyserialclient.pexpect() as session: + session.sendline("Hello, world!") + session.expect("Hello, world!") +``` + +Using expect without a context manager +```{testcode} +session = pyserialclient.open() +session.sendline("Hello, world!") +session.expect("Hello, world!") +pyserialclient.close() +``` + +Using a simple BlockingStream with a context manager +```{testcode} +with pyserialclient.stream() as stream: + stream.send(b"Hello, world!") + data = stream.receive() +``` + +Using a simple BlockingStream without a context manager +```{testcode} +stream = pyserialclient.open_stream() +stream.send(b"Hello, world!") +data = stream.receive() +``` + +```{testsetup} * +from jumpstarter_driver_pyserial.driver import PySerial +from jumpstarter.common.utils import serve + +instance = serve(PySerial(url="loop://")) + +pyserialclient = instance.__enter__() +``` + +```{testcleanup} * +instance.__exit__(None, None, None) +``` diff --git a/packages/jumpstarter-driver-qemu/README.md b/packages/jumpstarter-driver-qemu/README.md deleted file mode 120000 index 17996ac2a..000000000 --- a/packages/jumpstarter-driver-qemu/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/qemu.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-qemu/README.md b/packages/jumpstarter-driver-qemu/README.md new file mode 100644 index 000000000..dce106570 --- /dev/null +++ b/packages/jumpstarter-driver-qemu/README.md @@ -0,0 +1,25 @@ +# QEMU driver + +`jumpstarter-driver-qemu` provides functionality for interacting with QEMU virtualization platform. + +## Installation + +```bash +pip install jumpstarter-driver-qemu +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + qemu: + driver: jumpstarter_driver_qemu.QEMUDriver + parameters: + # Add required parameters here +``` + +## API Reference + +Add API documentation here. diff --git a/packages/jumpstarter-driver-raspberrypi/README.md b/packages/jumpstarter-driver-raspberrypi/README.md deleted file mode 120000 index b48a80033..000000000 --- a/packages/jumpstarter-driver-raspberrypi/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/raspberrypi.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-raspberrypi/README.md b/packages/jumpstarter-driver-raspberrypi/README.md new file mode 100644 index 000000000..185d0faf2 --- /dev/null +++ b/packages/jumpstarter-driver-raspberrypi/README.md @@ -0,0 +1,25 @@ +# Raspberry Pi driver + +`jumpstarter-driver-raspberrypi` provides functionality for interacting with Raspberry Pi devices. + +## Installation + +```bash +pip install jumpstarter-driver-raspberrypi +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + raspberrypi: + driver: jumpstarter_driver_raspberrypi.RaspberryPiDriver + parameters: + # Add required parameters here +``` + +## API Reference + +Add API documentation here. diff --git a/packages/jumpstarter-driver-sdwire/README.md b/packages/jumpstarter-driver-sdwire/README.md deleted file mode 120000 index 4a4279388..000000000 --- a/packages/jumpstarter-driver-sdwire/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/sdwire.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-sdwire/README.md b/packages/jumpstarter-driver-sdwire/README.md new file mode 100644 index 000000000..dfb6c2e43 --- /dev/null +++ b/packages/jumpstarter-driver-sdwire/README.md @@ -0,0 +1,35 @@ +# SDWire driver + +`jumpstarter-driver-sdwire` provides functionality for using the SDWire storage multiplexer. This device multiplexes an SD card between the DUT and the exporter host. + +## Installation + +```bash +pip install jumpstarter-driver-sdwire +``` + +## Configuration + +Example configuration: + +```{literalinclude} sdwire.yaml +:language: yaml +``` + +```{doctest} +:hide: +>>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance +>>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/sdwire.yaml").instantiate() +Traceback (most recent call last): +... +FileNotFoundError: failed to find sd-wire device +``` + +## API Reference + +The SDWire driver implements the `StorageMuxClient` class, which is a generic storage class. + +```{eval-rst} +.. autoclass:: jumpstarter_driver_opendal.client.StorageMuxClient() + :members: +``` diff --git a/packages/jumpstarter-driver-shell/README.md b/packages/jumpstarter-driver-shell/README.md deleted file mode 120000 index b9836ac20..000000000 --- a/packages/jumpstarter-driver-shell/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/shell.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-shell/README.md b/packages/jumpstarter-driver-shell/README.md new file mode 100644 index 000000000..827add1de --- /dev/null +++ b/packages/jumpstarter-driver-shell/README.md @@ -0,0 +1,63 @@ +# Shell driver + +`jumpstarter-driver-shell` provides functionality for shell command execution. + +## Installation + +```bash +pip install jumpstarter-driver-shell +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + shell: + driver: jumpstarter_driver_shell.driver.Shell + parameters: + methods: + ls: "ls" + method2: "echo 'Hello World 2'" + #multi line method + method3: | + echo 'Hello World $1' + echo 'Hello World $2' + env_var: "echo $1,$2,$ENV_VAR" + # optional parameters + cwd: "/tmp" + log_level: "INFO" + shell: + - "/bin/bash" + - "-c" +``` + +## API Reference + +Assuming the exporter driver is configured as in the example above, the client methods will be generated dynamically, and they will be available as follows: + +```{eval-rst} +.. autoclass:: jumpstarter_driver_shell.client.ShellClient + :members: + +.. function:: ls() + :noindex: + + :returns: A tuple(stdout, stderr, return_code) + +.. function:: method2() + :noindex: + + :returns: A tuple(stdout, stderr, return_code) + +.. function:: method3(arg1, arg2) + :noindex: + + :returns: A tuple(stdout, stderr, return_code) + +.. function:: env_var(arg1, arg2, ENV_VAR="value") + :noindex: + + :returns: A tuple(stdout, stderr, return_code) +``` diff --git a/packages/jumpstarter-driver-snmp/README.md b/packages/jumpstarter-driver-snmp/README.md deleted file mode 120000 index b7166a39b..000000000 --- a/packages/jumpstarter-driver-snmp/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/snmp.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-snmp/README.md b/packages/jumpstarter-driver-snmp/README.md new file mode 100644 index 000000000..71756d5c6 --- /dev/null +++ b/packages/jumpstarter-driver-snmp/README.md @@ -0,0 +1,72 @@ +# SNMP driver + +`jumpstarter-driver-snmp` provides functionality for controlling power via SNMP-enabled PDUs (Power Distribution Units). + +## Installation + +```bash +pip install jumpstarter-driver-snmp +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + power: + driver: jumpstarter_driver_snmp.driver.SNMPServer + parameters: + host: "pdu.mgmt.com" + user: "labuser" + plug: 32 + port: 161 + oid: "1.3.6.1.4.1.13742.6.4.1.2.1.2.1" + auth_protocol: "NONE" + auth_key: null + priv_protocol: "NONE" + priv_key: null + timeout: 5.0 +``` + +### Config parameters + +| Parameter | Description | Type | Required | Default | +| ------------- | --------------------------------------------------- | ----- | -------- | --------------------------------- | +| host | Hostname or IP address of the SNMP-enabled PDU | str | yes | | +| user | SNMP v3 username | str | yes | | +| plug | PDU outlet number to control | int | yes | | +| port | SNMP port number | int | no | 161 | +| oid | Base OID for power control | str | no | "1.3.6.1.4.1.13742.6.4.1.2.1.2.1" | +| auth_protocol | Authentication protocol ("NONE", "MD5", "SHA") | str | no | "NONE" | +| auth_key | Authentication key when auth_protocol is not "NONE" | str | no | null | +| priv_protocol | Privacy protocol ("NONE", "DES", "AES") | str | no | "NONE" | +| priv_key | Privacy key when priv_protocol is not "NONE" | str | no | null | +| timeout | SNMP timeout in seconds | float | no | 5.0 | + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_snmp.client.SNMPServerClient() + :members: + :show-inheritance: +``` + +### Examples + +Power cycling a device: +```python +snmp_client.cycle(wait=3) +``` + +Basic power control: +```python +snmp_client.off() +snmp_client.on() +``` + +Using the CLI: +```bash +j power on +j power off +j power cycle --wait 3 diff --git a/packages/jumpstarter-driver-tftp/README.md b/packages/jumpstarter-driver-tftp/README.md deleted file mode 120000 index 6e23a485e..000000000 --- a/packages/jumpstarter-driver-tftp/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/tftp.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-tftp/README.md b/packages/jumpstarter-driver-tftp/README.md new file mode 100644 index 000000000..9dd891a3a --- /dev/null +++ b/packages/jumpstarter-driver-tftp/README.md @@ -0,0 +1,75 @@ +# TFTP driver + +`jumpstarter-driver-tftp` provides functionality for a read-only TFTP server that can be used to serve files. + +## Installation + +```bash +pip install jumpstarter-driver-tftp +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + tftp: + driver: jumpstarter_driver_tftp.driver.Tftp + parameters: + root_dir: /var/lib/tftpboot # Directory to serve files from + host: 192.168.1.100 # Host IP to bind to (optional) + port: 69 # Port to listen on (optional) +``` + +### Config parameters + +| Parameter | Description | Type | Required | Default | +| --------- | ---------------------------------- | ---- | -------- | ------------------- | +| root_dir | Root directory for the TFTP server | str | no | "/var/lib/tftpboot" | +| host | IP address to bind the server to | str | no | auto-detect | +| port | Port number to listen on | int | no | 69 | + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_tftp.client.TftpServerClient() + :members: + :show-inheritance: +``` + +### Exception Classes + +```{eval-rst} +.. autoclass:: jumpstarter_driver_tftp.driver.TftpError + :members: + :show-inheritance: + +.. autoclass:: jumpstarter_driver_tftp.driver.ServerNotRunning + :members: + :show-inheritance: +``` + +### Examples + +```{doctest} +>>> import tempfile +>>> import os +>>> from jumpstarter_driver_tftp.driver import Tftp +>>> from jumpstarter.common.utils import serve +>>> with tempfile.TemporaryDirectory() as tmp_dir: +... # Create a test file +... test_file = os.path.join(tmp_dir, "test.txt") +... with open(test_file, "w") as f: +... _ = f.write("hello") +... +... # Start TFTP server +... with serve(Tftp(root_dir=tmp_dir, host="127.0.0.1", port=6969)) as tftp: +... tftp.start() +... +... # List files +... files = list(tftp.storage.list("/")) +... assert "test.txt" in files +... +... tftp.stop() +``` diff --git a/packages/jumpstarter-driver-uboot/README.md b/packages/jumpstarter-driver-uboot/README.md deleted file mode 120000 index 4be2bf7ce..000000000 --- a/packages/jumpstarter-driver-uboot/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/uboot.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-uboot/README.md b/packages/jumpstarter-driver-uboot/README.md new file mode 100644 index 000000000..346cf4939 --- /dev/null +++ b/packages/jumpstarter-driver-uboot/README.md @@ -0,0 +1,31 @@ +# U-Boot driver + +`jumpstarter-driver-uboot` provides functionality for interacting with the U-Boot bootloader. This driver does not interact with the DUT directly, instead it should be configured with backing power and serial drivers. + +## Installation + +```bash +pip install jumpstarter-driver-uboot +``` + +## Configuration + +Example configuration: + +```{literalinclude} uboot.yaml +:language: yaml +``` + +```{doctest} +:hide: +>>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance +>>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/uboot.yaml").instantiate() +UbootConsole(...) +``` + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_uboot.client.UbootConsoleClient() + :members: +``` diff --git a/packages/jumpstarter-driver-ustreamer/README.md b/packages/jumpstarter-driver-ustreamer/README.md deleted file mode 120000 index 2c6f05610..000000000 --- a/packages/jumpstarter-driver-ustreamer/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/ustreamer.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-ustreamer/README.md b/packages/jumpstarter-driver-ustreamer/README.md new file mode 100644 index 000000000..e4eaa7c0f --- /dev/null +++ b/packages/jumpstarter-driver-ustreamer/README.md @@ -0,0 +1,33 @@ +# Ustreamer driver + +`jumpstarter-driver-ustreamer` provides functionality for using the ustreamer video streaming server driven by the jumpstarter exporter. This driver takes a video device and exposes both snapshot and streaming interfaces. + +## Installation + +```bash +pip install jumpstarter-driver-ustreamer +``` + +## Configuration + +Example configuration: + +```{literalinclude} ustreamer.yaml +:language: yaml +``` + +```{doctest} +:hide: +>>> from jumpstarter.config import ExporterConfigV1Alpha1DriverInstance +>>> ExporterConfigV1Alpha1DriverInstance.from_path("source/api-reference/drivers/ustreamer.yaml").instantiate() +Traceback (most recent call last): +... +io.UnsupportedOperation: fileno +``` + +## API Reference + +```{eval-rst} +.. autoclass:: jumpstarter_driver_ustreamer.client.UStreamerClient() + :members: +``` diff --git a/packages/jumpstarter-driver-yepkit/README.md b/packages/jumpstarter-driver-yepkit/README.md deleted file mode 120000 index b903f7638..000000000 --- a/packages/jumpstarter-driver-yepkit/README.md +++ /dev/null @@ -1 +0,0 @@ -../../docs/source/api-reference/drivers/yepkit.md \ No newline at end of file diff --git a/packages/jumpstarter-driver-yepkit/README.md b/packages/jumpstarter-driver-yepkit/README.md new file mode 100644 index 000000000..d23b9c9de --- /dev/null +++ b/packages/jumpstarter-driver-yepkit/README.md @@ -0,0 +1,80 @@ +# Yepkit driver + +`jumpstarter-driver-yepkit` provides functionality for interacting with Yepkit products. + +## Installation + +```bash +pip install jumpstarter-driver-yepkit +``` + +## Configuration + +Example configuration: + +```yaml +interfaces: + power: + driver: jumpstarter_driver_yepkit.driver.Ykush + parameters: + serial: "YK25838" + port: "1" + + power2: + driver: jumpstarter_driver_yepkit.driver.Ykush + parameters: + serial: "YK25838" + port: "2" +``` + +### Config parameters + +| Parameter | Description | Type | Required | Default | +| --------- | ----------------------------------------------------------------- | ---- | -------- | ------- | +| serial | The serial number of the ykush hub, empty means auto-detection | no | None | | +| port | The port number to be managed, "0", "1", "2", "a" which means all | str | yes | "a" | + +## API Reference + +The yepkit ykush driver provides a `PowerClient` with the following API: + +```{eval-rst} +.. autoclass:: jumpstarter_driver_power.client.PowerClient() + :members: on, off +``` + +### Examples + +Powering on and off a device +```{testcode} +:skipif: True +client.power.on() +time.sleep(1) +client.power.off() +``` + +### CLI access + +```bash +$ sudo ~/.cargo/bin/uv run jmp shell --exporter-config ./packages/jumpstarter-driver-yepkit/examples/exporter.yaml +WARNING:Ykush:No serial number provided for ykush, using the first one found: YK25838 +INFO:Ykush:Power OFF for Ykush YK25838 on port 1 +INFO:Ykush:Power OFF for Ykush YK25838 on port 2 + +$$ j +Usage: j [OPTIONS] COMMAND [ARGS]... + + Generic composite device + +Options: + --help Show this message and exit. + +Commands: + power Generic power + power2 Generic power + +$$ j power on +INFO:Ykush:Power ON for Ykush YK25838 on port 1 + +$$ exit +```