viam.components.board.client

Attributes

ValueTypes

Types that can be encoded into a protobuf Value

TickStream

LOGGER

Classes

DoCommandRequest

DoCommandRequest represents a generic DoCommand input

DoCommandResponse

DoCommandResponse represents a generic DoCommand output

Geometry

Geometry contains the dimensions of a given geometry and the pose of its center. The geometry is one of either a sphere or a box.

BoardServiceStub

GetDigitalInterruptValueRequest

Digital Interrupt

GetDigitalInterruptValueResponse

Abstract base class for protocol messages.

GetGPIORequest

Abstract base class for protocol messages.

GetGPIOResponse

Abstract base class for protocol messages.

PowerMode

Power Management API

PWMFrequencyRequest

Abstract base class for protocol messages.

PWMFrequencyResponse

Abstract base class for protocol messages.

PWMRequest

Abstract base class for protocol messages.

PWMResponse

Abstract base class for protocol messages.

ReadAnalogReaderRequest

Analog Reader

SetGPIORequest

Abstract base class for protocol messages.

SetPowerModeRequest

Abstract base class for protocol messages.

SetPWMFrequencyRequest

Abstract base class for protocol messages.

SetPWMRequest

Abstract base class for protocol messages.

StreamTicksRequest

Abstract base class for protocol messages.

StreamTicksResponse

Abstract base class for protocol messages.

WriteAnalogRequest

Analog Writer

ReconfigurableResourceRPCClientBase

A base RPC client that can reset its channel.

StreamWithIterator

Board

Board represents a physical general purpose compute board that contains various

AnalogClient

Analog represents an analog pin reader or writer that resides on a Board.

DigitalInterruptClient

DigitalInterrupt represents a configured interrupt on the Board that

GPIOPinClient

Abstract representation of an individual GPIO pin on a board.

BoardClient

gRPC client for the Board component.

Functions

getLogger(→ logging.Logger)

dict_to_struct(→ google.protobuf.struct_pb2.Struct)

get_geometries(→ List[viam.proto.common.Geometry])

struct_to_dict(→ Dict[str, ValueTypes])

Module Contents

