diff --git a/docs/guides/lab-assembly/pcengines.md b/docs/guides/lab-assembly/pcengines.md new file mode 100644 index 00000000000..318f0409e6f --- /dev/null +++ b/docs/guides/lab-assembly/pcengines.md @@ -0,0 +1,224 @@ +# Laboratory stand dedicated to PC Engines platforms assembly guide + +## Introduction + +This document describes platform-specific details for assembling PC Engines +apu2/3/4/6 series testing stands. Author get through the procedure on PC +Engines apu3 in his homelab. Use this document as reference while going through +[Generic Testing Stand +Setup](../../unified-test-documentation/generic-testing-stand-setup.md) + +## Prerequisites + +The below table contains platform-specific information about all elements which +are needed to create testing stands for Protectli machines. + +!!! warning + Please note that using RTE v1.0.0 or older change way how [OSFV + cli](https://github.com/Dasharo/osfv-scripts/blob/main/osfv_cli/src/osfv/libs/rte.py#L284) + works. On v1.0.0 and older there is no need for additional step of enabling + SPI GPIO, it is required only from v1.1.0 onwards. If it would not be + reflected in [model file](https://github.com/Dasharo/osfv-scripts/tree/main/osfv_cli/src/osfv/models) + it may lead to issues. For more details please check [here](https://github.com/Dasharo/osfv-scripts/issues/86). + +* [RTE +v1.1.0](https://shop.3mdeb.com/shop/open-source-hardware/open-source-hardware-3mdeb/rte/) +or RTE v1.0.0 +* RTE power supply 5V 2A Micro-USB +* 10x standard female-female connection wire 2.54 mm raster +* 4x RJ45 cable: 1 for RTE and 3 for the platform OR + - 5x RJ45 cable for apu4: 1 for RTE and 4 for the platform + +* [apu2/3/4/6](https://www.pcengines.ch/apu2.htm) + +* RS-232 D-Sub-D-Sub cross cable +* Power to the apu2/3/4/6 is delivered by 2.5/5.5 mm DC Jack cable. + +### External flashing enabling + +| RTE J7 pin | PC Engines SPI pin | +|:-----------------:|:-------------------:| +| 1 (VCC) | 1 (VCC) | +| 2 (GND) | 2 (GND) | +| 3 (CS) | 3 (SPICS#) | +| 4 (SCLK) | 4 (SPICLK) | +| 5 (MISO) | 5 (SPIDI) | +| 6 (MOSI) | 6 (SPIDO) | +| 7 (NC) | Not connected | +| 8 (NC) | Not connected | + +SPI connection can be realized with IDC 8 pin wire, but 7th and 8th wires +have to be opened. + +### Power and Reset switch connection + +Connect the RTE J11 header to the platform front panel header using 2.54mm +wires as described in the table: + +=== "APU2/APU4" + + | RTE | PC Engines | + |:---------:|:----------------------:| + | J11 pin 6 | J2 pin 3 (PWR) | + | J11 pin 5 | J2 pin 5 (RST) | + +=== "APU3/APU6" + + | RTE | PC Engines | + |:---------:|:----------------------:| + | J11 pin 6 | J3 pin 3 (PWR) | + | J11 pin 5 | J3 pin 5 (RST) | + +### Device power status readout + +Connect the RTE J1 header to the platform front panel header using 2.54mm +wires as described in the table: + +=== "APU2" + + | RTE | PC Engines | + |:-------------------------------:|:----------------------:| + | J1 pin 1(Closer to J7 header) | J4 pin 8 (APU_LED1) | + | J1 pin 2 | J4 pin 7 (APU_LED2) | + | J1 pin 3 | J4 pin 6 (APU_LED3) | + +=== "APU3/APU4/APU6" + + | RTE | PC Engines | + |:-------------------------------:|:----------------------:| + | J1 pin 1(Closer to J7 header) | J5 pin 8 (APU_LED1) | + | J1 pin 2 | J5 pin 7 (APU_LED2) | + | J1 pin 3 | J5 pin 6 (APU_LED3) | + +## Theory of operation + +The following sections describe how to use all of the enabled features: + +* serial connection to the platform, +* controlling power supply, +* enabling basic power actions with the platform (power off/power on/reset), +* external flashing with the RTE, +* CMOS reset. + +### Serial connection + +The method of setting and using serial connection is described in the +[Serial connection guide](../../transparent-validation/rte/v1.1.0/serial-port-connection-guide.md). + +### Power supply controlling + +Power supply controlling is performed with the relay module on RTE +connected to one of RTE GPIOs. Power operation should be performed using +the `rte_ctrl` script implemented in `meta-rte` (OS image dedicated to the +RTE platform). + +To toggle the power supply use the below command: + +```bash +rte_ctrl rel +``` + +Or using [OSFV cli](https://github.com/Dasharo/osfv-scripts) from remote +machine: + +```sh +osfv_cli rte --model= --rte_ip rel tgl +``` + +### Basic power operations + +Basic power operations should be performed based on the `rte_ctrl` script +implemented in `meta-rte` (OS image dedicated to the RTE platform). To perform +basic power operations use the below-described commands: + +1. Turn on the platform: + + ```bash + rte_ctrl pon + ``` + +1. Turn off the platform: + + ```bash + rte_ctrl poff + ``` + +1. Reset the platform: + + ```bash + rte_ctrl reset + ``` + +Or using OSFV cli from remote machine: + +```sh +osfv_cli rte --model= --rte_ip pwr on +``` + +```sh +osfv_cli rte --model= --rte_ip pwr off +``` + +```sh +osfv_cli rte --model= --rte_ip pwr reset +``` + +### CMOS clear + +To clear the CMOS, turn off the power with Sonoff or relay and use the +following commands: + +```bash +echo 1 > /sys/class/gpio/gpio412/value +sleep 10 +echo 0 > /sys/class/gpio/gpio412/value +``` + +### S1 button + +S1 button is used to re-enable disabled serial console. More information about +this feature can be found in: + +* [S1 switch button properties](https://pcengines.github.io/apu2-documentation/gpios/#s1-switch-button) +* [Disable serial console and enable with S1 button](https://pcengines.github.io/apu2-documentation/theory-of-operation/#pc-engines-apu-firmware-features) + +To expose this feature to OSFV we have to add additional wire between: + +=== "APU2" + + | RTE J11 pin | PC Engines J4 pin | + |:-----------------:|:-------------------:| + | 7 | 5 (MODESW#) | + +=== "APU3/APU4/APU6" + + | RTE J11 pin | PC Engines J5 pin | + |:-----------------:|:-------------------:| + | 7 | 5 (MODESW#) | + +### USB devices + +Since some issues with USB controllers may only happen on select USB ports, +it's important to plug in USB devices to all external USB ports of the board. + +### SD card + +Insert at least 16GB SD card into platform SD card socket. + +### BIOS WP + +BIOS WP (aka SPIWP#) pin can be used to enable or disable write protection. +Feature was described in [sortbootorder +documentation](https://github.com/pcengines/sortbootorder?tab=readme-ov-file#bios-wp-option). + +=== "APU2" + + | RTE J11 pin | PC Engines J2 pin | + |:-----------------:|:-------------------:| + | 9 | 1 (SPIWP#) | + +=== "APU3/APU4/APU6" + + | RTE J11 pin | PC Engines J3 pin | + |:-----------------:|:-------------------:| + | 9 | 1 (SPIWP#) | diff --git a/mkdocs.yml b/mkdocs.yml index 7235a228eae..a4ca6da0ddf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -437,7 +437,7 @@ nav: - 'Protectli': guides/lab-assembly/protectli.md - 'Odroid H4': guides/lab-assembly/odroid-assembly-guide.md - 'NovaCustom laptops': guides/lab-assembly/novacustom.md - + - 'PC Engines': guides/lab-assembly/pcengines.md - 'Development Process': - 'Source code structure': dev-proc/source-code-structure.md - 'Dasharo Product Guidelines: SMBIOS Information': dev-proc/smbios-rules.md