Configure a pi board
REQUIREMENTS
Follow the setup guide to prepare your Pi for running viam-server
before configuring a pi
board.
Configure a pi
board to integrate a Raspberry Pi 4, Raspberry Pi 3 or Raspberry Pi Zero 2 W into your robot:
Navigate to the Config tab of your robot’s page in the Viam app.
Click on the Components subtab and click Create component.
Select the board
type, then select the pi
model.
Enter a name for your board and click Create.
Copy and paste the following attribute template into your board’s Attributes box. Then remove and fill in the attributes as applicable to your board, according to the table below.
{
"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>",
"average_over_ms": <int>,
"samples_per_sec": <int>
}
],
"digital_interrupts": [
{
"name": "<your-digital-interrupt-name>",
"pin": "<pin-number>",
"type": "<basic|servo>"
}
],
"spis": [
{
"name": "<your-bus-name>",
"bus_select": "<your-bus-index>"
}
],
"i2cs": [
{
"name": "<your-bus-name>",
"bus": "<your-bus-index>"
}
]
}
{
"digital_interrupts": [
{
"name": "your-interrupt-1",
"pin": "15"
},
{
"name": "your-interrupt-2",
"pin": "16"
}
]
}
{
"components": [
{
"name": "<your-pi-board-name>",
"model": "pi",
"type": "board",
"namespace": "rdk",
"attributes": {
"analogs": [
<...See table below...>
],
"digital_interrupts": [
<...See table below...>
],
"spis": [
<...See table below...>
],
"i2cs": [
<...See table below...>
]
},
"depends_on": []
}
]
}
The following attributes are available for pi
boards:
Name | Type | Inclusion | Description |
---|---|---|---|
analogs | object | Optional | Attributes of any pins that can be used as analog-to-digital converter (ADC) inputs. See configuration info. |
digital_interrupts | object | Optional | Any digital interrupts’s pin number and name. See configuration info. |
spis | object | Optional | Any Serial Peripheral Interface (SPI) chip select pins’ bus index and name. See configuration info. Review these instructions to learn how to enable SPI on a Raspberry Pi 4. |
i2cs | object | Optional | Any Inter-Integrated Circuit (I2C) pins’ bus index and name. See configuration info. Review these instructions to learn how to enable I2C on a Raspberry Pi 4. |
Attribute Configuration
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>",
"average_over_ms": <int>,
"samples_per_sec": <int>
}
]
{
"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 | Only applies to pi model boards.
|
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 | string | 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.
Have questions, or want to meet other people working on robots? Join our Community Discord.
If you notice any issues with the documentation, feel free to file an issue or edit this file.
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!