Skip to content

Jcarolinares/phc usermanual additional improvements #1446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 27, 2023
Merged

Jcarolinares/phc usermanual additional improvements #1446

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
308640c
Small improvements, hello world with linux and python improved
jcarolinares Oct 26, 2023
a1bb4d1
Examples improvements, small text additions to improve user experience
jcarolinares Oct 26, 2023
e29ad5f
New grammarly check
jcarolinares Oct 26, 2023
972d026
CAN bus content update
TaddyHC Oct 26, 2023
e04da65
Content nested linter patch
TaddyHC Oct 26, 2023
f8c9f97
UART Arduino section updated
TaddyHC Oct 27, 2023
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Examples improvements, small text additions to improve user experience
  • Loading branch information
@jcarolinares
jcarolinares committed Oct 26, 2023
commit a1bb4d19c0353120adc44190c5863b7954f0d6c5
60 changes: 32 additions & 28 deletions .../hardware/04.pro/carriers/portenta-hat-carrier/tutorials/user-manual/content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -557,7 +557,7 @@ The Portenta Hat Carrier features a USB interface suitable for data logging and

![Portenta Hat Carrier USB-A Port](assets/portentaHATcarrier_USBA.png)

If you are interested in USB-A port pinout, the following table may serve to understand its connection distribution:
If you are interested in the USB-A port pinout, the following table may serve to understand its connection distribution:

| **Pin number** | **Power Net** | **Portenta HD Standard Pin** | **High-Density Pin** | **Interface** |
|:--------------:|:-------------:|:----------------------------:|:--------------------------------------------------------------------:|:-------------:|
Expand All @@ -571,49 +571,42 @@ Devices with a USB-A interface, such as storage drives, can be used for logging
#### Using Linux
<br></br>

As an example, following command on Portenta X8's shell can be used to test write command with a USB memory drive. To write a file, following sequence of commands can help you accomplish such task.
As an example, the following command on Portenta X8's shell can be used to test a write command with a USB memory drive. To write a file, the following sequence of commands can help you to accomplish such task.

```bash
dmesg -w
sudo su -
```

The `dmesg -w` command displays kernel messages, helping you monitor system events in real-time. It is particularly useful to see if it has recognized the USB drive when plugged in.
First of all let's enter in root mode to have the right permissions to mount and unmount related peripherals like our USB memory drive.

```bash
lsblk
```

The `lsblk` command lists all available block devices, such as hard drives and USB drives. It helps in identifying the device name, like `/dev/sda1` which is the partition designation, of the plugged-in USB drive.
The `lsblk` command lists all available block devices, such as hard drives and USB drives. It helps in identifying the device name, like `/dev/sda1` which is will be probably the partition designation of the USB drive you just plugged in. A common trick to identify and check the USB drive connected is to execute the `lsblk` command twice; once with the USB disconnected and the next one to the USB connected, to compare both results and spot easily the new connected USB drive. Additionally, the command `lsusb` can be used to gather more information about the connected USB drive.

```bash
mkdir -p /mnt/USBmount
```

The `mkdir -p` command creates the directory `/mnt/USBmount`. If the directory already exists, this command won't produce an error. This directory will be used as a mount point for the USB drive.
The `mkdir -p` command creates the directory `/mnt/USBmount`. This directory will be used as a mount point for the USB drive.

```bash
mount -t vfat /dev/sda1 /mnt/USBmount
```

This mount command mounts the USB drive, assumed to have a FAT filesystem (`vfat`), located at `/dev/sda1` to the directory `/mnt/USBmount`. Once mounted, the content of the USB drive can be accessed from the `/mnt/USBmount` directory.
This mount command mounts the USB drive, assumed to have a FAT filesystem (`vfat`), located at `/dev/sda1` to the directory `/mnt/USBmount`. Once mounted, the content of the USB drive can be accessed from the `/mnt/USBmount` directory with `cd`:

```bash
dd if=/dev/urandom of=/mnt/USBmount/random.bin bs=1K count=16
cd /mnt/USBmount
```

This command will create a _random.bin_ file filled with 16 Kilobytes of random data. It reads data from the system's pseudo-random number generator `/dev/urandom` and writes it to the file in chunks of 1 Kilobyte.

To read the _random.bin_ file with random data, you can use the following command:
Now if you do and `ls` you can see the actual content of the connected USB Drive.

```bash
dd if=/mnt/USBmount/random.bin bs=1K count=16 | hexdump -C
ls
```

This will read the previously generated _random.bin_ file and displays its content in a hexadecimal format on the console. Data is read in chunks of 1 Kilobyte up to 16 Kilobytes and then processed for display using `hexdump`.

***Reading the entire _random.bin_ file with the `hexdump` command will produce a large output on the console. Use with caution.***

In the Portenta X8's shell, if you aim to create a text file containing the message `Hello, World!` on a USB memory drive, you can employ the command:
Let's create a simple text file containing the message `Hello, World!` in the already connected USB memory drive using the following command:

