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=kirkstone-next
export MACHINE=hbjc386f951t-x86           WELMA_REF=kirkstone-next
export MACHINE=k393x-mini-x86             WELMA_REF=kirkstone-next
export MACHINE=imx8mm-cgt-sx8m-rev-a      WELMA_REF=kirkstone-next
export MACHINE=maaxboard-8ulp-welma       WELMA_REF=kirkstone-next
export MACHINE=qemuarm-welma              WELMA_REF=kirkstone-next
export MACHINE=raspberrypi4-64-welma      WELMA_REF=kirkstone-next
export MACHINE=sm2s-imx8plus-mbep5        WELMA_REF=scarthgap-next
export MACHINE=sm2s-imx93-mbep5           WELMA_REF=scarthgap-next
export MACHINE=stm32mp15-disco-welma      WELMA_REF=kirkstone-next
export MACHINE=stm32mp25-disco-welma      WELMA_REF=scarthgap-next
export MACHINE=tungsten-700-smarc-welma   WELMA_REF=kirkstone-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

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 STM32MP15-DISCO¶

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

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-stm32mp15/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
- BOOT2 ON
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 STM32MP15-DISCO, see page STMP32MP15.

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 ethernt port in your board
Set up the corresponding network interface of your PC (say eth2).
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 MediaTek Tungsten700¶

Quick start on this board:

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-boundary-mtk/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
```
This will generate 3 files: 1- WIC Image (.wic.img) 2- BL2 Image (bl2.img) 3- Little Kernel Image used as a bootstrap for flashing the eMMC (lk.bin)
Download the bootrom-tool utility and extract it in the deployment directory

$ cd ./build/tmp/deploy/images/tungsten-700-smarc-welma$ 
$ wget http://linode.boundarydevices.com/mediatek/tungsten700-recovery.zip
$ unzip tungsten700-recovery.zip

- Put SW1 Dip Switch to the ON position, then connect the OTG TypeC USB port. - Power on the board, you should see a “Mediatek” device show up in “lsusb”

$ lsusb
...
Bus 001 Device 059: ID 0e8d:0003 MediaTek Inc. MT6227 phone
...

- Run the bootrom-tool

$ ./bootrom-tool 
Looking for MediaTek SoC matching USB device 0e8d:0003
Opening /dev/ttyACM0 using baudrate=115200
Connected to MediaTek SoC: hw_code[0x8188]
Sending bootstrap to address: 0x201000
Jumping to bootstrap at address 0x201000 in AArch64 mode

After running the tool, you should now see the device show up under “lsusb” as “MediaTek Inc. Fastboot”
```
$ lsusb
...
Bus 001 Device 076: ID 0e8d:201c MediaTek Inc. Fastboot
...
```

Erase the eMMC, program the BL2 and the Wic image

$ fastboot flash mmc0boot0 bl2.img
$ fastboot erase mmc0
$ fastboot flash mmc0 welma-image-minimal-dev-tungsten-700-smarc-welma.wic.img

Power off the board, Put SW1 Dip Switch to the OFF position and power on the board again
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

You can log in with username root or user, and an empty password.

For more details on MediaTek Tungsten700, see page MediaTek Tungsten700

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

Run on a Maaxboard 8ULP¶

These instructions provide a quick-start guide to run Welma on Maaxboard 8ULP.

Set up your build environment:

source meta-welma/setup/setup-build-env meta-welma-maaxboard/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 all switch to OFF and Switch 4 (BT_ MODE0) to ON
- Upload imx-boot onto the board and have it running
- Transfer the image to the board via TFTP and install it on the eMMC
- Set all switch to OFF and Switch 5 (BT_ MODE1) to On
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 Maaxboard 8ULP, see page Maaxboard 8ULP.
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