diff --git a/docs/dev/reference/apis/components/switch.md b/docs/dev/reference/apis/components/switch.md index f5409df825..ad9555f380 100644 --- a/docs/dev/reference/apis/components/switch.md +++ b/docs/dev/reference/apis/components/switch.md @@ -12,6 +12,7 @@ date: "2025-02-20" The switch API allows you to give commands to your [switch components](/operate/reference/components/switch/) for reading the state of a physical switch that has multiple discrete positions. A simple switch has two positions, and a knob could have any number of positions. +Switch positions can have human-readable labels (such as "Off", "Low", "Medium", "High") to make them more intuitive to work with. The switch component supports the following methods: diff --git a/docs/operate/reference/components/switch/_index.md b/docs/operate/reference/components/switch/_index.md index 2118a402ea..27e440b441 100644 --- a/docs/operate/reference/components/switch/_index.md +++ b/docs/operate/reference/components/switch/_index.md @@ -16,6 +16,7 @@ date: "2025-02-20" The switch component provides an API for reading the state of a physical switch on a machine that has multiple discrete positions. A simple switch has two positions, and a knob could have any number of positions. +Switch components can provide human-readable labels for each position, making it easier to work with meaningful position names rather than just numeric indices. ## Configuration diff --git a/docs/operate/reference/components/switch/fake.md b/docs/operate/reference/components/switch/fake.md new file mode 100644 index 0000000000..46bf36cd45 --- /dev/null +++ b/docs/operate/reference/components/switch/fake.md @@ -0,0 +1,99 @@ +--- +title: "Configure a Fake Switch" +linkTitle: "fake" +weight: 10 +type: "docs" +description: "Configure a fake switch for testing." +images: ["/icons/components/switch.svg"] +tags: ["switch", "components"] +aliases: + - "/components/switch/fake/" +component_description: "A model used for testing, with no physical hardware." +# SMEs: +--- + +The `fake` switch model is used for testing switch functionality without requiring physical hardware. +It simulates a multi-position switch that can be controlled programmatically. + +{{< tabs >}} +{{% tab name="Config Builder" %}} + +Navigate to the **CONFIGURE** tab of your machine's page. +Click the **+** icon next to your machine part in the left-hand menu and select **Component or service**. +Select the `switch` type, then select the `fake` model. +Enter a name or use the suggested name for your arm and click **Create**. + +Fill in the attributes as applicable to your switch, according to the table below. + +{{% /tab %}} +{{% tab name="JSON Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [ + { + "name": "", + "model": "fake", + "type": "switch", + "namespace": "rdk", + "attributes": { + "position_count": , + "labels": ["", "", ""] + } + } + ] +} +``` + +{{% /tab %}} +{{% tab name="JSON Example" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [ + { + "name": "my_switch", + "model": "fake", + "type": "switch", + "namespace": "rdk", + "attributes": { + "position_count": 4, + "labels": ["Off", "Low", "Medium", "High"] + } + } + ] +} +``` + +{{% /tab %}} +{{< /tabs >}} + +## Attributes + +The following attributes are available for the `fake` switch model: + + +| Name | Type | Required? | Description | +| ---- | ---- | --------- | ----------- | +| `position_count` | int | **Required** | The number of positions that the switch can be in. If omitted, the switch will have two positions. Default: `2` | +| `labels` | array | Optional | An array of labels corresponding to the positions. If omitted, the switch will have labels of "Position 1", "Position 2", etc. The number of labels should match the `position_count`. | + +## Test the switch + +{{< readfile "/static/include/components/test-control/switch-control.md" >}} + +## Troubleshooting + +If your fake switch is not working as expected: + +1. Check your machine logs on the **LOGS** tab to check for errors. +2. Make sure the `position_count` matches the number of `labels` if both are specified. +3. Verify that position values used with `SetPosition` are within the valid range (0 to `position_count - 1`). +4. Click on the **TEST** panel on the **CONFIGURE** or **CONTROL** tab and test if you can use the switch there. + +## Next steps + +{{< cards >}} +{{% card link="/operate/control/web-app/" noimage="true" %}} +{{% card link="/dev/reference/apis/components/switch/" noimage="true" %}} +{{< /cards >}} \ No newline at end of file diff --git a/static/include/components/apis/generated/switch-table.md b/static/include/components/apis/generated/switch-table.md index 557dafec67..6141d8992e 100644 --- a/static/include/components/apis/generated/switch-table.md +++ b/static/include/components/apis/generated/switch-table.md @@ -3,6 +3,6 @@ | ----------- | ----------- | --------------------------- | | [`SetPosition`](/dev/reference/apis/components/switch/#setposition) | Set the position of the switch. |

