Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 73cb387

Browse files
authored
Merge pull request #1461 from arduino/sync/taddy/hatCarrier-overlay-update
Portenta Hat Carrier: User Manual & DTB Overlay Update
2 parents de71806 + 79ab10f commit 73cb387

File tree

1 file changed

+138
-16
lines changed
  • content/hardware/04.pro/carriers/portenta-hat-carrier/tutorials/user-manual

1 file changed

+138
-16
lines changed

‎content/hardware/04.pro/carriers/portenta-hat-carrier/tutorials/user-manual/content.md‎

Lines changed: 138 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,7 @@ adb shell
278278
sudo su -
279279
```
280280

281-
When you execute the _sudo su -_ command, you will be prompted for a password:
281+
When you execute the _sudo su -_ command, you will be prompted for a password:
282282

283283
***The default password is `fio`***
284284

@@ -1806,7 +1806,16 @@ To configure the Ethernet settings, depending on the paired Portenta board, one
18061806
#### Ethernet Interface With Linux
18071807
<br></br>
18081808

1809-
Using the Portenta X8 in combination with the Hat Carrier allows you to evaluate the Ethernet speed. First, make sure the Portenta X8 is mounted on the Hat Carrier, and then connect them using a RJ45 LAN cable. To measure the bandwidth, we will use the _iperf3_ tool, which is available [here](https://github.com/userdocs/iperf3-static).
1809+
Using the Portenta X8 in combination with the Hat Carrier allows you to evaluate the Ethernet speed. First, ensure that the Portenta X8 is mounted on the Hat Carrier, and then connect them using an RJ45 LAN cable.
1810+
1811+
Subsequently, open a terminal to access the shell of the Portenta X8 with admin (root) privileges.
1812+
1813+
```bash
1814+
adb shell
1815+
sudo su -
1816+
```
1817+
1818+
When prompted, enter the password `fio`. To measure the bandwidth, we will use the _iperf3_ tool, which is available [here](https://github.com/userdocs/iperf3-static).
18101819

18111820
To use the _iperf3_ tool, we will set the Portenta X8 and Hat Carrier as the Server and the controlling computer as the Client. The commands will measure the bandwidth between the Portenta Hat Carrier with Portenta X8 and the computer. For a deeper understanding of _iperf3_, refer to its [official documentation](https://iperf.fr/iperf-doc.php).
18121821

@@ -2241,7 +2250,6 @@ For a comprehensive understanding of these connectivity options, kindly refer to
22412250
- Portenta H7 connectivity: [Wi-Fi® access point](https://docs.arduino.cc/tutorials/portenta-h7/wifi-access-point) and [BLE connectivity](https://docs.arduino.cc/tutorials/portenta-h7/ble-connectivity)
22422251
- Portenta C33 User Manual: [Wi-Fi®](https://docs.arduino.cc/tutorials/portenta-c33/user-manual#wi-fi) and [Bluetooth®](https://docs.arduino.cc/tutorials/portenta-c33/user-manual#bluetooth)
22432252

2244-
22452253
## Pins
22462254

22472255
The Portenta Hat Carrier is a versatile platform, and a significant feature of this carrier is its extensive pin availability. These pins provide a range of functionalities, including power, I/Os, communication, and more.
@@ -2327,11 +2335,30 @@ Next conditions will help you properly set the hardware to test GPIO controls:
23272335

23282336
1. Begin by positioning the Portenta-X8 securely onto the Portenta Hat Carrier. Make sure the High-Density connectors are securely connected.
23292337

2330-
2. Each GPIO on the Portenta Hat Carrier is versatile and robust, designed to safely accept input voltages ranging between 0.0 V and 3.3 V. This wide range ensures compatibility with a variety of sensors and external devices.
2338+
2. Each GPIO on the Portenta Hat Carrier is versatile and robust, designed to safely accept input voltages ranging between 0.0 V and 3.3 V. This input range ensures compatibility with an array of sensors and external devices.
23312339

23322340
3. To prevent floating states and offer a consistent and predictable behavior, internal pull-ups are automatically enabled on all input pins. This default configuration means that, unless actively driven low, the pins will naturally read as high (or 3.3 V).
23332341

2334-
When all conditions are set and in place, use the following script to read all available GPIOs on 40-Pin header:
2342+
When all conditions are set and in place, access the Portenta X8's shell with admin (root) access as follows:
2343+
2344+
```bash
2345+
adb shell
2346+
sudo su -
2347+
```
2348+
2349+
Enter the password `fio` when prompted. Next, access the `x8-devel` Docker container with the command:
2350+
2351+
```bash
2352+
docker exec -it x8-devel sh
2353+
```
2354+
2355+
Navigate to the directory containing the GPIO example, named `gpios.py`:
2356+
2357+
```bash
2358+
cd root/examples/portenta-hat-carrier
2359+
```
2360+
2361+
Run the `gpios.py` script to read the status of all available GPIOs on the 40-pin header:
23352362

23362363
```python
23372364
#!/usr/bin/env python3
@@ -2553,6 +2580,101 @@ The pins used for the JTAG debug port on the Portenta Hat Carrier are the follow
25532580
| 9 | | JTAG_TRST | J1-80 | JTAG TRST |
25542581
| 10 | | JTAG_RST | J1-73 | JTAG RST |
25552582

