Quick Start¶

This page will guide you through the process of building and running a Welma image on one of the supported hardware platform.

System Requirements¶

Yocto Project System Requirements
- Make sure you have enough space available on disk (100GB minimum), enough RAM, and have Yocto's required packages installed
envsubst (usually provided by a gettext- subpackage)

Choose a machine¶

Set the MACHINE variable for the hardware you want to use (and WELMA_REF for the Yocto branch), which can be one of the following:

export MACHINE=de-next-rap8-x86               WELMA_REF=scarthgap-next
export MACHINE=dh-stm32mp13-dhcor-dhsbc-welma WELMA_REF=scarthgap-next
export MACHINE=hbjc386f951t-x86               WELMA_REF=scarthgap-next
export MACHINE=k393x-mini-x86                 WELMA_REF=scarthgap-next
export MACHINE=imx8mm-cgt-sx8m-rev-a          WELMA_REF=scarthgap-next
export MACHINE=qemuarm-welma                  WELMA_REF=scarthgap-next
export MACHINE=raspberrypi4-64-welma          WELMA_REF=scarthgap-next
export MACHINE=sm2s-imx8plus-mbep5            WELMA_REF=scarthgap-next
export MACHINE=sm2s-imx93-mbep5               WELMA_REF=scarthgap-next
export MACHINE=stm32mp25-disco-welma          WELMA_REF=scarthgap-next

(see also the Supported Features page to find out in which versions are supported the chosen hardware)

Download Yocto Layers¶

Set Welma's GitLab namespace to the required value:

# Remember to change the namespace and branch if you were provided with different instructions
export WELMA_GIT_NAMESPACE=witekio/rnd/theembeddedkit/welma

Download Yocto layers:

git clone git@gitlab.com:${WELMA_GIT_NAMESPACE}/welma-manifest.git
welma-manifest/setup-download welma-manifest/${WELMA_REF}/manifest-${MACHINE}.txt

The next sections are hardware specific, pick the one that applies to your platform.

Run on QEMU ARM¶

These instructions provide a quick-start guide to run Welma on QEMU using qemuarm.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-qemuarm/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Start the system in a Qemu emulator:
```
runqemu nographic
```
You should see U-Boot and Linux start, and the login prompt:
```
[...]
Welma by Witekio x.y.z qemuarm-welma

qemuarm-welma login:
```

Notes

When using nographic, press ctrl-a h to show the help, and ctrl-a x to quit.

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more information, see QEMU target page.
Or have a look at the Next steps

Run on a Raspberry Pi 4B¶

These instructions provide a quick-start guide to run Welma on a Raspberry Pi 4B.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-raspberrypi/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

If your Raspberry Pi 4B board is not in secure mode (ie: has no PBKH fused), disable secure boot support in the image:
```
echo 'WELMA_SECURE_BOOT="0"' >> conf/local.conf
```
Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Copy the generated WIC image to the SD card (for example /dev/mmcblk0).
```
SDDEV=<sdcard-device>
SDIMG=tmp/deploy/images/$MACHINE/welma-image-minimal-dev-$MACHINE.wic
gunzip --keep --force $SDIMG.gz
sudo dd if="$SDIMG" of="$SDDEV" bs=1M
```
Warning

Make sure that the of= parameter is correct before running the command, dd will irreversibly override the targeted device and any data it contains.
Insert the SD card in the SD slot of the board
Power up the board
Connect an Ethernet cable between your PC and the board
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more details on Raspberry Pi 4B, see page Raspberry Pi 4B
Or have a look at the Next steps

Run on a MSC SM2S-IMX8PLUS¶

These instructions provide a quick-start guide to run Welma on MSC's SM2S-IMX8PLUS board, with a EP5 motherboard.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-sm2s-imx8/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Install on eMMC. The big steps are:
- Install imx-boot on the SD card and boot the board from the SD card
- Transfer the image to the board via TFTP and install it on eMMC
- Select boot mode from eMMC
Reset the board
Connect an Ethernet cable between your PC and the board
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```

Notes

The image is intended to be installed on eMMC, not on SD card, as some paths inside the filesystem refer to /dev/mmcblk2 (eMMC) and not /dev/mmcblk1 (SD card).

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more details on SM2S IMX8PLUS, see page MSC SM2S IMX8PLUS.
Or have a look at the Next steps

Run on an MSC SM2S-IMX93¶

These instructions provide a quick-start guide to run Welma on MSC's SM2S-IMX93 board, with an EP5 motherboard.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-sm2s-imx9/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Install on eMMC. The big steps are:
- Upload and start imx-boot onto the board using uuu
- Transfer the image to the board via TFTP and install it on eMMC
Reset the board
Connect an Ethernet cable between your PC and the board
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```

