Wiki-DB - User contributions [en]

Avenger96

2023-10-20T06:49:13Z

Pzimmermann: /* Useful instructions */ Added link to page of display calibration

'''The Avenger96 board is the official DHCOR STM32MP1 reference design!'''

{|
|
|
|-
|__TOC__
|[[Image:Avenger96Board.png|600px|COM Avenger96Board]]
|}

== Introduction ==
The AVENGER Board is a 96Boards compliant consumer edition board based on the STM32MP15 series of SoCs. The STM32MP15 series
is a highly integrated multi-market applications processor designed to enable secure and portable applications within the Internet of Things.
AVENGER board features Dual-core Arm® Cortex®-A7 processors operating at up to 650 MHz, Single core Arm® Cortex® M4 operating up to
209 MHz. In addition, an extensive set of interfaces and connectivity peripherals are included to interface to cameras, touch-screen displays,
MMC/SD cards and media processor engine. It also fully supports wireless communication, including WLAN and BLE.

== Technical Details ==
{| class="wikitable" align="center" | style="width: 100%; color: #000000; background: #f3f3f3;" valign="top" |
|-
| style="width: 50%; background: #076b8d; border: 0pt;" |
| style="width: 50%; background: #076b8d; border: 0pt;" |
|-
|valign="top" style="border: 0pt;" |
* '''STM32MP157AAC
**2x ARM® Cortex-A7 up to 650 MHz
**1x ARM® Cortex-M4 up to 209 MHz
'''
*'''GPU''' 1x 3D GPU Vivante® @ 533 MHz - OpenGL® ES 2.0
*'''PMIC''' STPMIC1A
*'''DDR3 DRAM''' 1024 Mbyte @ 533 MHz
*'''eMMC Flash''' 8 Gbyte, v4.51 interface
*'''NOR Flash''' 2 Mbyte, Quad SPI interface
*'''EEPROM''' 128 byte
*'''microSD Socket''' UHS-I speed grade, v3.01
*'''USB Host''' 2x type A, 2.0 high-speed
*'''USB OTG''' 1x type micro-AB, 2.0 high-speed
*'''HDMI''' WXGA (1366x768) @ 60 fps, HDMI 1.4
*'''WiFi / Bluetooth'''
**WiFi 5 GHz & 2.4GHz IEEE 802.11a / b / g / n / ac
**Bluetooth® v4.2 (BR/EDR/BLE)
**PCB antenna
*'''Ethernet''' 10 / 100 / 1000 Mbit/s, IEEE 802.3-compliant
|valign="top" style="border: 0pt;" |
*'''Push-Buttons''' Power and reset
*'''Battery Socket''' CR1216, CR1220 and CR1225
*'''LEDs'''
**4x green user controlled LEDs
**1x blue Bluetooth enabled
**1x yellow WiFi enabled
**1x red power supply okay
*'''Boot Mode''' 3 bit boot mode switch
*'''Debug Interface''' JTAG interface via tag-connect
*'''Supply (SYS_DCIN)''' 8 - 18 VDC
*'''Temperature Range''' 0 - 40 °C
*'''Dimensions ''' 100 x 85 mm
*'''Expansion Connectors'''
**2 x UART
**2 x I2C
**1 x I2S
**1 x SPI
**12 x GPIOs (also useable as 2x CAN, 2x ADC)
**1 x MIPI-CSI2
**1 x MIPI-DSI
|}

== Product Change Notifications (PCN) ==
==== DHCOR STM32MP15====
* [[media:PCN_DHCOR-STM32MP1-001_R01_2022-10-07.pdf|PCN_DHCOR-STM32MP1-001_R01_2022-10-07.pdf (New default bootloader, based on testbench configuration)]]