2583+
## Understanding Device Tree Blobs (DTB) Overlays
2584+
2585+
### Device Tree Blobs (DTB) And DTB Overlays
2586+
2587+
In the world of embedded systems, _U-boot_ and the _Linux kernel_ use a concept called __Device Tree Blobs (DTB)__ to describe a board's hardware configuration. This approach allows for a unified main source tree to be used across different board configurations, ensuring consistency.
2588+
2589+
The boards, acting as carriers, allow various peripherals to be connected, such as temperature sensors or accelerometers. These carriers serve as expansion connectors. You might want to connect various peripherals and be able to add or remove them easily.
2590+
2591+
The concept of modularity is applied to the _DTB_, resulting in __DTB overlays__. The hardware configuration is split into multiple small files, each representing a different peripheral or function in the form of a DTB overlay.
2592+
2593+
During the early boot stage, these overlays are merged together into a single DTB and loaded into RAM. This approach enables users to select and change configurations with ease. However, it is important to note that changing the hardware configuration requires a system reboot to maintain system stability.
2594+
2595+
### Handling DTB Overlays
2596+
2597+
You can modify and maintain the Device Tree Blob (DTB) overlays through a couple of methods. In builds that do not prioritize security, you can edit the file located at the following location:
2598+
2599+
```
2600+
/boot/devicetree/overlays.txt
2601+
```
2602+
2603+
After making the desired changes, it is necessary to save the changes and reboot the system to apply them.
2604+
2605+
On the other hand, in builds that prioritize security, the *fw_setenv tool* accessible in user space must be used to apply the corresponding changes to the U-boot settings as follows:
2606+
2607+
```
2608+
fw_setenv overlays=name_ov1 name_ov2
2609+
```
2610+
2611+
Currently, parameters are passed indirectly to the overlays; however, upcoming enhancements to U-boot will introduce direct parameter passing functionality.
2612+
2613+
### Custom DTB Overlays
2614+
2615+
In cases where the required DTB overlay is not readily available and a specific configuration that is not part of the pre-compiled set is needed, it is possible to create customized DTB overlays.
2616+
2617+
DTB overlays originate from readable source files known as _DTS files_. Users with the respective experience can modify these DTS files and cross-compile them to create tailored overlays suited to their needs.
2618+
2619+
### Automated Load And Carrier Detection
2620+
2621+
U-boot can be configured to automatically load specific DTB overlays based on the carrier board it detects, in this case the Portenta Hat Carrier, either by probing specific hardware or by reading an identification ID from an EEPROM.
2622+
2623+
For instance, for a Portenta-X8 placed on a Portenta HAT Carrier, upon logging into the board and executing subsequent commands on the shell, the expected output is as follows:
2624+
2625+
```bash
2626+
fw_printenv overlays
2627+
overlays=ov_som_lbee5kl1dx ov_som_x8h7 ov_carrier_rasptenta_base
2628+
2629+
fw_printenv carrier_name
2630+
carrier_name=rasptenta
2631+
2632+
fw_printenv is_on_carrier
2633+
is_on_carrier=yes
2634+
```
2635+
2636+
This information is written by U-boot during boot in a step referred to as _auto carrier detection_. You can modify the variables from user space, but after a reboot, they revert to their default state unless the `carrier_custom` variable is set to `1`.
2637+
2638+
```bash
2639+
fw_setenv carrier_custom 1
2640+
```
2641+
2642+
This serves as an escape mechanism to enable user-based configurations.
2643+
2644+
```bash
2645+
fw_setenv carrier_custom 1
2646+
fw_setenv carrier_name rasptenta
2647+
fw_setenv is_on_carrier yes
2648+
fw_setenv overlays "ov_som_lbee5kl1dx ov_som_x8h7 ov_carrier_rasptenta_base ov_carrier_rasptenta_pwm_fan ov_carrier_rasptenta_ov5647_camera_mipi ov_rasptenta_iqaudio_codec"
2649+
```
2650+
2651+
The commands above enable functionalities such as a speed-controlled fan connector, an OV5647 based RPi v1.3 camera, and an IQ Audio Codec Zero audio HAT.
2652+
2653+
### Hardware Configuration Layers
2654+
2655+
Hardware configuration is divided into the following layers:
2656+
2657+
- __Layer 0__: System on Module (SoM), prefixed with `ov_som_`.
2658+
- __Layer 1__: Carrier boards, prefixed with `ov_carrier_`.
2659+
- __Layer 2__: HATs and Cameras, which is usually a concatenation of the carrier name and the hat name or functionality.
2660+
2661+
EEPROMs, which store identification IDs, are typically defined on _Layer 1_ and accessible on _I2C1_. Some HATs may also have EEPROMs according to the Raspberry Pi® standard (*ID_SD*, *ID_SC*), accessible on _I2C0_.
2662+
2663+
There are some overlays which add specific functionalities. For example:
2664+
2665+
- `ov_som_lbee5kl1dx`: Adds Wi-Fi®
2666+
- `ov_som_x8h7`: Adds the H7 external microcontroller
2667+
- `ov_carrier_rasptenta_base`: Base support for Portenta Hat Carrier
2668+
2669+
When no known carrier is detected and the Portenta X8 is mounted as the main board, the first two overlays mentioned above are applied by default.
2670+
2671+
#### Distinction Between System And Hardware Configuration
2672+
<br></br>
2673+
2674+
The distinction between system and hardware configuration is crucial. System configuration includes settings such as user creation and Wi-Fi® passwords, whereas hardware configuration is explicitly defined through the device tree.
2675+
2676+
In production environments, the addition of custom compiled device tree overlays is restricted to maintain system integrity and security.
2677+
25562678
## Raspberry Pi® HAT
25572679

