From d88dc76081da22dd086adb98d0c0a5c2c025a64d Mon Sep 17 00:00:00 2001 From: JessamyT <75634662+JessamyT@users.noreply.github.com> Date: Tue, 5 Nov 2024 15:10:33 -0800 Subject: [PATCH] DOCS-2949: Fix mismapped methods (#3651) Co-authored-by: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> --- .github/workflows/sdk_protos_map.csv | 14 +- docs/appendix/changelog.md | 4 +- .../components/apis/generated/board-table.md | 12 +- .../components/apis/generated/board.md | 303 ++++++++++-------- .../protos/board.GetDigitalInterruptValue.md | 3 +- ...oard.Read.md => board.ReadAnalogReader.md} | 0 .../apis/overrides/protos/board.Value.md | 1 - .../{board.Write.md => board.WriteAnalog.md} | 0 .../board/board-digital-interrupts.md | 2 +- 9 files changed, 183 insertions(+), 156 deletions(-) rename static/include/components/apis/overrides/protos/{board.Read.md => board.ReadAnalogReader.md} (100%) delete mode 100644 static/include/components/apis/overrides/protos/board.Value.md rename static/include/components/apis/overrides/protos/{board.Write.md => board.WriteAnalog.md} (100%) diff --git a/.github/workflows/sdk_protos_map.csv b/.github/workflows/sdk_protos_map.csv index ef28ab50aa..36a69be7ff 100644 --- a/.github/workflows/sdk_protos_map.csv +++ b/.github/workflows/sdk_protos_map.csv @@ -38,18 +38,18 @@ board,GetPWM,Yes,get_pwm,PWM,pwm board,SetPWM,Yes,set_pwm,SetPWM,setPwm board,PWMFrequency,Yes,get_pwm_frequency,PWMFreq,pwmFrequency board,SetPWMFrequency,Yes,set_pwm_frequency,SetPWMFreq,setPwmFrequency -board,AnalogByName,No,analog_by_name,AnalogByName,analogReaderValue -## HACK: Omitting PySDK: write_analog, currently borked: https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.write_analog -board,Write,Yes,,Write,writeAnalog -board,GetDigitalInterruptValue,No,digital_interrupt_by_name,DigitalInterruptByName,, +board,GetDigitalInterruptValue,No,value,Value,digitalInterruptValue +board,ReadAnalogReader,Yes,read,Read,analogReaderValue +## HACK: PySDK: write_analog currently borked; deprecated in favor of write: https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.write_analog +board,WriteAnalog,Yes,write,Write,writeAnalog board,StreamTicks,No,stream_ticks,StreamTicks,streamTicks board,SetPowerMode,No,set_power_mode,SetPowerMode,setPowerMode -board,GetGeometries,No,get_geometries,, ## HACK: Board (python, go) provides additional helper functions, adding 5 pseudo-entries: -board,Read,Yes,read,Read, -board,Value,No,value,Value,digitalInterruptValue +board,AnalogByName,No,analog_by_name,AnalogByName, +board,DigitalInterruptByName,No,digital_interrupt_by_name,DigitalInterruptByName,, board,GPIOPinByName,No,gpio_pin_by_name,GPIOPinByName, ## HACK: No proto for these (and/or inherited in Go SDK), manually mapping: +board,GetGeometries,No,get_geometries,, board,Reconfigure,No,,Reconfigure, board,DoCommand,Yes,do_command,DoCommand,doCommand board,Name,No,,Name, diff --git a/docs/appendix/changelog.md b/docs/appendix/changelog.md index 56df615fac..995ddd5374 100644 --- a/docs/appendix/changelog.md +++ b/docs/appendix/changelog.md @@ -90,7 +90,7 @@ The `errors_only` parameter has been removed from [`get_robot_part_logs()`](/app {{% changelog date="2024-05-28" color="changed" title="Return type of analog Read" %}} -The board analog API [`Read()`](/appendix/apis/components/board/#read) method now returns an `AnalogValue` struct instead of a single int. +The board analog API [`Read()`](/appendix/apis/components/board/#readanalogreader) method now returns an `AnalogValue` struct instead of a single int. The struct contains an int representing the value of the reading, min and max range of values, and the precision of the reading. {{% /changelog %}} @@ -144,7 +144,7 @@ detections = await detector.get_detections(cropped_frame) {{% changelog date="2024-05-08" color="removed" title="WriteAnalog from Go SDK" %}} The `WriteAnalog()` method has been removed from the Go SDK. -Use [`AnalogByName()`](/appendix/apis/components/board/#analogbyname) followed by [`Write()`](/appendix/apis/components/board/#write) instead. +Use [`AnalogByName()`](/appendix/apis/components/board/#analogbyname) followed by [`Write()`](/appendix/apis/components/board/#writeanalog) instead. {{% /changelog %}} diff --git a/static/include/components/apis/generated/board-table.md b/static/include/components/apis/generated/board-table.md index 92d6d62eab..869f299288 100644 --- a/static/include/components/apis/generated/board-table.md +++ b/static/include/components/apis/generated/board-table.md @@ -7,15 +7,15 @@ | [`SetPWM`](/appendix/apis/components/board/#setpwm) | Set the pin's Pulse-width modulation (PWM) duty cycle: a float [`0.0`, `1.0`] indicating the percentage of time the digital signal output of this pin is in the high state (active, >0V) relative to the interval period of the PWM signal (interval period being the mathematical inverse of the PWM frequency). |

| | [`PWMFrequency`](/appendix/apis/components/board/#pwmfrequency) | Get the PWM frequency of the GPIO pin. |

| | [`SetPWMFrequency`](/appendix/apis/components/board/#setpwmfrequency) | Set the pin to the given PWM `frequency` (in Hz). When `frequency` is 0, it will use the board’s default PWM frequency. |

| -| [`AnalogByName`](/appendix/apis/components/board/#analogbyname) | Get a configured `Analog` by `name`. |

| -| [`Write`](/appendix/apis/components/board/#write) | Write an analog value to a pin on the board. |

| -| [`GetDigitalInterruptValue`](/appendix/apis/components/board/#getdigitalinterruptvalue) | Get a configured `DigitalInterrupt` by `name`. |

| +| [`GetDigitalInterruptValue`](/appendix/apis/components/board/#getdigitalinterruptvalue) | Get the current value of a configured digital interrupt. |

| +| [`ReadAnalogReader`](/appendix/apis/components/board/#readanalogreader) | Read the current integer value of the digital signal output by the ADC. |

| +| [`WriteAnalog`](/appendix/apis/components/board/#writeanalog) | Write an analog value to a pin on the board. |

| | [`StreamTicks`](/appendix/apis/components/board/#streamticks) | Start a stream of `DigitalInterrupt` ticks. |

| | [`SetPowerMode`](/appendix/apis/components/board/#setpowermode) | Set the board to the indicated `PowerMode`. |

| -| [`GetGeometries`](/appendix/apis/components/board/#getgeometries) | Get all the geometries associated with the board in its current configuration, in the frame of the board. |

| -| [`Read`](/appendix/apis/components/board/#read) | Read the current integer value of the digital signal output by the ADC. |

| -| [`Value`](/appendix/apis/components/board/#value) | Get the current value of this interrupt. |

| +| [`AnalogByName`](/appendix/apis/components/board/#analogbyname) | Get a configured `Analog` by `name`. |

| +| [`DigitalInterruptByName`](/appendix/apis/components/board/#digitalinterruptbyname) | Get a DigitalInterrupt by `name`. |

| | [`GPIOPinByName`](/appendix/apis/components/board/#gpiopinbyname) | Get a `GPIOPin` by {{< glossary_tooltip term_id="pin-number" text="pin number" >}}. |

| +| [`GetGeometries`](/appendix/apis/components/board/#getgeometries) | Get all the geometries associated with the board in its current configuration, in the frame of the board. |

| | [`Reconfigure`](/appendix/apis/components/board/#reconfigure) | Reconfigure this resource. |

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

| | [`Name`](/appendix/apis/components/board/#name) | Get the name of the digital interrupt. |

| diff --git a/static/include/components/apis/generated/board.md b/static/include/components/apis/generated/board.md index fd69cc7f6b..4a3d901b35 100644 --- a/static/include/components/apis/generated/board.md +++ b/static/include/components/apis/generated/board.md @@ -510,42 +510,50 @@ For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_s {{% /tab %}} {{< /tabs >}} -### AnalogByName +### GetDigitalInterruptValue -Get a configured `Analog` by `name`. +Get the current value of a configured digital interrupt. +The value is the number of times the interrupt has been interrupted with a tick. {{< tabs >}} {{% tab name="Python" %}} **Parameters:** -- `name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): Name of the analog reader to be retrieved. +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. **Returns:** -- ([viam.components.board.board.Board.Analog](https://python.viam.dev/autoapi/viam/components/board/board/index.html#viam.components.board.board.Board.Analog)): The analog reader or writer. +- ([int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)): The current value. **Example:** ```python {class="line-numbers linkable-line-numbers"} my_board = Board.from_robot(robot=machine, name="my_board") -# Get the Analog "my_example_analog_reader". -reader = await my_board.analog_by_name(name="my_example_analog_reader") +# Get the DigitalInterrupt "my_example_digital_interrupt". +interrupt = await my_board.digital_interrupt_by_name( + name="my_example_digital_interrupt") + +# Get the amount of times this DigitalInterrupt has been interrupted with a +# tick. +count = await interrupt.value() ``` -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.analog_by_name). +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.DigitalInterruptClient.value). {{% /tab %}} {{% tab name="Go" %}} **Parameters:** -- `name` [(string)](https://pkg.go.dev/builtin#string): Name of the analog pin you want to retrieve. Set as the `"name"` property in board configuration. +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. **Returns:** -- [(Analog)](https://pkg.go.dev/go.viam.com/rdk/components/board#Analog): An interface representing an analog pin configured and residing on the board. +- [(int64)](https://pkg.go.dev/builtin#int64): The amount of ticks that have occurred. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. **Example:** @@ -553,52 +561,83 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ```go {class="line-numbers linkable-line-numbers"} myBoard, err := board.FromRobot(robot, "my_board") -// Get the Analog pin "my_example_analog". -analog, err := myBoard.AnalogByName("my_example_analog") +// Get the DigitalInterrupt "my_example_digital_interrupt". +interrupt, err := myBoard.DigitalInterruptByName("my_example_digital_interrupt") + +// Get the amount of times this DigitalInterrupt has ticked. +count, err := interrupt.Value(context.Background(), nil) ``` -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Board). +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#DigitalInterrupt). {{% /tab %}} {{% tab name="Flutter" %}} **Parameters:** -- `analogReaderName` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required) +- `digitalInterruptName` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required) - `extra` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html)\<[String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic\>? (optional) **Returns:** -- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)\<[AnalogValue](https://flutter.viam.dev/viam_sdk/AnalogValue.html)\> +- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)\<[int](https://api.flutter.dev/flutter/dart-core/int-class.html)\> **Example:** ```dart {class="line-numbers linkable-line-numbers"} -// Get the current value of an analog reader named "my_example_analog" -var analogVal = await myBoard.analogReaderValue('my_example_analog'); +// Get the current value of a digital interrupt named "my_example_digital_interrupt" +var interruptVal = await myBoard.digitalInterruptValue('my_example_digital_interrupt'); ``` -For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Board/analogReaderValue.html). +For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Board/digitalInterruptValue.html). {{% /tab %}} {{< /tabs >}} -### Write +### ReadAnalogReader -Write an analog value to a pin on the board. +Read the current integer value of the digital signal output by the ADC. Supported by `viam-micro-server`. {{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- (viam.components.board.board.Board.Analog.Value): The current value, including the min, max, and step_size of the reader. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_board = Board.from_robot(robot=robot, name="my_board") + +# Get the Analog "my_example_analog_reader". +reader = await my_board.analog_reader_by_name( + name="my_example_analog_reader") + +# Get the value of the digital signal "my_example_analog_reader" has most +# recently measured. +reading = await reader.read() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.AnalogClient.read). + +{{% /tab %}} {{% tab name="Go" %}} **Parameters:** - `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `value` [(int)](https://pkg.go.dev/builtin#int): Value to write to the pin. - `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. **Returns:** +- [(AnalogValue)](https://pkg.go.dev/go.viam.com/rdk/components/board#AnalogValue): The current value, including the integer `Value` of the digital signal output by the analog pin and the `Min`, `Max`, and `StepSize` of the reader. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. **Example:** @@ -606,11 +645,13 @@ Supported by `viam-micro-server`. ```go {class="line-numbers linkable-line-numbers"} myBoard, err := board.FromRobot(robot, "my_board") -// Get the Analog pin "my_example_analog". +// Get the analog pin "my_example_analog". analog, err := myBoard.AnalogByName("my_example_analog") -// Set the pin to value 48. -err := analog.Write(context.Background(), 48, nil) +// Get the value of the analog signal "my_example_analog" has most recently measured. +reading, err := analog.Read(context.Background(), nil) +readingValue := reading.Value +stepSize := reading.StepSize ``` For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Analog). @@ -620,63 +661,68 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c **Parameters:** -- `pin` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required) -- `value` [int](https://api.flutter.dev/flutter/dart-core/int-class.html) (required) +- `analogReaderName` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required) - `extra` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html)\<[String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic\>? (optional) **Returns:** -- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)\ +- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)\<[AnalogValue](https://flutter.viam.dev/viam_sdk/AnalogValue.html)\> **Example:** ```dart {class="line-numbers linkable-line-numbers"} -// Set pin 11 to value 48 -await myBoard.writeAnalog('11', 48); +// Get the current value of an analog reader named "my_example_analog" +var analogVal = await myBoard.analogReaderValue('my_example_analog'); ``` -For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Board/writeAnalog.html). +For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Board/analogReaderValue.html). {{% /tab %}} {{< /tabs >}} -### GetDigitalInterruptValue +### WriteAnalog -Get a configured `DigitalInterrupt` by `name`. +Write an analog value to a pin on the board. +Supported by `viam-micro-server`. {{< tabs >}} {{% tab name="Python" %}} **Parameters:** -- `name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): Name of the digital interrupt. +- `value` ([int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): Value to write to the analog writer. +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. **Returns:** -- ([viam.components.board.board.Board.DigitalInterrupt](https://python.viam.dev/autoapi/viam/components/board/board/index.html#viam.components.board.board.Board.DigitalInterrupt)): The digital interrupt. +- None. **Example:** ```python {class="line-numbers linkable-line-numbers"} my_board = Board.from_robot(robot=machine, name="my_board") -# Get the DigitalInterrupt "my_example_digital_interrupt". -interrupt = await my_board.digital_interrupt_by_name( - name="my_example_digital_interrupt") +# Get the Analog "my_example_analog_writer". +writer = await my_board.analog_by_name( + name="my_example_analog_writer") + +await writer.write(42) ``` -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.digital_interrupt_by_name). +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.AnalogClient.write). {{% /tab %}} {{% tab name="Go" %}} **Parameters:** -- `name` [(string)](https://pkg.go.dev/builtin#string): Name of the digital interrupt you want to retrieve. Set as the `"name"` property in board configuration. +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `value` [(int)](https://pkg.go.dev/builtin#int): Value to write to the pin. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. **Returns:** -- [(DigitalInterrupt)](https://pkg.go.dev/go.viam.com/rdk/components/board#DigitalInterrupt): An interface representing a configured interrupt on the board. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. **Example:** @@ -684,11 +730,36 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ```go {class="line-numbers linkable-line-numbers"} myBoard, err := board.FromRobot(robot, "my_board") -// Get the DigitalInterrupt "my_example_digital_interrupt". -interrupt, err := myBoard.DigitalInterruptByName("my_example_digital_interrupt") +// Get the Analog pin "my_example_analog". +analog, err := myBoard.AnalogByName("my_example_analog") + +// Set the pin to value 48. +err := analog.Write(context.Background(), 48, nil) ``` -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Board). +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Analog). + +{{% /tab %}} +{{% tab name="Flutter" %}} + +**Parameters:** + +- `pin` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required) +- `value` [int](https://api.flutter.dev/flutter/dart-core/int-class.html) (required) +- `extra` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html)\<[String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic\>? (optional) + +**Returns:** + +- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)\ + +**Example:** + +```dart {class="line-numbers linkable-line-numbers"} +// Set pin 11 to value 48 +await myBoard.writeAnalog('11', 48); +``` + +For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Board/writeAnalog.html). {{% /tab %}} {{< /tabs >}} @@ -829,7 +900,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ - `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. - `mode` [(pb.PowerMode)](https://pkg.go.dev/go.viam.com/api/component/board/v1#PowerMode): Options to specify power usage of the board: `boardpb.PowerMode_POWER_MODE_UNSPECIFIED`, `boardpb.PowerMode_POWER_MODE_NORMAL`, and `boardpb.PowerMode_POWER_MODE_OFFLINE_DEEP`. -- `duration` [(*time.Duration)](https://pkg.go.dev/time#Duration): If provided, the board will exit the given power mode after the specified duration. +- `duration` [(\*time.Duration)](https://pkg.go.dev/time#Duration): If provided, the board will exit the given power mode after the specified duration. **Returns:** @@ -874,82 +945,42 @@ For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_s {{% /tab %}} {{< /tabs >}} -### GetGeometries - -Get all the geometries associated with the board in its current configuration, in the [frame](/services/frame-system/) of the board. -The [motion](/services/motion/) and [navigation](/services/navigation/) services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning. - -{{< tabs >}} -{{% tab name="Python" %}} - -**Parameters:** - -- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. -- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. - -**Returns:** - -- ([List[viam.proto.common.Geometry]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Geometry)): The geometries associated with the Component. - -**Example:** - -```python {class="line-numbers linkable-line-numbers"} -geometries = await my_board.get_geometries() - -if geometries: - # Get the center of the first geometry - print(f"Pose of the first geometry's centerpoint: {geometries[0].center}") -``` - -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.get_geometries). - -{{% /tab %}} -{{< /tabs >}} - -### Read +### AnalogByName -Read the current integer value of the digital signal output by the ADC. -Supported by `viam-micro-server`. +Get a configured `Analog` by `name`. {{< tabs >}} {{% tab name="Python" %}} **Parameters:** -- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. -- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. +- `name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): Name of the analog reader to be retrieved. **Returns:** -- (viam.components.board.board.Board.Analog.Value): The current value, including the min, max, and step_size of the reader. +- ([viam.components.board.board.Board.Analog](https://python.viam.dev/autoapi/viam/components/board/board/index.html#viam.components.board.board.Board.Analog)): The analog reader or writer. **Example:** ```python {class="line-numbers linkable-line-numbers"} -my_board = Board.from_robot(robot=machine, name="my_board") +my_board = Board.from_robot(robot=robot, name="my_board") # Get the Analog "my_example_analog_reader". -reader = await my_board.analog_reader_by_name( - name="my_example_analog_reader") - -# Get the value of the digital signal "my_example_analog_reader" has most -# recently measured. -reading = await reader.read() +reader = await my_board.analog_by_name(name="my_example_analog_reader") ``` -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.AnalogClient.read). +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.analog_by_name). {{% /tab %}} {{% tab name="Go" %}} **Parameters:** -- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. +- `name` [(string)](https://pkg.go.dev/builtin#string): Name of the analog pin you want to retrieve. Set as the `"name"` property in board configuration. **Returns:** -- [(AnalogValue)](https://pkg.go.dev/go.viam.com/rdk/components/board#AnalogValue): The current value, including the integer `Value` of the digital signal output by the analog pin and the `Min`, `Max`, and `StepSize` of the reader. +- [(Analog)](https://pkg.go.dev/go.viam.com/rdk/components/board#Analog): An interface representing an analog pin configured and residing on the board. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. **Example:** @@ -957,35 +988,28 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ ```go {class="line-numbers linkable-line-numbers"} myBoard, err := board.FromRobot(robot, "my_board") -// Get the analog pin "my_example_analog". +// Get the Analog pin "my_example_analog". analog, err := myBoard.AnalogByName("my_example_analog") - -// Get the value of the analog signal "my_example_analog" has most recently measured. -reading, err := analog.Read(context.Background(), nil) -readingValue := reading.Value -stepSize := reading.StepSize ``` -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Analog). +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Board). {{% /tab %}} {{< /tabs >}} -### Value - -Get the current value of this interrupt. +### DigitalInterruptByName +Get a DigitalInterrupt by `name`. {{< tabs >}} {{% tab name="Python" %}} **Parameters:** -- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. -- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. +- `name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): Name of the digital interrupt. **Returns:** -- ([int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)): The current value. +- ([viam.components.board.board.Board.DigitalInterrupt](https://python.viam.dev/autoapi/viam/components/board/board/index.html#viam.components.board.board.Board.DigitalInterrupt)): The digital interrupt. **Example:** @@ -995,25 +1019,20 @@ my_board = Board.from_robot(robot=machine, name="my_board") # Get the DigitalInterrupt "my_example_digital_interrupt". interrupt = await my_board.digital_interrupt_by_name( name="my_example_digital_interrupt") - -# Get the amount of times this DigitalInterrupt has been interrupted with a -# tick. -count = await interrupt.value() ``` -For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.DigitalInterruptClient.value). +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.digital_interrupt_by_name). {{% /tab %}} {{% tab name="Go" %}} **Parameters:** -- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. -- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. +- `name` [(string)](https://pkg.go.dev/builtin#string): Name of the digital interrupt you want to retrieve. Set as the `"name"` property in board configuration. **Returns:** -- [(int64)](https://pkg.go.dev/builtin#int64): The amount of ticks that have occurred. +- [(DigitalInterrupt)](https://pkg.go.dev/go.viam.com/rdk/components/board#DigitalInterrupt): An interface representing a configured interrupt on the board. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. **Example:** @@ -1023,33 +1042,9 @@ myBoard, err := board.FromRobot(robot, "my_board") // Get the DigitalInterrupt "my_example_digital_interrupt". interrupt, err := myBoard.DigitalInterruptByName("my_example_digital_interrupt") - -// Get the amount of times this DigitalInterrupt has ticked. -count, err := interrupt.Value(context.Background(), nil) -``` - -For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#DigitalInterrupt). - -{{% /tab %}} -{{% tab name="Flutter" %}} - -**Parameters:** - -- `digitalInterruptName` [String](https://api.flutter.dev/flutter/dart-core/String-class.html) (required) -- `extra` [Map](https://api.flutter.dev/flutter/dart-core/Map-class.html)\<[String](https://api.flutter.dev/flutter/dart-core/String-class.html), dynamic\>? (optional) - -**Returns:** - -- [Future](https://api.flutter.dev/flutter/dart-async/Future-class.html)\<[int](https://api.flutter.dev/flutter/dart-core/int-class.html)\> - -**Example:** - -```dart {class="line-numbers linkable-line-numbers"} -// Get the current value of a digital interrupt named "my_example_digital_interrupt" -var interruptVal = await myBoard.digitalInterruptValue('my_example_digital_interrupt'); ``` -For more information, see the [Flutter SDK Docs](https://flutter.viam.dev/viam_sdk/Board/digitalInterruptValue.html). +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/components/board#Board). {{% /tab %}} {{< /tabs >}} @@ -1106,6 +1101,38 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c {{% /tab %}} {{< /tabs >}} +### GetGeometries + +Get all the geometries associated with the board in its current configuration, in the [frame](/services/frame-system/) of the board. +The [motion](/services/motion/) and [navigation](/services/navigation/) services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `extra` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any]) (optional): Extra options to pass to the underlying RPC call. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([List[viam.proto.common.Geometry]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Geometry)): The geometries associated with the Component. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +geometries = await my_board.get_geometries() + +if geometries: + # Get the center of the first geometry + print(f"Pose of the first geometry's centerpoint: {geometries[0].center}") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/board/client/index.html#viam.components.board.client.BoardClient.get_geometries). + +{{% /tab %}} +{{< /tabs >}} + ### Reconfigure Reconfigure this resource. diff --git a/static/include/components/apis/overrides/protos/board.GetDigitalInterruptValue.md b/static/include/components/apis/overrides/protos/board.GetDigitalInterruptValue.md index f9514d4e07..39f84087e8 100644 --- a/static/include/components/apis/overrides/protos/board.GetDigitalInterruptValue.md +++ b/static/include/components/apis/overrides/protos/board.GetDigitalInterruptValue.md @@ -1 +1,2 @@ -Get a configured `DigitalInterrupt` by `name`. +Get the current value of a configured digital interrupt. +The value is the number of times the interrupt has been interrupted with a tick. diff --git a/static/include/components/apis/overrides/protos/board.Read.md b/static/include/components/apis/overrides/protos/board.ReadAnalogReader.md similarity index 100% rename from static/include/components/apis/overrides/protos/board.Read.md rename to static/include/components/apis/overrides/protos/board.ReadAnalogReader.md diff --git a/static/include/components/apis/overrides/protos/board.Value.md b/static/include/components/apis/overrides/protos/board.Value.md deleted file mode 100644 index a10439dc3d..0000000000 --- a/static/include/components/apis/overrides/protos/board.Value.md +++ /dev/null @@ -1 +0,0 @@ -Get the current value of this interrupt. diff --git a/static/include/components/apis/overrides/protos/board.Write.md b/static/include/components/apis/overrides/protos/board.WriteAnalog.md similarity index 100% rename from static/include/components/apis/overrides/protos/board.Write.md rename to static/include/components/apis/overrides/protos/board.WriteAnalog.md diff --git a/static/include/components/board/board-digital-interrupts.md b/static/include/components/board/board-digital-interrupts.md index c2ff7944d9..5d72def2a4 100644 --- a/static/include/components/board/board-digital-interrupts.md +++ b/static/include/components/board/board-digital-interrupts.md @@ -2,7 +2,7 @@ Configuring digital interrupts to monitor GPIO pins on your board is useful when your application needs to know precisely when there is a change in GPIO value between high and low. - When an interrupt configured on your board processes a change in the state of the GPIO pin it is configured to monitor, it ticks to record the state change. - You can stream these ticks with the board API's [`StreamTicks()`](/appendix/apis/components/board/#streamticks), or get the current value of the digital interrupt with [`Value()`](/appendix/apis/components/board/#value). + You can stream these ticks with the board API's [`StreamTicks()`](/appendix/apis/components/board/#streamticks), or get the current value of the digital interrupt with [`Value()`](/appendix/apis/components/board/#getdigitalinterruptvalue). - Calling [`GetGPIO()`](/appendix/apis/components/board/#getgpio) on a GPIO pin, which you can do without configuring interrupts, is useful when you want to know a pin's value at specific points in your program, but is less precise and convenient than using an interrupt. Integrate `digital_interrupts` into your machine in the `attributes` of your board by following the **Config Builder** instructions, or by adding the following to your board's JSON configuration: