From 48c4494f1cb724d959f250bb6478b4b584954a58 Mon Sep 17 00:00:00 2001 From: Jordan Bonser Date: Thu, 24 Apr 2025 16:21:20 +0100 Subject: [PATCH 1/2] docs: provide user docs for ssh devices document how to make use of the ssh platforms and `labgrid_config_toolchain`. --- docs/README.md | 1 + docs/ssh-devices.md | 36 ++++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 docs/ssh-devices.md diff --git a/docs/README.md b/docs/README.md index 3f2dd06..6f772a9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,2 +1,3 @@ ## User Guides - [Custom Runners](./custom-runners.md) +- [SSH Devices](./ssh-devices.md) diff --git a/docs/ssh-devices.md b/docs/ssh-devices.md new file mode 100644 index 0000000..d483671 --- /dev/null +++ b/docs/ssh-devices.md @@ -0,0 +1,36 @@ +# SSH Devices +The [`ssh`](/labgrid/toolchain/config/ssh/BUILD.bazel) toolchain and accompanying platforms make it possible for ssh-capable devices to be used with labgrid workflow rules (e.g. `labgrid_test`, `labgrid_genrule`) + +To use an ssh platform it can be specified on the commandline, along with the device network flags. + +As long as the platform field is not specified on the target, it allows the use of an existing target without modification: +```bash +bazelisk test //test:data-from-env --platforms=@rules_labgrid//labgrid/platform:ssh-amd64-linux --@rules_labgrid//labgrid/flag/device:password=password --@rules_labgrid//labgrid/flag/device:port=2022 +``` +The above example does specify the platform, so the field would need to be removed before running the command. + +This example uses the `ssh-amd64-linux` platform, with the password as 'password' and the port as 2022. + +## Platforms +To make use of the toolchain and labgrid config, a platform has to be used with the [`@rules_labgrid//labgrid/constraint/device:ssh`](/labgrid/constraint/device/BUILD.bazel) constraint specified. + +The devices must also be pre-booked and pre-configured, as the toolchain doesn't support acquiring or flashing devices. + +There are some pre-defined platforms in [`@rules_labgrid//labgrid/platform`](/labgrid/platform/BUILD.bazel) for `arm64` and `amd64` on linux. + +Those platforms can be used as a reference if any new platforms need to be created. + +## Flags + +The `ssh` toolchain makes use of Bazel's `string_flag` and `int_flag` to modify the networking parameters for the ssh device. + +The [`device flags`](/labgrid/flag/device/BUILD.bazel) that are available for use with the `ssh` toolchain are: + +```bash +--@rules_labgrid//labgrid/flag/device:username +--@rules_labgrid//labgrid/flag/device:address +--@rules_labgrid//labgrid/flag/device:port +--@rules_labgrid//labgrid/flag/device:password +``` + +Any network parameters that are not provided will use the default values specified in the ssh [`device flags`](/labgrid/flag/device/BUILD.bazel) -- GitLab From edf0ea691acc03bb36ae243832fd1a7dd43f989c Mon Sep 17 00:00:00 2001 From: Jordan Bonser Date: Wed, 30 Apr 2025 09:32:26 +0000 Subject: [PATCH 2/2] docs: tweak formatting and wording. --- docs/ssh-devices.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ssh-devices.md b/docs/ssh-devices.md index d483671..65eca54 100644 --- a/docs/ssh-devices.md +++ b/docs/ssh-devices.md @@ -3,11 +3,11 @@ The [`ssh`](/labgrid/toolchain/config/ssh/BUILD.bazel) toolchain and accompanyin To use an ssh platform it can be specified on the commandline, along with the device network flags. -As long as the platform field is not specified on the target, it allows the use of an existing target without modification: +As long as the `platform` attribute is not specified on the target, it allows the use of an existing target without modification: ```bash bazelisk test //test:data-from-env --platforms=@rules_labgrid//labgrid/platform:ssh-amd64-linux --@rules_labgrid//labgrid/flag/device:password=password --@rules_labgrid//labgrid/flag/device:port=2022 ``` -The above example does specify the platform, so the field would need to be removed before running the command. +The above example does specify the platform, so the attribute would need to be removed before running the command. This example uses the `ssh-amd64-linux` platform, with the password as 'password' and the port as 2022. @@ -24,7 +24,7 @@ Those platforms can be used as a reference if any new platforms need to be creat The `ssh` toolchain makes use of Bazel's `string_flag` and `int_flag` to modify the networking parameters for the ssh device. -The [`device flags`](/labgrid/flag/device/BUILD.bazel) that are available for use with the `ssh` toolchain are: +The [device flags](/labgrid/flag/device/BUILD.bazel) that are available for use with the `ssh` toolchain are: ```bash --@rules_labgrid//labgrid/flag/device:username @@ -33,4 +33,4 @@ The [`device flags`](/labgrid/flag/device/BUILD.bazel) that are available for us --@rules_labgrid//labgrid/flag/device:password ``` -Any network parameters that are not provided will use the default values specified in the ssh [`device flags`](/labgrid/flag/device/BUILD.bazel) +Any network parameters that are not provided will use the default values specified in the ssh [device flags](/labgrid/flag/device/BUILD.bazel) -- GitLab