25582680
The Portenta Hat Carrier is notable for its compatibility with __Hardware Attached on Top (HAT)__ add-on boards.
@@ -2871,7 +2993,7 @@ Please, refer to the [board pinout section](#pinout) of the user manual to find
28712993
#### Using Linux
28722994
<br></br>
28732995

2874-
For Portenta X8, it is possible to use the following commands:
2996+
With admin (root) access, you can use the following commands within the shell for the Portenta X8:
28752997

28762998
```
28772999
sudo modprobe spidev
@@ -2888,7 +3010,7 @@ sudo systemctl reboot
28883010
services:
28893011
my_spi_service:
28903012
devices:
2891-
- /dev/spi-1
3013+
- '/dev/spidev0.0'
28923014
```
28933015
Following section configures a service named `my_spi_service` to use the SPI device available at `/dev/spi-1`.
28943016

@@ -2999,7 +3121,7 @@ Please, refer to the [pinout section](#pinout) of the user manual to find them o
29993121
#### Using Linux
30003122
<br></br>
30013123

3002-
For Portenta X8, it is possible to use the following commands:
3124+
For the Portenta X8, it is possible to use the following commands within the shell when you have admin (root) access:
30033125

30043126
```
30053127
sudo modprobe i2c-dev
@@ -3018,7 +3140,7 @@ Following section configures a service named `my_i2c_service` to use the I2C dev
30183140
services:
30193141
my_i2c_service:
30203142
devices:
3021-
- /dev/i2c-3
3143+
- `/dev/i2c-3`
30223144
```
30233145

30243146
Within the Portenta X8 shell, you can use specific commands to quickly test I2C communication with compatible devices. The command below lists all the connected I2C devices:
@@ -3183,7 +3305,7 @@ Since the CAN bus pins are integrated within the High-Density connectors, they a
31833305
#### Using Linux
31843306
<br></br>
31853307

3186-
For Portenta X8, the following instructions can help control CAN bus protocol. The CAN transceiver is enabled using the following command:
3308+
For the Portenta X8, when you have admin (root) access, you can execute the following commands within the shell to control the CAN bus protocol. The CAN transceiver can be enabled using the following command
31873309

31883310
```
31893311
echo 164 > /sys/class/gpio/export && echo out > /sys/class/gpio/gpio164/direction && echo 0 > /sys/class/gpio/gpio164/value
@@ -3497,14 +3619,14 @@ Please, refer to the board pinout section of the user manual to find them on the
34973619
#### Using Linux
34983620
<br></br>
34993621

3500-
Within Portenta X8, the command `ls /dev/ttyUSB* /dev/ttyACM*` can be used to list available serial ports in Linux. Typically, USB serial devices appear as _/dev/ttyUSBx_or _/dev/ttyACMx_.
3622+
For the Portenta X8, when you have admin (root) access, you can execute the command `ls /dev/ttyUSB* /dev/ttyACM* /dev/ttymxc*` within the shell to list available serial ports in Linux. Typically, USB serial devices could appear as _/dev/ttyUSBx_, _/dev/ttyACMx_, or _/dev/ttymxcx_.
35013623

35023624
```
3503-
ls /dev/ttyUSB* /dev/ttyACM*
3504-
/dev/ttymxc1 // Something similar
3625+
ls /dev/ttyUSB* /dev/ttyACM* /dev/ttymxc*
3626+
/dev/ttymxc2 // Something similar
35053627
```
35063628

3507-
The output _/dev/ttymxc1_ is an example of a potential serial device you might find on Portenta X8.
3629+
The output _/dev/ttymxc2_ is an example of a potential serial device you might find on Portenta X8.
35083630

35093631
Following Python® script uses the _pyserial_ library to communicate with devices over UART. It defines the `processData` function which prints the received data. You can modify this function based on your application's needs.
35103632

@@ -3517,7 +3639,7 @@ def processData(data):
35173639
print("Received:", data) # For now, just print the data. Modify as needed.
35183640

35193641
# Set up the serial port
3520-
ser = serial.Serial('/dev/ttymxc3', 9600) # Use the appropriate port and baud rate for your device
3642+
ser = serial.Serial('/dev/ttymxc2', 9600) # Use the appropriate port and baud rate for your device
35213643

35223644
incoming = ""
35233645

@@ -3540,7 +3662,7 @@ while True:
35403662
time.sleep(0.002) # Delay for data buffering, equivalent to Arduino's delay(2);
35413663
```
35423664

3543-
The script sets up a serial connection on port _/dev/ttymxc1_ at a baud rate of _9600_. It then continuously checks for incoming data. When a newline character (`\n`) is detected, indicating the end of a message, the script processes the accumulated data and then resets the data string to be ready for the next incoming message.
3665+
The script sets up a serial connection on port _/dev/ttymxc2_ at a baud rate of _9600_. It then continuously checks for incoming data. When a newline character (`\n`) is detected, indicating the end of a message, the script processes the accumulated data and then resets the data string to be ready for the next incoming message.
35443666

35453667
The `time.sleep(0.002)` line adds a slight delay, ensuring data has enough time to buffer, similar to using `delay(2);` in Arduino.
35463668

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /