Document switch position labels

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:
 

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
 

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": "<your-switch-name>",
+      "model": "fake",
+      "type": "switch",
+      "namespace": "rdk",
+      "attributes": {
+        "position_count": <number>,
+        "labels": ["<label1>", "<label2>", "<label3>"]
+      }
+    }
+  ]
+}
+```
+
+{{% /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:
+
+<!-- prettier-ignore -->
+| 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 >}}

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. | <p class="center-text"><i class="fas fa-check" title="yes"></i></p> |
 | [`GetPosition`](/dev/reference/apis/components/switch/#getposition) | Return the current position of the switch. | <p class="center-text"><i class="fas fa-check" title="yes"></i></p> |
-| [`GetNumberOfPositions`](/dev/reference/apis/components/switch/#getnumberofpositions) | Return the number of valid positions for this switch. | <p class="center-text"><i class="fas fa-check" title="yes"></i></p> |
+| [`GetNumberOfPositions`](/dev/reference/apis/components/switch/#getnumberofpositions) | Return the number of valid positions for this switch and their labels. | <p class="center-text"><i class="fas fa-check" title="yes"></i></p> |
 | [`DoCommand`](/dev/reference/apis/components/switch/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. | <p class="center-text"><i class="fas fa-check" title="yes"></i></p> |
-| [`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. |  |

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<number>)
+- (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 >}}

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.