Skip to content

Commit

Permalink
DOCS-1240: Update board configurations (#2044)
Browse files Browse the repository at this point in the history
  • Loading branch information
@npentrel
npentrel authored Oct 16, 2023
1 parent 849cb7d commit a23a255
Show file tree
Hide file tree
Showing 13 changed files with 395 additions and 295 deletions.
271 changes: 4 additions & 267 deletions docs/components/board/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,286 +56,23 @@ For model-specific configuration information, click on one of the following mode

## 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](#analogs), [digital interrupts](#digital_interrupts), and components that must communicate through the [SPI](#spis) and [I<sup>2</sup>C](#i2cs) protocols into your robot.

### `analogs`

An [analog-to-digital converter](https://www.electronics-tutorials.ws/combination/analogue-to-digital-converter.html) (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](/components/sensor/) 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](#spis), 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:

{{< tabs name="Configure an Analog Reader" >}}
{{% tab name="JSON Template" %}}

```json {class="line-numbers linkable-line-numbers"}
// "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>
}
]
```

{{% /tab %}}
{{% tab name="JSON Example" %}}

```json {class="line-numbers linkable-line-numbers"}
{
"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"
}
]
}
}
]
}
```

{{% /tab %}}
{{< /tabs >}}

The following properties are available for `analogs`:

<!-- prettier-ignore -->
| 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 {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the board's connection pin, wired to the ADC. |
|`spi_bus` | string | Optional | The `name` of the [SPI bus](#spis) 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. |
{{< readfile "/static/include/components/board/board-analogs.md" >}}

### `digital_interrupts`

[Interrupts](https://en.wikipedia.org/wiki/Interrupt) 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()`](#tick) to record the state change and notify any interested [callbacks](#addcallback) to "interrupt" the program.
- Calling [`Get()`](#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:

{{< tabs name="Configure a Digital Interrupt" >}}
{{% tab name="JSON Template" %}}

```json {class="line-numbers linkable-line-numbers"}
// "attributes": { ... ,
"digital_interrupts": [
{
"name": "<your-digital-interrupt-name>",
"pin": "<pin-number>",
}
]
```

{{% /tab %}}
{{% tab name="JSON Example" %}}

```json {class="line-numbers linkable-line-numbers"}
{
"components": [
{
"model": "pi",
"name": "your-board",
"type": "board",
"attributes": {
"digital_interrupts": [
{
"name": "your-interrupt-1",
"pin": "15"
},
{
"name": "your-interrupt-2",
"pin": "16"
}
]
}
}
]
}
```

{{% /tab %}}
{{< /tabs >}}

The following properties are available for `digital_interrupts`:

<!-- prettier-ignore -->
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
|`name` | string | **Required** | Your name for the digital interrupt. |
|`pin`| string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="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._ <ul><li>`basic`: Recommended. Tracks interrupt count. </li> <li>`servo`: For interrupts configured for a pin controlling a [servo](/components/servo/). Tracks pulse width value. </li></ul> |
{{< readfile "/static/include/components/board/board-digital-interrupts.md" >}}

### `spis`

[Serial Peripheral Interface (SPI)](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface) is a serial communication protocol that uses four [signal wires](https://learn.sparkfun.com/tutorials/serial-peripheral-interface-spi) 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](/components/) that requires SPI communication (peripheral device), wire a connection between CS and MOSI/MISO/SLCK pins on the board and component.

{{% alert title="Important" color="note" %}}

You must also enable SPI on your board if it is not enabled by default.
See your [board model's configuration instructions](#configuration) if applicable.

{{% /alert %}}

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:

{{< tabs name="Configure a SPI Bus" >}}
{{% tab name="JSON Template" %}}

```json {class="line-numbers linkable-line-numbers"}
// "attributes": { ... ,
"spis": [
{
"name": "<your-bus-name>",
"bus_select": "<your-bus-index>"
}
]
```

{{% /tab %}}
{{% tab name="JSON Example" %}}

```json {class="line-numbers linkable-line-numbers"}
"spis": [
{
"name": "main",
"bus_select": "0"
}
]
```

{{% /tab %}}
{{< /tabs >}}

The following properties are available for `spis`:

<!-- prettier-ignore -->
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
|`name`| string | **Required** | The `name` of the SPI bus. |
|`bus_select`| string | **Required** | The index of the SPI bus. |

{{% alert title="WIRING WITH SPI" color="tip" %}}

Refer to your board's pinout diagram or data sheet for SPI bus indexes and corresponding CS/MOSI/MISO/SCLK {{< glossary_tooltip term_id="pin-number" text="pin numbers" >}}.

Refer to your peripheral device's data sheet for CS/MOSI/MISO/SLCK pin layouts.

{{% /alert %}}
{{< readfile "/static/include/components/board/board-spis.md" >}}

### `i2cs`

The [Inter-Integrated circuit (I<sup>2</sup>C)](https://learn.sparkfun.com/tutorials/i2c/all) 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](/components/) that requires I<sup>2</sup>C communication (peripheral device), wire a connection between SDA and SCL pins on the board and component.

{{% alert title="Important" color="note" %}}

You must also enable I<sup>2</sup>C on your board if it is not enabled by default.
See your [board model's configuration instructions](#configuration) if applicable.

{{% /alert %}}

As supported boards have SDA and SCL pins internally configured to correspond with I<sup>2</sup>C 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:

{{< tabs name="Configure i2cs" >}}
{{% tab name="JSON Template" %}}

```json {class="line-numbers linkable-line-numbers"}
// "attributes": { ... ,
{
"i2cs": [
{
"name": "<your-bus-name>",
"bus": "<your-bus-index>"
}
]
}
```

{{% /tab %}}
{{% tab name="JSON Example" %}}

```json {class="line-numbers linkable-line-numbers"}
// "attributes": { ... ,
{
"i2cs": [
{
"name": "bus1",
"bus": "1"
}
]
}
```

{{% /tab %}}
{{< /tabs >}}

The following properties are available for `i2cs`:

<!-- prettier-ignore -->
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
|`name`| string| **Required** | `name` of the I<sup>2</sup>C bus. |
|`bus`| string | **Required** | The index of the I<sup>2</sup>C bus. |

{{% alert title="WIRING WITH I<sup>2</sup>C" color="tip" %}}

Refer to your board's pinout diagram or data sheet for I<sup>2</sup>C bus indexes and corresponding SDA/SCL {{< glossary_tooltip term_id="pin-number" text="pin numbers" >}}.

Refer to your peripheral device's data sheet for SDA/SCL pin layouts.

{{% /alert %}}
{{< readfile "/static/include/components/board/board-i2cs.md" >}}

## Control your board with Viam's client SDK libraries

Expand Down
22 changes: 19 additions & 3 deletions docs/components/board/beaglebone.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,22 @@ The following attributes are available for `beaglebone` boards:
<!-- prettier-ignore -->
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
| `digital_interrupts` | object | Optional | Any digital interrupts's {{< glossary_tooltip term_id="pin-number" text="pin number" >}} and name. See [configuration info](/components/board/#digital_interrupts). |
| `spis` | object | Optional | Any serial peripheral interface (SPI) chip select bus pins' index and name. See [configuration info](/components/board/#spis). |
| `i2cs` | object | Optional | Any inter-integrated circuit (I<sup>2</sup>C) bus pins' index and name. See [configuration info](/components/board/#i2cs). |
| `digital_interrupts` | object | Optional | Any digital interrupts's {{< glossary_tooltip term_id="pin-number" text="pin number" >}} and name. See [configuration info](#digital_interrupts). |
| `spis` | object | Optional | Any serial peripheral interface (SPI) chip select bus pins' index and name. See [configuration info](#spis). |
| `i2cs` | object | Optional | Any inter-integrated circuit (I<sup>2</sup>C) bus pins' index and name. See [configuration info](#i2cs). |

## Attribute Configuration

Configuring these attributes on your board allows you to integrate [digital interrupts](#digital_interrupts), and components that must communicate through the [SPI](#spis) and [I<sup>2</sup>C](#i2cs) protocols into your robot.

### `digital_interrupts`

{{< readfile "/static/include/components/board/board-digital-interrupts.md" >}}

### `spis`

{{< readfile "/static/include/components/board/board-spis.md" >}}

### `i2cs`

{{< readfile "/static/include/components/board/board-i2cs.md" >}}
28 changes: 24 additions & 4 deletions docs/components/board/fake.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,27 @@ The following attributes are available for `fake` boards:
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
| `fail_new` | bool | **Required** | If the fake board should raise an error at robot start-up. |
<!-- | `analogs` | object | Optional | Attributes of any pins that can be used as Analog-to-Digital Converter (ADC) inputs. See [configuration info](/components/board/#analogreader). |
| `digital_interrupts` | object | Optional | Pin and name of any digital interrupts. See [configuration info](/components/board/#digital-interrupts). |
| `spis` | object | Optional | Any serial peripheral interface (SPI) chip select bus pins' index and name. See [configuration info](/components/board/#spi-buses). |
| `i2cs` | object | Optional | Any inter-integrated circuit (I2C) bus pins' index and name. See [configuration info](/components/board/#i2cs). | -->
| `analogs` | object | Optional | Attributes of any pins that can be used as Analog-to-Digital Converter (ADC) inputs. See [configuration info](#analogs). |
| `digital_interrupts` | object | Optional | Pin and name of any digital interrupts. See [configuration info](#digital_interrupts). |
| `spis` | object | Optional | Any serial peripheral interface (SPI) chip select bus pins' index and name. See [configuration info](#spis). |
| `i2cs` | object | Optional | Any inter-integrated circuit (I2C) bus pins' index and name. See [configuration info](#i2cs). |

## Attribute Configuration

Configuring these attributes on your board allows you to integrate [analog-to-digital converters](#analogs), [digital interrupts](#digital_interrupts), and components that must communicate through the [SPI](#spis) and [I<sup>2</sup>C](#i2cs) protocols into your robot.

### `analogs`

{{< readfile "/static/include/components/board/board-analogs.md" >}}

### `digital_interrupts`

{{< readfile "/static/include/components/board/board-digital-interrupts.md" >}}

### `spis`

{{< readfile "/static/include/components/board/board-spis.md" >}}

### `i2cs`

{{< readfile "/static/include/components/board/board-i2cs.md" >}}
22 changes: 19 additions & 3 deletions docs/components/board/jetson.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,22 @@ The following attributes are available for `jetson` boards:
<!-- prettier-ignore -->
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
| `digital_interrupts` | object | Optional | Any digital interrupts's {{< glossary_tooltip term_id="pin-number" text="pin number" >}} and name. See [configuration info](/components/board/#digital_interrupts). |
| `spis` | object | Optional | Any Serial Peripheral Interface (SPI) chip select pins' bus index and name. See [configuration info](/components/board/#spis). |
| `i2cs` | object | Optional | Any Inter-Integrated Circuit (I<sup>2</sup>C) pins' bus index and name. See [configuration info](/components/board/#i2cs). |
| `digital_interrupts` | object | Optional | Any digital interrupts's {{< glossary_tooltip term_id="pin-number" text="pin number" >}} and name. See [configuration info](#digital_interrupts). |
| `spis` | object | Optional | Any Serial Peripheral Interface (SPI) chip select pins' bus index and name. See [configuration info](#spis). |
| `i2cs` | object | Optional | Any Inter-Integrated Circuit (I<sup>2</sup>C) pins' bus index and name. See [configuration info](#i2cs). |

## Attribute Configuration

Configuring these attributes on your board allows you to integrate [digital interrupts](#digital_interrupts), and components that must communicate through the [SPI](#spis) and [I<sup>2</sup>C](#i2cs) protocols into your robot.

### `digital_interrupts`

{{< readfile "/static/include/components/board/board-digital-interrupts.md" >}}

### `spis`

{{< readfile "/static/include/components/board/board-spis.md" >}}

### `i2cs`

{{< readfile "/static/include/components/board/board-i2cs.md" >}}
12 changes: 8 additions & 4 deletions docs/components/board/numato.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,12 @@ The following attributes are available for `numato` boards:
| Name | Type | Inclusion | Description |
| ---- | ---- | --------- | ----------- |
| `pins` | int | **Required** | Number of GPIO pins available on the module. |
| `analogs` | object | Optional | Attributes of any pins that can be used as Analog-to-Digital Converter (ADC) inputs. See [configuration info](#analogs). |

<!-- I think these are available but I need to confirm
| `digital_interrupts` | object | Optional | Pin and name of any digital interrupts. See [configuration info](/components/board/#digital-interrupts). |
| `spis` | object | Optional | Any Serial Peripheral Interface (SPI) chip select bus pins' index and name. See [configuration info](/components/board/#spi-buses). |
| `i2cs` | object | Optional | Any Inter Integrated Circuit (I2C) bus pins' index and name. See [configuration info](/components/board/#i2cs). | -->
## Attribute Configuration

Configuring these attributes on your board allows you to integrate [analog-to-digital converters](#analogs) into your robot.

### `analogs`

{{< readfile "/static/include/components/board/board-analogs.md" >}}
Loading

0 comments on commit a23a255

Please sign in to comment.