DOCS-821: Add Power Sensor Component

docs/components/power-sensor/_index.md

@@ -0,0 +1,232 @@
+---
+title: "Power Sensor Component"
+linkTitle: "Power Sensor"
+childTitleEndOverwrite: "Power Sensor"
+weight: 70
+no_list: true
+type: "docs"
+description: "A device that provides information about a robot's power systems, including voltage, current, and power consumption."
+tags: ["sensor", "components", "power sensor", "ina219", "ina226", "renogy"]
+icon: "/icons/components/sensor.svg"
+images: ["/icons/components/sensor.svg"]
+# SME: #team-bucket
+---
+
+A power sensor is a device that reports measurements of the voltage, current and power consumption in your robot's system.
+Integrate this component to monitor your power levels.
+
+## Configuration
+
+For configuration information, click on your sensor’s model:
+
+Model | Description <a name="model-table"></a>
+----- | -----------
+[`fake`](./fake/) | a digital power sensor for testing
+[`ina219`](./ina219/) | INA219 power sensor; current and power monitor
+[`ina226`](./ina226/) | INA226 power sensor; current and power monitor
+[`renogy`](./renogy/) | solar charge controller
+
+## Control your power sensor with Viam’s client SDK libraries
+
+To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated.
+
+{{% snippet "show-secret.md" %}}
+
+When executed, this sample code will create a connection to your robot as a client.
+Once connected, you can control your robot programmatically by adding API method calls as shown in the following examples.
+
+These examples assume you have a power sensor called `"my_power_sensor"` configured as a component of your robot.
+If your power sensor has a different name, change the `name` in the code.
+
+Import the power sensor package for the SDK you are using:
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+```python
+from viam.components.powersensor import powersensor
+```
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+```go
+import (
+  "go.viam.com/rdk/components/powersensor"
+)
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## API
+
+The power sensor component supports the following methods:
+
+{{< readfile "/static/include/components/apis/power-sensor.md" >}}
+
+### GetCurrent
+
+Return the current of a specified device and whether it is AC or DC.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `extra` [(Optional[Dict[str,Any]])](https://docs.python.org/library/typing.html#typing.Optional): Pass additional data and configuration options to the {{< glossary_tooltip term_id="grpc" text="RPC call" >}}.
+- `timeout` [(Optional[float])](https://docs.python.org/3/library/typing.html#typing.Optional): Specify a time limit in seconds for how long `get_current` should wait for a response.
+
+**Returns:**
+
+- [(Tuple[float, bool])](https://docs.python.org/3/library/functions.html#float): A tuple which includes a float representing the current reading in amps, and a bool indicating whether the current is AC (`true`) or DC (`false`).
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/power_sensor/power_sensor/index.html#viam.components.power_sensor.power_sensor.PowerSensor.get_current).
+
+```python
+# Get the current reading from the power sensor
+current, is_ac = await my_power_sensor.get_current()
+print("The current is ", current, " A, Is AC: ", is_ac)
+```
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+**Parameters:**
+
+- `ctx` [Context](https://pkg.go.dev/context): Control the lifecycle of the operation by handling timeouts and managing cancellations.
+- `extra`[(Optional[Dict[str, Any]])](https://docs.python.org/3/library/typing.html#typing.Optional): Pass additional data and configuration options to the [RPC call](/appendix/glossary/#term-grpc).
+
+**Returns:**
+
+- `float64`: The measurement of the current, represented as a 64-bit float number.
+- `bool`: Indicate whether current is AC (`true`) or DC (`false`).
+- `error`: Report any errors that might occur during operation. For a successful operation, `error` returns `nil`.
+
+For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/powersensor#PowerSensor).
+
+```go
+// Create a power sensor instance
+myPowerSensor, err := powersensor.FromRobot(robot, "my_power_sensor")
+if err != nil {
+  logger.Fatalf("cannot get power sensor: %v", err)
+}
+
+// Get the current reading from device in amps
+current, isAC, err := myPowerSensor.Current(context.Background(), nil)
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetVoltage
+
+Return the voltage reading of a specified device and whether it is AC or DC.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `extra`[(Optional[Dict[str, Any]])](https://docs.python.org/3/library/typing.html#typing.Optional): Pass additional data and configuration options to the [RPC call](/appendix/glossary/#term-grpc).
+- `timeout`[(Optional[float])](https://docs.python.org/3/library/functions.html#float): Specify a time limit in seconds for how long `get_voltage` should wait for a response.
+
+**Returns:**
+
+- [(Tuple[float, bool])](https://docs.python.org/3/library/stdtypes.html): A float representing the current reading in amps. A bool indicating whether the voltage is AC (`true`) or DC (`false`).
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/power_sensor/power_sensor/index.html#viam.components.power_sensor.power_sensor.PowerSensor.get_voltage).
+
+```Python
+# Get the voltage reading from the power sensor
+    voltage, is_ac = await my_power_sensor.get_voltage()
+    print("The voltage is", voltage, "V, Is AC:", is_ac)
+```
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+**Parameters:**
+
+- `ctx` [Context](https://pkg.go.dev/context): Control the lifecycle of the operation by handling timeouts and managing cancellations.
+- `extra`[(Optional[Dict[str, Any]])](https://docs.python.org/3/library/typing.html#typing.Optional): Pass additional data and configuration options to the [RPC call](/appendix/glossary/#term-grpc).
+
+**Returns:**
+
+- `float64`: The measurement of the voltage, represented as a 64-bit float number.
+- `bool`: Indicate whether voltage is AC (`true`) or DC (`false`).
+- `error`: Report any errors that might occur during operation. For a successful operation, `error` returns `nil`.
+
+For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/powersensor#PowerSensor).
+
+```Go
+// Create a power sensor instance
+myPowerSensor, err := powersensor.FromRobot(robot, "my_power_sensor")
+if err != nil {
+  logger.Fatalf("cannot get power sensor: %v", err)
+}
+
+// Get the voltage from device in volts
+voltage, isAC, err := myPowerSensor.Voltage(context.Background(), nil)
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetPower
+
+Return the power reading in watts.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `extra`[(Optional[Dict[str, Any]])](https://docs.python.org/3/library/typing.html#typing.Optional): Pass additional data and configuration options to the [RPC call](/appendix/glossary/#term-grpc).
+- `timeout`[(Optional[float])](https://docs.python.org/3/library/functions.html#float): Specify a time limit in seconds for how long `get_power` should wait for a response.
+
+**Returns:**
+
+- `float`: The measurement of the power, represented as a float.
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/power_sensor/power_sensor/index.html#viam.components.power_sensor.power_sensor.PowerSensor.get_power).
+
+```Python
+# Get the power reading from the power sensor
+    power = await my_power_sensor.get_power()
+    print("The power is", power, "Watts")
+```
+
+{{% /tab %}}
+{{% tab name="Go" %}}
+
+**Parameters:**
+
+- `ctx` [Context](https://pkg.go.dev/context): Control the lifecycle of the operation by handling timeouts and managing cancellations.
+- `extra`[(Optional[Dict[str, Any]])](https://docs.python.org/3/library/typing.html#typing.Optional): Pass additional data and configuration options to the [RPC call](/appendix/glossary/#term-grpc).
+
+**Returns:**
+
+- `float64`: The measurement of the power, represented as a 64-bit float number.
+- `error`: Report any errors that might occur during operation. For a successful operation, `error` returns `nil`.
+
+For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/powersensor#PowerSensor).
+
+```Go
+// Create a power sensor instance
+myPowerSensor, err := powersensor.FromRobot(robot, "my_power_sensor")
+if err != nil {
+  logger.Fatalf("cannot get power sensor: %v", err)
+}
+
+// Get the power measurement from device in watts
+power, err := myPowerSensor.Power(context.Background(), nil)
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+## Troubleshooting
+
+You can find additional assistance in the [Troubleshooting section](/appendix/troubleshooting/).
+
+You can also ask questions on the [Viam Community Slack](https://join.slack.com/t/viamrobotics/shared_invite/zt-1f5xf1qk5-TECJc1MIY1MW0d6ZCg~Wnw) and we will be happy to help.

docs/components/power-sensor/fake.md

@@ -0,0 +1,42 @@
+---
+title: "Configure a fake power sensor"
+linkTitle: "fake"
+weight: 10
+type: "docs"
+description: "Configure a fake power sensor to test software without the physical hardware."
+tags: ["sensor", "power sensor"]
+icon: "/icons/components/sensor.svg"
+images: ["/icons/components/sensor.svg"]
+# SME: #team-bucket
+---
+
+Use a `fake` power sensor to test implementing a power sensor component on your robot without any physical hardware.
+
+Configure a `fake` power sensor to integrate into your robot:
+
+{{< tabs name="Configure a Fake Power Sensor" >}}
+{{% tab name="Config Builder" %}}
+
+Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+Click on the **Components** subtab and navigate to the **Create component** menu.
+Select the type `power_sensor`, then select the `fake` model.
+Name your sensor, and click **Create**.
+
+{{<imgproc src="/components/power-sensor/fake-config-builder.png" resize="750x" declaredimensions=true alt="Fake power sensor configuration builder">}}
+
+{{% /tab %}}
+{{% tab name="JSON Template" %}}
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+    "name": "<your-sensor-name>",
+    "type": "power_sensor",
+    "model": "fake",
+    "attributes": {}
+}
+```
+
+{{% /tab %}}
+{{< /tabs >}}
+
+No attributes are available for `fake` power sensors.

docs/components/power-sensor/ina219.md

@@ -0,0 +1,58 @@
+---
+title: "Configure an INA219 power sensor"
+linkTitle: "ina219"
+weight: 10
+draft: false
+type: "docs"
+description: "Configure an INA219 model power sensor to return voltage and current readings."
+tags: ["power sensor", "ina219"]
+icon: "/icons/components/sensor.svg"
+images: ["/icons/components/sensor.svg"]
+# SME:
+---
+
+Configure an `INA219` power sensor to integrate into your robot:
+
+{{< tabs name="Configure an INA219 Power Sensor" >}}
+{{% tab name="Config Builder" %}}
+
+Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+Click on the **Components** subtab and navigate to the **Create component** menu.
+Select the type `power_sensor`, then select the `ina219` model.
+Name your sensor, and click **Create**.
+
+{{<imgproc src="/components/power-sensor/ina219-config-builder.png" resize="900x" declaredimensions=true alt="ina219 power sensor configuration tab">}}
+
+Edit and fill in the attributes as applicable.
+
+{{% /tab %}}
+{{% tab name="JSON Template" %}}
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "components": [
+    {
+      "name": "<your-INA219-sensor-name>",
+      "type": "power_sensor",
+      "model": "INA219",
+      "attributes": {
+        "board": "<your-board-name>",
+        "i2c_bus": "<your-i2c-bus-name-on-board>"
+      },
+      "depends_on": []
+    }
+  ]
+}
+```
+
+{{% /tab %}}
+{{% /tabs %}}
+
+The following attributes are available for `INA219` sensors:
+
+| Attribute | Type | Inclusion | Description |
+| --------- | -----| --------- | ----------- |
+| `i2c_bus` | integer | **Required** | The `name` of the [I<sup>2</sup>C bus](/components/board/#i2cs) that the sensor is connected to. |
+| `i2c_address` | integer | Optional | The sensor's unique [I<sup>2</sup>C address](https://learn.adafruit.com/i2c-addresses/overview). <br>Default: `0x40`
+| `max_current_amps` | number | Optional | The maximum current that the sensor can measure in amperes (A).
+| `shunt_resistance` | number | Optional | The shunt resistance value of the sensor in Ohms (Ω).

docs/components/power-sensor/ina226.md

@@ -0,0 +1,56 @@
+---
+title: "Configure an INA226 power sensor"
+linkTitle: "ina226"
+weight: 10
+type: "docs"
+description: "Configure an INA226 power sensor to return voltage and current readings."
+tags: ["power sensor", "ina226"]
+images: ["/icons/components/imu.svg"]
+# SME:
+---
+
+Configure an `INA226` power sensor to integrate into your robot:
+
+{{< tabs name="Configure an INA226 Power Sensor" >}}
+{{% tab name="Config Builder" %}}
+
+Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+Click on the **Components** subtab and navigate to the **Create component** menu.
+Select the type `power_sensor`, then select the `ina226` model.
+Name your sensor, and click **Create**.
+
+{{<imgproc src="/components/power-sensor/ina226-config-builder.png" resize="800x" declaredimensions=true alt="ina226 power sensor configuration tab ">}}
+
+Edit and fill in the attributes as applicable.
+
+{{% /tab %}}
+{{% tab name="JSON Template" %}}
+
+```json {class="line-numbers linkable-line-numbers"}
+{
+  "components": [
+    {
+      "name": "<your-INA226-sensor-name>",
+      "type": "power_sensor",
+      "model": "INA226",
+      "attributes": {
+        "board": "<your-board-name>",
+        "i2c_bus": "<your-i2c-bus-name-on-board>"
+      },
+      "depends_on": []
+    }
+  ]
+}
+```
+
+{{% /tab %}}
+{{% /tabs %}}
+
+The following attributes are available for `INA226` sensors:
+
+| Attribute | Type | Inclusion | Description |
+| --------- | -----| --------- | ----------- |
+| `i2c_bus` | integer | **Required** | The `name` of the [I<sup>2</sup>C bus](/components/board/#i2cs) that the sensor is connected to. |
+| `i2c_address` | integer | Optional | Default: `0x40`. The sensor's unique [I<sup>2</sup>C address](https://learn.adafruit.com/i2c-addresses/overview). |
+| `max_current_amps` | number | Optional | The maximum current that the sensor can measure in amperes (A).
+| `shunt_resistance` | number | Optional | The shunt resistance value of the sensor in Ohms (Ω).