viam.components.board.client.getLogger(name: str) logging.Logger[source]
class viam.components.board.client.DoCommandRequest(*, name: str = ..., command: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

DoCommandRequest represents a generic DoCommand input

name: str
property command: google.protobuf.struct_pb2.Struct
HasField(field_name: Literal['command', b'command']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.DoCommandResponse(*, result: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

DoCommandResponse represents a generic DoCommand output

property result: google.protobuf.struct_pb2.Struct
HasField(field_name: Literal['result', b'result']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.Geometry(*, center: global___Pose | None = ..., sphere: global___Sphere | None = ..., box: global___RectangularPrism | None = ..., capsule: global___Capsule | None = ..., label: str = ...)

Bases: google.protobuf.message.Message

Geometry contains the dimensions of a given geometry and the pose of its center. The geometry is one of either a sphere or a box.

label: str

Label of the geometry. If none supplied, will be an empty string.

property center: global___Pose

Pose of a geometries center point

property sphere: global___Sphere
property box: global___RectangularPrism
property capsule: global___Capsule
HasField(field_name: Literal['box', b'box', 'capsule', b'capsule', 'center', b'center', 'geometry_type', b'geometry_type', 'sphere', b'sphere']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: Literal['geometry_type', b'geometry_type']) Literal['sphere', 'box', 'capsule'] | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.components.board.client.BoardServiceStub(channel: grpclib.client.Channel)[source]
class viam.components.board.client.GetDigitalInterruptValueRequest(*, board_name: str = ..., digital_interrupt_name: str = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Digital Interrupt

board_name: str
digital_interrupt_name: str
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.GetDigitalInterruptValueResponse(*, value: int = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

value: int
class viam.components.board.client.GetGPIORequest(*, name: str = ..., pin: str = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str
pin: str
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.GetGPIOResponse(*, high: bool = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

high: bool
class viam.components.board.client.PowerMode

Bases: _PowerMode

Power Management API

class viam.components.board.client.PWMFrequencyRequest(*, name: str = ..., pin: str = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str
pin: str
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.PWMFrequencyResponse(*, frequency_hz: int = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

frequency_hz: int
class viam.components.board.client.PWMRequest(*, name: str = ..., pin: str = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str
pin: str
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.PWMResponse(*, duty_cycle_pct: float = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

duty_cycle_pct: float

0-1

class viam.components.board.client.ReadAnalogReaderRequest(*, board_name: str = ..., analog_reader_name: str = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Analog Reader

board_name: str
analog_reader_name: str
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.SetGPIORequest(*, name: str = ..., pin: str = ..., high: bool = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str
pin: str
high: bool
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.SetPowerModeRequest(*, name: str = ..., power_mode: global___PowerMode = ..., duration: google.protobuf.duration_pb2.Duration | None = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str

name of board

power_mode: global___PowerMode

Requested power mode

property duration: google.protobuf.duration_pb2.Duration

Requested duration to stay in power_mode

property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['_duration', b'_duration', 'duration', b'duration', 'extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

WhichOneof(oneof_group: Literal['_duration', b'_duration']) Literal['duration'] | None

Returns the name of the field that is set inside a oneof group.

If no field is set, returns None.

Parameters:

oneof_group (str) – the name of the oneof group to check.

Returns:

The name of the group that is set, or None.

Return type:

str or None

Raises:

ValueError – no group with the given name exists

class viam.components.board.client.SetPWMFrequencyRequest(*, name: str = ..., pin: str = ..., frequency_hz: int = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str
pin: str
frequency_hz: int
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.SetPWMRequest(*, name: str = ..., pin: str = ..., duty_cycle_pct: float = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str
pin: str
duty_cycle_pct: float

0-1

property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.StreamTicksRequest(*, name: str = ..., pin_names: collections.abc.Iterable[str] | None = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

name: str

Board name

property pin_names: google.protobuf.internal.containers.RepeatedScalarFieldContainer[str]

Name of digital interrupts to recieve ticks from

property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.StreamTicksResponse(*, pin_name: str = ..., time: int = ..., high: bool = ...)

Bases: google.protobuf.message.Message

Abstract base class for protocol messages.

Protocol message classes are almost always generated by the protocol compiler. These generated types subclass Message and implement the methods shown below.

pin_name: str

name of interrupt

time: int

Time in nanoseconds of a tick

high: bool

Value high or low of the tick

class viam.components.board.client.WriteAnalogRequest(*, name: str = ..., pin: str = ..., value: int = ..., extra: google.protobuf.struct_pb2.Struct | None = ...)

Bases: google.protobuf.message.Message

Analog Writer

name: str
pin: str
value: int
property extra: google.protobuf.struct_pb2.Struct

Additional arguments to the method

HasField(field_name: Literal['extra', b'extra']) bool

Checks if a certain field is set for the message.

For a oneof group, checks if any field inside is set. Note that if the field_name is not defined in the message descriptor, ValueError will be raised.

Parameters:

field_name (str) – The name of the field to check for presence.

Returns:

Whether a value has been set for the named field.

Return type:

bool

Raises:

ValueError – if the field_name is not a member of this message.

class viam.components.board.client.ReconfigurableResourceRPCClientBase[source]

Bases: ResourceRPCClientBase

A base RPC client that can reset its channel.

Useful if connection is lost and then regained.

reset_channel(channel: grpclib.client.Channel)[source]

Called when the RPC channel was reset. Passes in the new channel.

Parameters:

channel (Channel) – The new RPC Channel

class viam.components.board.client.StreamWithIterator(stream: collections.abc.AsyncIterator[StreamType])[source]

Bases: Stream[StreamType]

async next() StreamType[source]
__aiter__()[source]
async __anext__() StreamType[source]
viam.components.board.client.ValueTypes

Types that can be encoded into a protobuf Value

viam.components.board.client.dict_to_struct(obj: Mapping[str, ValueTypes]) google.protobuf.struct_pb2.Struct[source]
async viam.components.board.client.get_geometries(client: viam.resource.types.SupportsGetGeometries, name: str, extra: Dict[str, Any] | None = None, timeout: float | None = None) List[viam.proto.common.Geometry][source]
viam.components.board.client.struct_to_dict(struct: google.protobuf.struct_pb2.Struct) Dict[str, ValueTypes][source]
class viam.components.board.client.Board(name: str)[source]

Bases: viam.components.component_base.ComponentBase

Board represents a physical general purpose compute board that contains various components such as analog readers/writers, and digital interrupts.

This acts as an abstract base class for any drivers representing specific board implementations. This cannot be used on its own. If the __init__() function is overridden, it must call the super().__init__() function.

from viam.components.board import Board

For more information, see Board component.

SUBTYPE: Final
class Analog(name: str)[source]

Analog represents an analog pin reader or writer that resides on a Board.

name: str

The name of the analog pin

Value: TypeAlias = ReadAnalogReaderResponse

Value contains the result of reading an analog reader. It contains the raw data read, the reader’s minimum and maximum possible values, and its step size (the minimum possible change between values it can read).

For more information, see analogs.

abstract read(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) Value[source]
Async:

Read the current value from the reader.

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()
Returns:

The current value, including the min, max, and step_size of the reader.

Return type:

Value

For more information, see Board component Analog API.

abstract write(value: int, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs)[source]
Async:

Write a value to the Analog writer.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the Analog "my_example_analog_writer".
writer = await my_board.analog_by_name(
    name="my_example_analog_writer")

await writer.write(42)
Parameters:

value (int) – Value to write to the analog writer.

For more information, see Board component Analog API.

class DigitalInterrupt(name: str)[source]

DigitalInterrupt represents a configured interrupt on the Board that when interrupted, calls the added callbacks. Post processors can be added to modify what Value it ultimately returns.

For more information, see digital_interrupts.

name: str

The name of the digital interrupt.

abstract value(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) int[source]
Async:

Get the current value of the interrupt, which is based on the type of interrupt.

my_board = Board.from_robot(robot=robot, 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()
Returns:

The current value.

Return type:

int

For more information, see Board component DigitalInterrupt API.

class GPIOPin(name: str)[source]

Abstract representation of an individual GPIO pin on a board.

name: str

The name of the GPIO pin.

abstract set(high: bool, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs)[source]
Async:

Set the pin to either low or high.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Set the pin to high.
await pin.set(high="true")
Parameters:

high (bool) – When true, sets the pin to high. When false, sets the pin to low.

For more information, see GPIOPin API.

abstract get(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) bool[source]
Async:

Get the high/low state of the pin.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Get if it is true or false that the state of the pin is high.
high = await pin.get()
Returns:

Indicates if the state of the pin is high.

Return type:

bool

For more information, see GPIOPin API.

abstract get_pwm(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) float[source]
Async:

Get the pin’s given duty cycle.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Get if it is true or false that the state of the pin is high.
duty_cycle = await pin.get_pwm()
Returns:

The duty cycle.

Return type:

float

For more information, see GPIOPin API.

abstract set_pwm(duty_cycle: float, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs)[source]
Async:

Set the pin to the given duty_cycle.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Set the duty cycle to .6, meaning that this pin will be in the high state for
# 60% of the duration of the PWM interval period.
await pin.set_pwm(cycle=.6)
Parameters:

duty_cycle (float) – The duty cycle.

For more information, see GPIOPin API.

abstract get_pwm_frequency(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs) int[source]
Async:

Get the PWM frequency of the pin.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Get the PWM frequency of this pin.
freq = await pin.get_pwm_frequency()
Returns:

The PWM frequency.

Return type:

int

For more information, see GPIOPin API.

abstract set_pwm_frequency(frequency: int, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs)[source]
Async:

Set the pin to the given PWM frequency (in Hz). When frequency is 0, it will use the board’s default PWM frequency.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Set the PWM frequency of this pin to 1600 Hz.
high = await pin.set_pwm_frequency(frequency=1600)
Parameters:

frequency (int) – The frequency, in Hz.

For more information, see GPIOPin API.

abstract analog_by_name(name: str) Analog[source]
Async:

Get an Analog (reader or writer) by name.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the Analog "my_example_analog_reader".
reader = await my_board.analog_by_name(name="my_example_analog_reader")
Parameters:

name (str) – Name of the analog reader to be retrieved.

Returns:

The analog reader or writer.

Return type:

Analog

For more information, see Board component.

abstract digital_interrupt_by_name(name: str) DigitalInterrupt[source]
Async:

Get a DigitalInterrupt by name.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt = await my_board.digital_interrupt_by_name(
    name="my_example_digital_interrupt")
Parameters:

name (str) – Name of the digital interrupt.

Returns:

The digital interrupt.

Return type:

DigitalInterrupt

For more information, see Board component.

abstract gpio_pin_by_name(name: str) GPIOPin[source]
Async:

Get a GPIO Pin by name.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")
Parameters:

name (str) – Name of the GPIO pin.

Returns:

The pin.

Return type:

GPIOPin

For more information, see Board component.

abstract analog_names() List[str][source]
Async:

Get the names of all known analog readers and/or writers.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the name of every Analog configured on the board.
names = await my_board.analog_names()
Returns:

The list of names of all known analog readers/writers.

Return type:

List[str]

For more information, see Board component.

abstract digital_interrupt_names() List[str][source]
Async:

Get the names of all known digital interrupts.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the name of every DigitalInterrupt configured on the board.
names = await my_board.digital_interrupt_names()
Returns:

The names of the digital interrupts.

Return type:

List[str]

For more information, see Board component.

abstract set_power_mode(mode: viam.proto.component.board.PowerMode.ValueType, duration: datetime.timedelta | None = None, *, timeout: float | None = None, **kwargs)[source]
Async:

Set the board to the indicated power mode.

my_board = Board.from_robot(robot=robot, name="my_board")

# Set the power mode of the board to OFFLINE_DEEP.
status = await my_board.set_power_mode(mode=PowerMode.POWER_MODE_OFFLINE_DEEP)
Parameters:
  • mode (PowerMode) – The desired power mode.

  • duration (Optional[timedelta]) – Requested duration to stay in power mode.

For more information, see Board component.

abstract stream_ticks(interrupts: List[DigitalInterrupt], *, timeout: float | None = None, **kwargs) TickStream[source]
Async:

Stream digital interrupt ticks.

my_board = Board.from_robot(robot=robot, name="my_board")
di8 = await my_board.digital_interrupt_by_name(name="8"))
di11 = await my_board.digital_interrupt_by_name(name="11"))

# Iterate over stream of ticks from pins 8 and 11.
async for tick in my_board.stream_ticks([di8, di11]):
    print(f"Pin {tick.pin_name} changed to {'high' if tick.high else 'low'} at {tick.time}")
Parameters:

interrupts (List[DigitalInterrupt]) – list of digital interrupts to receive ticks from.

Returns:

stream of ticks.

Return type:

TickStream

For more information, see Board component.

classmethod from_robot(robot: viam.robot.client.RobotClient, name: str) typing_extensions.Self

Get the component named name from the provided robot.

Parameters:
  • robot (RobotClient) – The robot

  • name (str) – The name of the component

Returns:

The component, if it exists on the robot

Return type:

Self

abstract do_command(command: Mapping[str, ValueTypes], *, timeout: float | None = None, **kwargs) Mapping[str, ValueTypes]
Async:

Send/Receive arbitrary commands to the Resource

command = {"cmd": "test", "data1": 500}
result = component.do(command)
Parameters:

command (Mapping[str, ValueTypes]) – The command to execute

Raises:

NotImplementedError – Raised if the Resource does not support arbitrary commands

Returns:

Result of the executed command

Return type:

Mapping[str, ValueTypes]

async get_geometries(*, extra: Dict[str, Any] | None = None, timeout: float | None = None) List[viam.proto.common.Geometry]

Get all geometries associated with the component, in their current configuration, in the frame of the component.

geometries = await component.get_geometries()

if geometries:
    # Get the center of the first geometry
    print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")
Returns:

The geometries associated with the Component.

Return type:

List[Geometry]

classmethod get_resource_name(name: str) viam.proto.common.ResourceName

Get the ResourceName for this Resource with the given name

# Can be used with any resource, using an arm as an example
my_arm_name = my_arm.get_resource_name("my_arm")
Parameters:

name (str) – The name of the Resource

Returns:

The ResourceName of this Resource

Return type:

ResourceName

get_operation(kwargs: Mapping[str, Any]) viam.operations.Operation

Get the Operation associated with the currently running function.

When writing custom resources, you should get the Operation by calling this function and check to see if it’s cancelled. If the Operation is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc. ).

Parameters:

kwargs (Mapping[str, Any]) – The kwargs object containing the operation

Returns:

The operation associated with this function

Return type:

viam.operations.Operation

async close()

Safely shut down the resource and prevent further use.

Close must be idempotent. Later configuration may allow a resource to be “open” again. If a resource does not want or need a close function, it is assumed that the resource does not need to return errors when future non-Close methods are called.

await component.close()
viam.components.board.client.TickStream
viam.components.board.client.LOGGER
class viam.components.board.client.AnalogClient(name: str, board: BoardClient)[source]

Bases: viam.components.board.board.Board.Analog

Analog represents an analog pin reader or writer that resides on a Board.

async read(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__) viam.components.board.board.Board.Analog.Value[source]

Read the current value from the reader.

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()
Returns:

The current value, including the min, max, and step_size of the reader.

Return type:

Value

For more information, see Board component Analog API.

async write(value: int, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **kwargs)[source]

Write a value to the Analog writer.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the Analog "my_example_analog_writer".
writer = await my_board.analog_by_name(
    name="my_example_analog_writer")

await writer.write(42)
Parameters:

value (int) – Value to write to the analog writer.

For more information, see Board component Analog API.

class viam.components.board.client.DigitalInterruptClient(name: str, board: BoardClient)[source]

Bases: viam.components.board.board.Board.DigitalInterrupt

DigitalInterrupt represents a configured interrupt on the Board that when interrupted, calls the added callbacks. Post processors can be added to modify what Value it ultimately returns.

For more information, see digital_interrupts.

async value(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__) int[source]

Get the current value of the interrupt, which is based on the type of interrupt.

my_board = Board.from_robot(robot=robot, 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()
Returns:

The current value.

Return type:

int

For more information, see Board component DigitalInterrupt API.

class viam.components.board.client.GPIOPinClient(name: str, board: BoardClient)[source]

Bases: viam.components.board.board.Board.GPIOPin

Abstract representation of an individual GPIO pin on a board.

async get(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__) bool[source]

Get the high/low state of the pin.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Get if it is true or false that the state of the pin is high.
high = await pin.get()
Returns:

Indicates if the state of the pin is high.

Return type:

bool

For more information, see GPIOPin API.

async set(high: bool, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__)[source]

Set the pin to either low or high.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Set the pin to high.
await pin.set(high="true")
Parameters:

high (bool) – When true, sets the pin to high. When false, sets the pin to low.

For more information, see GPIOPin API.

async get_pwm(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__) float[source]

Get the pin’s given duty cycle.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Get if it is true or false that the state of the pin is high.
duty_cycle = await pin.get_pwm()
Returns:

The duty cycle.

Return type:

float

For more information, see GPIOPin API.

async set_pwm(duty_cycle: float, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__)[source]

Set the pin to the given duty_cycle.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Set the duty cycle to .6, meaning that this pin will be in the high state for
# 60% of the duration of the PWM interval period.
await pin.set_pwm(cycle=.6)
Parameters:

duty_cycle (float) – The duty cycle.

For more information, see GPIOPin API.

async get_pwm_frequency(*, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__) int[source]

Get the PWM frequency of the pin.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Get the PWM frequency of this pin.
freq = await pin.get_pwm_frequency()
Returns:

The PWM frequency.

Return type:

int

For more information, see GPIOPin API.

async set_pwm_frequency(frequency: int, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__)[source]

Set the pin to the given PWM frequency (in Hz). When frequency is 0, it will use the board’s default PWM frequency.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")

# Set the PWM frequency of this pin to 1600 Hz.
high = await pin.set_pwm_frequency(frequency=1600)
Parameters:

frequency (int) – The frequency, in Hz.

For more information, see GPIOPin API.

class viam.components.board.client.BoardClient(name: str, channel: grpclib.client.Channel)[source]

Bases: viam.components.board.board.Board, viam.resource.rpc_client_base.ReconfigurableResourceRPCClientBase

gRPC client for the Board component.

async analog_by_name(name: str) viam.components.board.board.Board.Analog[source]

Get an Analog (reader or writer) by name.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the Analog "my_example_analog_reader".
reader = await my_board.analog_by_name(name="my_example_analog_reader")
Parameters:

name (str) – Name of the analog reader to be retrieved.

Returns:

The analog reader or writer.

Return type:

Analog

For more information, see Board component.

async digital_interrupt_by_name(name: str) viam.components.board.board.Board.DigitalInterrupt[source]

Get a DigitalInterrupt by name.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt = await my_board.digital_interrupt_by_name(
    name="my_example_digital_interrupt")
Parameters:

name (str) – Name of the digital interrupt.

Returns:

The digital interrupt.

Return type:

DigitalInterrupt

For more information, see Board component.

async gpio_pin_by_name(name: str) viam.components.board.board.Board.GPIOPin[source]

Get a GPIO Pin by name.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the GPIOPin with pin number 15.
pin = await my_board.gpio_pin_by_name(name="15")
Parameters:

name (str) – Name of the GPIO pin.

Returns:

The pin.

Return type:

GPIOPin

For more information, see Board component.

async analog_names() List[str][source]

Get the names of all known analog readers and/or writers.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the name of every Analog configured on the board.
names = await my_board.analog_names()
Returns:

The list of names of all known analog readers/writers.

Return type:

List[str]

For more information, see Board component.

async digital_interrupt_names() List[str][source]

Get the names of all known digital interrupts.

my_board = Board.from_robot(robot=robot, name="my_board")

# Get the name of every DigitalInterrupt configured on the board.
names = await my_board.digital_interrupt_names()
Returns:

The names of the digital interrupts.

Return type:

List[str]

For more information, see Board component.

async do_command(command: Mapping[str, viam.utils.ValueTypes], *, timeout: float | None = None, **__) Mapping[str, viam.utils.ValueTypes][source]

Send/Receive arbitrary commands to the Resource

command = {"cmd": "test", "data1": 500}
result = component.do(command)
Parameters:

command (Mapping[str, ValueTypes]) – The command to execute

Raises:

NotImplementedError – Raised if the Resource does not support arbitrary commands

Returns:

Result of the executed command

Return type:

Mapping[str, ValueTypes]

async set_power_mode(mode: viam.proto.component.board.PowerMode.ValueType, duration: datetime.timedelta | None = None, *, timeout: float | None = None, **__)[source]

Set the board to the indicated power mode.

my_board = Board.from_robot(robot=robot, name="my_board")

# Set the power mode of the board to OFFLINE_DEEP.
status = await my_board.set_power_mode(mode=PowerMode.POWER_MODE_OFFLINE_DEEP)
Parameters:
  • mode (PowerMode) – The desired power mode.

  • duration (Optional[timedelta]) – Requested duration to stay in power mode.

For more information, see Board component.

async get_geometries(*, extra: Dict[str, Any] | None = None, timeout: float | None = None) List[viam.proto.common.Geometry][source]

Get all geometries associated with the component, in their current configuration, in the frame of the component.

geometries = await component.get_geometries()

if geometries:
    # Get the center of the first geometry
    print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")
Returns:

The geometries associated with the Component.

Return type:

List[Geometry]

async write_analog(pin: str, value: int, *, extra: Dict[str, Any] | None = None, timeout: float | None = None, **__)[source]
async stream_ticks(interrupts: List[viam.components.board.board.Board.DigitalInterrupt], *, extra: Dict[str, Any] | None = None, **__) viam.components.board.board.TickStream[source]

Stream digital interrupt ticks.

my_board = Board.from_robot(robot=robot, name="my_board")
di8 = await my_board.digital_interrupt_by_name(name="8"))
di11 = await my_board.digital_interrupt_by_name(name="11"))

# Iterate over stream of ticks from pins 8 and 11.
async for tick in my_board.stream_ticks([di8, di11]):
    print(f"Pin {tick.pin_name} changed to {'high' if tick.high else 'low'} at {tick.time}")
Parameters:

interrupts (List[DigitalInterrupt]) – list of digital interrupts to receive ticks from.

Returns:

stream of ticks.

Return type:

TickStream

For more information, see Board component.

classmethod from_robot(robot: viam.robot.client.RobotClient, name: str) typing_extensions.Self

Get the component named name from the provided robot.

Parameters:
  • robot (RobotClient) – The robot

  • name (str) – The name of the component

Returns:

The component, if it exists on the robot

Return type:

Self

classmethod get_resource_name(name: str) viam.proto.common.ResourceName

Get the ResourceName for this Resource with the given name

# Can be used with any resource, using an arm as an example
my_arm_name = my_arm.get_resource_name("my_arm")
Parameters:

name (str) – The name of the Resource

Returns:

The ResourceName of this Resource

Return type:

ResourceName

get_operation(kwargs: Mapping[str, Any]) viam.operations.Operation

Get the Operation associated with the currently running function.

When writing custom resources, you should get the Operation by calling this function and check to see if it’s cancelled. If the Operation is cancelled, then you can perform any necessary (terminating long running tasks, cleaning up connections, etc. ).

Parameters:

kwargs (Mapping[str, Any]) – The kwargs object containing the operation

Returns:

The operation associated with this function

Return type:

viam.operations.Operation

async close()

Safely shut down the resource and prevent further use.

Close must be idempotent. Later configuration may allow a resource to be “open” again. If a resource does not want or need a close function, it is assumed that the resource does not need to return errors when future non-Close methods are called.

await component.close()