Board Component
A board is the signal wire hub of a robot that provides access to general purpose input/output (GPIO) pins: a collection of pins on the motherboard of a computer that can receive electrical signals.
You can control the flow of electricity to these pins to change their state between “high” (active) and “low” (inactive), and wire them to send digital signals to and from other hardware.
This control is simplified with viam-server
.
When Viam’s software is running on a computer with GPIO pins accessible to external hardware components, it manages GPIO signaling to abstract control to resource APIs.

The RDK also provides the GPIOPin
interface for direct control and monitoring of the state of GPIO pins.
Configuration
Configure a board component on your robot to communicate with the other components of the robot.
Signaling is overseen by a computer running viam-server
.
A board can be:
- A single-board computer (SBC) with GPIO pins and a CPU capable of running
viam-server
. - A GPIO peripheral device that must connect to an external computer.
- A PWM peripheral device that must connect to an SBC that has a CPU and GPIO pins.
For model-specific configuration information, click on one of the following models:
Model | Description |
---|---|
pi | Raspberry Pi 4, Raspberry Pi 3 or Raspberry Pi Zero 2 W |
ti | Texas Instruments TDA4VM |
beaglebone | BeagleBoard’s BeagleBone AI-64 |
jetson | NVIDIA Jetson AGX Orin, NVIDIA Jetson Orin Nano, NVIDIA Jetson Xavier NX, NVIDIA Jetson Nano |
numato | Numato GPIO Modules, peripherals for adding GPIO pins |
pca9685 | PCA9685 Arduino I2C Interface, a 16-channel I2C PWM/servo driver peripheral |
upboard | An Intel-based board like the UP4000 |
fake | A model used for testing, with no physical hardware |
other | You can use other boards with modular components such as periph_board |
Attribute Configuration
The following configuration attributes are available for every board model besides the numato
and pca9685
peripherals and fake
.
Configuring these attributes on your board allows you to integrate analog-to-digital converters, digital interrupts, and components that must communicate through the SPI and I2C protocols into your robot.
analogs
An analog-to-digital converter (ADC) takes a continuous voltage input (analog signal) and converts it to an discrete integer output (digital signal).
ADCs are useful when building a robot, as they enable your board to read the analog signal output by most types of sensors and other hardware components.
To integrate an ADC into your robot, you must first physically connect the pins on your ADC to your board.
If your ADC communicates with your board using SPI, you need to wire and configure the SPI bus in addition to the analogs
.
Then, integrate analogs
into the attributes
of your board by adding the following to your board’s JSON configuration:
// "attributes": { ... ,
"analogs": [
{
"chip_select": "<chip-select-pin-number-on-board>",
"name": "<your-analog-reader-name>",
"pin": "<pin-number-on-adc>",
"spi_bus": "<your-spi-bus-name>"
}
]
{
"components": [
{
"model": "pi",
"name": "your-board",
"type": "board",
"attributes": {
"analogs": [
{
"chip_select": "24",
"name": "current",
"pin": "1",
"spi_bus": "main"
},
{
"chip_select": "24",
"name": "pressure",
"pin": "0",
"spi_bus": "main"
}
],
"spis": [
{
"bus_select": "0",
"name": "main"
}
]
}
}
]
}
The following properties are available for analogs
:
Name | Type | Inclusion | Description |
---|---|---|---|
name | string | Required | Your name for the analog reader. |
pin | string | Required | The pin number of the ADC’s connection pin, wired to the board. This should be labeled as the physical index of the pin on the ADC. |
chip_select | string | Required | The pin number of the board’s connection pin, wired to the ADC. |
spi_bus | string | Optional | The name of the SPI bus connecting the ADC and board. Required if your board must communicate with the ADC with the SPI protocol. |
average_over_ms | int | Optional | Duration in milliseconds over which the rolling average of the analog input should be taken. |
samples_per_sec | int | Optional | Sampling rate of the analog input in samples per second. |
digital_interrupts
Interrupts are a method of signaling precise state changes.
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 calls
Tick()
to record the state change and notify any interested callbacks to “interrupt” the program. - Calling
Get()
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 robot in the attributes
of your board by adding the following to your board’s JSON configuration:
// "attributes": { ... ,
"digital_interrupts": [
{
"name": "<your-digital-interrupt-name>",
"pin": "<pin-number>"
}
]
{
"components": [
{
"model": "pi",
"name": "your-board",
"type": "board",
"attributes": {
"digital_interrupts": [
{
"name": "your-interrupt-1",
"pin": "15"
},
{
"name": "your-interrupt-2",
"pin": "16"
}
]
}
}
]
}
The following properties are available for digital_interrupts
:
Name | Type | Inclusion | Description |
---|---|---|---|
name | string | Required | Your name for the digital interrupt. |
pin | string | Required | The pin number of the board’s GPIO pin that you wish to configure the digital interrupt for. |
type | string | Optional |
|
spis
Serial Peripheral Interface (SPI) is a serial communication protocol that uses four signal wires to exchange information between a controller and peripheral devices:
- Main Out/Secondary In: MOSI
- Main In/Secondary Out: MISO
- Clock, an oscillating signal line: SCLK
- Chip Select, with 1 line for each peripheral connected to controller: CS*
To connect your board (controller) and a component that requires SPI communication (peripheral device), wire a connection between CS and MOSI/MISO/SLCK pins on the board and component.
Important
You must also enable SPI on your board if it is not enabled by default. See your board model’s configuration instructions if applicable.
As supported boards have CS pins internally configured to correspond with SPI bus indices, you can enable this connection in your board’s configuration by specifying the index of the bus at your CS pin’s location and giving it a name.
Integrate spis
into your robot in the attributes
of your board by adding the following to your board’s JSON configuration:
// "attributes": { ... ,
"spis": [
{
"name": "<your-bus-name>",
"bus_select": "<your-bus-index>"
}
]
"spis": [
{
"name": "main",
"bus_select": "0"
}
]
The following properties are available for spis
:
Name | Type | Inclusion | Description |
---|---|---|---|
name | string | Required | The name of the SPI bus. |
bus_select | string | Required | The index of the SPI bus. |
WIRING WITH SPI
Refer to your board’s pinout diagram or data sheet for SPI bus indexes and corresponding CS/MOSI/MISO/SCLK pin numbers.
Refer to your peripheral device’s data sheet for CS/MOSI/MISO/SLCK pin layouts.
i2cs
The Inter-Integrated circuit (I2C) serial communication protocol is similar to SPI, but requires two signal wires to exchange information between a controller and a peripheral device:
- Serial Data: SDA
- Serial Clock: SCL
To connect your board (controller) and a component that requires I2C communication (peripheral device), wire a connection between SDA and SCL pins on the board and component.
Important
You must also enable I2C on your board if it is not enabled by default. See your board model’s configuration instructions if applicable.
As supported boards have SDA and SCL pins internally configured to correspond with I2C bus indices, you can enable this connection in your board’s configuration by specifying the index of the bus and giving it a name.
Integrate i2cs
into your robot in the attributes
of your board as follows:
// "attributes": { ... ,
{
"i2cs": [
{
"name": "<your-bus-name>",
"bus": "<your-bus-index>"
}
]
}
// "attributes": { ... ,
{
"i2cs": [
{
"name": "bus1",
"bus": "1"
}
]
}
The following properties are available for i2cs
:
Name | Type | Inclusion | Description |
---|---|---|---|
name | string | Required | name of the I2C bus. |
bus_select | int | Required | The index of the I2C bus. |
WIRING WITH I2C
Refer to your board’s pinout diagram or data sheet for I2C bus indexes and corresponding SDA/SCL pin numbers.
Refer to your peripheral device’s data sheet for SDA/SCL pin layouts.
Control your board 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, navigate to the Code sample tab, select your preferred programming language, and copy the sample code generated.
Location secret
By default, the sample code does not include your robot location secret. We strongly recommend that you add your location secret as an environment variable and import this variable into your development environment as needed.
To show your robot’s location secret in the sample code, toggle Include secret on the Code sample tab. You can also see your location secret on the locations page.
Caution
Do not share your location secret, part secret, or robot address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your robot, or to the computer running your robot.
When executed, this sample code will create a connection to your robot as a client.
Then control your robot programmatically by getting your board
component from the robot with FromRobot
and adding API method calls, as shown in the following examples.
These examples assume you have a board called “my_board” configured as a component of your robot.
If your board has a different name, change the name
in the code.
Be sure to import the board package for the SDK you are using:
from viam.components.board import Board
import (
"go.viam.com/rdk/components/board"
)
API
The board component supports the following methods:
Method Name | Description |
---|---|
AnalogReaderByName | Get an AnalogReader by name . |
DigitalInterruptByName | Get a DigitalInterrupt by name . |
GPIOPinByName | Get a GPIOPin by its pin number. |
AnalogReaderNames | Get the name of every AnalogReader . |
DigitalInterruptNames | Get the name of every DigitalInterrupt . |
Status | Get the current status of this board. |
ModelAttributes | Get the attributes related to the model of this board. |
SetPowerMode | Set the board to the indicated power mode. |
DoCommand | Send or receive model-specific commands. |
Additionally, the nested GPIOPin
, AnalogReader
, and DigitalInterrupt
interfaces support the following methods:
GPIOPin
API:
Method Name | Description |
---|---|
Set | Set the output of this pin to high/low. |
Get | Get if this pin is active (high). |
GetPWM | Get the pin’s pulse-width modulation duty cycle. |
SetPWM | Set the pin’s pulse-width modulation duty cycle. |
PWMFreq | Get the pulse-width modulation frequency of this pin. |
SetPWMFreq | Set the pulse-width modulation frequency of this pin. |
AnalogReader
API:
Method Name | Description |
---|---|
Read | Read the current integer value of the digital signal output by the ADC. |
DigitalInterrupt
API:
Method Name | Description |
---|---|
Value | Get the current value of this interrupt. |
Tick | Record an interrupt. |
AddCallback | Add a channel as a callback for Tick(). |
AddPostProcessor | Add a PostProcessor function for Value(). |
AnalogReaderByName
Get an AnalogReader
by name.
Parameters:
name
(str): Name of the analog reader you want to retrieve.
Returns:
- (AnalogReader): An interface representing an analog reader configured and residing on the board.
For more information, see the Python SDK Docs.
my_board = Board.from_robot(robot=robot, name="my_board")
# Get the AnalogReader "my_example_analog_reader".
reader = await my_board.analog_reader_by_name(name="my_example_analog_reader")
Parameters:
name
(str): Name of the analog reader you want to retrieve. Set as the"name"
property in configuration.
Returns:
- (AnalogReader): An interface representing an analog reader configured and residing on the board.
- (bool): True if there was an analog reader of this
name
found on your board.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the AnalogReader "my_example_analog_reader".
reader, err := myBoard.AnalogReaderByName("my_example_analog_reader")
DigitalInterruptByName
Get an DigitalInterrupt
by name.
Parameters:
name
(str): Name of the digital interrupt you want to retrieve. Set as the"name"
property in configuration.
Returns:
- (DigitalInterrupt): An interface representing a configured interrupt on the board.
For more information, see the Python SDK Docs.
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
(string): Name of the digital interrupt you want to retrieve. Set as the"name"
property in configuration.
Returns:
- (DigitalInterrupt): An interface representing a configured interrupt on the board.
- (bool): True if there was a digital interrupt of this
name
found on your board.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
GPIOPinByName
Get a GPIOPin
by pin number.
Parameters:
name
(str): Pin number of the GPIO pin you want to retrieve as aGPIOPin
interface. Refer to the pinout diagram and data sheet of your board model for pin numbers.
Returns:
- (GPIOPin): An interface representing an individual GPIO pin on the board.
For more information, see the Python SDK Docs.
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
(string): pin number of the GPIO pin you want to retrieve as aGPIOPin
interface. Refer to the pinout diagram and data sheet of your board model for pin numbers.
Returns:
- (GPIOPin): An interface representing an individual GPIO pin on the board.
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
AnalogReaderNames
Get the name of every AnalogReader
configured and residing on the board.
Parameters:
- None
Returns:
- (List[str]): An list containing the
"name"
of every analog reader configured on the board.
For more information, see the Python SDK Docs.
my_board = Board.from_robot(robot=robot, name="my_board")
# Get the name of every AnalogReader configured on the board.
names = await my_board.analog_reader_names()
Parameters:
- None
Returns:
- ([]string): An slice containing the
"name"
of every analog reader configured on the board.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the name of every AnalogReader configured on the board.
names := myBoard.AnalogReaderNames()
DigitalInterruptNames
Get the name of every DigitalInterrupt
configured on the board.
Parameters:
- None
Returns:
- (List[str]): A list containing the
"name"
of every interrupt configured on the board.
For more information, see the Python SDK Docs.
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()
Parameters:
- None
Returns:
- ([]string): A slice containing the
"name"
of every interrupt configured on the board.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the name of every DigitalInterrupt configured on the board.
names := myBoard.DigitalInterruptNames()
Status
Get the current status of the board as a BoardStatus
.
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (BoardStatus): Mappings of the current status of the fields and values of any AnalogReaders and DigitalInterrupts configured on the board.
For more information, see the Python SDK Docs.
my_board = Board.from_robot(robot=robot, name="my_board")
# Get the current status of the board.
status = await my_board.status()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (error): An error, if one occurred.
- (BoardStatus): Mappings of the current status of the fields and values of any AnalogReaders and DigitalInterrupts configured on the board.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the current status of the board.
err := myBoard.Status(context.Background(), nil)
ModelAttributes
Get the attributes related to the model of this board.
Parameters:
- None
Returns:
- (Attributes): Attributes related to the model of this board.
Will include the board’s innate
remote
attribute, which is not specified in configuration and is abool
indicating whether this model of board is accessed over a remote connection like gRPC.
For more information, see the Python SDK Docs.
my_board = Board.from_robot(robot=robot, name="my_board")
# Get the attributes related to the model of this board.
attributes = await my_board.model_attributes()
Parameters:
- None
Returns:
- (ModelAttributes): Attributes related to the model of this board.
Will include the board’s innate
remote
attribute, which is not specified in configuration and is abool
indicating whether this model of board is accessed over a remote connection like gRPC.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the attributes related to the model of this board.
attributes := myBoard.ModelAttributes()
SetPowerMode
Set the board to the indicated PowerMode
.
Info
This method may not receive a successful response from gRPC when you set the board to the offline power mode PowerMode.POWER_MODE_OFFLINE_DEEP
.
When this is the case for your board model, the call is returned with an error specifying that the remote procedure call timed out or that the endpoint is no longer available. This is expected: the board has been successfully powered down and can no longer respond to messages.
Parameters:
mode
(PowerMode): Options to specify power usage of the board:PowerMode.POWER_MODE_UNSPECIFIED
,PowerMode.POWER_MODE_NORMAL
, andPowerMode.POWER_MODE_OFFLINE_DEEP
.extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.duration
(Optional[datetime.timedelta]): If provided, the board will exit the given power mode after the specified duration.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- None
For more information, see the Python SDK Docs.
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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.mode
(PowerMode): Options to specify power usage of the board:boardpb.PowerMode_POWER_MODE_UNSPECIFIED
,boardpb.PowerMode_POWER_MODE_NORMAL
, andboardpb.PowerMode_POWER_MODE_OFFLINE_DEEP
.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.duration
(*time.Duration): If provided, the board will exit the given power mode after the specified duration.
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Set the power mode of the board to OFFLINE_DEEP.
err := myBoard.Status(context.Background(), nil)
myBoard.SetPowerMode(context.Background(), boardpb.PowerMode_POWER_MODE_OFFLINE_DEEP, nil)
DoCommand
Execute model-specific commands that are not otherwise defined by the component API.
For built-in models, model-specific commands are covered with each model’s documentation.
If you are implementing your own board and add features that have no built-in API method, you can access them with DoCommand
.
Parameters:
command
(Dict[str, Any]): The command to execute.
Returns:
- (Dict[str, Any]): Result of the executed command.
my_board = Board.from_robot(robot=robot, name="my_board")
my_command = {
"command": "dosomething",
"someparameter": 52
}
await my_board.do_command(my_command)
For more information, see the Python SDK Docs.
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.cmd
(map[string]interface{}): The command to execute.
Returns:
- (map[string]interface{}): Result of the executed command.
- (error): An error, if one occurred.
myBoard, err := board.FromRobot(robot, "my_board")
resp, err := myBoard.DoCommand(ctx, map[string]interface{}{"command": "dosomething", "someparameter": 52})
For more information, see the Go SDK Code.
GPIOPin
API
Set
Set the digital signal output of this pin to low (0V) or high (active, >0V).
Parameters:
high
(bool): Iftrue
, set the state of the pin to high. Iffalse
, set the state of the pin to low.extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- None
For more information, see the Python SDK Docs.
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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.high
(bool): Iftrue
, set the state of the pin to high. Iffalse
, set the state of the pin to low.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
// Set the pin to high.
err := pin.Set(context.Background(), "true", nil)
Get
Get if the digital signal output of this pin is high (active, >0V).
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (bool): If
true
, the state of the pin is high. Iffalse
, the state of the pin is low.
For more information, see the Python SDK Docs.
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()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (bool): If
true
, the state of the pin is high. Iffalse
, the state of the pin is low. - (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
// Get if it is true or false that the state of the pin is high.
high := pin.Get(context.Background(), nil)
GetPWM
Info
Pulse-width modulation (PWM) is a method where of transmitting a digital signal in the form of pulses to control analog circuits. With PWM on a board, the continuous digital signal output by a GPIO pin is sampled at regular intervals and transmitted to any hardware components wired to the pin that read analog signals. This enables the board to communicate with these components.
Get the pin’s pulse-width modulation (PWM) duty cycle: a float [0.0
, 1.0
] representing the percentage of time the digital signal output by 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).
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (float): A float [
0.0
,1.0
] representing the percentage of time the digital signal output by this pin is in the high state relative to the interval period of the PWM signal.
For more information, see the Python SDK Docs.
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()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (float64): A float [
0.0
,1.0
] representing the percentage of time the digital signal output by this pin is in the high state relative to the interval period of the PWM signal. - (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
// Get if it is true or false that the state of the pin is high.
duty_cycle := pin.PWM(context.Background(), nil)
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).
Parameters:
cycle
(float64): A float [0.0
,1.0
] representing the percentage of time the digital signal output by this pin is in the high state relative to the interval period of the PWM signal.extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (bool): If
true
, the state of the pin is high. Iffalse
, the state of the pin is low.
For more information, see the Python SDK Docs.
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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.cycle
(float64): A float [0.0
,1.0
] representing the percentage of time the digital signal output by this pin is in the high state relative to the interval period of the PWM signal.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("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.
err := pin.SetPWM(context.Background(), .6, nil)
PWMFreq
Get the Pulse-width modulation (PWM) frequency in Hertz (Hz) of this pin, the count of PWM interval periods per second. The optimal value for PWM Frequency depends on the type and model of component you control with the signal output by this pin. Refer to your device’s data sheet for PWM Frequency specifications.
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (int): The PWM Frequency in Hertz (Hz) (the count of PWM interval periods per second) the digital signal output by this pin is set to.
For more information, see the Python SDK Docs.
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()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (unit): The PWM Frequency in Hertz (Hz) (the count of PWM interval periods per second) the digital signal output by this pin is set to.
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
// Get the PWM frequency of this pin.
freqHz, err := pin.PWMFreq(context.Background(), nil)
SetPWMFreq
Set the Pulse-width modulation (PWM) frequency in Hertz (Hz) of this pin, the count of PWM interval periods per second. The optimal value for PWM Frequency depends on the type and model of component you control with the PWM signal output by this pin. Refer to your device’s data sheet for PWM Frequency specifications.
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (int): The PWM Frequency in Hertz (Hz), the count of PWM interval periods per second, to set the digital signal output by this pin to.
For more information, see the Python SDK Docs.
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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.freqHz
(unit): The PWM Frequency in Hertz (Hz), the count of PWM interval periods per second, to set the digital signal output by this pin to.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
// Set the PWM frequency of this pin to 1600 Hz.
high := pin.SetPWMFreq(context.Background(), 1600, nil)
AnalogReader
API
Read
Read the current integer value of the digital signal output by the ADC.
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (int): The value of the digital signal output by the analog reader.
For more information, see the Python SDK Docs.
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 pin is set to high.
duty_cycle = await pin.get_pwm()
# Get the AnalogReader "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 = reader.read()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (int): The value of the digital signal output by the analog reader.
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the AnalogReader "my_example_analog_reader".
reader, err := myBoard.AnalogReaderByName("my_example_analog_reader")
// Get the value of the digital signal "my_example_analog_reader" has most recently measured.
reading := reader.Read(context.Background(), nil)
DigitalInterrupt
API
Value
Get the current value of this interrupt.
If a post processor function has been added with AddPostProcessor()
, it will be applied to this value before it is returned.
Calculation of value differs between the "type"
of interrupt configured:
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
For more information, see the Python SDK Docs.
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()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
// Get the amount of times this DigitalInterrupt has been interrupted with a tick.
count, err := interrupt.Value(context.Background(), nil)
Parameters:
extra
(Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.timeout
(Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.
Returns:
- (int): The RollingAverage of the time in nanoseconds between two successive low signals (pulse width) recorded by
Tick()
, computed over a window of size10
.
For more information, see the Python SDK Docs.
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 rolling average of the pulse width across each time the
# DigitalInterrupt is interrupted with a tick.
rolling_avg = await interrupt.value()
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.extra
(map[string]interface{}): Extra options to pass to the underlying RPC call.
Returns:
- (int64): The RollingAverage of the time in nanoseconds between two successive low signals (pulse width) recorded by
Tick()
, computed over a window of size10
. - (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
// Get the rolling average of the pulse width across each time the DigitalInterrupt is interrupted with a tick.
rolling_avg, err := interrupt.Value(context.Background(), nil)
Tick
Record an interrupt and notify any channels that have been added with AddCallback().
Tip
You should only need to integrate this method into your application code for testing purposes, as the handling of Tick()
should be automated once the interrupt is configured.
Calling this method is not yet fully implemented with the Viam Python SDK.
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.high
(bool): Iftrue
, the state of the pin is set to high. Iffalse
, the state of the pin is set to low.now
(uint64): The time that has elapsed in nanoseconds since the last time the interrupt was ticked.
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
// Record an interrupt and notify any interested callbacks.
err := interrupt.Tick(context.Background(), true, 12345)
Parameters:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.high
(bool): Iftrue
, the state of the pin is set to high. Iffalse
, the state of the pin is set to low.nanoseconds
(uint64): The time in nanoseconds between two successive low signals (pulse width).
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
// Record an interrupt and notify any interested callbacks.
err := interrupt.Tick(context.Background(), true, 12345)
AddCallback
Add a channel as a listener for when the state of the configured GPIO pin changes.
When Tick() is called, callbacks added to an interrupt will be sent the returned value high
.
Support Notice
This method is not available for digital interrupts configured with "type": "servo"
.
It is also not yet fully implemented with the Viam Python SDK.
Parameters:
callback
(chan Tick): The channel to add as a listener for when the state of the GPIO pin this interrupt is configured for changes between high and low.
Returns:
- None
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
// Make the channel for Tick().
ch := make(chan Tick)
// Add the channel to "my_example_digital_interrupt" as a callback.
interrupt.AddCallback(ch)
AddPostProcessor
Add a PostProcessor function that takes an integer input and transforms it into a new integer value. Functions added to an interrupt will be used to modify values before they are returned by Value().
Support Notice
This method is not yet fully implemented with the Viam Python SDK.
Parameters:
processor
(PostProcessor): The post processor function to add.
Returns:
- (error): An error, if one occurred.
For more information, see the Go SDK Docs.
myBoard, err := board.FromRobot(robot, "my_board")
// Get the GPIOPin with pin number 15.
pin, err := myBoard.GPIOPinByName("15")
// Get the DigitalInterrupt "my_example_digital_interrupt".
interrupt, ok := myBoard.DigitalInterruptByName("my_example_digital_interrupt")
// Create a simple post processing function calculating absolute value of integers.
MySimplePP := int64(math.Abs)
// Add "MySimplePP" as a post processor to "my_example_digital_interrupt".
interrupt.AddPostProcessor(MySimplePP)
Troubleshooting
You can find additional assistance in the Troubleshooting section.
You can also ask questions in the Community Discord and we will be happy to help.
Next Steps
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!