| | [`GetPosition`](/dev/reference/apis/components/switch/#getposition) | Return the current position of the switch. |

| -| [`GetNumberOfPositions`](/dev/reference/apis/components/switch/#getnumberofpositions) | Return the number of valid positions for this switch. |

| +| [`GetNumberOfPositions`](/dev/reference/apis/components/switch/#getnumberofpositions) | Return the number of valid positions for this switch and their labels. |

| | [`DoCommand`](/dev/reference/apis/components/switch/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. |

| -| [`Close`](/dev/reference/apis/components/switch/#close) | Safely shut down the resource and prevent further use. | | +| [`Close`](/dev/reference/apis/components/switch/#close) | Safely shut down the resource and prevent further use. | | \ No newline at end of file diff --git a/static/include/components/apis/generated/switch.md b/static/include/components/apis/generated/switch.md index e0e029bb85..7c802a78de 100644 --- a/static/include/components/apis/generated/switch.md +++ b/static/include/components/apis/generated/switch.md @@ -165,7 +165,7 @@ For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/ ### GetNumberOfPositions -Return the number of valid positions for this switch. +Return the number of valid positions for this switch and their labels. Supported by `viam-micro-server`. {{< tabs >}} @@ -179,13 +179,17 @@ Supported by `viam-micro-server`. **Returns:** - ([int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)): The number of available positions. +- (List[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)]): Human-readable labels for each switch position. **Example:** ```python {class="line-numbers linkable-line-numbers"} my_switch = Switch.from_robot(robot=machine, name="my_switch") -print(await my_switch.get_number_of_positions()) +num_positions, labels = await my_switch.get_number_of_positions() +print(f"Switch has {num_positions} positions:") +for i, label in enumerate(labels): + print(f" Position {i}: {label}") ``` For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/switch/client/index.html#viam.components.switch.client.SwitchClient.get_number_of_positions). @@ -200,9 +204,26 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ **Returns:** -- [(uint32)](https://pkg.go.dev/builtin#uint32) +- [(uint32)](https://pkg.go.dev/builtin#uint32): The number of available positions. +- [([]string)](https://pkg.go.dev/builtin#string): Human-readable labels for each switch position. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +mySwitch, err := switch.FromRobot(machine, "my_switch") + +numPositions, labels, err := mySwitch.GetNumberOfPositions(context.Background(), nil) +if err != nil { + logger.Fatalf("Failed to get switch positions: %v", err) +} + +logger.Infof("Switch has %d positions:", numPositions) +for i, label := range labels { + logger.Infof(" Position %d: %s", i, label) +} +``` + For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/switch#Switch). {{% /tab %}} @@ -215,16 +236,19 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c **Returns:** -- (Promise) +- (Promise<{numPositions: number, labels: string[]}>) **Example:** ```ts {class="line-numbers linkable-line-numbers"} const mySwitch = new VIAM.SwitchClient(machine, 'my_switch'); -// Get the number of available positions -const numPositions = await mySwitch.getNumberOfPositions(); -console.log('Number of positions:', numPositions); +// Get the number of available positions and their labels +const {numPositions, labels} = await mySwitch.getNumberOfPositions(); +console.log(`Switch has ${numPositions} positions:`); +labels.forEach((label, index) => { + console.log(` Position ${index}: ${label}`); +}); ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/SwitchClient.html#getnumberofpositions). @@ -365,4 +389,4 @@ err = mySwitch.Close(context.Background()) For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource). {{% /tab %}} -{{< /tabs >}} +{{< /tabs >}} \ No newline at end of file diff --git a/static/include/components/test-control/switch-control.md b/static/include/components/test-control/switch-control.md new file mode 100644 index 0000000000..ab201f83b8 --- /dev/null +++ b/static/include/components/test-control/switch-control.md @@ -0,0 +1,2 @@ +Once you have configured your switch, open the switch’s TEST panel on the **CONFIGURE** or [**CONTROL**](/operate/control/web-app/) tab. +You will be able to view the current position and change the switch's position.