== Downloads ==
* [https://github.com/dh-electronics/kas-dhsom/releases/tag/2023-08-28 DH Mainline based starter image 2023-09-20 (based on 6.1.54 Linux Kernel)]

== Documentation ==
* [[media:DOC_Getting-Started-588-200_R04_2023-09-19.pdf|Getting-Started with Avenger96 (R04)]]
* [[media:USM_DHCOR-STM32MP1_R05_2019-12-12.pdf|DHCOR STM32MP1 User Manual R05 <span style="color:#FF0000">'''IMPORTANT: Please have a look at NEW chapter 24. Hardware design checklist'''</span>]]
* More about the STM32 MPU is on the [[Avenger96#Links | Links section]]

== Design Files ==
* [[media:SCH_588-200-HS00008-public_R07_2019-08-01.pdf|Avenger96 Schematic]]
* [[media:BOM_588-200-HS00008-public_R07_2019-08-01.xlsx|Avenger96 Bill of Material]]
* [[media:588-200_TOP_ASSEMBLY__R04_2019-04-12.pdf|Avenger96 Assembly Top]]
* [[media:588-200_BOTTOM_ASSEMBLY__R04_2019-04-12.pdf|Avenger96 Assembly Bottom]]
* [[media:BRD_588-200-with-DHCOR_2020-06-22.STEP|Avenger96 3D STEP file]]
* [[media:DHCOR-STM32MP1-Design-Symbols_2019-10-16.zip|DHCOR STM32MP1 Allegro/Orcad schematic and layout symbols (release date: 16.10.2019) '''Now with Allegro *.brd file and 3D information''']]
* [[media:DHCOR_STM32MP1_3D_STEP_586-100_R02.zip|DHCOR STM32MP1 3D STEP file]]
* [[media:Stm32mp15xx-dhcor-avenger96_2023-04-18.zip | Avenger96 CubeMX configuration (release date: 18.04.2023)]]

== Software ==
=== DH Mainline based Linux ===
* [https://github.com/dh-electronics/kas-dhsom Build your own Yocto Kirkstone LTS via kas (GitHub)]
* [https://github.com/dh-electronics/meta-dhsom-stm32-bsp Yocto BSP meta layer (Github)]
* [[Default Bootloader "stm32mp15xx-dhcor-testbench" | Default Bootloader "stm32mp15xx-dhcor-testbench" programmed with delivered DHCOR module]]
* [[DHCOR_STM32MP1_Linux| Linux and bootloader documentation]]
:<span style="color:#008000">'''NEW How to start with custom DHCOR design?'''</span>
:The patch below is an example patch which applies on top of u-boot v2021.01 and implements a custom board derived from 3V3 option of DHCOR STM32MP1 SoM. That's pretty much all you have to change to implement the board. But, please tweak the DTs esp. where there are the FIXME comments.
:[[media:0001-ARM-dts-stm32-Add-DHCOR-based-FOO-board-u-boot-v2021.01.patch|'''NEW''' 0001-ARM-dts-stm32-Add-DHCOR-based-FOO-board-u-boot-v2021.01.patch]]
* [[Add Yocto SDK with QT5 to QT Creator | Start with Qt]]
* [[Debugging_M4_on_STM32MP15xxxx|STM32MP1: Debugging M4]]
* [https://wiki.dh-electronics.com/index.php/STM32MP1_Browser_Performance STM32MP1 Browser Performance]
* [[DHSOM device tree structure | DHSOM device tree structure]]

=== OpenSTLinux ===
: <span style="color:#FF0000"> '''This project is NOT maintained from DH electronics!!! Please use the "DH Mainline based Linux" version for your project. The OpenSTLinux should only be used for testing!!!'''</span>
* '''Info:'''
:- Based on OpenSTLinux v3.0
:- GPU support based on original vivante GPU driver.
:- Based on kernel 5.10.x and Yocto version dunfell
* [https://github.com/dh-electronics/manifest-av96 Yocto meta layer (Github)]
:DH electronics Github contains the meta-av96 layer for ST SDK. Please see readme.txt which describes the build process.

* [[media:Avenger96_v7.0_2021-10-29.img.zip|OpenSTLinux-3.0 based on Yocto Dunfell LTS and Linux 5.10.10 - v7.0 Starter Image]] (Supported by Arrow Electronics)
:[[Starter Image Changelog]]
: This Image includes four different bootmodes to support some additional mezzanine boars. [https://wiki.dh-electronics.com/index.php/Starter_Image_Bootmode Click here to learn, how to change them.]

:'''X-LINUX-AI OpenSTLinux Expansion Package:''' Description: Expansion Package that targets artificial intelligence for STM32MP1 Series devices.
* [https://wiki.st.com/stm32mpu/wiki/X-LINUX-AI_OpenSTLinux_Expansion_Package '''NEW''' X-LINUX-AI OpenSTLinux Expansion Package]
* [https://wiki.st.com/stm32mpu/wiki/How_to_install_X-LINUX-AI_v2.0.0_on_Avenger96_board '''NEW''' How to install X-LINUX-AI v2.0.0 on Avenger96 board]

== Useful instructions ==
==== How to test OV5640 camera ====
To use the D3 mezzanine board with AV96 and the OV5640 camera, one has to apply the correct DTO first:
STM32MP> setenv loaddtos '#conf-stm32mp157a-avenger96.dtb#conf-stm32mp15xx-avenger96-overlay-ov5640-x7.dtbo'; boot

Afterward it is possible to stream frames from the camera:
$ XDG_RUNTIME_DIR=/var/run/user/$(id -u weston)/ gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=1280,height=720 ! queue ! waylandsink

==== How to load U-Boot with dfu-util ====
*[[U-Boot recovery for STM32MP1 DHSOM via DFU |U-Boot recovery for STM32MP1 DHSOM via DFU]]

==== SPI Flash and eMMC Image Programming via UMS (universal mass storage) ====
*[[Avenger96 UMS Image Programming | Avenger96 UMS Image Programming]]

==== SPI Flash and eMMC Image Programming via Cube Programmer (OLD) ====
*[[Avenger96 Image Programming | Avenger96 Image Programming]]

==== How to calibrate resistive touchscreens ====
*[[Calibration of resistive touchscreens]]

== Mezzanine Boards by DH electronics ==

==== DSI Display Adaptor Board ====
You can easily add an DSI display to your Avenger96 with the help of the DSI Display Adaptor Board.
The display can be activated easily on our Mainline Image with a device tree overlay as described [[DHCOR_STM32MP1_Linux| here]].
To get one of the boards, simply reach out to us and we'll prepare one for you.

[[File:DSI Display Adaptor Board.jpg|400px|DSI Display Adaptor Board]]

== Links ==
* [https://wiki.st.com/stm32mpu/wiki/Main_Page STM32 MPU wiki]
* [https://wiki.st.com/stm32mpu/wiki/Category:Device_tree_configuration STM32 MPU wiki - Device tree configuration]
* [https://wiki.st.com/stm32mpu/index.php/STM32MP15_resources STM32MP15 resources]
* [https://www.96boards.org 96Boards]

COM iMX6 Linux

2023-10-20T06:45:49Z

Pzimmermann: Added Subpage for calibration of resistive touchscreens

== Storage Layout ==
<br/>
::[[Image:DHCM_Boot_Storage_imx6.jpg|500px|DHCOM Boot Storage i.MX6]]
<br/>
:[[Image:DHCM_Storage_Layout_imx6.jpg|1000px|DHCOM Storage Layout i.MX6]]

== Linux virtual machine for development ==
:* Please have a look at: '''[[Virtual Machine for Application Development]]'''

== Linux Kernel ==
=== Sources: Look at page [[DHCOM iMX6-D2#BSP Sources|i.MX6 BSP Sources]] ===

=== How to build a Kernel ===
{| class="wikitable" align="center" | style="width: 98%; background: #f3f3f3;" valign="top" |
|
Get sources from Github
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
1. Start the Console on Linux<br/>
2. <tt>''git clone https://github.com/dh-electronics/linux-imx6qdl.git --branch dev/4.4.60_dhcom''</tt><br/>
3. <tt>''cd linux-imx6qdl''</tt>
|}
Configure and build the Device Tree + Kernel
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
4. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make imx6_dhcom_defconfig''</tt><br/>
5. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make menuconfig''</tt> (optional: If you want to add/remove Kernel features)<br/>
6. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make dtbs''</tt><br/>
7. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-linaro-4.9-2014.11-x86_64_arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make zImage</tt>
|}
*The built <font size=5><tt>imx6<font color="#B8A71A">x</font>-dhcom<font color="#0000FF">#</font><font color="#0EC3C1">Y</font>-<font color="#C90646">BOARD</font>.dtb</tt></font> devicetree files are available in <tt>arch/arm/boot/dts</tt>
**<font color="#B8A71A">x = s, dl, d, q</font>
**<font color="#0000FF"># = 2 for HW200, 3 for HW300, 4 for HW400</font>
**<font color="#0EC3C1">Y = B for Base, H for Hi-Speed-Interfaces</font>
**<font color="#C90646">BOARD = pdk1, pdk2, ...</font>
*The built <tt>zImage</tt> kernel file will you find in <tt>arch/arm/boot</tt>
|}

=== Update the Kernel and Device Tree with U-Boot ===
:Please refere to the [[DHCOM Update Mechanism|DHCOM Update Mechanism for i.MX6]].

=== Update Kernel and Device Tree on a running Linux ===
{| class="wikitable" align="center" | style="width: 98%; background: #f3f3f3;" valign="top" |
|
==== Kernel ====
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
'''1.''' Copy the kernel '''zImage''' file to the path '''/boot''' (You can rename it after the Kernel version '''zImage_X.Y.Z''')<br/>
'''2.''' Check '''zImage_file''' variable in '''/boot/uLinuxEnv.txt''' (e.g. <tt>'''zImage_file=zImage_4.4.60'''</tt>)<br/>
|}
==== Device Tree ====
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
'''3.''' Copy the Device Tree '''*.dtb''' file to the path '''/boot/dtbs_X.Y.Z'''<br/>
'''4.''' Check '''fdt_file''' variable in '''/boot/uLinuxEnv.txt''' (e.g. <tt>'''fdtfile=/dtbs_4.4.60/imx6dl-dhcom4B-pdk2.dtb'''</tt>) <br/>
|}
==== Reboot System ====
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
'''5.''' Restart the system (e.g. <tt>'''reboot'''</tt>)
|}
|}

=== Make your own Device Tree for your board ===
:The recommended proceeding for making your our Device Tree should be the following:

:1. Clone the DH Device Tree Board file and change it to fit for your board
::- Based on i.MX6 and PDK1 (works with i.MX6 HW200)
:::<code>imx6qdl-dh_pdk1.dtsi --> imx6qdl-COMPANY_BOARDNAME.dtsi</code>
::- Based on i.MX6 and PDK2 (works with i.MX6 HW300)
:::<code>imx6qdl-dh_pdk2.dtsi --> imx6qdl-COMPANY_BOARDNAME.dtsi</code>

:2. Clone the main Device Tree file and change the included boad file to yours
:: E.g. based on i.MX6DL HW300 with PDK2
:::<code>imx6dl-dhcom3B-pdk2.dts --> imx6dl-dhcom3B-BOARDNAME.dts</code>

:3. Add your new main Device Tree file to <code>Makefile</code> (located in the same folder)
<br/>
:'''DH Device Tree pattern (Kernel 4.4.x)''':
:[[Image:DHCM_Device_Tree_pattern.jpg|1200px|DHCOM Device Tree pattern]]

== Rootfilesystem ==

=== Available Rootfilesystems ===
:Please have a look at the [[DHCOM_iMX6-D2#Download binaries/images | iMX6 Images]] section.

=== Login ===
:{| class="wikitable" align="center" | style="width: 400px; color: #000000; background: #FFFFFF;" valign="top" |
||
<tt>
dhcom login: '''root'''<br/>
Password: '''foo'''
</tt>
|}

=== Reboot ===
:{| class="wikitable" align="center" | style="width: 400px; color: #000000; background: #FFFFFF;" valign="top" |
|<tt># reboot</tt>
|}
:or
:{| class="wikitable" align="center" | style="width: 400px; color: #000000; background: #FFFFFF;" valign="top" |
|<tt># shutdown -r now</tt>
|}

=== Shutdown ===
:{| class="wikitable" align="center" | style="width: 400px; color: #000000; background: #FFFFFF;" valign="top" |
|<tt># poweroff</tt>
|}
:or
:{| class="wikitable" align="center" | style="width: 400px; color: #000000; background: #FFFFFF;" valign="top" |
|<tt># shutdown -h now</tt>
|}
:Note: If the watchdog is active, the system will be reset.

=== Calibrating the touchscreen (only on Debian 6.0) ===
:{| class="wikitable" align="center" | style="width: 400px; color: #000000; background: #FFFFFF;" valign="top" |
|<tt># ts_calibrate</tt>
|}
:Check the enviroment variable "TSLIB_TSDEVICE=/dev/input/event0" with <tt> printenv </tt> if an error occurs.

=== How to calibrate resistive touchscreens (only on Yocto images) ===
{{:Calibration of resistive touchscreens}}

== Kernel Userspace Interfaces to Access Hardware ==

=== Ethernet Interfaces ===
:{| class="wikitable" style="width: 400px"
||DHCOM ENET 1||<tt>ethsom0</tt>
|-
||DHCOM ENET 2||<tt>ethsom1</tt>
|}

=== Serial (UART) Interfaces ===
:{| class="wikitable" style="width: 400px"
||DHCOM (FF) UART 1||<tt>/dev/ttymxc0</tt>
|-
||DHCOM (BT) UART 2 ||<tt>/dev/ttymxc4</tt>
|-
||DHCOM (STD) UART 3 ||<tt>/dev/ttymxc3</tt>
|}

=== I2C Interfaces ===
:Hardware revision '''300''' and '''newer''' (dhcom3.., dhcom4.., ...)
:{| class="wikitable" style="width: 400px"
||DHCOM I2C 1||<tt>/dev/i2c-1</tt>
|-
||DHCOM I2C 2 ||<tt>/dev/i2c-0</tt>
|-
||On Module Devices ||<tt>/dev/i2c-2</tt>
|}

:Hardware revision '''100 / 200''' (dhcom1.. / dhcom2..)
:{| class="wikitable" style="width: 400px"
||DHCOM I2C 1||<tt>/dev/i2c-0</tt>
|-
||DHCOM I2C 2 ||<tt>/dev/i2c-1</tt>
|-
||On Module Devices ||<tt>/dev/i2c-2</tt>
|}

=== SPI Interfaces ===
:{| class="wikitable" style="width: 400px"
||<b>Device</b>||<b>Kernel <= 5.4.xxx</b>||<b>Kernel >= 5.10.xxx</b>
|-
||DHCOM SPI 1||<tt>/dev/spidev0.2</tt>||<tt>/dev/spidev0.1</tt>
|-
||DHCOM SPI 2 ||<tt>/dev/spidev1.0</tt>||<tt>/dev/spidev1.0</tt>
|}

:: '''Remark:''' DHCOM SPI1 interface doesn‘t work with DHCOM Premium Developer Kit (HD00013).
::Reason: At DHCOM Premium Developer Kit SPI 1 isn‘t connected, because otherwise i.MX6 doesn‘t boot with the current schematic.

=== MMC/SD/eMMC Interfaces ===
:{| class="wikitable" style="width: 400px"
||DHCOM SD-Interface ||<tt>/dev/mmcblk0pX</tt>
|-
||on module µSD Card ||<tt>/dev/mmcblk1pX</tt>
|-
||on module eMMC ||<tt>/dev/mmcblk2pX</tt>
|}

: 'X' has to be replaced with the partition number

=== Control the display brightness ===
:Set brightness level (X = 0...10)
:{| class="wikitable"
|<tt>''echo X >/sys/class/backlight/display/brightness''</tt>
|}

=== Control GPIOs ===
:See which gpio is already used by the system
:{| class="wikitable"
|<tt>''cat /sys/kernel/debug/gpio | grep -v "gpio-... ( "''</tt> <br>or<br> <tt>''gpioinfo | grep -v unnamed''</tt>
|}

:{|class="wikitable" style="text-align: center; width: 1000px"
|-
! DHCOM Name: !! alt. DHCOM Name: !! SO-DIMM Pin# !! CPU Pad Name !! Linux <GPIO#> * !! gpiod label (deprecated): !! gpiod label:
|-
| GPIO A || || 154 || PAD_GPIO_2 || 2 || A || DHCOM-A
|-
| GPIO B || || 156 || PAD_GPIO_4 || 4 || B || DHCOM-B
|-
| GPIO C || || 162 || PAD_GPIO_5 || 5 || C || DHCOM-C
|-
| GPIO D || || 163 || PAD_CSI0_DAT17 || 163 || D || DHCOM-D
|-
| GPIO E || || 164 || PAD_GPIO_19 || 101 || E || DHCOM-E
|-
| GPIO F || || 165 || PAD_DI0_PIN4 || 116 || F || DHCOM-F
|-
| GPIO G || || 167 || PAD_EIM_D27 || 91 || G || DHCOM-G
|-
| GPIO H || || 173 || PAD_KEY_ROW0 || 103 || H || DHCOM-H
|-
| GPIO I || || 175 || PAD_KEY_COL1 || 104 || I || DHCOM-I
|-
| GPIO J || CIF HSYNC || 74 || PAD_NANDF_CS1 || 174 || J || DHCOM-J
|-
| GPIO K || CIF PCLK || 72 || PAD_NANDF_CS2 || 175 || K || DHCOM-K
|-
| GPIO L || CIF MCLK || 70 || PAD_KEY_ROW1 || 105 || L || DHCOM-L
|-
| GPIO M || CIF VSYNC || 68 || PAD_SD3_DAT5 || 192 || M || DHCOM-M
|-
| GPIO N || CIF D9 || 66 || PAD_SD3_DAT4 || 193 || N || DHCOM-N
|-
| GPIO O || CIF D8 || 64 || PAD_CSI0_VSYNC || 149 || O || DHCOM-O
|-
| GPIO P || CIF D7 || 62 || PAD_GPIO_18 || 205 || P || DHCOM-P
|-
| GPIO Q || CIF D6 || 60 || PAD_SD1_CMD || 18 || Q || DHCOM-Q
|-
| GPIO R || CIF D5 || 58 || PAD_SD1_DAT0 || 16 || R || DHCOM-R
|-
| GPIO S || CIF D4 || 56 || PAD_SD1_DAT1 || 17 || S || DHCOM-S
|-
| GPIO T || CIF D3 || 54 || PAD_SD1_DAT2 || 19 || T || DHCOM-T
|-
| GPIO U || CIF D2 || 52 || PAD_SD1_CLK || 20 || U || DHCOM-U
|-
| GPIO V || CIF D1 || 50 || PAD_CSI0_PIXCLK || 146 || V || DHCOM-V
|-
| GPIO W || CIF D0 || 48 || PAD_CSI0_MCLK || 147 || W || DHCOM-W
|-
| INT HIGHEST PRIORITY || || 151 || PAD_KEY_COL0|| 102 || INT || DHCOM-INT
|}
:: * = Valid if you didn't change the CONFIG_ARCH_NR_GPIO value in kernel config '''AND''' if your kernel doesn't probe another GPIO controller before the imx6 GPIO controller
:: '''Remark:''' Depending on your board configuration some of the additional gpios shared with the camera interface are not available on your system.

:'''GPIO pin configuration'''
:: The default Linux Device Tree pin configurarion of the DHCOM GPIOs A - W is <code>0x400120b0</code>
::{| class="wikitable"
|
Pad Mux Register (0x020E_xxxx) = 0x0000_0015
SION: 1 Enabled (Force input path of pad)
MUX_MODE: 0101 ALT5

Pad Control Register (0x020E_xxxx) = 0x0001_20B0
HYS: 1 Hysteresis enabled (Schmitt trigger input)
==============
PUS: 00 100k Pull Down
PUE: 1 PULL (Pull enabled)
PKE: 0 Disable (Pull/Keeper disabled)
ODE: 0 Disable (Output is CMOS)
RESERVED: 000
--------------
SPEED: 10 imx6: 100MHz (medium)
imx6ull: 100MHz (medium)
DSE: 110 Drive strength imx6: 40 Ohm
imx6ull: 43 Ohm @ 3.3V
RESERVED 00
SRE: 0 SLOW (Slow Slew Rate)
|}

:'''Controlled by gpiod tools (need Kernel v4.7 or higher)'''
::Set state
::{| class="wikitable"
|<tt>''gpioset $(gpiofind GPIO_LABEL)=0''</tt>
|-
|<tt>''gpioset $(gpiofind GPIO_LABEL)=1''</tt>
|}

::Get state
::{| class="wikitable"
|<tt>''gpioget $(gpiofind GPIO_LABEL)''</tt>
|-
|<tt>''gpioget $(gpiofind GPIO_LABEL)''</tt>
|}
:: '''Remark:''' GPIO_LABEL could be DHCOM-A, DHCOM-B, DHCOM-C, ... see table above

:'''Controlled by sysfs (since Kernel v4.8 deprecated)'''
::Export
::{| class="wikitable"
|<tt>''echo <GPIO#> >/sys/class/gpio/export''</tt>
|}
:: '''Remark:''' Have a look into <tt> /sys/class/gpio/ </tt> for already configured gpios.
::Set direction
::{| class="wikitable"
|<tt>''echo in >/sys/class/gpio/gpio<GPIO#>/direction''</tt>
|-
|<tt>''echo out >/sys/class/gpio/gpio<GPIO#>/direction''</tt>
|}

::Set state
::{| class="wikitable"
|<tt>''echo 0 >/sys/class/gpio/gpio<GPIO#>/value''</tt>
|-
|<tt>''echo 1 >/sys/class/gpio/gpio<GPIO#>/value''</tt>
|}

::Get state
::{| class="wikitable"
|<tt>''cat /sys/class/gpio/gpio<GPIO#>/value''</tt>
|}

=== Initialize and Test CAN Interface ===
:Initialize:
:{| class="wikitable"
|<tt>''ip link set can0 up type can bitrate 500000''</tt>
|}

:Send test message via cansend (part of can-utils):
:{| class="wikitable"
|<tt>''cansend can0 100#11.2233.44556677.88''</tt>
|}

:Receive can messages (part of can-utils):
:{| class="wikitable"
|<tt>''candump can0''</tt>
|}

:Get can-utils:
:{| class="wikitable"
|<tt>''apt-get install can-utils''</tt>
|}

=== Parallel Address- / Databus ===

:To use the 16-bit address / databus from Linux userspace you can use the UIO driver interface. To enable and configure the interface it is necessary to setup the WEIM controller with the device tree. See the documentation of the device tree bindings of weim [https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/Documentation/devicetree/bindings/bus/imx-weim.txt here].

:Here is an example code which demonstrates how to do enable and configure the WEIM interface (parallel address- / databus):
:{|
|<tt>
&weim {
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_dhcom_weim &pinctrl_dhcom_weim_cs0 &pinctrl_dhcom_weim_cs1>;
#address-cells = <2>;
#size-cells = <1>;
/* it is necessary to setup 2x 64MB otherwise setting gpr fails */
ranges = <0 0 0x08000000 0x04000000>, // Chip select 0 == DHCOM CS A
<1 0 0x0c000000 0x04000000>; // Chip select 1 == DHCOM CS B
fsl,weim-cs-gpr = <&gpr>;
status = "okay";

uiomap_cs0@0,0 {
compatible = "generic-uio";
reg = <0 0x00000000 0x04000000>;
reg-names = "uio_cs0";
interrupt-parent = <&gpio1>;
interrupts = <2 2>; // Add gpio A == interrupt
#address-cells = <1>;
#size-cells = <1>;
fsl,weim-cs-timing = <0x00610089 0x00001002 0x0F011061
0x00000000 0x0F068A31 0x00000000>;
status = "okay";
};

uiomap_cs1@0,1 {
compatible = "generic-uio";
reg = <1 0x00000000 0x04000000>;
reg-names = "uio_cs1";
interrupt-parent = <&gpio1>;
interrupts = <4 2>; // Add gpio B == interrupt
#address-cells = <1>;
#size-cells = <1>;
fsl,weim-cs-timing = <0x00610089 0x00001002 0x0F011061
0x00000000 0x0F068A31 0x00000000>;
status = "disabled";
};
};
</tt>
|}
: We have already written some demo code at [https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/arch/arm/boot/dts/imx6qdl-dhcom_cfg-weim.dtsi /arch/arm/boot/dts/imx6qdl-dhcom_cfg-weim.dtsi]. It is easy to enable in the matching device-tree file:
::*[https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/arch/arm/boot/dts/imx6s-dhcom3B-pdk2.dts /arch/arm/boot/dts/imx6s-dhcom3B-pdk2.dts]
::*[https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/arch/arm/boot/dts/imx6dl-dhcom3B-pdk2.dts /arch/arm/boot/dts/imx6dl-dhcom3B-pdk2.dts]
::*[https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/arch/arm/boot/dts/imx6d-dhcom3B-pdk2.dts /arch/arm/boot/dts/imx6d-dhcom3B-pdk2.dts]
::*[https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/arch/arm/boot/dts/imx6q-dhcom3B-pdk2.dts /arch/arm/boot/dts/imx6q-dhcom3B-pdk2.dts]
:{|
| <tt>
<font color="#FF1010">- // #include "imx6qdl-dhcom_cfg-weim.dtsi</font>
<font color="#00FF10">+ #include "imx6qdl-dhcom_cfg-weim.dtsi </font>
</tt>
|}

:To use the generic uio driver it has to be enabled in the kernel configuration (<code>[[#Linux Kernel|make menuconfig]]</code>)
::*Device Drivers -> Userspace I/O Drivers -> Userspace I/O platform driver with generic IRQ handling
: The device-tree of_id of the uio driver has to be set via kernel command line
::*Add "optargs='uio_pdrv_genirq.of_id=generic-uio'" to uLinuxEnv.txt

:Example for a UIO userspace driver:
:* [[media:uio_access.zip| uio_access.cpp]]
:* for further information have a look at the paper [https://www.osadl.org/fileadmin/dam/rtlws/12/Koch.pdf Userspace I/O drivers in a realtime context]

=== Configure your own display ===

:To configure your own display you have to do the following steps:

:1. Configure your display and build a settings file by our tool DHCOMSettingsGenerator ([[media:DHCOMSettingsGeneratorV2_V2.0.0.2.zip|Download v2.0.0.2]])

:2. Place generated file into the first partition (label: "boot")

:3. Create a symbolic link to the file settings.bin ($ ln -s YourSettingsFile.bin settings.bin)

:Remake: It is still possible to config the display via Device Tree e.g. <code>[https://github.com/dh-electronics/linux-imx6qdl/blob/dev/4.4.60_dhcom/arch/arm/boot/dts/imx6qdl-dh_pdk2.dtsi dev/4.4.60_dhcom/arch/arm/boot/dts/imx6qdl-dh_pdk2.dtsi]</code> (not recommended by DH)
<br/>
:'''The following picture showing the sequence and priorities:'''
:[[Image:DHCM_Display_Settings.jpg|1300px|DHCOM Display Settings]]
<br/>
For detailed description of the '''display boot args''' please have a look at [[DHCOM iMX6 Bootloader U-Boot#Display and Hardware settings|Display and Hardware settings]] of the iMX6 Bootloader.

== Additional Information ==
:*[[Linux Kernel Features | Linux Kernel Features ]]
:*[[ELBE Overview| Embedded Linux Build Environment (ELBE)]]

DHCOM STM32MP1 Linux

2023-10-20T06:40:51Z

Pzimmermann: Added Subpage for calibration of resistive touchscreens

== Linux virtual machine for development ==
:* Please have a look at: '''[[Virtual Machine for Application Development]]'''

== Linux Kernel ==



=== How to build a Kernel ===
{| class="wikitable" align="center" | style="width: 98%; background: #f3f3f3;" valign="top" |
|
Get sources from Github
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
1. Start the Console on Linux<br/>
2. <tt>''git clone https://github.com/dh-electronics/linux-stm32mp1.git --branch dev/5.4.69_dhsom''</tt><br/>
3. <tt>''cd linux-stm32mp1''</tt>
|}
Configure and build the Device Tree + Kernel
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
4. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make stm32mp1_dhsom_defconfig''</tt><br/>
5. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make menuconfig''</tt> (optional: If you want to add/remove Kernel features)<br/>
6. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make dtbs''</tt><br/>
7. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make zImage</tt>
|}
Create the FIT-image with our script ([[media:Dh-create-fitimage_1.0_all.deb|Download link]])
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|-
| '''Interactive mode for selecting device trees'''
| '''Device trees are set as parameter'''
|-
|
8. <tt>''create_fitimage''</tt><br/>
Enter the numbers (space seperated) of the device trees to include (e.g. if you want to include the device tree for the PDK2 include the number of <tt>''./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb''</tt> (usually 3).<br/>
Enter the numbers (space seperated) of the device trees overlays to include (e.g. for the PDK2 enter the files which contain <tt>''PDK2''</tt> (usually 8 9 10 11 12 13 14).
|
(Example is for the PDK2) <br>
8. <tt>''create_fitimage --dtb ./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2.dtb --dtbo ./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-460-200-x11.dtbo,./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-497-200-x12.dtbo,./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-505-200-x12-ch101olhlwh.dtbo,./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-531-100-x21.dtbo,./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-531-100-x22.dtbo,./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-560-200-x12.dtbo,./arch/arm/boot/dts/stm32mp157c-dhcom-pdk2-overlay-638-100-x12-rpi7inch.dtbo''</tt>
|}
|}

=== DHSOM device tree structure ===
DHCOM and PDK2
--------------
* stm32mp15xx-dhcom-som.dtsi [1] -------------------------.
[ STM32MP15xx based DHCOM SoM DT, common for all ] |
[ variants of the SoC populated on the SoM. ] +--.
| |
* stm32mp15xx-dhcom-pdk2.dtsi -----------------------------' |
[ STM32MP15xx based DHCOM PDK2 carrier board DT, ] |
[ common for all of the PDK2 and SoM combinations. ] |
|
* stm32mp157c-dhcom-pdk2.dts <-----------------------------'
[ STM32MP157C based DHCOM SoM populated on PDK2 ] :
[ carrier board combined DT. This DT describes ] :
[ specific combination of SoM populated on PDK2 ] :
[ carrier board. ] :
:
:
Both common SoM and PDK2 DTs can be extended by DTOs :
.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - '
: DTOs add additional bindings into base DTs at runtime.
:
:
* stm32mp15xx-dhcom-pdk2-overlay-460-200-x11.dts
: [ DH 460-200 FMC2 SRAM expansion card inserted into header X11. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-497-200-x12.dts
: [ DH 497-200 7" 800x480 DPI TFT LCD and resistive touchscreen ]
: [ expansion card inserted into header X12. ]
: [ This DT uses common DPI panel base DT, see [2]. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-505-200-x12-ch101olhlwh.dts
: [ DH 505-200 10" 1280x800 LVDS TFT LCD and capacitive ]
: [ touchscreen expansion card inserted into header X12. ]
: [ The panel interface is LVDS, connected to SoC via DPI-to-LVDS ]
: [ bridge chip OnSemi FIN3385. ]
: [ This DT uses common CH101 panel base DT, see [3]. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-560-200-x12.dts
: [ DH 560-200 7" 800x480 DPI TFT LCD and capacitive touchscreen ]
: [expansion card inserted into header X12. ]
: [ This DT uses common DPI panel base DT, see [2]. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-638-100-x12-rpi7inch.dts
: [ DH 638-100 adapter card connected to 7" 800x480 DSI TFT LCD and ]
: [ capacitive touchscreen module, and inserted into header X12. ]
: [ The panel interface is DPI, connected to SoC via DSI-to-DPI ]
: [ bridge chip Toshiba TC358762. ]
: [ This DT uses common DPI panel base DT, see [2]. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-672-100-x18.dts
: [ DH 672-100 CAN transceiver chip expansion board inserted into ]
: [ header X18. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-531-100-x21.dts
: [ DH 531-100 I2C and SPI EEPROM expansion board inserted into ]
: [ header X21. ]
:
* stm32mp15xx-dhcom-pdk2-overlay-531-100-x22.dts
[ DH 531-100 I2C and SPI EEPROM expansion board inserted into ]
[ header X22. ]

DHCOM and PicoITX
-----------------
* stm32mp15xx-dhcom-som.dtsi -----------------------------.
[ STM32MP15xx based DHCOM SoM DT, see also [1] above.] |
+----.
| |
* stm32mp15xx-dhcom-picoitx.dtsi --------------------------' |
[ STM32MP15xx based DHCOM PicoITX carrier board DT, ] |
[ common for all of the PicoITX and SoM combinations.] |
|
* stm32mp157c-dhcom-picoitx.dts <----------------------------'
[ STM32MP157C based DHCOM SoM populated on PicoITX ] :
[ carrier board combined DT. This DT describes ] :
[ specific combination of SoM populated on PicoITX ] :
[ carrier board. ] :
:
:
Both common SoM and PicoITX DTs can be extended by DTOs :
.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - '
: DTOs add additional bindings into base DTs at runtime.
:
:
* stm32mp15xx-dhcom-picoitx-overlay-548-200-x2-mi0700s4t-6.dts
: [ DH 548-200 7" 800x480 DPI TFT LCD and resistive touchscreen ]
: [ expansion card inserted into header X2. ]
:
* stm32mp15xx-dhcom-picoitx-overlay-626-100-x2-ch101olhlwh.dts
[ DH 626-100 10" 1280x800 LVDS TFT LCD and capacitive ]
[ touchscreen expansion card inserted into header X2. ]
[ The panel interface is LVDS, connected to SoC via DPI-to-LVDS ]
[ bridge chip OnSemi FIN3385. ]
[ This DT uses common CH101 panel base DT, see [3]. ]

DHCOM and DRC02
---------------
* stm32mp15xx-dhcom-som.dtsi -----------------------------.
[ STM32MP15xx based DHCOM SoM DT, see also [1] above.] |
+--.
| |
* stm32mp15xx-dhcom-picoitx.dtsi --------------------------' |
[ STM32MP15xx based DHCOM DRC02 carrier board DT, ] |
[ common for all of the DRC02 and SoM combinations.] |
|
* stm32mp153c-dhcom-picoitx.dts <--------------------------'
[ STM32MP153C based DHCOM SoM populated on DRC02 ] :
[ carrier board combined DT. This DT describes ] :
[ specific combination of SoM populated on DRC02 ] :
[ carrier board. ] :
:
:
Both common SoM and DRC02 DTs can be extended by DTOs :
.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - '
: DTOs add additional bindings into base DTs at runtime.
:
:
* stm32mp15xx-dhcom-drc02-overlay-wifi-rsi.dts
[ DH DHCOM DRC02 populated with DHCOM carrying RSI WiFi. ]
[ The carrier board MicroSD card is not available in this setup.]

DHCOM common DTSIs
------------------
* stm32mp15xx-dhcom-overlay-panel-dpi-ch101olhlwh.dtsi [3]
[ Common CH101 panel DT bindings used by all DHCOM systems. ]
[ This DT uses common DPI panel base DT, see [2]. ]
* stm32mp15xx-dhcom-overlay-panel-dpi.dtsi [2]
[ Common DPI panel DT bindings used by all DHCOM systems. ]

== Kernel Userspace Interfaces to Access Hardware ==

=== Control GPIOs ===
:Show gpio definition in Linux
:{| class="wikitable"
|<tt>''gpioinfo''</tt>
|}
:: '''Note:'''
:: gpiochip0 = STM port-A, gpiochip1 = STM port-B, ...

:{|class="wikitable" style="text-align: center; width: 800px"
|-
! DHCOM Name: !! alt. DHCOM Name: !! SO-DIMM Pin# !! CPU Pad Name !! gpiod label:
|-
| GPIO A || || 154 || PF3 || DHCOM-A
|-
| GPIO B || || 156 || PD6 || DHCOM-B
|-
| GPIO C || || 162 || PG0 || DHCOM-C
|-
| GPIO D || || 163 || PD12 || DHCOM-D
|-
| GPIO E || || 164 || PC6 || DHCOM-E
|-
| GPIO F || || 165 || PD11 || DHCOM-F
|-
| GPIO G || || 167 || PI0 || DHCOM-G
|-
| GPIO H || || 173 || PI2 || DHCOM-H
|-
| GPIO I || || 175 || PI3 || DHCOM-I
|-
| GPIO J || CIF HSYNC || 74 || PH8 || DHCOM-J
|-
| GPIO K || CIF PCLK || 72 || PA6 || DHCOM-K
|-
| GPIO L || CIF MCLK || 70 || PG8 || DHCOM-L
|-
| GPIO M || CIF VSYNC || 68 || PI5 || DHCOM-M
|-
| GPIO N || CIF D9 || 66 || PH7 || DHCOM-N
|-
| GPIO O || CIF D8 || 64 || PI1 || DHCOM-O
|-
| GPIO P || CIF D7 || 62 || PE6 || DHCOM-P
|-
| GPIO Q || CIF D6 || 60 || PB8 || DHCOM-Q
|-
| GPIO R || CIF D5 || 58 || PI4 || DHCOM-R
|-
| GPIO S || CIF D4 || 56 || PH14 || DHCOM-S
|-
| GPIO T || CIF D3 || 54 || PH12 || DHCOM-T
|-
| GPIO U || CIF D2 || 52 || PH11 || DHCOM-U
|-
| GPIO V || CIF D1 || 50 || PH10 || DHCOM-V
|-
| GPIO W || CIF D0 || 48 || PH9 || DHCOM-W
|-
| INT HIGHEST PRIORITY || || 151 || PI8 || DHCOM-INT
|}

::'''Set state'''
::{| class="wikitable"
|<tt>''gpioset $(gpiofind DHCOM-<#>)=0''</tt>
|-
|<tt>''gpioset $(gpiofind DHCOM-<#>)=1''</tt>
|}

::or
::{| class="wikitable"
|<tt>''gpioset gpiochip<port#> <pin#>=0''</tt>
|-
|<tt>''gpioset gpiochip<port#> <pin#>=1''</tt>
|}

::'''Get state'''
::{| class="wikitable"
|<tt>''gpioget $(gpiofind DHCOM-<#>)''</tt>
|}

::or
::{| class="wikitable"
|<tt>''gpioget gpiochip<port#> <pin#>''</tt>
|}

=== RS-485 (only picoITX or DRC02) ===
:'''RS-485 device'''
:{| class="wikitable" style="width: 400px"
||DHCOM UART 2||<tt>/dev/ttySTM2</tt>
|}

:'''Compilation on target'''
:{| class="wikitable"
|<tt>''gcc tty_rs485_test_v1.1.c -o tty_rs485_test''</tt>
|-
|<tt>''gcc tty_rs485_flags_v1.0.c -o tty_rs485_flags''</tt>
|}

:'''Show UART flags'''
:{| class="wikitable"
|<tt>''./tty_rs485_flags /dev/ttySTM2''</tt>
|}

:'''Set tty device to raw mode'''
:{| class="wikitable"
|<tt>''stty -F /dev/ttySTM2 115200 raw -echo -echoe''</tt>
|}

:'''Send data with demo program'''
:{| class="wikitable"
|<tt>''echo -n -e "\n\rHallo RS485 Welt!" ¦ ./tty_rs485_test /dev/ttySTM2''</tt>
|}

:'''Receive data with demo program'''
:{| class="wikitable"
|<tt>''./tty_rs485_test /dev/ttySTM2''</tt>
|}

:'''Download example source code'''
:* [[media:tty_rs485_test_v1.1.zip | tty_rs485_test_v1.1.c & tty_rs485_flags_v1.0.c]]

=== CAN interface ===
:'''Setup CAN interface with baudrate 500kbit/sec.'''
:{| class="wikitable"
|<tt>''ip link set can0 up type can bitrate 500000''</tt>
|}

:'''Start to listen on CAN port'''
:{| class="wikitable"
|<tt>''candump can0''</tt>
|}

:'''Send test message'''
:{| class="wikitable"
|<tt>''cansend can0 100#11.2233.44556677.88''</tt>
|}

:'''Deinitialize CAN port'''
:{| class="wikitable"
|<tt>''ip link set can0 down''</tt>
|}

=== UART Interfaces ===
:{| class="wikitable" style="width: 400px"
||DHCOM UART 1 ||<tt>/dev/ttySTM0</tt>
|-
||DHCOM UART 2 ||<tt>/dev/ttySTM2</tt>
|-
||DHCOM UART 3 ||<tt>/dev/ttySTM1</tt>
|}

=== I2C Interfaces ===
:{| class="wikitable" style="width: 400px"
||DHCOM I2C 1||<tt>/dev/i2c-1</tt>
|-
||DHCOM I2C 2 ||<tt>/dev/i2c-0</tt>
|-
||On Module Devices ||<tt>/dev/i2c-2</tt>
|}

=== ADC/DAC Interfaces ===
:{|class="wikitable" style="text-align: center; width: 800px"
|-
! DHCOM Name !! SO-DIMM Pin# !! PDK2 Header !! Linux device !! sysfs in/out name !! STM32MP1 pin
|-
| AD0 || 8 || X18 Pin 8|| iio:device2 || in_voltage0_* || ANA0
|-
| AD1 || 6 || X18 Pin 6 || iio:device3 || in_voltage1_* || ANA1
|-
| AD2 || 4 || X18 Pin 4 || iio:device0 || out_voltage1_* || PA4_DAC_OUT1
|-
| AD3 || 2 || X18 Pin 2 || iio:device1 || out_voltage2_* || PA5_DAC_OUT2
|}

==== ADC inputs ====
:sysfs path
:{| class="wikitable"
|<tt>''/sys/bus/iio/devices/iio:device*''</tt>
|}

:Show offset and voltage scale
:{| class="wikitable"
|<tt>''cat in_voltage_scale''</tt>
|-
|<tt>''cat in_voltage_offset''</tt>
|}

: '''Notes:'''
:*Voltage = (RAW + OFFSET) * SCALE
:*Maximum input voltage = 2.9V (VDDA is connected to PMIC LDO1)

:Read analog value
:{| class="wikitable"
|<tt>''cat in_voltage*_raw''</tt>
|}

==== DAC outputs ====
:sysfs path
:{| class="wikitable"
|<tt>''/sys/bus/iio/devices/iio:device*''</tt>
|}

:Show output voltage scale
:{| class="wikitable"
|<tt>''cat out_voltage*_scale''</tt>
|}

:Enable DAC
:{| class="wikitable"
|<tt>''echo 0 > out_voltage*_powerdown''</tt>
|}

: '''Notes:'''
:*Voltage = RAW * SCALE
:*Maximum output voltage = 2.9V (VDDA is connected to PMIC LDO1)

:Set analog output value
:{| class="wikitable"
|<tt>''echo xxxx > out_voltage*_raw''</tt>
|}

== FAQ ==
==== How to connect to WiFi network with WPA2 PSK? ====
:'''Establish connection'''
:{| class="wikitable"
|<tt>wpa_passphrase "SSID" >/etc/wpa_supplicant.conf</tt>
|}
:-> In the next step, please enter the password
:{| class="wikitable"
|<tt>ip link set wlan0 up</tt>
|-
|<tt>wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf &</tt>
|-
|<tt>udhcpc -i wlan0</tt>
|}
:'''Disconnect'''
:{| class="wikitable"
|<tt>fg</tt>
|}
:-> Moves a background process wpa_supplicant on your current Linux shell to the foreground. Then Press "Strg + C" to end the process.
:{| class="wikitable"
|<tt>ip link set wlan0 down</tt>
|}

==== How to set up WiFi AP? ====
:Create new AP configuration file
:{| class="wikitable"
|<tt>nano /etc/hostapd_myAP.conf</tt>
|}
:Insert the following to the file: (SSID = rsiwifi and default password = rsiTest1)
ctrl_interface=/var/run/hostapd
ctrl_interface_group=0
interface=wlan0
ssid=rsiwifi
hw_mode=g
channel=6
wpa=2
wpa_passphrase=rsiTest1
wpa_key_mgmt=WPA-PSK
:Configure the AP wlan0 interface or start DHCP server on it etc.
:{| class="wikitable"
|<tt>nano /etc/systemd/network/80-wlan0.network</tt>
|}
:Insert the following to the file:
[Match]
Path=platform-soc

[Network]
Address=11.11.11.11/24
DHCPServer=yes
:-> Reboot the system

:Start hostapd to start the AP:
:{| class="wikitable"
|<tt>hostapd -d hostapd_DRC02.conf >/dev/null &</tt>
|}

:'''Stop AP'''
:{| class="wikitable"
|<tt>fg</tt>
|}
:-> Moves a background process hostapd on your current Linux shell to the foreground. Then Press "Strg + C" to end the process.
:{| class="wikitable"
|<tt>ip link set wlan0 down</tt>
|}

==== How to enable WiFi/BT support, if missing? How to configure RSI mode (WiFi alone, Bluetooth, ...)? ====
:The needed sdmmc3 interface will be activated by the stm32mp15xx-dhcom-som.dtsi file. This is included by default with picoITX, PDK2 and DRC02 configuration.

:Next to this the kernel module is needed. The Yocto build instructions can be found at the following file:
:https://github.com/dh-electronics/meta-dhsom-stm32-bsp/blob/dunfell-3.1/conf/machine/dh-stm32mp1-dhcom-picoitx.conf

# Ship kernel modules
MACHINE_ESSENTIAL_EXTRA_RDEPENDS += " linux-firmware-rs9116 "
KERNEL_MODULE_AUTOLOAD += " rsi_sdio "
KERNEL_MODULE_PROBECONF += " rsi_sdio "
module_conf_rsi_sdio = "options rsi_sdio dev_oper_mode=1"

:If you are using a different root filesystem (compared to our Yocto configuration) please ensure, that the firmware files and the rsi_sdio.conf file are included in the filesystem:
:[[media:rsi_firmware.zip|rsi_firmware.zip]]
:* Copy the directory rsi to /lib/firmware/
:* Copy the file rsi_sdio.conf to /etc/modprobe.d/

:'''Note to DRC02:'''

:DRC02 default images with date Oct. 2021 or newer support WiFi/BT by an additional device tree overlay.
:To use the DTO, please add it to the U-Boot environment:

:{| class="wikitable"
|<tt>setenv loaddtos '#conf-stm32mp153c-dhcom-drc02.dtb#conf-stm32mp15xx-dhcom-drc02-overlay-wifi-rsi.dtbo'</tt>
|}

:'''RSI mode:'''

:By default, the RSI module is configured to WiFi alone mode with our Yocto image. The mode can be configured by rsi_sdio.conf file:
According to Linux kernel source, the dev_oper_mode has the following meaning:
linux-2.6$ git grep -n DEV_OPMODE_ drivers/net/wireless/rsi/ [...]
drivers/net/wireless/rsi/rsi_hal.h:21:#define DEV_OPMODE_WIFI_ALONE 1
drivers/net/wireless/rsi/rsi_hal.h:22:#define DEV_OPMODE_BT_ALONE 4
drivers/net/wireless/rsi/rsi_hal.h:23:#define DEV_OPMODE_BT_LE_ALONE 8
drivers/net/wireless/rsi/rsi_hal.h:24:#define DEV_OPMODE_BT_DUAL 12
drivers/net/wireless/rsi/rsi_hal.h:25:#define DEV_OPMODE_STA_BT 5
drivers/net/wireless/rsi/rsi_hal.h:26:#define DEV_OPMODE_STA_BT_LE 9
drivers/net/wireless/rsi/rsi_hal.h:27:#define DEV_OPMODE_STA_BT_DUAL 13
drivers/net/wireless/rsi/rsi_hal.h:28:#define DEV_OPMODE_AP_BT 6
drivers/net/wireless/rsi/rsi_hal.h:29:#define DEV_OPMODE_AP_BT_DUAL 14

:If you like to use Bluetooth alone mode, change dev_oper_mode to 12. Then you can use the standard hci commands. Start with 'hciconfig hci0 up' to activate the interface.

==== USB 1.1 problems: Custom board without USB 2.0 hub inbetween the MP1 USB host port? ====
And in that case, have a look at arch/arm/boot/dts/stm32mp15xx-dhcom-picoitx.dtsi and how the OHCI (!) is enabled there. And of course, make sure the kernel config options are enabled accordingly (like for the PicoITX machine)

{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt>meta-dhsom-stm32-bsp$ git grep OHCI</tt>
|}

{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt>recipes-kernel/linux/linux-stable/5.10/dh-stm32mp1-common/dh-stm32mp1-dhsom-common.cfg:CONFIG_USB_OHCI_HCD=y</tt><br/>
<tt>recipes-kernel/linux/linux-stable/5.10/dh-stm32mp1-common/dh-stm32mp1-dhsom-common.cfg:CONFIG_USB_OHCI_HCD_PLATFORM=y</tt>
|}

arch/arm/boot/dts/stm32mp15xx-dhcom-picoitx.dtsi snippet:
&usbh_ehci {
phys = <&usbphyc_port0>;
status = "okay";
};

&usbh_ohci { // <---------------- HERE
phys = <&usbphyc_port0>;
status = "okay";
};

&usbotg_hs {
dr_mode = "otg";
pinctrl-0 = <&usbotg_hs_pins_a>;
pinctrl-names = "default";
phy-names = "usb2-phy";
phys = <&usbphyc_port1 0>;
vbus-supply = <&vbus_otg>;
status = "okay";
};

&usbphyc {
status = "okay";
};

&usbphyc_port0 {
phy-supply = <&vdd_usb>;
vdda1v1-supply = <&reg11>;
vdda1v8-supply = <&reg18>;
};

&usbphyc_port1 {
phy-supply = <&vdd_usb>;
vdda1v1-supply = <&reg11>;
vdda1v8-supply = <&reg18>;
};

==== System stability or USB Host problems? ====
If a display with higher resolution and pixel clock > 48 MHz is used, then this can case USB host and/or system stability problems.

Workaround:
The OSPEEDR must be set to OSPEEDR = 1 for LCD_CLK and OSPEEDR = 0 for all other LTDC signals.
&pinctrl {
ltdc_pins_ customhmi: ltdc-dh-1 {
pins1 {
pinmux = <STM32_PINMUX('I', 14, AF14)>; /* LCD_CLK */
bias-disable;
drive-push-pull;
'''slew-rate = <1>;'''
};
pins2 {
pinmux = <STM32_PINMUX('I', 12, AF14)>, /* LCD_HSYNC */
<STM32_PINMUX('I', 13, AF14)>, /* LCD_VSYNC */
...
<STM32_PINMUX('K', 6, AF14)>; /* LCD_B7 */
bias-disable;
drive-push-pull;
'''slew-rate = <0>;'''
};
};

ltdc_sleep_pins_ customhmi: ltdc-sleep-dh-1 {
pins {
pinmux = <STM32_PINMUX('I', 14, ANALOG)>, /* LCD_CLK */
...
<STM32_PINMUX('K', 6, ANALOG)>; /* LCD_B7 */
};
};
};

==== USB OTG: Custom board where the USB-OTG port is only used as host? ====

On the DHCOM standard, the second USB port of the STM32MP1 is usually an USB-OTG port. If you have a custom board where you want to use the USB-OTG port in host mode only, you should consider the following:

The USB-OTG controller on the STM32MP1, DWC2, does support host mode but is rather inefficient (in comparison to a dedicated USB host controller). The following block diagram shows, that it is possible on the STM32MP1 to alter the pinmuxing, so that the USB-OTG port is used with the USB Host controller of the STM32MP1 (instead of using the DWC2 OTG controller):

Host port#1: EHCI/OHCI controller _________ HS PHY port #1 (SoC balls D+/D- #1)

Host port#2: EHCI/OHCI controller __
\
|_____ HS PHY port #2 (SoC balls D+/D- #2)
DWC2 OTG controller_________________/|
|
UTIM switch__________________|

This change can be made in the device tree with disabling the DWC2 controller and adding the second usb_phyc port to the nodes of usbh_ehci and (if applicable) usbh_ohci. These nodes are usually in the .dtsi file of the board (e.g. for the PicoITX: arch/arm/boot/dts/stm32mp15xx-dhcom-picoitx.dtsi). Here a is snippet how this could look like:

&usbh_ehci {
phys = <&usbphyc_port0>''', <&usbphyc_port1 1>'''; // <-------- HERE
status = "okay";
};

&usbh_ohci {
phys = <&usbphyc_port0>''', <&usbphyc_port1 1>'''; // <-------- HERE
status = "okay";
};

&usbotg_hs {
'''status = "disabled";''' // <-------- HERE
};

&usbphyc {
status = "okay";
};

&usbphyc_port0 {
phy-supply = <&vdd_usb>;
vdda1v1-supply = <&reg11>;
vdda1v8-supply = <&reg18>;
};

&usbphyc_port1 {
phy-supply = <&vdd_usb>;
vdda1v1-supply = <&reg11>;
vdda1v8-supply = <&reg18>;
};

==== How to try QtWebengine ====
The QtWebengine is part of the DH default images.
Please stop the Weston desktop, before the start of the Browser.
Older images: "systemctl stop weston@root.service"
Newer images: "systemctl stop weston.service"
How to start the Browser:
QT_QPA_PLATFORM=eglfs QT_QPA_EGLFS_ALWAYS_SET_MODE=1 QT_QPA_EGLFS_KMS_CONFIG=/etc/default/qt5-eglfs-kms.json qtwebengine-minimal http://YOUR-TEST-PAGE/ --no-sandbox

==== How is the Browser Perfomance on the STM32MP1? ====
[https://wiki.dh-electronics.com/index.php/STM32MP1_Browser_Performance STM32MP1 Browser Performance]

==== How to calibrate resistive touchscreens ====
{{:Calibration of resistive touchscreens}}

Calibration of resistive touchscreens

2023-10-20T06:39:56Z

Pzimmermann: Remove headings

On devices with resistive touchscreens, the touchscreen has to be calibrated.

At our yocto images, we usually use libinput as library for handling input.

'''<big>Prerequisites</big>'''

* Yocto packages ''weston'', ''weston-init'' and ''weston-examples'' have to be installed inside the image.
* The config file <tt>/etc/xdg/weston/weston.ini</tt> needs the following lines (to enable touchscreen calibration):
[libinput]
touchscreen_calibrator=true
After changing the configuration of weston, weston needs to be restarted:
{| class="wikitable"
|-
| <tt>systemctl restart weston</tt>
|}

'''<big>Steps for calibration</big>'''

'''1.''' Get the touchscreen device name with weston-touch-calibrator
{| class="wikitable"
|-
| <tt>XDG_RUNTIME_DIR=/var/run/user/$(id -u weston) weston-touch-calibrator</tt>
|}

Example result (bold part is needed for next steps):
{| class="wikitable"
|-
| <tt>device "'''/sys/devices/platform/soc/2100000.bus/21a8000.i2c/i2c-2/2-0049/input/input0/event0'''" - head "DPI-1"</tt>
|}

'''2.''' Run weston-touch-calibrator on the device for starting the calibration. With the example part of the last result, the command looks like this (bold part is from the last result):
{| class="wikitable"
|-
| <tt>XDG_RUNTIME_DIR=/var/run/user/$(id -u weston) weston-touch-calibrator -v '''/sys/devices/platform/soc/2100000.bus/21a8000.i2c/i2c-2/2-0049/input/input0/event0'''</tt>
|}

Now you press the highlighted points at the touchscreen to calibrate it. You will now get an output on the console like this (the important part is marked bold):
{| class="wikitable"
|-
| <tt>Calibration values: '''-0.001472 -1.081086 1.033880 -1.135099 0.000319 1.082698'''</tt>
|}

'''3.''' To make the calibration permanent, you need to add a udev rule. Create the file <tt>/etc/udev/rules.d/touchscreen-cal.rules</tt> and use the calibration values there. With the result of the previous example, the file looks like this (bold part is the result of the last example):
SUBSYSTEM=="input", KERNEL=="event[0-9]*", ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="'''-0.001472 -1.081086 1.033880 -1.135099 0.000319 1.082698'''"

Calibration of resistive touchscreens

2023-10-20T06:38:32Z

Pzimmermann: Change the level of the heading

On devices with resistive touchscreens, the touchscreen has to be calibrated.

At our yocto images, we usually use libinput as library for handling input.

===== Prerequisites =====
* Yocto packages ''weston'', ''weston-init'' and ''weston-examples'' have to be installed inside the image.
* The config file <tt>/etc/xdg/weston/weston.ini</tt> needs the following lines (to enable touchscreen calibration):
[libinput]
touchscreen_calibrator=true
After changing the configuration of weston, weston needs to be restarted:
{| class="wikitable"
|-
| <tt>systemctl restart weston</tt>
|}

===== Steps for calibration =====

'''1.''' Get the touchscreen device name with weston-touch-calibrator
{| class="wikitable"
|-
| <tt>XDG_RUNTIME_DIR=/var/run/user/$(id -u weston) weston-touch-calibrator</tt>
|}

Example result (bold part is needed for next steps):
{| class="wikitable"
|-
| <tt>device "'''/sys/devices/platform/soc/2100000.bus/21a8000.i2c/i2c-2/2-0049/input/input0/event0'''" - head "DPI-1"</tt>
|}

'''2.''' Run weston-touch-calibrator on the device for starting the calibration. With the example part of the last result, the command looks like this (bold part is from the last result):
{| class="wikitable"
|-
| <tt>XDG_RUNTIME_DIR=/var/run/user/$(id -u weston) weston-touch-calibrator -v '''/sys/devices/platform/soc/2100000.bus/21a8000.i2c/i2c-2/2-0049/input/input0/event0'''</tt>
|}

Now you press the highlighted points at the touchscreen to calibrate it. You will now get an output on the console like this (the important part is marked bold):
{| class="wikitable"
|-
| <tt>Calibration values: '''-0.001472 -1.081086 1.033880 -1.135099 0.000319 1.082698'''</tt>
|}

'''3.''' To make the calibration permanent, you need to add a udev rule. Create the file <tt>/etc/udev/rules.d/touchscreen-cal.rules</tt> and use the calibration values there. With the result of the previous example, the file looks like this (bold part is the result of the last example):
SUBSYSTEM=="input", KERNEL=="event[0-9]*", ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="'''-0.001472 -1.081086 1.033880 -1.135099 0.000319 1.082698'''"

Calibration of resistive touchscreens

2023-10-20T06:31:49Z

Pzimmermann: Create page for calibration of touchscreen, it is meant to be included in other pages

On devices with resistive touchscreens, the touchscreen has to be calibrated.

At our yocto images, we usually use libinput as library for handling input.

==== Prerequisites ====
* Yocto packages ''weston'', ''weston-init'' and ''weston-examples'' have to be installed inside the image.
* The config file <tt>/etc/xdg/weston/weston.ini</tt> needs the following lines (to enable touchscreen calibration):
[libinput]
touchscreen_calibrator=true
After changing the configuration of weston, weston needs to be restarted:
{| class="wikitable"
|-
| <tt>systemctl restart weston</tt>
|}

==== Steps for calibration ====

'''1.''' Get the touchscreen device name with weston-touch-calibrator
{| class="wikitable"
|-
| <tt>XDG_RUNTIME_DIR=/var/run/user/$(id -u weston) weston-touch-calibrator</tt>
|}

Example result (bold part is needed for next steps):
{| class="wikitable"
|-
| <tt>device "'''/sys/devices/platform/soc/2100000.bus/21a8000.i2c/i2c-2/2-0049/input/input0/event0'''" - head "DPI-1"</tt>
|}

'''2.''' Run weston-touch-calibrator on the device for starting the calibration. With the example part of the last result, the command looks like this (bold part is from the last result):
{| class="wikitable"
|-
| <tt>XDG_RUNTIME_DIR=/var/run/user/$(id -u weston) weston-touch-calibrator -v '''/sys/devices/platform/soc/2100000.bus/21a8000.i2c/i2c-2/2-0049/input/input0/event0'''</tt>
|}

Now you press the highlighted points at the touchscreen to calibrate it. You will now get an output on the console like this (the important part is marked bold):
{| class="wikitable"
|-
| <tt>Calibration values: '''-0.001472 -1.081086 1.033880 -1.135099 0.000319 1.082698'''</tt>
|}

'''3.''' To make the calibration permanent, you need to add a udev rule. Create the file <tt>/etc/udev/rules.d/touchscreen-cal.rules</tt> and use the calibration values there. With the result of the previous example, the file looks like this (bold part is the result of the last example):
SUBSYSTEM=="input", KERNEL=="event[0-9]*", ENV{ID_INPUT_TOUCHSCREEN}=="1", ENV{LIBINPUT_CALIBRATION_MATRIX}="'''-0.001472 -1.081086 1.033880 -1.135099 0.000319 1.082698'''"

DHCOM STM32MP1 Linux

2021-08-18T10:22:00Z

Pzimmermann: /* FAQ */ Added entry for switching USB-OTG to Host controller

FAQ General

2021-04-27T12:16:34Z

Pzimmermann: /* Root Filesystem */ Added section for autologin

__TOC__

== General ==
==== ''Do the DHCOM modules have a serial numbers included? If yes, how is it accessible?'' ====
The serial number of a DHCOM module is stored inside the bootloader environment. It can be retrieved by u-boot commands like printenv or by Linux commands like “fw_printenv”

== Bootloader ==
====''How can I access the bootloader u-boot console?'' ====
It is not possible to enter to the bootloader console by pressing a various key (e.g. "Enter") on your keyboard. You have to send "DEL" (ASCII 0x7F) to the device. We recommend you to use the terminal program '''teraterm''' if you are working on windows and to use '''kermit''' or '''minicom''' if you use a linux operating system on your pc.
:*You can configure teraterm to send "DEL" when the delete key or the backspace key is pressed by clicking through the menu to <code> Setup->Keyboard-Setup </code> and enable the required checkbox.

:*Kermit is sending a "DEL" if you hit the backspace key.

:*Minicom is able to send "DEL" when you hit the backspace key if you configure minicom to do that within a terminal window: run <code> $ minicom -s </code> and navigate to <code> Screen and keyboard </code> press "B"

==== ''The automatic update does not execute before the operating system boots!'' ====
Check if the command <code> update auto </code> is included in the bootloader environment variable <code>bootcmd</code> or in a script-variable which is called within <code> bootcmd </code> before <code> bootm </code>.

==== ''The automatic update does not work with my desired update-media!'' ====
The command <code> update auto </code> can be configured with flags within the DHCOM settings.bin block. It is possible to disable a interface for the update mechanism. You can run a update from a disabled interface if you use the command <code> update </code> without the argument <code> auto </code>.

==== ''Which USB Port should i use to run updates with the bootloader?'' ====
Our systems are designed to run updates via the DHCOM USB Host 1 interface. We can support additional usb nterfaces on request.

==== ''My usb stick (flash memory) device is not recognized by the bootloader'' ====
The are limitations when you use usb flash memory devices with u-boot. Please check that a master boot record is available and that a FAT32 filesystem is used on the first primary partition of the device. Please use gparted to format the device.

== Linux ==
=== Root Filesystem ===
==== ''How to handle "FATAL: Could not load /lib/modules/.../modules.dep: No such file or directory"?'' ====
Check the path to your loadable kernel modules. It has to be <tt>/lib/modules/$(uname -r)</tt>.
If your system works without loadable Linux kernel modules:
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># mkdir /lib/modules/$(uname -r)</tt><br/>
<tt># depmod –m</tt>
|}
==== ''Could not install standard packages on the Debian Squeeze based file system'' ====
Reason: The Debian package server address was changed.

Fix: Add the following lines into the <tt>/etc/apt/sources.list</tt> file
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt>deb http://archive.debian.org/debian squeeze main<br/></tt>
<tt>deb-src http://archive.debian.org/debian squeeze main</tt>
|}

==== ''Ethernet does not work'' ====
Check if the line "allow-hotplug eth0" in the file "/etc/network/interfaces" is activated. You can activate the ethernet interface on a running system with the command:
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''ifconfig eth0 up''</tt>
|}
'''Remark:''' To work with a nfs-rootfilesystem you have to disable the line "allow-hotplug eth0" in the file "/etc/network/interfaces". Maybe the system was prepared for this method for development and nobody did change it back.

==== ''How to set a Linux environment variable?'' ====
This example shows you how to configure the system to use a proxy-server with a environment variable.
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''export http_proxy=http://192.168.xxx.xxx:xxxx</tt>
|}

==== ''How to schedule jobs to run periodically at certain times or dates?'' ====
You can use the cron daemon and/or anacron. To use anacron you have to copy or link your program or script into one of the the following folders:
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt>/etc/cron.hourly<br/></tt>
<tt>/etc/cron.daily<br/></tt>
<tt>/etc/cron.weekly<br/></tt>
<tt>/etc/cron.monthly</tt>
|}
For further information have a look at the general linux documentation.

==== ''Enable autologin on a serial console with systemd'' ====
If you want to automaticly log into the serial console at bootup, you can alter the configuration of systemd.
Open the file <tt>/lib/systemd/system/serial-getty@.service</tt> with a text editor.
Look for the following line:
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|<tt>ExecStart=-/sbin/agetty -8 -L %I 115200 $TERM</tt>
|}
Add <tt>--autologin <username></tt> before the <tt>%I</tt> so it looks like this (with root as an example):
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|<tt>ExecStart=-/sbin/agetty -8 -L '''--autologin root''' %I 115200 $TERM</tt>
|}
'''Remark''': If the <tt>-o</tt> option of agetty is used to alter the call of the login-program, then you have to add <tt>-f</tt> to the options which are given to the login program. If you do not this, you will have still enter your password. Here is an example:
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|<tt>ExecStart=-/sbin/agetty -8 -L -o '-p '''-f''' -- \\u' --autologin root %I 115200 $TERM</tt>
|}

=== NAND ===
==== ''We would like to use UBIFS for the root filesystem volume'' ====
UBI/UBIFS is the standard file system for DHCOM systems with NAND flash storage.

==== ''We have the need for additional UBI/UBIFS volumens (partitions)'' ====
It shouldn't be necessary to make changes in the Bootloader u-boot, the Linux kernel, or devicetree. We recommend to use the available NAND Flash storage as a single UBI partition and create if needed multiple UBIFS volumes on it.

==== ''We want to backup the root filesystem from the NAND-Flash of the target'' ====
You can use the DHCOM Update Mechanism of root filesystem of the bootloader for the rootfs in the backup mode. This feature is available on i.MX25 and AM35x DHCOMs. Further information at: [[DHCOM Update: Linux Root Filesystem|DHCOM Update: Linux Root Filesystem]]

=== GPIOs ===
==== ''How to use the GPIO sysfs?'' ====
export
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># echo <GPIO#> >/sys/class/gpio/export</tt>
|}
: '''Remark:''' Have a look into <tt> /sys/class/gpio/ </tt> for already configured gpios.
Set direction
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># echo in >/sys/class/gpio/gpio<GPIO#>/direction</tt><br/>
<tt># echo out >/sys/class/gpio/gpio<GPIO#>/direction</tt>
|}
Set state
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># echo 0 >/sys/class/gpio/gpio<GPIO#>/value</tt><br/>
<tt># echo 1 >/sys/class/gpio/gpio<GPIO#>/value</tt>
|}
unexport
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># echo <GPIO#> >/sys/class/gpio/unexport</tt>
|}
==== ''I want to use GPIO buttons/keys'' ====
We recommend to add a gpio-keys section to the devicetree of your board. For example:
gpio-keys {
compatible = "gpio-keys";

volume-up {
label = "Volume Up";
gpios = <&gpio1 4 0>;
gpio-key,wakeup;
linux,code = <115>; /* KEY_VOLUMEUP */
};

volume-down {
label = "Volume Down";
gpios = <&gpio1 5 0>;
gpio-key,wakeup;
linux,code = <114>; /* KEY_VOLUMEDOWN */
};
};
Please check for the "input/gpio-keys.c" driver to be enabled. For further details how to customize the device tree please refer to [https://www.kernel.org/doc/Documentation/devicetree/bindings/input/gpio-keys.txt www.kernel.org].

You should get a device <tt>'''/dev/input/eventX'''</tt> which provides the key events. Validate your configuration with <tt>cat /dev/input/eventX</tt> or use "evtest" which is available on [https://packages.debian.org/de/squeeze/evtest debian] .

==== ''How to cleanly shutdown the target using a GPIO?'' ====
A common solution is to define a [[FAQ_General#We want to use GPIO buttons/keys. | gpio key]] '''"KEY_POWER"''' in the devicetree of your target. Please have a look on the following example:
gpio-keys {
compatible = "gpio-keys";
pinctrl-names = "default";
pinctrl-0 = <&pinctrl_gpiopowerkey>;
power {
label = "Power-Key";
gpios = <&gpio1 9 GPIO_ACTIVE_HIGH>;
linux,code = <KEY_POWER>;
debounce-interval = <5>;
};
};

Depending on your root filesystem configuration you have to add a daemon which handles the event. Please have a look at "esekeyd" or "triggerhappy". There are Debian Packages available ([https://packages.debian.org/search?keywords=esekeyd esekeyd][https://packages.debian.org/wheezy/triggerhappy triggerhappy ]). Alternative it is possible to use a udev rule (e.g. /etc/udev/rules.d/..).

==== ''The target should power off ifself after a shutdown'' ====
To switch off the power after shutdown you can use a GPIO. Keep in mind that the hardware design of you baseboard has to support this feature (The Premium Developer Kit does not). The Linux Kernel provides a specific GPIO power-off driver to handle this requirement. It has to be enabled with CONFIG_POWER_RESET_GPIO in the kernel configuration. Add a gpio-poweroff section to the device-tree of your board:

gpio-poweroff {
compatible = "gpio-poweroff";
gpios = <&gpio1 2 GPIO_ACTIVE_LOW>;
};

Use the <tt>poweroff</tt> command to power-off the system

{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># poweroff</tt>
|}

For further details please have a look at [https://www.kernel.org/doc/Documentation/devicetree/bindings/gpio/gpio-poweroff.txt www.kernel.org]

=== Features ===
==== ''We want to capture the screen content'' ====
The VLC media player provides the necessary features: [http://www.howtogeek.com/120202/how-to-record-your-desktop-to-a-file-or-stream-it-over-the-internet-with-vlc/ Capture Sceen Content with VLC media player: http://www.howtogeek.com] A x-window-system is required. Have a look at our Yocto tutorial: [[Building Chromium, VLC and X11VNC using Yocto | Building Chromium, VLC and X11VNC using Yocto]]

==== ''View and interact (mouse, keyboard) with a target running the x window system'' ====
Install x11vnc and execute on the target. You can use ssvnc to connect via SSH. See '[[Building Chromium, VLC and X11VNC using Yocto | Building Chromium, VLC and X11VNC using Yocto]]' and 'SSVNC (SSL/SSH VNC viewer): [http://www.karlrunge.com/x11vnc/ssvnc.html http://www.karlrunge.com/x11vnc/ssvnc.html]'

=== Power Management ===

==== ''How to use CPU Frequency scaling?'' ====
If your target supports CPU Frequency scaling (e.g. DHCOM i.MX6, DHCOM AM335x) it is possible to change the clock speed of CPUs on the fly. Check if <tt>CONFIG_CPU_FREQ=y</tt> is enabled in your kernel configuration. Note that this driver doesn't automatically change the CPU clock speed, you need to either enable a dynamic cpufreq governor after boot, or use a userspace tool. Have a look at the [https://www.kernel.org/doc/Documentation/cpu-freq/user-guide.txt cpufreq user guide].

* So far we use the CPU Frequency scaling with the dynamic cpufreq governor. Please have a look at [https://www.kernel.org/doc/Documentation/cpu-freq/governors.txt www.kernel.org].

==== ''Thermal Management: Reasonable Values For Thermal Thresholds'' ====
To get some general information we reference to [https://www.kernel.org/doc/Documentation/thermal/sysfs-api.txt www.kernel.org]. The general meaning of passive and critical threshold:
* The '''passive trip point''' is a preventative measure before reaching critical that does things to lower temperature such as reducing cpu/gpu frequencies
* The '''critical trip point''' should not be exceeded to avoid damaging the SoC and as such when this threshold is reached the operating systems shutdown function is called to attempt to shut down the OS.

A (carefull) example for industrial grade i.MX6 SoC (-40 to 105C):
* critical Trip Point = maxT – 5C = 100C
* passive Trip Point = maxT – 20C = 85C

Sysfs path on i.MX6 with Linux Kernel based on Freescale 3.10.17_1.0.2

{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt> /sys/class/thermal/thermal_zone0 </tt><br/>
<tt> /sys/class/thermal/thermal_zone0/trip_point_0_temp </tt> (critical trip point)<br/>
<tt> /sys/class/thermal/thermal_zone0/trip_point_1_temp </tt> (passive trip point)<br/>
|}
'''Attention:''' The thermal driver does not detect the thermal grade of your SoC. This does mean that you have to adjust the thresholds in some cases.

==== ''Thermal Management: i.MX6 Vivante GPU'' ====
The Vivante GPU does some frequency scaling based on temperature which enabled by default in the Vivante driver. If enabled the driver will scale the GPU frequency down by a specified divisor. By default it is 1/64. Please have a look the your sysfs (when using 3.10.17_1.0.2 Kernel):

{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># echo 3 > /sys/module/galcore/parameters/gpu3DMinClock </tt> # set gpu frequency divisor to 3/64
|}
'''Remark:''' It is possible to do some further customizations at other parameters, too. This should be done depending on your use case.

=== Tweaks ===
==== ''Simulate SoC with less cpu cores'' ====
To use ony n number of CPU cores instead of available cores for example to simulate another system on chip performane add "maxcpus=n" to the linux bootargs. For example add "optargs='maxcpus=1'" to /boot/uLinuxEnv.txt to use only one cpu core.

=== Kernel version ===
==== ''Get Kernel version (on target)'' ====
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># uname -a</tt>
|}
'''Example:'''<br/>
Linux dhcom 3.14.12-rt9-g'''a81067a''' #1 SMP PREEMPT RT Thu Mar 3 09:32:46 CET 2016 armv7l GNU/Linux<br/>
short git SHA = a81067a (this is an identifier for each git commit)

==== ''git commit of a specific version (on a develop machine)'' ====
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># git show SHA</tt>
|}
'''Example:'''
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
<tt># git show a81067a</tt>
|}
'''Remark:''' Before you can do this you have to clone the DH repository from GitHub (look at the Linux section of your module type)

=== Write/Clone/Copy a SD/µSD card Images ===
==== ''How to write a *.sdcard binary image to a sdcard?'' ====
The easiest way is to use <tt>'''dd'''</tt> on your Linux development PC.
* Insert your µSD Card in your Card-Reader and connect it to your PC.
* Find out the /dev/DEVNAME device name for example with <tt>'''dmesg'''</tt> in the terminal.
* '''Important:''' Be sure to write in the following step to the correct device.
* Flash your Image.sdcard with:
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|<tt>dd if=/path/to/Image.sdcard of=/dev/DEVNAME bs=1M</tt>
|}
* You can use <tt>'''dd'''</tt> to create a backup of a µSD card when you swap the <tt>'''if='''</tt> and <tt>'''of='''</tt> args.

==== ''Cloning the complete card (bit by bit)'' ====
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
Insert source card<br/>
<tt># mount | grep ^/dev </tt># Identify the device name DEVNAME of the sd card (the device name is without a number at the end: e.g. sde / sdf / ...)<br/>
<tt># sudo dd if=/dev/DEVNAME of=image.sdcard bs=1M </tt># Copy the source card content to an image file image.sdcard<br/>
Replace source card with target card<br/>
<tt># sudo dd if=image.sdcard of=/dev/DEVNAME bs=1M </tt># Copy the image file to the target card<br/>
<tt># sync </tt># write cached content to card<br/>
|}
'''Remark:''' Only possible if the card size are identical or the target card is greater!

==== ''Copy the sd card content via a copmpressed archive file'' ====
{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
Insert source card<br/>
<tt># mount | grep ^/dev </tt># Identify the partition SOURCEPART to copy e.g. /media/devel/rootfs<br/>
<tt># cd SOURCEPART </tt># change to source partition<br/>
<tt># sudo tar cfJv path/image.tar.xz . </tt># Compress the source card to an archive file image.tar.xz<br/>
Replace source card with target card<br/>
<tt># cd TARGETPART </tt># change to target partition</tt><br/>
<tt># sudo tar xfJv path/image.tar.xz</tt># Decompress the archive file to the target partition<br/>
<tt># sync </tt># write cached content to card<br/>
|}
'''Remark:'''
You have to partition an format the target sd card<br/>
We therefore recommend the tool "Disks"<br/>
Our recommendation is to use two partitions:<br/>
1. ext3 partition named "boot" with 50BM - 100MB<br/>
2. ext3 partition named "rootfs" with the remaining storage size

=== fb_videomode struct description ===
To integrate support for an additional display it is necessary to expand the fb_videomode struct in linux.
struct fb_videomode {
const char *name; /* optional */
u32 refresh; /* optional */
u32 xres;
u32 yres;
u32 pixclock; /* value in pico seconds */
u32 left_margin; /* H back porch */
u32 right_margin; /* H front porch */
u32 upper_margin; /* V back porch */
u32 lower_margin; /* V front porch */
u32 hsync_len;
u32 vsync_len;
u32 sync;
u32 vmode;
u32 flag;
};

{| class="wikitable" | style="width: 100%; color: #000000; background: #FFFFFF;" valign="top" |
|
sync flags:<br/>
<tt>FB_SYNC_HOR_HIGH_ACT </tt> --> HSYNC pulse is active high<br/>
<tt>FB_SYNC_VERT_HIGH_ACT </tt> --> VSYNC pulse is active high<br/>
<tt>FB_SYNC_CLK_LAT_FALL </tt> --> Display must sample data on falling edge<br/>
<tt>FB_SYNC_OE_LOW_ACT </tt> --> OE pulse is active low<br/>
<tt>FB_SYNC_DATA_INVERT </tt> --> Data inverted<br/>
|}

Environment for running local DHCOM Update

2021-02-01T10:00:01Z

Pzimmermann: Added explanation of some additional variables

If you want to make a update of your DHSOM system, without using an USB-stick or a SD-card, it is possible to alter the environment of U-Boot to start a local version of the DHCOM Update Mechanism.

== Requirements ==

The DHSOM system requires the following things:
* A spare partition on the eMMC (NAND-flash is usually too small) where the components of the update are stored.
* U-Boot must be built with the <tt>setexpr</tt>-command included (This command is used for arithmetic expressions).
* The Linux on the DHSOM-System needs the <tt>fw-tools</tt> for accessing the bootloader environment. '''WARNING''': The configuration of the <tt>fw-tools</tt> must match the layout of the bootflash, else when setting the environment, the command may write to the wrong location on the flash. This may cause that the system won't work anymore.

== Setting up the Environment ==

Use the following commands as <tt>root</tt> (or prepend them with <tt>sudo</tt>) to set up the bootloader environment:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv local_update_max_tries 3
fw_setenv check_if_local_update 'if test "${local_update}" = "true" -a ${local_update_tries} -lt ${local_update_max_tries} ; then run do_local_update; fi'
fw_setenv do_local_update 'setexpr local_update_tries ${local_update_tries} + 1; saveenv; load ${src_intf} ${src_dev_part} ${loadaddr} zImage_${dhcom}.update; run setupdateargs; bootz ${loadaddr}' </tt>

Here is a short explanation what each variable does:
{| class="wikitable"
|-
! Name !! Function of the variable
|-
| local_update || This is a flag which determines if an update via local DHCOM_Update should be made. The user can set this to true to activate the update.
|-
| local_update_tries || Here the number of tries to update the system is stored. On each start of an update this counter is increased by one. If the update finishes successful the counter should be set to 0.
|-
| local_update_max_tries || This variable stores a number which says how often an update should be tried, before it is aborted. At the command atop this is set to 3.
|-
| check_if_local_update || This variable contains a script. Here is checked if <tt>local_update</tt> is true and if <tt>local_update_tries</tt> is less then <tt>local_update_max_tries</tt>. If both are true, the script at variable <tt>do_local_update</tt> is run, else nothing happens.
|-
| do_local_update || This script increments <tt>local_update_tries</tt> by one and saves the new value. Then the update-kernel is loaded into memory. The variables <tt>src_intf</tt> and <tt>src_dev_part</tt> determine which interface, device and partition are used for this. After that the script <tt>setupdateargs</tt> (which is also used by the regular update kernel) is run. Now the update-kernel is loaded.
|}

These variables are referenced by the prior variables:
{| class="wikitable"
|-
! Name !! Function of the variable
|-
| src_intf|| This is the type of interface where the update is located (mmc or usb). The variable has to be set when the update is activated.
|-
| src_dev_part || Here the device number of the used device and the partition where the update is stored in the form <tt><device_number>:<partition></tt>. The variable has to be set when the update is activated. Note that the device numbers start with 0, while the partition numbers start with 1.
|-
| loadaddr || This variable contains an address where the kernel is loaded onto RAM. This is preset in the environment and nothing has to be changed here by the user.
|-
| setupdateargs || This variable contains a script, which sets up the bootargs of the update-kernel. <tt>src_intf</tt> and <tt>src_dev_part</tt> are given to the kernel as arguments, so the software inside the kernel can determine where the update is located (the <tt>CMDLINE</tt> environment variable contains a list of all bootargs of the kernel).
|}

You have to alter the <tt>bootcmd</tt> variable (is always executed at startup of the module) that the check is run. You have to add <tt> run check_if_local_update;</tt> after the <tt>update auto;</tt> part.
For a standard i.MX6-based DHSOM-module the needed command should look like this:
<tt>fw_setenv bootcmd 'update auto; run check_if_local_update; mmc dev ${mmcdev}; if mmc rescan; then run bootlinux; else echo Boot failed, because mmc${mmcdev} not found!;fi;</tt>
On other DHSOM-modules the needed <tt>bootcmd</tt> may vary.

When connected to the DHSOM module via serial cable, it is also possible to make these changes to the environment from the U-Boot console. There are two differences when doing this from the U-Boot console:
* Instead of using the <tt>fw_setenv</tt> command you have to use <tt>setenv</tt> which is the built in command of U-Boot.
* After the last command you have to use <tt>saveenv</tt> to save the changed environment. Without doing this the changes will be lost after the next reboot of the module.

== Activate Booting Update Kernel ==

After the update image and the update-kernel is put onto the device, you can activate the update from inside the Linux. The following example assumes that the components of the update are on the third partition of the eMMC of an i.MX6 based DHSOM-module. The eMMC on the i.MX6 has the device number 2, on other modules this can be different (like the AM335X: There the eMMC has the device number 1).

<tt>fw_setenv local_update true
fw_setenv local_update_tries 0
fw_setenv src_intf mmc
fw_setenv src_dev_part 2:3</tt>

At the next reboot the update will be executed.

After the update has finished, the update mechanism must disable the local update or else the update will be triggered again. The following commands do unset the source variables and reset the counter and flag:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv src_intf
fw_setenv src_dev_part</tt>

If the update fails the update will be tried again until <tt>local_update_tries</tt> hits the number in <tt>local_update_max_tries</tt>. After that the bootloader tries to boot the system as normal. You can see that the update was aborted from inside the Linux system if the variables <tt>local_update</tt> is <tt>true</tt> and <tt>local_update_tries</tt> contains the same number as <tt>local_update_max_tries</tt>. You can use the command <tt>fw_printenv</tt> to read the content of these variables.

Environment for running local DHCOM Update

2021-01-29T07:23:44Z

Pzimmermann:

If you want to make a update of your DHSOM system, without using an USB-stick or a SD-card, it is possible to alter the environment of U-Boot to start a local version of the DHCOM Update Mechanism.

== Requirements ==

The DHSOM system requires the following things:
* A spare partition on the eMMC (NAND-flash is usually too small) where the components of the update are stored.
* U-Boot must be built with the <tt>setexpr</tt>-command included (This command is used for arithmetic expressions).
* The Linux on the DHSOM-System needs the <tt>fw-tools</tt> for accessing the bootloader environment. '''WARNING''': The configuration of the <tt>fw-tools</tt> must match the layout of the bootflash, else when setting the environment, the command may write to the wrong location on the flash. This may cause that the system won't work anymore.

== Setting up the Environment ==

Use the following commands as <tt>root</tt> (or prepend them with <tt>sudo</tt>) to set up the bootloader environment:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv local_update_max_tries 3
fw_setenv check_if_local_update 'if test "${local_update}" = "true" -a ${local_update_tries} -lt ${local_update_max_tries} ; then run do_local_update; fi'
fw_setenv do_local_update 'setexpr local_update_tries ${local_update_tries} + 1; saveenv; load ${src_intf} ${src_dev_part} ${loadaddr} zImage_${dhcom}.update; run setupdateargs; bootz ${loadaddr}' </tt>

Here is a short explanation what each variable does:
{| class="wikitable"
|-
! Name !! Function of the variable
|-
| local_update || This is a flag which determines if an update via local DHCOM_Update should be made. The user can set this to true to activate the update.
|-
| local_update_tries || Here the number of tries to update the system is stored. On each start of an update this counter is increased by one. If the update finishes successful the counter should be set to 0.
|-
| local_update_max_tries || This variable stores a number which says how often an update should be tried, before it is aborted. At the command atop this is set to 3.
|-
| check_if_local_update || This variable contains a script. Here is checked if <tt>local_update</tt> is true and if <tt>local_update_tries</tt> is less then <tt>local_update_max_tries</tt>. If both are true, the script at variable <tt>do_local_update</tt> is run, else nothing happens.
|-
| do_local_update || This script increments <tt>local_update_tries</tt> by one and saves the new value. Then the update-kernel is loaded into memory. The variables <tt>src_intf</tt> and <tt>src_dev_part</tt> determine which interface, device and partition are used for this. After that the script <tt>setupdateargs</tt> (which is also used by the regular update kernel) is run. Now the update-kernel is loaded.
|}

You have to alter the <tt>bootcmd</tt> variable (is always executed at startup of the module) that the check is run. You have to add <tt> run check_if_local_update;</tt> after the <tt>update auto;</tt> part.
For a standard i.MX6-based DHSOM-module the needed command should look like this:
<tt>fw_setenv bootcmd 'update auto; run check_if_local_update; mmc dev ${mmcdev}; if mmc rescan; then run bootlinux; else echo Boot failed, because mmc${mmcdev} not found!;fi;</tt>
On other DHSOM-modules the needed <tt>bootcmd</tt> may vary.

When connected to the DHSOM module via serial cable, it is also possible to make these changes to the environment from the U-Boot console. There are two differences when doing this from the U-Boot console:
* Instead of using the <tt>fw_setenv</tt> command you have to use <tt>setenv</tt> which is the built in command of U-Boot.
* After the last command you have to use <tt>saveenv</tt> to save the changed environment. Without doing this the changes will be lost after the next reboot of the module.

== Activate Booting Update Kernel ==

After the update image and the update-kernel is put onto the device, you can activate the update from inside the Linux. The following example assumes that the components of the update are on the third partition of the eMMC of an i.MX6 based DHSOM-module. The eMMC on the i.MX6 has the device number 2, on other modules this can be different (like the AM335X: There the eMMC has the device number 1).

<tt>fw_setenv local_update true
fw_setenv local_update_tries 0
fw_setenv src_intf mmc
fw_setenv src_dev_part 2:3</tt>

At the next reboot the update will be executed.

After the update has finished, the update mechanism must disable the local update or else the update will be triggered again. The following commands do unset the source variables and reset the counter and flag:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv src_intf
fw_setenv src_dev_part</tt>

If the update fails the update will be tried again until <tt>local_update_tries</tt> hits the number in <tt>local_update_max_tries</tt>. After that the bootloader tries to boot the system as normal. You can see that the update was aborted from inside the Linux system if the variables <tt>local_update</tt> is <tt>true</tt> and <tt>local_update_tries</tt> contains the same number as <tt>local_update_max_tries</tt>. You can use the command <tt>fw_printenv</tt> to read the content of these variables.

Environment for running local DHCOM Update

2021-01-29T06:45:32Z

Pzimmermann: Revising some phrases, error correction

If you want to make a update of your DHSOM system, without using an USB-stick or a SD-card, it is possible to alter the environment of U-Boot to start a local version of the DHCOM Update Mechanism.

== Requirements ==

The DHSOM system requires the following things:
* A spare partition on the eMMC (NAND-flash is usually too small) where the components of the update are stored.
* U-Boot must be built with the <tt>setexpr</tt>-command included (This command is used for arithmetic expressions).
* The Linux on the DHSOM-System needs the <tt>fw-tools</tt> for accessing the bootloader environment. '''WARNING''': The configuration of the <tt>fw-tools</tt> must match the layout of the bootflash, else when setting the environment, the command may write to the wrong location on the flash. This may cause that the system won't work anymore.

== Setting up the Environment ==

Use the following commands as <tt>root</tt> (or prepend them with <tt>sudo</tt>) to set up the bootloader environment:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv local_update_max_tries 3
fw_setenv check_if_local_update 'if test "${local_update}" = "true" -a ${local_update_tries} -lt ${local_update_max_tries} ; then run do_local_update; fi'
fw_setenv do_local_update 'setexpr local_update_tries ${local_update_tries} + 1; saveenv; load ${src_intf} ${src_dev_part} ${loadaddr} zImage_${dhcom}.update; run setupdateargs; bootz ${loadaddr}' </tt>

Here is a short explanation what each variable does:
{| class="wikitable"
|-
! Name !! Function of the variable
|-
| local_update || This is a flag which determines if an update via local DHCOM_Update should be made. The user can set this to true to activate the update.
|-
| local_update_tries || Here the number of tries to update the system is stored. On each start of an update this counter is increased by one. If the update finishes successful the counter should be set to 0.
|-
| local_update_max_tries || This variable stores a number which says how often an update should be tried, before it is aborted. At the command atop this is set to 3.
|-
| check_if_local_update || This variable contains a script. Here is checked if <tt>local_update</tt> is true and if <tt>local_update_tries</tt> is less then <tt>local_update_max_tries</tt>. If both are true, the script at variable <tt>do_local_update</tt> is run, else nothing happens.
|-
| do_local_update || This script increments <tt>local_update_tries</tt> by one and saves the new value. Then the update-kernel is loaded into memory. The variables <tt>src_intf</tt> and <tt>src_dev_part</tt> determine which interface, device and partition are used for this. After that the script <tt>setupdateargs</tt> (which is also used by the regular update kernel) is run. Now the update-kernel is loaded.
|}

You have to alter the <tt>bootcmd</tt> variable (is always executed at startup of the module) that the check is run. You have to add <tt> run check_if_local_update;</tt> after the <tt>update auto;</tt> part.
For a standard i.MX6-based DHSOM-module the needed command should look like this:
<tt>fw_setenv bootcmd 'update auto; run check_if_local_update; mmc dev ${mmcdev}; if mmc rescan; then run bootlinux; else echo Boot failed, because mmc${mmcdev} not found!;fi;</tt>
On other DHSOM-modules the needed <tt>bootcmd</tt> may vary.

When connected to the DHSOM module via serial cable, it is also possible to make these changes to the environment from the U-Boot console. There are two differences when doing this from the U-Boot console:
* Instead of using the <tt>fw_setenv</tt> command you have to use <tt>setenv</tt> which is the built in command of U-Boot.
* After the last command you have to use <tt>saveenv</tt> to save the changed environment. Without doing this the changes will be lost after the next reboot of the module.

== Activate Booting Update Kernel ==

When the update image and the update-kernel is put onto the device, you can activate the update from inside the Linux. The following example assumes that the components of the update are on the third partition of the eMMC of an i.MX6 based DHSOM-module. The eMMC on the i.MX6 has the device number 2, on other modules this can be different (like the AM335X: There the eMMC has the device number 1).

<tt>fw_setenv local_update true
fw_setenv local_update_tries 0
fw_setenv src_intf mmc
fw_setenv src_dev_part 2:3</tt>

At the next reboot the update will be executed.

After the update has finished, the update mechanism must disable the local update or else the update will be triggered again. The following commands do unset the source variables and reset the counter and flag:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv src_intf
fw_setenv src_dev_part</tt>

If the update fails the update will be tried again until <tt>local_update_tries</tt> hits the number in <tt>local_update_max_tries</tt>. After that the bootloader tries to boot the system as normal. You can see that the update was aborted from inside the Linux system if the variables <tt>local_update</tt> is <tt>true</tt> and <tt>local_update_tries</tt> contains the same number as <tt>local_update_max_tries</tt>. You can use the command <tt>fw_printenv</tt> to read the content of these variables.

Environment for running local DHCOM Update

2021-01-28T15:39:40Z

Pzimmermann: Finished writing the draft of the documentation

If you want to make a update of your DHSOM system, without using an USB-stick or a SD-card, it is possible to alter the environment of U-Boot to start a local version of the DHCOM Update Mechanism.

== Requirements ==

The DHSOM system requires the following things:
* A spare partition on the eMMC (NAND-flash is usually too small) where the components of the update are stored.
* U-Boot must be built with the <tt>setexpr</tt>-command included (This command is used for arithmetic expressions).
* The Linux on the DHSOM-System needs the fw-tools for accessing the bootloader environment. '''WARNING''': The configuration of the fw-tools must match the layout of the bootflash, else when setting the environment, the command will write to the wrong location on the flash. This may cause that the system won't work anymore.

== Setting up the Environment ==

Use the following commands as <tt>root</tt> (or prepend them with <tt>sudo</tt>) to set up the bootloader environment:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv local_update_max_tries 3
fw_setenv check_if_local_update 'if test "${local_update}" = "true" -a ${local_update_tries} -lt ${local_update_max_tries} ; then run do_local_update; fi'
fw_setenv do_local_update 'setexpr local_update_tries ${local_update_tries} + 1; saveenv; load ${src_intf} ${src_dev_part} ${loadaddr} zImage_${dhcom}.update; run setupdateargs; bootz ${loadaddr}' </tt>

Here is a short explanation what each variable does:
{| class="wikitable"
|-
! Name !! Function of the variable
|-
| local_update || This is a flag which determines if an update via local DHCOM_Update should be made. The user can set this to true to activate the update.
|-
| local_update_tries || Here the number of tries to update the system is stored. On each start of an update this counter is increased by one. If the update finishes successful the counter should be set to 0.
|-
| local_update_max_tries || This variable stores a number which says how often an update should be tried, before it is aborted. At the command atop this is set to 3.
|-
| check_if_local_update || This variable contains a script. Here is checked if <tt>local_update</tt> is true and if <tt>local_update_tries</tt> is less then <tt>local_update_max_tries</tt>. If both are true, the script at variable <tt>do_local_update</tt> is run, else nothing happens.
|-
| do_local_update || This script increments <tt>local_update_tries</tt> by one and saves the new value. Then the update-kernel is loaded into memory. The variables <tt>src_intf</tt> and <tt>src_dev_part</tt> determine which interface, device and partition are used for this. After that the script <tt>setupdateargs</tt> (which is also used by the regular update kernel) is run. Now the update-kernel is loaded.
|}

You have to alter the <tt>bootcmd</tt> variable that the check is run. You have to add <tt> run check_if_local_update;</tt> after the <tt>update auto;</tt> part.
For a standard i.MX6-based DHSOM-module the needed command should look like this:
<tt>fw_setenv bootcmd 'update auto; run check_if_local_update; mmc dev ${mmcdev}; if mmc rescan; then run bootlinux; else echo Boot failed, because mmc${mmcdev} not found!;fi;</tt>
On other DHSOM-modules the needed <tt>bootcmd</tt> may vary.

When connected to the DHSOM module via serial cable, it is also possible to make these changes to the environment from the U-Boot console. There are two differences when doing this from the U-Boot console:
* Instead of using the <tt>fw_setenv</tt> command you have to use <tt>setenv</tt> which is the built in command of U-Boot.
* After the last command you have to use <tt>saveenv</tt> to save the changed environment. Without doing this the changes will be lost after the next reboot of the module.

== Activate Booting Update Kernel ==

When the update image and the update-kernel is put onto the device, you can activate the update from inside the Linux. The following example assumes that the components of the update are on the third partition of the eMMC of an i.MX6 based DHSOM-module. The eMMC on the i.MX6 has the device number 2, other modules can differ here (like the AM335X: There the eMMC has the device number 1).

<tt>fw_setenv local_update true
fw_setenv local_update_tries 0
fw_setenv src_intf mmc
fw_setenv src_dev_part 2:3</tt>

At the next reboot the update will be executed.

After the update has finished, the update mechanism must disable the local update or else the update will be triggered again. The following commands do unset the source variables and reset the counter and flag:

<tt>fw_setenv local_update false
fw_setenv local_update_tries 0
fw_setenv src_intf
fw_setenv src_dev_part</tt>

If the update fails the update tried again until <tt>local_update_tries</tt> hits the number in <tt>local_update_max_tries</tt>. After that the bootloader tries to boot the system as normal. You can see that the update was aborted from inside the Linux system if the variables <tt>local_update</tt> is <tt>true</tt> and <tt>local_update_tries</tt> contains the same number as <tt>local_update_max_tries</tt>. You can use the command <tt>fw_printenv</tt> to read the content of these variables.

Environment for running local DHCOM Update

2021-01-25T15:28:01Z

Pzimmermann: First part of the site

DHCOM STM32MP1 Linux

2020-10-23T09:24:23Z

Pzimmermann: Error correction at FIT-Image example

DHCOR STM32MP1 Linux

2020-10-23T09:19:37Z

Pzimmermann: Added "How to build the Linux Kernel"

== U-Boot Bootloader Commands ==

=== Activating Device Tree Overlays ===
:Some of the hardware features can be activated with the help of a device tree overlay. To activate a device tree overlay, you have to go into the U-Boot console first. This can be done during the first seconds after startup, by simply hitting any button on a keyboard once the system tells you to do so.

:When you are in the bootloder, you can view a list of all available device tree overlays with the following command.
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> ls mmc 0:4 /boot </tt>
|}

:After that, you can select a device tree overlay with the following commands:

:To activate CAN support:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> setenv loaddtos '#conf@stm32mp157a-avenger96.dtb#conf@stm32mp157a-avenger96-overlay-fdcan1-x6.dtbo#conf@stm32mp157a-avenger96-overlay-fdcan2-x6.dtbo' </tt>
|}

:To activate the 96Boards D3Camera Mezzanine Board enter:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> setenv loaddtos '#conf@stm32mp157a-avenger96.dtb#conf@stm32mp157a-avenger96-overlay-ov5640-x7.dtbo' </tt>
|}

:If you want to make use of the MIPI DSI interface, you can start with an MIPI DSI interface board developed by DH electronics. If you want to use it, simply contact us to find out more about it.
:To activate the MIPI DSI Interface enter the following device tree overlay.
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> setenv loaddtos '#conf@stm32mp157a-avenger96.dtb#conf@stm32mp157a-avenger96-overlay-644-100-x6-otm8009a.dtbo' </tt>
|}

:If you want to save your settings, so that you don't have to enter the device tree overlay after every reboot, enter this command:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> saveenv </tt>
|}

:To reset your device tree overlay, simply override the last settings:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> setenv loaddtos '#conf@stm32mp157a-avenger96.dtb' </tt>
|}

:Once the device tree overlay is set, you can boot up your board by entering boot:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''> boot </tt>
|}

== Linux Userspace Commands ==

=== Logging in after Startup ===
:After booting, you con login as the user "root" without any password. Note, that the standard console is connected to the UART 1 port (96Boards name).
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>dh-stm32mp1-dhcor-avenger96 login: '''root'''</tt>
|}

=== Interacting with GPIOs ===
:An GPIO can be activated with the gpioset command. To find out which GPIO is connected to what gpiochip-device, take a look at the Hardware Section below.
:The GPIO "A" can be turned on by
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# gpioset gpiochip0 14=1</tt>
|}

:and off by
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# gpioset gpiochip0 14=0</tt>
|}

=== Interacting with the User LEDs ===
:In between the two USB-Host connectors of the Avenger96, you can find four so called User LEDs. These LEDs can be used for simple programming examples and be accessed and manipulated by the user form the userspace.
:The LEDs are located under /sys/class/leds.
:To disable the blinking of the LED0 hit following command:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# echo none > /sys/class/leds/green:user0/trigger</tt>
|}

:The LEDs can also be turned on or off permanently by writing either "1" or "0" to the following file:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# echo 1 > /sys/class/leds/green:user0/brightness</tt>
|}

:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# echo 0 > /sys/class/leds/green:user0/brightness</tt>
|}

=== Accessing Devices over I2C ===
:Once you have connected some I2C devices to the Avenger96, you can scan the I2C bus and see if your device is available.
:To scan for devices on the I2C-Bus 1 enter the following command:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# i2cdetect -y 1 </tt>
|}

:To write on the device on the address 0x50 to its register number 0x10 the value 0x20 enter the following command:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# i2cset -y 1 0x50 0x10 0x20 </tt>
|}

:To read the data of the device on the address 0x50 at its register 0x10 enter this:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# i2cget -y 1 0x50 0x10 </tt>
|}

:For a dump of the entire registers of the device at address 0x50 enter the following command:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# i2cdump -f 1 0x50 </tt>
|}

=== Unsing the internal RTC ===
:Read out the current date and time of the system (not the RTC itself)
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# date</tt>
|}

:Set a specific system time
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# date -s "2020-01-30 10:00:00"</tt>
|}

:Save the current system time to the RTC of the STM32MP1
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# hwclock -w</tt>
|}

:When you allready have stored a date on the RTC and you want to read it out, use the next command. This command only gives back the time, but does not synchronize it with the system time. This is done in the next step.
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# hwclock -r</tt>
|}

:The system time can be synchronised to the RTC by this command:
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# hwclock -s</tt>
|}

=== Using the second UART port ===
:If you want to use the second UART Port available on the Low Speed Expansion Connector of the Avenger96, you can access it easily with the tool called minicom
:To open up its configuration enter the following command
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# minicom -s</tt>
|}

:Once you've opend minicom, navigate to ''<tt>Serial port setup</tt>'' and change the Serial Device to ''<tt>/dev/ttySTM1</tt>''.
:Now you can hit ''<tt>exit</tt>'' and you are in a terminal which is connected to the second UART port.

:To reopen the settings of minicom press ''<tt>CTRL + A</tt>'' and then ''<tt>O</tt>'' on your keyboard.
:To close minicom press ''<tt>CTRL + A</tt>'' and then ''<tt>X</tt>'' on your keyboard.

=== Connecting to a WiFi network ===
:After bootup, you have to enter the following commands:

:activating the wlan0 interface
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# ifconfig wlan0 up</tt>
|}

:Enter the SSID and the WPA Key
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# wpa_passphrase "YOUR SSID" your-wpa-key > wpa_supplicant.conf </tt>
|}

:Defining the settings
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# wpa_supplicant -B -Dnl8011 -iwlan0 -cwpa_supplicant.conf </tt>
|}

:After that you should get the message "successfully initialized wpa_supplicant"

:Requesting an IP-Address from the DHCP-Server
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# udhcpc -i wlan0 </tt>
|}

:Checking your IP Address
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# ifconfig </tt>
|}

=== Connecting to a Bluetooth Device ===
:In this example you can see how to connect a bluetooth headset to the Avenger96 and play a song over it.
:For this you have to first store a *.wav audiofile in the home directory (/home/root).

:First start pulsaudio
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# pulseaudio --start</tt>
|}

:Bring up the Bluetooth Device
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# hciconfig hci0 up</tt>
|}

:Start the Bluetooth configuration tool
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# bluetoothctl</tt>
|}

:Now you are controlling the configuration tool. Here you can start the scanning for bluetooth devices
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# scan on</tt>
|}

:Once you see the device you like to connect to stop the scanning.
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# scan off</tt>
|}

:Now Copy the MAC-address of your bluetooth device and pair to it
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# pair xx:xx:xx:xx:xx:xx</tt>
|}

:Next add it to the list of trusted devices
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# trust xx:xx:xx:xx:xx:xx</tt>
|}

:Finally connect to it
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# connect xx:xx:xx:xx:xx:xx</tt>
|}

:Your Headphone should now be connected to the Avenger96, so you can leave the bluetooth configuration tool
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# exit</tt>
|}

:Now you can start playing your audiofile
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# aplay audiofile.wav</tt>
|}

:When you want to remove your device from the Avenger96, open ''<tt>bluetoothctl</tt>'' again and remove its MAC-address
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''[bluetooth]# remove xx:xx:xx:xx:xx:xx</tt>
|}

=== Activating the CAN interface ===
:The Avenger96 has two CAN FD ports which can be accessed from the GPIOs on the Low Speed Expansion Connector:
::FDCAN 1:
:::PA12 - TX
:::PA11 - RX

::FDCAN 2:
:::PB13 - TX
:::PB5 - RX

:To activate them, you have to add a Device Tree Overlay in the bootloader, like mentioned in the beginning of this page.
:Once this is done, you have to connect a CAN-Transceiver to the GPIOs and from here you can access the CAN-Bus.

:Setup CAN interface with baudrate 500kbit/sec.
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# ip link set can0 up type can bitrate 500000</tt>
|}

:Start to listen on CAN port
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# candump can0</tt>
|}

:Send test message
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cansend can0 100#11.2233.44556677.88</tt>
|}

:Deinitialize CAN port
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# ip link set can0 down</tt>
|}

=== Activating the MIPI CSI Interface ===
:The Avenger96 is compatible with the [https://www.96boards.org/product/d3camera/ D3Camera Mezzanine Board] available on the 96Boards website.

:To activate this Mezzanine Board you have to connect it to the Avenger96 before you power it up. Note, that you also have to access the UART0 which is then available on the Solderpins of the D3Camera Mezzanine board.
:Like for CAN you also have to activate the proper device tree overlay as describte in the beginning of this page.

:Once the system is booted, you have to connect a display to the Avenger96 via HDMI and then enter the following command.
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# XDG_RUNTIME_DIR=/var/run/user/0/ gst-launch-1.0 v4l2src device=/dev/video0 ! video/x-raw,width=1280,height=720,pixelformat=RGB565 ! waylandsink</tt>
|}

=== Mounting a USB Drive ===
:To mount a USB drive connect it to the Avenger96 and mount it with the following command
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# mount /dev/sda1 /mnt</tt>
|}

:Now your USB drive is available under the following directory
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cd /mnt</tt>
|}

:To unmount the drive enter the following command
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# umount /dev/sda1 </tt>
|}

=== Formatting and mounting the eMMC ===
:At first you can check all block devices by this command
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# lsblk</tt>
|}

:First partitionate the eMMC device
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cfdisk /dev/mmcblk2</tt>
|}

:Now select the partitiontable ''<tt>gpt</tt>''. Then in the menu you can add a new partiton by entering ''<tt>new</tt>'' and then the size of your partition e.g. ''<tt>7G</tt>''.
:After that enter ''<tt>write</tt>'' and confirm it with ''<tt>yes</tt>''. Then you can ''<tt>quit</tt>'' this tool.

:Now you can format the new partition
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# mkfs.ext4 /dev/mmcblk2p1</tt>
|}

:To access this partition you have to mount it just like an USB-Stick
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# mount /dev/mmcblk2p1 /mnt</tt>
|}

=== Read out the ADC Pins ===
:The GPIOs G and H are mapped as ADC pins. These pins can meassure a value from 0 V to 2,9 V. This reference voltage of 2,9 V is driven by the LDO1 of the PMIC.
:The value measured is calculated as followed:
::''<tt>Umeassured = ( RAW + OFFSET ) * SCALE</tt>''

:You can read out the values as followed:

:'''GPIO G:'''
:Navigate to its directory
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cd /sys/bus/iio/devices/iio:device0</tt>
|}

:Read out ''<tt>SCALE</tt>''
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cat in_voltage_scale</tt>
|}

:Read out ''<tt>OFFSET</tt>''
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cat in_voltage_offset</tt>
|}

:Once you know these two values, you can read the actual ADC value
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cat in_voltage6_raw</tt>
|}

:'''GPIO H:'''
:Navigate to its directory
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cd /sys/bus/iio/devices/iio:device1</tt>
|}

:Read out ''<tt>SCALE</tt>''
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cat in_voltage_scale</tt>
|}

:Read out ''<tt>OFFSET</tt>''
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cat in_voltage_offset</tt>
|}

:Once you know these two values, you can read the actual ADC value
:{| class="wikitable" align="center" | style="color: #000000; background: #FFFFFF;" valign="top" |
|<tt>''# cat in_voltage2_raw</tt>
|}

== Kernel Userspace Interfaces to Access Hardware ==
The pinmuxing of the DHCOR STM32MP1 can be configured just as needed by you as a customer and therefore the interfaces used in each configuration might be different. However, to give you an easy way to start developing with the DHCOR STM32MP1 you can use the Avenger96 Board, which is the reference design for our DHCOR module. Thus, the interfaces described here, are the configuration for the Avenger96.

=== Serial (UART) Interfaces ===
:{| class="wikitable"
! style="background-color:#efefef; width: 200px; text-align:left" | 96Boards Name
! style="background-color:#efefef; width: 200px; text-align:left" | Linux Name
! style="background-color:#efefef; width: 200px; text-align:left" | Hardware Name
|-
| UART 0
| <tt>/dev/ttySTM1</tt>
| UART 7
|-
| UART 1 (Standard UART)
| <tt>/dev/ttySTM0</tt>
| UART 4
|}

=== I²C Interfaces ===
:{| class="wikitable"
! style="background-color:#efefef; width: 200px; text-align:left" | 96Boards Name
! style="background-color:#efefef; width: 200px; text-align:left" | Linux Name
! style="background-color:#efefef; width: 200px; text-align:left" | Hardware Name
|-
| I2C0
| <tt>/dev/i2c-1</tt>
| I2C2
|-
| I2C1
| <tt>/dev/i2c-0</tt>
| I2C1
|-
| OnBoard
| <tt>/dev/i2c-2</tt>
| I2C4
|}

=== microSD and eMMC ===
:{| class="wikitable"
! style="background-color:#efefef; width: 200px; text-align:left" | 96Boards Name
! style="background-color:#efefef; width: 200px; text-align:left" | Linux Name
! style="background-color:#efefef; width: 200px; text-align:left" | Hardware Name
|-
| microSD
| <tt>mmcblk1</tt>
| SDMMC1
|-
| eMMC
| <tt>mmcblk2</tt>
| SDMMC2
|}

=== GPIOs ===
:{| class="wikitable"
! style="background-color:#efefef; width: 200px; text-align:left" | 96Boards Name
! style="background-color:#efefef; width: 200px; text-align:left" | Linux Name
! style="background-color:#efefef; width: 200px; text-align:left" | Hardware Name
|-
| A
| <tt>gpiochip0 14</tt>
| PA14
|-
| B
| <tt>gpiochip1 11</tt>
| PB11
|-
| C
| <tt>gpiochip2 3</tt>
| PC3
|-
| D
| <tt>gpiochip3 8</tt>
| PD8
|-
| E
| <tt>gpiochip3 14</tt>
| PD14
|-
| F
| <tt>gpiochip3 15</tt>
| PD15
|-
| G (mapped as ADC)
| <tt>gpiochip5 12</tt>
| PF12
|-
| H (mapped as ADC)
| <tt>gpiochip5 13</tt>
| PF13
|-
| I
| <tt>gpiochip0 12</tt>
| PA12
|-
| J
| <tt>gpiochip1 5</tt>
| PB5
|-
| K
| <tt>gpiochip0 11</tt>
| PA11
|-
| L
| <tt>gpiochip1 13</tt>
| PB13
|}

:Beside the GPIOs, the Avenger96 has also four user LEDs, which are controlled the same way as the GPIOs.
:{| class="wikitable"
! style="background-color:#efefef; width: 200px; text-align:left" | 96Boards Name
! style="background-color:#efefef; width: 200px; text-align:left" | Linux Name
! style="background-color:#efefef; width: 200px; text-align:left" | Hardware Name
|-
| LED 0
| <tt>/sys/class/leds/green:user0</tt>
| PZ7
|-
| LED 1
| <tt>/sys/class/leds/green:user1</tt>
| PF3
|-
| LED 2
| <tt>/sys/class/leds/green:user2</tt>
| PG0
|-
| LED 3
| <tt>/sys/class/leds/green:user3</tt>
| PG1
|}

== Linux Kernel ==



=== How to build a Kernel ===
{| class="wikitable" align="center" | style="width: 98%; background: #f3f3f3;" valign="top" |
|
Get sources from Github
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
1. Start the Console on Linux<br/>
2. <tt>''git clone https://github.com/dh-electronics/linux-stm32mp1.git --branch dev/5.4.69_dhsom''</tt><br/>
3. <tt>''cd linux-stm32mp1''</tt>
|}
Configure and build the Device Tree + Kernel
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|
4. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make stm32mp1_dhsom_defconfig''</tt><br/>
5. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make menuconfig''</tt> (optional: If you want to add/remove Kernel features)<br/>
6. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make dtbs''</tt><br/>
7. <tt>''ARCH=arm CROSS_COMPILE=/opt/gcc-arm-8.3-2019.03-x86_64-arm-linux-gnueabihf/bin/arm-linux-gnueabihf- make zImage</tt>
|}
Create the FIT-image with our script ([[media:Dh-create-fitimage_1.0_all.deb|Download link]])
{| class="wikitable" style="width: 100%; color: #000000; background: #ffffff;" |
|-
| '''Interactive mode for selecting device trees'''
| '''Device trees are set as parameter'''
|-
|
8. <tt>''create_fitimage''</tt><br/>
Enter the numbers (space seperated) of the device trees to include (e.g. if you want to include the device tree for the Avenger96 include the number of <tt>''./arch/arm/boot/dts/stm32mp157a-avenger96.dtb''</tt> (usually 1).<br/>
Enter the numbers (space seperated) of the device trees overlays to include (e.g. for the Avenger96 enter the files which contain <tt>''Avenger96''</tt> (usually 0 1 2 3 4 5 6 7).
|
(Example is for the Avenger96) <br>
8. <tt>''create_fitimage --dtb ./arch/arm/boot/dts/stm32mp157a-avenger96.dtb --dtbo ./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-644-100-x6-otm8009a.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-644-100-x6-rpi7inch.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-fdcan1-x6.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-fdcan2-x6.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-i2c1-eeprom-x6.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-i2c2-eeprom-x6.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-ov5640-x7.dtbo,./arch/arm/boot/dts/stm32mp157a-avenger96-overlay-spi2-eeprom-x6.dtbo''</tt>
|}
|}

2020-09-16T09:30:12Z

Pzimmermann:

2020-09-14T14:34:51Z

Pzimmermann: Created page with "== Overview == <tt>docker-symlink-wrapper.py</tt> is a wrapper script which creates symlinks for applications. If the symlink is called the script starts the corresoponding a..."

2020-06-25T07:13:03Z

Pzimmermann:

Basic structure of ELBE building a root-filesystem (as of version 12.4). Loosely based on both diagrams at https://elbe-rfs.org/docs/sphinx/releases_v12.4/article-elbeoverview-en.html#overview

ELBE Overview

2020-06-24T14:40:30Z

Pzimmermann: First part of rework done, the rework is currently inside a comment

<div id="header">


The Embedded Linux Build Environment (elbe) is a system to generate root-filesystems for embedded devices. For the latest documentation and version please have a look at [https://github.com/Linutronix/elbe https://github.com/Linutronix/elbe]. The following tutorial was made to get started with elbe 0.3.1 which was used to build debian '''''squeeze'''''

== General Notes ==

Generally root-filesystem creation faces the following requirements:

* Creation of root-filesystem for a specific architecture.
* Generation of a development environment for the specific architecture.

Trying to solve this via cross-compilation of the required packages, we face the following problems:

* Many packages are not designed and tested for cross-compilation.
* Big projects consume a significant amount of time to cross compile.
* Dependencies are not resolved automatically. The Engineer is required to manually find out which package versions of dependencies are required.
* Changes and patches to the packages need to be updated to new version, this process makes an update a very time consuming process.
* One must make sure that the same toolchain is used in the development environment, and root-filesystem.

Elbe takes a different approach at solving these Problems:

* Standard Packages are not self compiled. We use the Debian distributions binary packages.
* Own applications are not cross compiled, but built natively on the target architecture in a virtual machine or emulator.
* The root-filesystem is a subset of of the debian system on the virtual development machine. This implicitly ensures, that the same toolchain is used on development machine and target.
* Updates, addition or package removal is done via debians package-management (apt), which also solves all the dependency problems.

== Installation ==

Elbe is shipped as debian package. This package will pull the necessary dependencies.

Configure <tt>/etc/apt/sources.list.d</tt> appropriately and install it using the following command:

<tt>aptitude install elbe</tt>

== Overview ==

The Elbe system consists of the Program <tt>elbe</tt>, which is completely implemented in Python. Similar to git, it can be called with several sub commands. For example:

<tt>elbe <command>
elbe create --directory /scratch/example example.xml
elbe chg_archive example.xml archive.tar.bz2</tt>

An elbe Project consist of an xml file, that describes the project. This description includes the kernel and initrd, which is used to boot the emulator. When creating a project, this kernel and initrd can be downloaded using the ''elbe dl_kernel'' command.

Then we use the ''elbe create'' command to generate the project directory, which contains the virtual hard disk image and ''Makefile'' to create the buildimage and root file system. We change to the project directory, and run ''make''.

This will start the root-filesystem generation process:

* The stock debian installer initrd is modified by elbe, so that it doesn’t ask questions during install. And it hooks the image generation into the install process.
* emulator is run with the specified kernel and initrd.
* inside the emulator, Debian installer will install the distribution without asking questions.
* The final step of the installer is to start the image generation.
* Image generation creates a copy of the buildimage. (We have a set of modes for this copy)
* To this copy the fine-tuning commands are applied.
* And the archive is unpacked into the copy.
* According to what is specified in the xml file. The copy is then baked into a tar archive or filesystem image.

This diagram illustrates the Process:

[[File:ELBE_Process_Illustration.png|1000px]]

Inside the emulator, the following happens:

[[File:ELBE_Emulator_process.png|800px]]

=== Example XML Files ===

A root-filesystem-project is described via an xml file.

Elbe ships with a set of example xml files.

This xml file describes a simple system in the default full copy mode. The root filesystem is essentially identical to the build system, and it will be saved as <tt>nfsroot.tar.gz</tt>

<div class="listingblock"><div class="title">arm-example.xml</div><div class="content">

<tt>'''<font color="#0000FF"><ns0:RootFileSystem</font>''' <font color="#009900">xmlns:ns0</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"https://www.linutronix.de/projects/Elbe"</font>
<font color="#009900">xmlns:xsi</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"http://www.w3.org/2001/XMLSchema-instance"</font>
<font color="#009900">created</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"2009-05-20T08:50:56"</font> <font color="#009900">revision</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"4"</font>
<font color="#009900">xsi:schemaLocation</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"https://www.linutronix.de/projects/Elbe dbsfed.xsd"</font>'''<font color="#0000FF">></font>'''
'''<font color="#0000FF"><project></font>'''
'''<font color="#0000FF"><name></font>'''ARMexample'''<font color="#0000FF"></name></font>'''
'''<font color="#0000FF"><version></font>'''08.15'''<font color="#0000FF"></version></font>'''
'''<font color="#0000FF"><mirror></font>'''
'''<font color="#0000FF"><primary_host></font>'''debian.tu-bs.de'''<font color="#0000FF"></primary_host></font>'''
'''<font color="#0000FF"><primary_path></font>'''/debian'''<font color="#0000FF"></primary_path></font>'''
'''<font color="#0000FF"><primary_proto></font>'''http'''<font color="#0000FF"></primary_proto></font>'''
'''<font color="#0000FF"></mirror></font>'''
'''<font color="#0000FF"><noauth</font>''' '''<font color="#0000FF">/></font>'''
'''<font color="#0000FF"><suite></font>'''squeeze'''<font color="#0000FF"></suite></font>'''
'''<font color="#0000FF"><buildimage></font>'''
'''<font color="#0000FF"><arch></font>'''armel'''<font color="#0000FF"></arch></font>'''
'''<font color="#0000FF"><size></font>'''20G'''<font color="#0000FF"></size></font>'''
'''<font color="#0000FF"><mem></font>'''256'''<font color="#0000FF"></mem></font>'''
'''<font color="#0000FF"><interpreter></font>'''qemu-system-arm'''<font color="#0000FF"></interpreter></font>'''
'''<font color="#0000FF"><console></font>'''ttyAMA0,115200n1'''<font color="#0000FF"></console></font>'''
'''<font color="#0000FF"><machine></font>'''versatilepb'''<font color="#0000FF"></machine></font>'''
'''<font color="#0000FF"><NIC></font>'''
'''<font color="#0000FF"><model></font>'''smc91c111'''<font color="#0000FF"></model></font>'''
'''<font color="#0000FF"><MAC></font>'''de:ad:be:ef:be:05'''<font color="#0000FF"></MAC></font>'''
'''<font color="#0000FF"></NIC></font>'''
'''<font color="#0000FF"><portforwarding></font>'''
'''<font color="#0000FF"><forward></font>'''
'''<font color="#0000FF"><proto></font>'''tcp'''<font color="#0000FF"></proto></font>'''
'''<font color="#0000FF"><buildenv></font>'''22'''<font color="#0000FF"></buildenv></font>'''
'''<font color="#0000FF"><host></font>'''5022'''<font color="#0000FF"></host></font>'''
'''<font color="#0000FF"></forward></font>'''
'''<font color="#0000FF"></portforwarding></font>'''
'''<font color="#0000FF"><pkg-list></font>'''
'''<font color="#0000FF"></pkg-list></font>'''
'''<font color="#0000FF"></buildimage></font>'''
'''<font color="#0000FF"></project></font>'''
'''<font color="#0000FF"><target></font>'''
'''<font color="#0000FF"><hostname></font>'''myARM'''<font color="#0000FF"></hostname></font>'''
'''<font color="#0000FF"><domain></font>'''tec.linutronix.de'''<font color="#0000FF"></domain></font>'''
'''<font color="#0000FF"><passwd></font>'''foo'''<font color="#0000FF"></passwd></font>'''
'''<font color="#0000FF"><console></font>'''ttyS0,115200'''<font color="#0000FF"></console></font>'''
'''<font color="#0000FF"><package></font>'''
'''<font color="#0000FF"><tar></font>'''
'''<font color="#0000FF"><name></font>'''nfsroot.tar.gz'''<font color="#0000FF"></name></font>'''
'''<font color="#0000FF"></tar></font>'''
'''<font color="#0000FF"></package></font>'''
'''<font color="#0000FF"><finetuning></font>'''
'''<font color="#0000FF"></finetuning></font>'''
'''<font color="#0000FF"><pkg-list></font>'''
'''<font color="#0000FF"><pkg></font>'''build-essential'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''bash'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''less'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''git'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''debhelper'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''nfs-common'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''openssh-server'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"></pkg-list></font>'''
'''<font color="#0000FF"></target></font>'''
'''<font color="#0000FF"></ns0:RootFileSystem></font>'''</tt>

This xml file is lacking the <tt>kernel</tt> and <tt>initrd</tt> tags, which are necessary for a successful build.

The following command will download these, and include them into the xml file:

<tt>elbe dl_kernel example.xml</tt>

To generate the project directory from the xml file the following command is used:

<tt>elbe create --directory /scratch/example example.xml</tt>

The project-directory must not exist before calling this command. It will contain several scripts, files and a Makefile, which controls the creation of the root-filesystem.

=== Creation of build system ===

<div class="paragraph">

Now change to the project directory and run

</div><div class="listingblock"><div class="content">

<tt>make</tt>

</div></div><div class="paragraph">

This will start the debian installer in the virtual machine, which will install the build system according to the xml file description. It also generates the archive <tt>nfsroot.tar.gz</tt> with a copy of the buildimage.

</div><div class="sidebarblock"><div class="content"><div class="title">Note</div><div class="paragraph">

This takes a while.

</div></div></div></div><div class="sect2">

=== Working inside the virtual machine ===

<div class="paragraph">

After successful installation, the virtual machine can be started with:

</div><div class="listingblock"><div class="content">

<tt>make run</tt>

</div></div><div class="paragraph">

or without graphical terminal with:

</div><div class="listingblock"><div class="content">

<tt>make run-con</tt>

</div></div></div></div></div><div class="sect1">

== Changing the subset that is extracted as the root filesystem ==

<div class="sectionbody"><div class="paragraph">

Elbe has several methods to select the subset that is packaged as the root-filesystem.

</div><div class="ulist">

* The finetuning section allows to remove, copy or move files before the archive or image is generated.
* The ''norecommend'' tag.
* The initial copy has several modes, which allow to extract very small subsets.
* The embedded archive.

</div><div class="sect2">

=== Finetuning ===

<div class="paragraph">

The finetuning section allows to copy, move and delete files in the target root-filesystem. Additionally it is possible to run commands. Here is an example finetuning section:

</div><div class="listingblock"><div class="content">

<tt> '''<font color="#0000FF"><finetuning></font>'''
'''<font color="#0000FF"><rm></font>'''/usr/share/doc'''<font color="#0000FF"></rm></font>'''
'''<font color="#0000FF"><mv</font>''' <font color="#009900">path</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"/var"</font>'''<font color="#0000FF">></font>'''/var_ro'''<font color="#0000FF"></mv></font>'''
'''<font color="#0000FF"><cp</font>''' <font color="#009900">path</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">/copy/me</font>'''<font color="#0000FF">></font>'''/my/name/on/target'''<font color="#0000FF"></mv></font>'''
'''<font color="#0000FF"></finetuning></font>'''</tt>

</div></div><div class="sidebarblock"><div class="content"><div class="title">Note</div><div class="paragraph">

The copy, mv, and rm commands operate on full directories.

</div></div></div><div class="sidebarblock"><div class="content"><div class="title">Advanced Copy</div><div class="paragraph">

To copy files from the buildimage into the target image, the <tt><command></tt> tag can be used. The current directory is the target.

</div><div class="paragraph">

For example to copy <tt>/etc/passwd</tt> from the buildenvironment into the target, the following command can be used:

</div><div class="paragraph">

<tt><command>cp /etc/passwd etc/ </command></tt>

</div></div></div></div><div class="sect2">

=== Useful directories to trim with finetuning ===

<div class="paragraph">

This section provides some useful directories that can safely be removed, and which generate big space savings:

</div><div class="listingblock"><div class="content">

<tt>'''<font color="#0000FF"><finetuning></font>'''
'''<font color="#0000FF"><rm></font>'''/usr/share/doc'''<font color="#0000FF"></rm></font>''' (1)
'''<font color="#0000FF"><rm></font>'''var/cache/apt/archives/*'''<font color="#0000FF"></rm></font>''' (2)
'''<font color="#0000FF"><rm></font>'''var/cache/apt/pkgcache.bin'''<font color="#0000FF"></rm></font>'''
'''<font color="#0000FF"><rm></font>'''var/cache/apt/srcpkgcache.bin'''<font color="#0000FF"></rm></font>'''
'''<font color="#0000FF"><rm></font>'''var/lib/apt/lists/*_Release'''<font color="#0000FF"></rm></font>'''
'''<font color="#0000FF"><rm></font>'''var/lib/apt/lists/*_Packages'''<font color="#0000FF"></rm></font>'''
'''<font color="#0000FF"><rm></font>'''var/lib/apt/lists/*_Sources'''<font color="#0000FF"></rm></font>'''

'''<font color="#0000FF"><rm></font>'''boot'''<font color="#0000FF"></rm></font>''' (3)

'''<font color="#0000FF"><rm></font>'''lib/modules/2.6.32-5-versatile/'''<font color="#0000FF"></rm></font>''' (4)
'''<font color="#0000FF"><rm></font>'''var/cache/man/*'''<font color="#0000FF"></rm></font>''' (5)
'''<font color="#0000FF"><rm></font>'''opt/elbe'''<font color="#0000FF"></rm></font>''' (6)
'''<font color="#0000FF"><rm></font>'''var/cache/debconf/*'''<font color="#0000FF"></rm></font>''' (7)
'''<font color="#0000FF"></finetuning></font>'''</tt>
</div></div><div class="colist arabic">

{|
|
(1)
| The doc file are not necessary.
|-
|
(2)
| The apt cache can be downloaded, when necessary.
|-
|
(3)
| The boot directory contains the kernel used for the VM. On embedded targets this is generally loaded through u-boot.
|-
|
(4)
| The kernel modules for the standard debian kernel.
|-
|
(5)
| The man page cache
|-
|
(6)
| The full copy mode, will also copy elbe onto the root-filesystem.
|-
|
(7)
| debconf cache is also not necessary
|}

</div></div><div class="sect2">

===Archive===

<div class="paragraph">

It’s also possible to include an archive into the xml file, that is unpacked into the target root-filesystem after the finetuning step. This archive must be a bzip2 compressed tar (.tar.bz2) and the following command can be used to embed the archive into the xml file:

</div><div class="listingblock"><div class="content">

<tt>elbe chg_archive <xmlfile> archive.tar.bz2</tt>

</div></div><div class="paragraph">

This feature is useful to place custom configuration-files into the final image.

</div></div></div></div><div class="sect1">

==Slimming the root filesystem with the different modes==

<div class="sectionbody"><div class="paragraph">

The copying process has several modes. The mode is configured in the ''target'' tag. It needs to be the tag before ''finetuning''.

</div><div class="paragraph">

The following commented example illustrates where the mode is configured.

</div><div class="listingblock"><div class="content">

<tt> '''<font color="#0000FF"><target></font>'''
'''<font color="#0000FF"><hostname></font>'''example'''<font color="#0000FF"></hostname></font>'''
'''<font color="#0000FF"><domain></font>'''example.com'''<font color="#0000FF"></domain></font>'''
'''<font color="#0000FF"><passwd></font>'''foo'''<font color="#0000FF"></passwd></font>'''
'''<font color="#0000FF"><package></font>'''
'''<font color="#0000FF"><tar></font>'''nfsroot.tar.gz'''<font color="#0000FF"></tar></font>'''
'''<font color="#0000FF"></package></font>'''

'''<font color="#0000FF"><diet</font>''' '''<font color="#0000FF">/></font>''' (1)

'''<font color="#0000FF"><norecommend</font>''' '''<font color="#0000FF">/></font>''' (2)

'''<font color="#0000FF"><finetuning</font>''' \'''<font color="#0000FF">></font>'''
'''<font color="#0000FF"><pkg-list></font>'''
'''<font color="#0000FF"><pkg></font>'''bash'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"></pkg-list></font>'''

'''<font color="#0000FF"></target></font>'''</tt>

</div></div><div class="colist arabic">

{|
|
(1)
| The mode is configured at this place, leaving it out, enables the default mode.
|-
|
(2)
| ''norecommend'' should be placed here.
|}

</div><div class="sect2">

===norecommend===

<div class="paragraph">

''norecommend'' disables installation of recommended packages. This is a frequent cause for big root-filesystems. Installed programs will still work, but some functionality requiring external programs might be disabled.

</div><div class="sidebarblock"><div class="content"><div class="title">Note</div><div class="paragraph">

This is not strictly a mode as described in the following paragraphs. It can be combined with any of them, and the following modes are mutually exclusive.

</div></div></div></div><div class="sect2">

===default===

<div class="paragraph">

The default mode generates a full copy of the build image. This mode is the easiest to use, but its not possible to generate images which have the debian package management removed.

</div></div><div class="sect2">

===setsel===

<div class="paragraph">

The setsel mode can be used to generate images which only contain ''dpkg'', and offers a more fine-grained control on which packages are installed.

</div><div class="paragraph">

The recommended usage is as follows:

</div><div class="ulist">

* Generate an image in the default mode.
* Run the image and use aptitude to purge unwanted packages.
* Maybe even use dpkg to remove apt and aptitude.
* Then generate the list of selected Packages using <tt>dpkg --get-selections > selections.list</tt>
* Transfer this file to the host System.
* Use <tt>elbe setsel <xmlfile> selections.list</tt> to import the pkg-list into the xml file.
* Rebuild using setsel mode.

</div><div class="sidebarblock"><div class="content"><div class="title">How it works</div><div class="paragraph">

The setsel mode works by feeding the pkg list to <tt>dpkg --set-selections</tt> in the target image copy. It has the advantage that we do not have to cope with some unregistered configuration files.

</div></div></div></div><div class="sect2">

===diet===

<div class="paragraph">

Diet Mode only copies the files that are referenced in the Package management. It resolves the dependencies so that one does not need to reference library packages.

</div><div class="sidebarblock"><div class="content"><div class="title">But</div><div class="paragraph">

Some packages rely on files generated in the post-inst scripts, which are not tracked by the package management. Work is in progress to execute the post-inst scripts in the target copy, but we are still facing some problems with corner-cases, when dependencies of these scripts get removed in the ''finetuning''.

</div><div class="paragraph">

This also holds for the ''tighten'' mode.

</div></div></div></div><div class="sect2">

===tighten===

<div class="paragraph">

Tighten mode only extracts the files referenced by the packages in ''pkg-list''. No dependencies are resolved. This mode is intended for compatibility with old xml files, do not use in new elbe projects.

</div></div></div></div><div class="sect1">

==XML Reference==

<div class="sectionbody"><div class="paragraph">

This section is a step by step rundown of the arm example.

</div><div class="paragraph">

The xml file starts with the following header, which should always be the same:

</div><div class="listingblock"><div class="content">

<tt>'''<font color="#0000FF"><ns0:RootFileSystem</font>''' <font color="#009900">xmlns:ns0</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"https://www.linutronix.de/projects/Elbe"</font>
<font color="#009900">xmlns:xsi</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"http://www.w3.org/2001/XMLSchema-instance"</font>
<font color="#009900">created</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"2009-05-20T08:50:56"</font> <font color="#009900">revision</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"4"</font>
<font color="#009900">xsi:schemaLocation</font><font color="#990000"><nowiki>=</nowiki></font><font color="#FF0000">"https://www.linutronix.de/projects/Elbe dbsfed.xsd"</font>'''<font color="#0000FF">></font>'''</tt>

</div></div><div class="paragraph">

After this Header follows the project description.

</div><div class="listingblock"><div class="content">

<tt> '''<font color="#0000FF"><project></font>'''
'''<font color="#0000FF"><name></font>'''ARMexample'''<font color="#0000FF"></name></font>'''
'''<font color="#0000FF"><version></font>'''08.15'''<font color="#0000FF"></version></font>'''
'''<font color="#0000FF"><mirror></font>'''
'''<font color="#0000FF"><primary_host></font>'''debian.tu-bs.de'''<font color="#0000FF"></primary_host></font>''' (1)
'''<font color="#0000FF"><primary_path></font>'''/debian'''<font color="#0000FF"></primary_path></font>'''
'''<font color="#0000FF"><primary_proto></font>'''http'''<font color="#0000FF"></primary_proto></font>'''
'''<font color="#0000FF"><url-list></font>''' (2)
'''<font color="#0000FF"><url></font>'''
'''<font color="#0000FF"><binary></font>'''http://192.168.1.2/custom/pkgs ./'''<font color="#0000FF"></binary></font>'''
'''<font color="#0000FF"></url></font>'''
'''<font color="#0000FF"></url-list></font>'''

'''<font color="#0000FF"></mirror></font>'''
'''<font color="#0000FF"><noauth</font>''' '''<font color="#0000FF">/></font>''' (3)
'''<font color="#0000FF"><suite></font>'''squeeze'''<font color="#0000FF"></suite></font>''' (4)</tt>

</div></div><div class="colist arabic">

{|
|
(1)
| The ''mirror'' tag contains ''primary_host'', ''primary_path'' and ''primary_proto''. It describes the debian mirror used.
|-
|
(2)
| The ''url-list'' can contain additional binary package sources.
|-
|
(3)
| The ''noauth'' tag can be used to disable authentication, when custom unsigned packages, are supposed to be installed.
|-
|
(4)
| The suite also controls which kernel and initrd is downloaded with the elbe dl_kernel` command. It also selects the distribution codename used from the primary mirror.
|}

</div><div class="sidebarblock"><div class="content"><div class="title">Note</div><div class="paragraph">

We did not close the ''project'' tag yet.

</div></div></div><div class="paragraph">

The following section describes the virtual machine in which the debian installer will run, and where we want to build our custom packages in.

</div><div class="listingblock"><div class="content">

<tt> '''<font color="#0000FF"><buildimage></font>'''
'''<font color="#0000FF"><arch></font>'''armel'''<font color="#0000FF"></arch></font>''' (1)
'''<font color="#0000FF"><size></font>'''20G'''<font color="#0000FF"></size></font>''' (2)
'''<font color="#0000FF"><mem></font>'''256'''<font color="#0000FF"></mem></font>''' (3)
'''<font color="#0000FF"><interpreter></font>'''qemu-system-arm'''<font color="#0000FF"></interpreter></font>''' (4)
'''<font color="#0000FF"><console></font>'''ttyAMA0,115200n1'''<font color="#0000FF"></console></font>''' (5)
'''<font color="#0000FF"><machine></font>'''versatilepb'''<font color="#0000FF"></machine></font>''' (6)
'''<font color="#0000FF"><NIC></font>'''
'''<font color="#0000FF"><model></font>'''smc91c111'''<font color="#0000FF"></model></font>'''
'''<font color="#0000FF"><MAC></font>'''de:ad:be:ef:be:05'''<font color="#0000FF"></MAC></font>'''
'''<font color="#0000FF"></NIC></font>'''
'''<font color="#0000FF"><portforwarding></font>''' (7)
'''<font color="#0000FF"><forward></font>'''
'''<font color="#0000FF"><proto></font>'''tcp'''<font color="#0000FF"></proto></font>'''
'''<font color="#0000FF"><buildenv></font>'''22'''<font color="#0000FF"></buildenv></font>'''
'''<font color="#0000FF"><host></font>'''5022'''<font color="#0000FF"></host></font>'''
'''<font color="#0000FF"></forward></font>'''
'''<font color="#0000FF"></portforwarding></font>'''
'''<font color="#0000FF"><pkg-list></font>''' (8)
'''<font color="#0000FF"></pkg-list></font>'''
'''<font color="#0000FF"></buildimage></font>'''
'''<font color="#0000FF"></project></font>'''</tt>

</div></div><div class="colist arabic">

{|
|
(1)
| ''arch'' is the debian architecture of the target.
|-
|
(2)
| ''size'' is the size of the hard-disk image.
|-
|
(3)
| ''mem'' controls the amount of RAM that is allocated to the virtual machine.
|-
|
(4)
| The ''interpreter'' is either ''qemu-system-<arch>'' or ''qemu-kvm''. Usage of kvm is usually only possible, when the target is ''x86''.
|-
|
(5)
| The ''console'' line needs special attention, because it is different on different emulation targets.
|-
|
(6)
| The ''machine'' tag contains the ''-machine'' parameter, that is provided to qemu.
|-
|
(7)
| ''portforwarding'' of network server ports from the virtual machine to the host. This example forwards the ssh port to port 5022 on the host.
|-
|
(8)
| This is the package list of buildimage.
|}

</div><div class="sidebarblock"><div class="content"><div class="title">Note</div><div class="paragraph">

Our advice is to only change the sizes of hard-disk and RAM, if thats necessary. The other values come correctly configured in the example files.

</div><div class="paragraph">

We provide examples for arm, powerpc and x86.

</div></div></div><div class="listingblock"><div class="content">

<tt> '''<font color="#0000FF"><target></font>'''
'''<font color="#0000FF"><hostname></font>'''myARM'''<font color="#0000FF"></hostname></font>''' (1)
'''<font color="#0000FF"><domain></font>'''tec.linutronix.de'''<font color="#0000FF"></domain></font>''' (2)
'''<font color="#0000FF"><passwd></font>'''foo'''<font color="#0000FF"></passwd></font>''' (3)
'''<font color="#0000FF"><console></font>'''ttyS0,115200'''<font color="#0000FF"></console></font>'''
'''<font color="#0000FF"><package></font>'''
'''<font color="#0000FF"><tar></font>'''
'''<font color="#0000FF"><name></font>'''nfsroot.tar.gz'''<font color="#0000FF"></name></font>''' (4)
'''<font color="#0000FF"></tar></font>'''
'''<font color="#0000FF"></package></font>'''
'''<font color="#0000FF"><finetuning></font>''' (5)
'''<font color="#0000FF"></finetuning></font>'''
'''<font color="#0000FF"><pkg-list></font>''' (6)
'''<font color="#0000FF"><pkg></font>'''build-essential'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''bash'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''less'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''git'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''debhelper'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''nfs-common'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"><pkg></font>'''openssh-server'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"></pkg-list></font>'''
'''<font color="#0000FF"></target></font>'''</tt>

</div></div><div class="colist arabic">

{|
|
(1)
| The hostname
|-
|
(2)
| and domainname
|-
|
(3)
| This is the root password of the machine.
|-
|
(4)
| This describes, that the resulting rootfilesystem, shall be generated as ''nfsroot.tar.gz''
|-
|
(5)
| Empty finetuning section. Format of this section was already explained above.
|-
|
(6)
| The Packages list resides here.
|}

</div><div class="sect2">

===Building ubi images===

<div class="paragraph">

Elbe also has the ability to generate ubi images, including different partitions and mountpoints. Lets look at an example ''target'' section.

</div><div class="listingblock"><div class="content">

<tt>'''<font color="#0000FF"><target></font>'''
'''<font color="#0000FF"><hostname></font>'''myARM'''<font color="#0000FF"></hostname></font>'''
'''<font color="#0000FF"><domain></font>'''tec.linutronix.de'''<font color="#0000FF"></domain></font>'''
'''<font color="#0000FF"><passwd></font>'''foo'''<font color="#0000FF"></passwd></font>'''
'''<font color="#0000FF"><console></font>'''ttyS0,115200'''<font color="#0000FF"></console></font>'''

'''<font color="#0000FF"><images></font>'''
'''<font color="#0000FF"><mtd></font>'''
'''<font color="#0000FF"><name></font>'''linux.img'''<font color="#0000FF"></name></font>''' (1)
'''<font color="#0000FF"><nr></font>'''0'''<font color="#0000FF"></nr></font>'''
'''<font color="#0000FF"><size></font>'''60MB'''<font color="#0000FF"></size></font>'''
'''<font color="#0000FF"><ubivg></font>'''
'''<font color="#0000FF"><label></font>'''nand'''<font color="#0000FF"></label></font>'''
'''<font color="#0000FF"><miniosize></font>'''2048'''<font color="#0000FF"></miniosize></font>''' (2)
'''<font color="#0000FF"><maxlogicaleraseblockcount></font>'''1533'''<font color="#0000FF"></maxlogicaleraseblockcount></font>'''
'''<font color="#0000FF"><logicaleraseblocksize></font>'''126976'''<font color="#0000FF"></logicaleraseblocksize></font>'''
'''<font color="#0000FF"><physicaleraseblocksize></font>'''128KiB'''<font color="#0000FF"></physicaleraseblocksize></font>'''
'''<font color="#0000FF"><ubi></font>''' (3)
'''<font color="#0000FF"><type></font>'''static'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"><label></font>'''kernel'''<font color="#0000FF"></label></font>'''
'''<font color="#0000FF"><id></font>'''0'''<font color="#0000FF"></id></font>'''
'''<font color="#0000FF"><size></font>'''4MiB'''<font color="#0000FF"></size></font>'''
'''<font color="#0000FF"><binary></font>'''/boot/vmlinuz-2.6.33.9-rt31'''<font color="#0000FF"></binary></font>'''
'''<font color="#0000FF"></ubi></font>'''
'''<font color="#0000FF"><ubi></font>'''
'''<font color="#0000FF"><type></font>'''dynamic'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"><label></font>'''rfs'''<font color="#0000FF"></label></font>'''
'''<font color="#0000FF"><id></font>'''1'''<font color="#0000FF"></id></font>'''
'''<font color="#0000FF"><size></font>'''26MiB'''<font color="#0000FF"></size></font>'''
'''<font color="#0000FF"></ubi></font>'''
'''<font color="#0000FF"><ubi></font>'''
'''<font color="#0000FF"><type></font>'''dynamic'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"><label></font>'''data'''<font color="#0000FF"></label></font>'''
'''<font color="#0000FF"><id></font>'''2'''<font color="#0000FF"></id></font>'''
'''<font color="#0000FF"><size></font>'''30MiB'''<font color="#0000FF"></size></font>'''
'''<font color="#0000FF"></ubi></font>'''
'''<font color="#0000FF"></ubivg></font>'''
'''<font color="#0000FF"></mtd></font>'''
'''<font color="#0000FF"></images></font>'''

'''<font color="#0000FF"><fstab></font>''' (4)
'''<font color="#0000FF"><bylabel></font>''' (5)
'''<font color="#0000FF"><label></font>'''data'''<font color="#0000FF"></label></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/opt'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''ubifs'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"><mkfs></font>'''-x lzo'''<font color="#0000FF"></mkfs></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"><options></font>'''rw'''<font color="#0000FF"></options></font>'''
'''<font color="#0000FF"></bylabel></font>'''
'''<font color="#0000FF"><bylabel></font>'''
'''<font color="#0000FF"><label></font>'''rfs'''<font color="#0000FF"></label></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''ubifs'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"><mkfs></font>'''-x lzo'''<font color="#0000FF"></mkfs></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"><options></font>'''ro'''<font color="#0000FF"></options></font>'''
'''<font color="#0000FF"></bylabel></font>'''
'''<font color="#0000FF"><bydev></font>''' (6)
'''<font color="#0000FF"><<nowiki />source></font>'''proc'''<font color="#0000FF"></source></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/proc'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''proc'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"></bydev></font>'''
'''<font color="#0000FF"><bydev></font>'''
'''<font color="#0000FF"><<nowiki />source></font>'''sysfs'''<font color="#0000FF"></source></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/sys'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''sysfs'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"></bydev></font>'''
'''<font color="#0000FF"><bydev></font>'''
'''<font color="#0000FF"><<nowiki />source></font>'''tmpfs'''<font color="#0000FF"></source></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/tmp'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''tmpfs'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"><options></font>'''size=2M'''<font color="#0000FF"></options></font>'''
'''<font color="#0000FF"></bydev></font>'''
'''<font color="#0000FF"><bydev></font>'''
'''<font color="#0000FF"><<nowiki />source></font>'''tmpfs'''<font color="#0000FF"></source></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/var/log'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''tmpfs'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"><options></font>'''size=4M'''<font color="#0000FF"></options></font>'''
'''<font color="#0000FF"></bydev></font>'''
'''<font color="#0000FF"><bydev></font>'''
'''<font color="#0000FF"><<nowiki />source></font>'''tmpfs'''<font color="#0000FF"></source></font>'''
'''<font color="#0000FF"><mountpoint></font>'''/var/run'''<font color="#0000FF"></mountpoint></font>'''
'''<font color="#0000FF"><fs></font>'''
'''<font color="#0000FF"><type></font>'''tmpfs'''<font color="#0000FF"></type></font>'''
'''<font color="#0000FF"></fs></font>'''
'''<font color="#0000FF"><options></font>'''size=2M'''<font color="#0000FF"></options></font>'''
'''<font color="#0000FF"></bydev></font>'''
'''<font color="#0000FF"></fstab></font>'''

'''<font color="#0000FF"><finetuning></font>'''
'''<font color="#0000FF"></finetuning></font>'''
'''<font color="#0000FF"><pkg-list></font>'''
'''<font color="#0000FF"><pkg></font>'''dash'''<font color="#0000FF"></pkg></font>'''
'''<font color="#0000FF"></pkg-list></font>'''
'''<font color="#0000FF"></target></font>'''</tt>

</div></div><div class="colist arabic">

{|
|
(1)
| This specifies an mtd image with 60MB size whose filename is linux.img
|-
|
(2)
| Parameters for the ubi tools, describing the NAND geometry.
|-
|
(3)
| Specification of ubi volumes.
|-
|
(4)
| Because we are dealing with a root-filesystem split into more than one partition, we need to specify the fstab, so that everything can be copied into the right place.
|-
|
(5)
| Normal partition entries are by label.
|-
|
(6)
| Since we now create the target fstab ourselves, we also need to include the entries for ''/proc'', ''/sys'' etc. These can be generated with ''bydev'' nodes.
|}

</div></div></div></div>