DOCS-954: Add info to customlinux board doc (#2014)

docs/components/board/_index.md

@@ -47,7 +47,7 @@ For model-specific configuration information, click on one of the following mode
 | [`pca9685`](pca9685/) | [PCA9685 Arduino I<sup>2</sup>C Interface](https://www.adafruit.com/product/815), a 16-channel [I<sup>2</sup>C](#i2cs) [PWM](https://docs.arduino.cc/learn/microcontrollers/analog-output)/[servo](/components/servo/) driver peripheral |
 | [`upboard`](upboard/) | An Intel-based board like the [UP4000](https://github.com/up-board/up-community/wiki/Pinout_UP4000) |
 | [`fake`](fake/) | A model used for testing, with no physical hardware |
-| [`customlinux`](customlinux/) | A model for other linux boards. |
+| [`customlinux`](customlinux/) | A model for other Linux boards. |
 | other | You can use other boards with modular components such as [`periph_board`](https://github.com/viam-labs/periph_board) |
 
 ### Modular Resources

docs/components/board/customlinux.md

@@ -6,14 +6,30 @@ type: "docs"
 description: "Configure a customlinux board."
 images: ["/icons/components/board.svg"]
 tags: ["board", "components"]
-# SMEs: Susmita
+# SMEs: Alan, Olivia, Susmita
 ---
 
-Configure a `customlinux` board to integrate linux boards like the [Mediatek Genio 500 Pumpkin](https://ologicinc.com/portfolio/mediateki500/) into your robot.
+The `customlinux` board model supports boards like the [Mediatek Genio 500 Pumpkin](https://ologicinc.com/portfolio/mediateki500/) that run Linux operating systems and are not supported by other built-in Viam models.
+
+To integrate a custom Linux board into your robot:
+
+1. First [create a pin mappings file](#create-a-pin-mappings-file).
+2. Then [configure a `customlinux` board](#configure-your-board) on your robot, specifying the path to the mappings file in the board config.
 
 ## Create a pin mappings file
 
-On your `customlinux` board, create a file in your <file>/home/root</file> directory called <file>board.json</file> with your board's pin mappings:
+{{% alert title="Caution" color="caution" %}}
+
+While some lines on a board are attached to GPIO pins, some lines are attached to other board hardware.
+It is important to carefully determine your `line_number` values.
+Randomly entering numbers may result in hardware damage.
+
+{{% /alert %}}
+
+The pin mappings file describes the location of each GPIO pin on the board so that `viam-server` can access the pins correctly.
+
+On your `customlinux` board, create a JSON file in the directory of your choice with your board's pin mappings.
+Use the template and example below to populate the JSON file with a single key, `"pins"`, whose value is a list of objects that each represent a pin on the board.
 
 {{< tabs >}}
 {{% tab name="Template" %}}
@@ -23,8 +39,9 @@ On your `customlinux` board, create a file in your <file>/home/root</file> direc
   "pins": [
     {
       "name": "<pin-name>",
-      "device_name": "<device-name>",
+      "device_name": "<gpio-device-name>",
       "line_number": <integer>,
+      "pwm_chip_sysfs_dir": "<pwm-device-name>"
       "pwm_id": <integer>
     },
     ...
@@ -213,15 +230,104 @@ On your `customlinux` board, create a file in your <file>/home/root</file> direc
 {{% /tab %}}
 {{< /tabs >}}
 
-The following parameters are available for pin mappings:
+The following parameters are available for each pin object:
 
 <!-- prettier-ignore -->
 | Name | Type | Inclusion | Description |
 | ---- | ---- | --------- | ----------- |
-| `name` | string | **Required** | The name of the pin. <br> Example: `"3"`. |
-| `device_name` | string | **Required** | The device name. <br> Example: `"gpiochip0"`. |
-| `line_number` | integer | **Required** | The line number of the pin. <br> Example: `81`. |
-| `pwm_id` | integer | **Required** | The power management id of the pin. Example: `-1`. |
+| `name` | string | **Required** | The name of the pin. This can be anything you want but it is convenient to use the physical board pin number. <br> Example: `"3"`. |
+| `device_name` | string | **Required** | The name of the device in <file>/dev</file> that this pin is attached to. Multiple pins may be attached to the same GPIO chip.  See [GPIO info tips](#tips-for-finding-gpio-information) below. <br> Example: `"gpiochip0"`.
+| `line_number` | integer | **Required** | The line on the chip that is attached to this pin. See [GPIO info tips](#tips-for-finding-gpio-information) below. <br> Example: `81`. |
+| `pwm_chip_sysfs_dir` | string | Optional | Uniquely specifies which PWM device within [sysfs](https://en.wikipedia.org/wiki/Sysfs) this pin is connected to. See [PWM info tips](#tips-for-finding-pwm-information) below. <br> Example: `3290000.pwm`. |
+| `pwm_id` | integer | Optional | The line number on the PWM chip. See [PWM info tips](#tips-for-finding-pwm-information) below. <br> Example: `0`. |
+
+{{% alert title="Tip" color="tip" %}}
+
+`pwm_chip_sysfs_dir` and `pwm_id` only apply to pins with hardware PWM supported and enabled.
+If your board supports hardware PWM, you will need to enable it if it is not enabled by default.
+This process depends on your specific board.
+
+{{% /alert %}}
+
+{{% alert title="Info" color="info" %}}
+
+The current version of `viam-server` creates PWM functionality with software.
+The implementation of hardware-based PWM for custom Linux boards is planned for release in the future, so we recommend that you add PWM information to your board now so that you do not need to update your config later.
+
+{{% /alert %}}
+
+### Tips for finding GPIO information
+
+To see which chips exist and how many lines each chip has, run this command on your board:
+
+```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+sudo gpiodetect
+```
+
+Here is example output from this command on an Odroid C4:
+
+```sh {id="terminal-prompt" class="command-line" data-output="1-10"}
+gpiochip0 [aobus-banks] (16 lines)
+gpiochip1 [periphs-banks] (86 lines)
+```
+
+This example output indicates that there are two GPIO chips on this board.
+One has 16 lines, numbered 0-15.
+The other has 86 lines, numbered 0-85.
+
+To see info about every line on every GPIO chip, run this command:
+
+```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+sudo gpioinfo
+```
+
+Here is example output from the `sudo gpioinfo` command on an Odroid C4:
+
+```sh {id="terminal-prompt" class="command-line" data-output="1-10"}
+...
+  line  62:      unnamed       unused   input  active-high
+  line  63:      unnamed       unused   input  active-high
+  line  64:     "PIN_27"       unused   input  active-high
+  line  65:     "PIN_28"       unused   input  active-high
+  line  66:     "PIN_16"       unused   input  active-high
+  line  67:     "PIN_18"       unused   input  active-high
+  line  68:     "PIN_22"       unused   input  active-high
+...
+```
+
+In this example, the human-readable names such as `"PIN_28"` indicate which physical board pin each line is attached to.
+However, these names are not standardized.
+Some boards have pin names like `"PH.03"`.
+In either case, you need to look at the data sheet for your board and determine how the pin names map to the hardware.
+
+### Tips for finding PWM information
+
+Run the following command and look for unique strings within each [symlink](https://en.wikipedia.org/wiki/Symbolic_link).
+
+```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+ls -l /sys/class/pwm
+```
+
+Here is example output from this command on a Jetson Orin AGX:
+
+```sh {id="terminal-prompt" class="command-line" data-output="1-10"}
+total 0
+lrwxrwxrwx 1 root root 0 Sep  8  2022 pwmchip0 -> ../../devices/platform/3280000.pwm/pwm/pwmchip0
+lrwxrwxrwx 1 root root 0 Sep  8  2022 pwmchip1 -> ../../devices/platform/32a0000.pwm/pwm/pwmchip1
+lrwxrwxrwx 1 root root 0 Sep  8  2022 pwmchip2 -> ../../devices/platform/32c0000.pwm/pwm/pwmchip2
+lrwxrwxrwx 1 root root 0 Sep  8  2022 pwmchip3 -> ../../devices/platform/32f0000.pwm/pwm/pwmchip3
+lrwxrwxrwx 1 root root 0 Sep  8  2022 pwmchip4 -> ../../devices/platform/39c0000.tachometer/pwm/pwmchip4
+```
+
+Based on this example output, the values to use for `pwm_chip_sysfs_dir` are `328000.pwm`, `32a0000.pwm`, and so on.
+
+Each of these directories contains a file named <file>npwm</file> containing a number.
+The number in each file is the number of lines on the chip.
+The `pwm_id` value will be between `0` and one less than the number of lines.
+For example, if the <file>npwm</file> contains `"4"`, then the valid `pwm_id` values are `0`, `1`, `2`, and `3`.
+
+Determining which specific chip and line are attached to each pin depends on the board.
+Try looking at your board's data sheet and cross-referencing with the output from the commands above.
 
 ## Configure your board
 
@@ -302,7 +408,7 @@ Then edit the file path to use your [pin mappings file](#create-a-pin-mappings-f
 {{% /tab %}}
 {{< /tabs >}}
 
-The following attributes are available for `board/customlinux` boards:
+The following attributes are available for `customlinux` boards:
 
 <!-- prettier-ignore -->
 | Name | Type | Inclusion | Description |