Notes

The image is intended to be installed on eMMC, not on SD card, as some paths inside the filesystem refer to /dev/mmcblk0 (eMMC) and not /dev/mmcblk1 (SD card).

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more details on SM2S IMX93, see page MSC SM2S IMX93.
Or have a look at the Next steps

Run on a DHSBC-STM32MP13¶

These instructions provide a quick-start guide to run Welma on DHSBC-STM32MP13 board.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-dh-stm32mp/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Install on eMMC. The big steps are:
- Select boot mode DFU with the DIP switch
- Upload and start TF-A, then U-Boot onto the board using dfu-util
- Transfer the images to the board via TFTP and install them on eMMC
Select boot mode eMMC with the DIP switch
Power up the board
Connect an Ethernet cable between your PC and the ETH1 port of the board
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more details and other booting mehods (DFU, eMMC, TFTP...), see page DHSBC-STM32MP13.

Run on a STM32MP257F-DK¶

These instructions provide a quick-start guide to run Welma on ST's STM32MP257F-DK board.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-stm32mp25/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Copy the generated WIC image to the SD card, say /dev/mmcblk0.
```
SDDEV=<sdcard-device>
SDIMG=tmp/deploy/images/$MACHINE/welma-image-minimal-dev-$MACHINE.wic
gunzip --keep --force $SDIMG.gz
sudo dd if="$SDIMG" of="$SDDEV" bs=1M
```
Warning

Make sure that the of= parameter is correct before running the command, dd will irreversibly override the targeted device and any data it contains.
Insert the SD card in the SD slot of the board
Set the boot mode switches of the mother board to select booting from SD card
- BOOT0 ON
- BOOT1 OFF
- BOOT2 OFF
- BOOT3 OFF
Power up the board
Connect an Ethernet cable between your PC and the ETH2 ethernet port in your board
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more details and other booting mehods (DFU, eMMC, TFTP...), see page STM32MP257F-DK.

Run on a CONGA SMX8 MINI¶

These instructions provide a quick-start guide to run Welma on CONGA SMX8 MINI board.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-congatec-imx/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Install on eMMC. The big steps are:
- Set SW4.1 (or SW5) recovery switch to ON
- Upload imx-boot onto the board and have it running
- Transfer the image to the board via TFTP and install it on NOR and eMMC
- Set SW4.1 (or SW5) recovery switch to OFF
Reset the board
Connect an Ethernet cable between your PC and the board
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```

You successfully ran Welma! You can log in with either root or user, and an empty password.

For more details on CONGA SMX8 MINI, see page CONGA SMX8 MINI.
Or have a look at the Next steps

Run on an Intel Jetway JBC386F951T, Kontron K393-Nx or De next-RAP8¶

These instructions are a quick-start guide to running Welma on Jetway JBC386F951T, Kontron K393-Nx or De next-RAP8 boards.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-intel/conf/templates/$MACHINE

Adjust WELMA_GIT_NAMESPACE (if you modified its default value):

echo "WELMA_GIT_NAMESPACE = \"$WELMA_GIT_NAMESPACE\"" >> conf/site.conf

Build the minimal Welma image for developers:
```
bitbake welma-image-minimal-dev
```
Plug the target's boot device into the host machine and install the .wic image file (see K393-Nx Machine , JBC386F951T Machine or NEXT-RAP8 Machine)
Insert device into target board
Power up the board
Enter the BIOS menu and select the Welma boot device. If no other boot entry exists on your system, the bios will automatically choose the Welma device. (see K393-Nx Machine , JBC386F951T Machine or NEXT-RAP8 Machine)
Connect an Ethernet cable between your host machine and the board.
Set up the corresponding network interface of your PC (say eth0).
Connect to the board:
```
ssh root@fe80::1%eth0
```
You successfully ran Welma! You can log in with either root or user, and an empty password.
After installing each new Welma build in the board's boot device using the host machine, the board will reboot at the first startup to update the BIOS environment.
For more details on Jetway JBC386F951T, see the page Jetway JBC386F951T
For more details on Kontron K393-Nx, see the page Kontron K393-Nx.
For more details on De next-RAP8, see the page De next-RAP8.
Or have a look at the Next steps

Next steps¶

Now that you have Welma running, you can:

Learn more about How to use Welma
Look at the Headless application demo
Look at the Graphical application demo