diff --git a/assets/components/power-sensor/fake-config-builder.png b/assets/components/power-sensor/fake-config-builder.png new file mode 100644 index 0000000000..ac6f5bb3e0 Binary files /dev/null and b/assets/components/power-sensor/fake-config-builder.png differ diff --git a/assets/components/power-sensor/ina219-config-builder.png b/assets/components/power-sensor/ina219-config-builder.png new file mode 100644 index 0000000000..708e4fce55 Binary files /dev/null and b/assets/components/power-sensor/ina219-config-builder.png differ diff --git a/assets/components/power-sensor/ina226-config-builder.png b/assets/components/power-sensor/ina226-config-builder.png new file mode 100644 index 0000000000..279ba0791e Binary files /dev/null and b/assets/components/power-sensor/ina226-config-builder.png differ diff --git a/assets/components/power-sensor/renogy-config-builder.png b/assets/components/power-sensor/renogy-config-builder.png new file mode 100644 index 0000000000..6645c50641 Binary files /dev/null and b/assets/components/power-sensor/renogy-config-builder.png differ diff --git a/assets/components/sensor/power-ina219-sensor-ui-config.png b/assets/components/sensor/power-ina219-sensor-ui-config.png deleted file mode 100644 index 6dfd81e086..0000000000 Binary files a/assets/components/sensor/power-ina219-sensor-ui-config.png and /dev/null differ diff --git a/assets/components/sensor/renogy-sensor-ui-config.png b/assets/components/sensor/renogy-sensor-ui-config.png deleted file mode 100644 index 1cd4895353..0000000000 Binary files a/assets/components/sensor/renogy-sensor-ui-config.png and /dev/null differ diff --git a/docs/components/power-sensor/_index.md b/docs/components/power-sensor/_index.md new file mode 100644 index 0000000000..b44fe16fc0 --- /dev/null +++ b/docs/components/power-sensor/_index.md @@ -0,0 +1,239 @@ +--- +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 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 into your robot's system to monitor its power levels. + +## Configuration + +For configuration information, click on your sensor’s model: + +Model | Description +----- | ----------- +[`fake`](./fake/) | Digital power sensor for testing +[`ina219`](/components/sensor/power_ina219/) | [INA219](https://pdf1.alldatasheet.com/datasheet-pdf/view/249609/TI/INA219.html) current and power sensor +[`ina226`](./ina226/) | [INA226](https://www.ti.com/lit/ds/symlink/ina226.pdf?ts=1688994548364&ref_url=https%253A%252F%252Fwww.ti.com%252Fproduct%252Fde-de%252FINA226) current and power sensor +[`renogy`](/components/sensor/renogy/) | [Renogy](https://www.renogy.com/content/RSP200D/RSP200D%20G2%20Datasheet.pdf) 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. +Then 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. + +Be sure to 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 [RPC call](/appendix/glossary/#term-grpc). +- `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 float representing the current reading in amps. 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. Successful operation will be `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. Successful operation will be `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 number. + +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. Successful operation will be `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. + +## Next Steps + +{{< cards >}} + {{% card link="/tutorials/projects/tipsy" %}} +{{< /cards >}} \ No newline at end of file diff --git a/docs/components/power-sensor/fake.md b/docs/components/power-sensor/fake.md new file mode 100644 index 0000000000..3f8d9d64d5 --- /dev/null +++ b/docs/components/power-sensor/fake.md @@ -0,0 +1,40 @@ +--- +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**. + +{{}} + +{{% /tab %}} +{{% tab name="JSON Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "name": "", + "type": "power_sensor", + "model": "fake", + "attributes": {} +} +``` + +{{% /tab %}} +{{< /tabs >}} + +No attributes are available for `fake` power sensors. \ No newline at end of file diff --git a/docs/components/power-sensor/ina219.md b/docs/components/power-sensor/ina219.md new file mode 100644 index 0000000000..669107cbd4 --- /dev/null +++ b/docs/components/power-sensor/ina219.md @@ -0,0 +1,56 @@ +--- +title: "Configure an INA219 power sensor" +linkTitle: "ina219" +weight: 70 +draft: false +type: "docs" +description: "Configure an INA219 model sensor." +tags: ["sensor", "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**. + +{{}} + +Edit and fill in the attributes as applicable. + +{{% /tab %}} +{{% tab name="JSON Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [ + { + "name": "", + "type": "power_sensor", + "model": "INA219", + "attributes": { + "board": "", + "i2c_bus": "" + }, + "depends_on": [] + } + ] +} +``` + +{{% /tab %}} +{{% /tabs %}} + +The following attributes are available for `INA219` sensors: + +| Attribute | Type | Inclusion | Description | +| --------- | -----| --------- | ----------- | +| `i2c_bus` | integer | **Required** | The `name` of the [I2C bus](/components/board/#i2cs) that the sensor is connected to. | +| `i2c_address` | integer | Optional | The sensor's unique [I2C address](https://learn.adafruit.com/i2c-addresses/overview).
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 (Ω). \ No newline at end of file diff --git a/docs/components/power-sensor/ina226.md b/docs/components/power-sensor/ina226.md new file mode 100644 index 0000000000..caaa71f8fb --- /dev/null +++ b/docs/components/power-sensor/ina226.md @@ -0,0 +1,53 @@ +--- +title: "Configure an INA226 power sensor" +linkTitle: "ina226" +weight: 10 +type: "docs" +description: "Configure an INA226 power sensor to test software." +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**. + +{{}} + +Edit and fill in the attributes as applicable. + +{{% /tab %}} +{{% tab name="JSON Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [ + { + "name": "", + "type": "power_sensor", + "model": "INA226", + "attributes": { + "board": "", + "i2c_bus": "" + }, + "depends_on": [] + } + ] +} +``` + +{{% /tab %}} +{{% /tabs %}} + +The following attributes are available for `INA226` sensors: + +| Attribute | Type | Inclusion | Description | +| --------- | -----| --------- | ----------- | +| `i2c_bus` | integer | **Required** | The `name` of the [I2C bus](/components/board/#i2cs) that the sensor is connected to. | +| `i2c_address` | integer | Optional | Default: `0x40`. The sensor's unique [I2C 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 (Ω). \ No newline at end of file diff --git a/docs/components/sensor/renogy.md b/docs/components/power-sensor/renogy.md similarity index 56% rename from docs/components/sensor/renogy.md rename to docs/components/power-sensor/renogy.md index 1abf644c18..3dfb6d1557 100644 --- a/docs/components/sensor/renogy.md +++ b/docs/components/power-sensor/renogy.md @@ -1,5 +1,5 @@ --- -title: "Configure a renogy Sensor" +title: "Configure a renogy sensor" linkTitle: "renogy" weight: 80 type: "docs" @@ -10,23 +10,20 @@ images: ["/icons/components/sensor.svg"] # SME: #team-bucket --- -Configure a `renogy` sensor to integrate a [Renogy battery temperature sensor](https://www.amazon.com/Renogy-Battery-Temperature-Sensor-Controllers/dp/B07WMMJFWY) into your robot: +Configure a `renogy` sensor to integrate a [Renogy battery temperature sensor](https://www.renogy.com/battery-temperature-sensor-for-renogy-solar-charge-controllers/) into your robot's system: -{{< tabs >}} +{{< tabs name="Configure an Renogy 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 click **Create component**. -Select the `sensor` type, then select the `renogy` model. -Enter a name for your sensor and click **Create**. +Click on the **Components** subtab and navigate to the **Create component** menu. Select the type `power_sensor`, then select the `renogy` model. Name your sensor, and click **Create**. -![Creation of a renogy sensor in the Viam app config builder.](/components/sensor/renogy-sensor-ui-config.png) +{{}} Edit and fill in the attributes as applicable. {{% /tab %}} {{% tab name="JSON Template" %}} - ```json {class="line-numbers linkable-line-numbers"} { "components": [ @@ -44,10 +41,8 @@ Edit and fill in the attributes as applicable. ] } ``` - {{% /tab %}} {{% tab name="JSON Example" %}} - ```json {class="line-numbers linkable-line-numbers"} { "components": [ @@ -65,14 +60,12 @@ Edit and fill in the attributes as applicable. ] } ``` - {{% /tab %}} {{% /tabs %}} - The following attributes are available for `renogy` sensors: | Attribute | Type | Inclusion | Description | | --------- | ---- | --------- | ----------- | -| `serial_path` | string | **Required** | The full filesystem path to the serial device, starting with /dev/. With your serial device connected, you can run `sudo dmesg \| grep tty` to show relevant device connection log messages, and then match the returned device name, such as `ttyS0`, to its device file, such as /dev/ttyS0. If you omit this attribute, Viam will attempt to automatically detect the path.
Default: `/dev/serial0` | -| `serial_baud_rate` | int | **Required** | The baud rate to use for serial communications.
Default: `9600` | -| `modbus_id` | int | **Required** | Controller MODBUS address.
Default: `1` | +| `serial_path` | string | Optional | The full filesystem path to the serial device, starting with /dev/. With your serial device connected, you can run `sudo dmesg \| grep tty` to show relevant device connection log messages, and then match the returned device name, such as `ttyS0`, to its device file, such as /dev/ttyS0. If you omit this attribute, Viam will attempt to automatically detect the path.
Default: `/dev/serial0` | +| `serial_baud_rate` | integer | Optional | The baud rate to use for serial communications.
Default: `9600` | +| `modbus_id` | integer | Optional | Controller MODBUS address.
Default: `1` | \ No newline at end of file diff --git a/docs/components/sensor/power_ina219.md b/docs/components/sensor/power_ina219.md deleted file mode 100644 index 58a7e13ba7..0000000000 --- a/docs/components/sensor/power_ina219.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: "Configure a power_ina219 Sensor" -linkTitle: "power_ina219" -weight: 70 -draft: false -type: "docs" -description: "Configure a power_ina219 model sensor." -tags: ["sensor", "components"] -icon: "/icons/components/sensor.svg" -images: ["/icons/components/sensor.svg"] -# SME: #team-bucket ---- - -Configure a `power_ina219` sensor to integrate a [INA219 current sensor](https://www.amazon.com/dp/B07QJW6L4C) into your robot: - -{{< tabs >}} -{{% 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 click **Create component**. -Select the `sensor` type, then select the `power_ina219` model. -Enter a name for your sensor and click **Create**. - -![Creation of a power_ina219 sensor in the Viam app config builder.](/components/sensor/power-ina219-sensor-ui-config.png) - -Edit and fill in the attributes as applicable. - -{{% /tab %}} -{{% tab name="JSON Template" %}} - -```json {class="line-numbers linkable-line-numbers"} -{ - "components": [ - { - "name": "", - "type": "sensor", - "model": "power_ina219", - "attributes": { - "board": "", - "i2c_bus": "" - }, - "depends_on": [] - } - ] -} -``` - -{{% /tab %}} -{{% /tabs %}} - -The following attributes are available for `power_ina219` sensors: - -| Attribute | Type | Inclusion | Description | -| --------- | -----| --------- | ----------- | -| `board` | string | **Required** | The `name` of the [board](/components/board/) the sensor is wired to. | -| `i2c_bus` | string | **Required** | The `name` of the [I2C bus](/components/board/#i2cs) on the board that the sensor is wired to. | -| `i2c_address` | string | Optional | Default: `0x40`. The [I2C device address](https://learn.adafruit.com/i2c-addresses/overview) of the sensor. | diff --git a/static/include/components/apis/power-sensor.md b/static/include/components/apis/power-sensor.md new file mode 100644 index 0000000000..8075a34f17 --- /dev/null +++ b/static/include/components/apis/power-sensor.md @@ -0,0 +1,5 @@ +Method Name | Description +----------- | ----------- +[`GetCurrent`](/components/power-sensor/#getcurrent) | Return the current of a specified device and whether it is AC or DC. +[`GetVoltage`](/components/power-sensor/#getvoltage) | Return the voltage of a specified device and whether it is AC or DC. +[`GetPower`](/components/power-sensor/#getpower) | Return the power consumption of a specified device in robot's system. diff --git a/static/include/snippet/show-secret.md b/static/include/snippet/show-secret.md index 7cf9c8e66a..030cff2ef6 100644 --- a/static/include/snippet/show-secret.md +++ b/static/include/snippet/show-secret.md @@ -6,4 +6,4 @@ To show your robot's location secret in the sample code, toggle **Include secret You can also see your location secret on the [locations page](/manage/fleet/locations/). {{< /alert >}} -{{% snippet "secret-share.md" %}} \ No newline at end of file +{{% snippet "secret-share.md" %}}