```bash
dd if=<(echo -n "Hello, World!") of=/mnt/USBmount/helloworld.txt
Expand All @@ -626,10 +619,12 @@ Subsequently, the message gets inscribed into a file named _helloworld.txt_ situ
After creating the file, if you wish to retrieve its contents and display them on the shell, you can use:

```bash
dd if=/mnt/USBmount/helloworld.txt bs=1K count=1
cat helloworld.txt
```

This command directs `dd` to peruse the contents of _helloworld.txt_. With a specified block size of 1 Kilobyte, the reading is confined to a single block—adequate given the brevity of the `Hello, World!` message. Upon executing this command, the content of the text file will be displayed on your shell.
This command `cat` prompts in the terminal the content of a file, in this case the words `Hello, World!`.

Now that you know how to locate, mount, write and read information from an external USB stick or hard drive you can expand the possibilities of your solution with the additional storage connected to the Portenta Hat Carrier.

#### Using Arduino IDE
<br></br>
Expand Down Expand Up @@ -939,9 +934,9 @@ void loop() {

### Analog Pins

The 16-pin header connector of the Portenta Hat Carrier integrates the analog channels. The analog pins `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, and `A7` are accessible through these connectors.
The 16-pin header connector of the Portenta Hat Carrier integrates the analog channels. The analog `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6`, and `A7` are accessible through these pins.

![Portenta Hat Carrier CAN Interface](assets/portentaHATcarrier_analogIOs.png)
![Portenta Hat Carrier Analog Pins](assets/portentaHATcarrier_analogIOs.png)

| **Pin number** | **Silkscreen** | **Portenta HD Standard Pin** | **High-Density Pin** |
|:--------------:|:--------------:|:----------------------------:|:--------------------:|
Expand All @@ -966,6 +961,11 @@ Using the Portenta X8, you can obtain a voltage reading that falls within a _0 -
```
cat /sys/bus/iio/devices/iio\:device0/in_voltage<adc_pin>_raw
```
Where `<adc_pin>` is the number of the analog pin to read. For example, in the case of `A0`:

```
cat /sys/bus/iio/devices/iio\:device0/in_voltage0_raw
```

If you are working in Python®, the command can be implemented as shown in the script below:

Expand All @@ -984,6 +984,10 @@ if __name__ == "__main__":

if value is not None:
print(f"Value from ADC pin {adc_pin}: {value}")

# Mapping between 0-3.3 V
new_value = (float) (value/65535)*3.3
print(f"Value mapped between 0-3.3 V: {new_value}")
```

#### Using Arduino IDE
Expand Down Expand Up @@ -3160,11 +3164,11 @@ The CAN bus, short for Controller Area Network bus, is a resilient communication

This approach ensures system continuity even if one device fails and is especially effective in electrically noisy settings like in vehicles, where various devices need reliable communication.

The Portenta Hat Carrier is equipped with CAN bus communication capabilities, powered by the TJA1049 module - a high-speed CAN FD transceiver. With this, developers can leverage the robustness and efficiency of CAN communication in their projects.
The Portenta Hat Carrier is equipped with CAN bus communication capabilities, powered by the TJA1049 module, a high-speed CAN FD transceiver. With this, developers can leverage the robustness and efficiency of CAN communication in their projects.

![Portenta Hat Carrier CAN Bus Port](assets/portentaHATcarrier_CAN.png)

Since the CAN bus pins are integrated within the High-Density connectors, they are conveniently accessible on the carrier through the screw terminal. This provides flexibility in connection, allowing developers to design and troubleshoot their systems easierly.
Since the CAN bus pins are integrated within the High-Density connectors, they are conveniently accessible on the carrier through the screw terminal. This provides flexibility in connection, allowing developers to design and troubleshoot their systems easily.

| **Pin number** | **Silkscreen** | **High-Density Pin** | **Interface** |
|:--------------:|:--------------:|:--------------------------------------------------------------------:|:------------------:|
Expand All @@ -3178,15 +3182,15 @@ Since the CAN bus pins are integrated within the High-Density connectors, they a
#### Using Linux
<br></br>

For Portenta X8, the following instructions can help control CAN bus protocol. The CAN transceiver is enabled using following command:
For Portenta X8, the following instructions can help control CAN bus protocol. The CAN transceiver is enabled using the following command:

```
echo 164 > /sys/class/gpio/export && echo out > /sys/class/gpio/gpio164/direction && echo 0 > /sys/class/gpio/gpio164/value
```

This command sequence activates the CAN transceiver. It does so by exporting _GPIO 164_, setting its direction to "`out`", and then writing a value of "`0`" to it. Writing 0 as a value to GPIO 164 means, it will set GPIO to LOW state.
This command sequence activates the CAN transceiver. It does so by exporting _GPIO 164_, setting its direction to "`out`", and then writing a value of "`0`" to it. Writing 0 as a value to GPIO 164 means that it will set the GPIO to a LOW state.

For Portenta X8, it is possible to use following commands:
For Portenta X8, it is possible to use the following commands:

```
sudo modprobe can-dev
Expand All @@ -3199,7 +3203,7 @@ echo "can-dev" | sudo tee > /etc/modules-load.d/can-dev.conf
sudo systemctl reboot
```

Within the Portenta X8's shell, Docker containers offer a streamlined environment for specific tasks, such as command-based CAN bus operations. The _cansend_ command is one such utility that facilitates sending CAN frames. The command to issue such task is as followss:
Within the Portenta X8's shell, Docker containers offer a streamlined environment for specific tasks, such as command-based CAN bus operations. The _cansend_ command is one such utility that facilitates sending CAN frames. The command to issue such task is as follows:

```bash
cansend
Expand Down