Getting Started

In this section, we will take the first steps towards installing Toradex images with Toradex Easy Installer.

If Toradex Easy Installer is already flashed in your module (in most modules this is the factory default), the boot process should automatically load it into RAM. Otherwise, you can download a Toradex Easy Installer image and load it into the module's RAM either through a host computer, using recovery mode, or through an SD card / USB stick, using the Distro Boot mechanism (see the Load Toradex Easy Installer tab).

Displaying the GUI

on the Display Output

Once the Toradex Easy Installer is loaded into RAM, you should see a User Interface appearing on the DVI-I/HDMI, VGA or on the parallel RGB (Unified Interface Display) ports of your carrier board (obviously a display must be connected at that port). For the 2.0b1 release currently the default output is the DVI-I/HDMI port.

on a Remote Desktop

If you can't use any of these display options, you can access the user interface remotely over the network using VNC. For this, you should connect a USB cable to the USB / OTG port of your carrier board. The module provides a connection via USB RNDIS with the default IP address of 192.168.11.1. Alternatively you can use the IP address of the ethernet interface, which will depend on the DHCP server serving your LAN. Use your preferred VNC client to connect to this address. For example,

vncviewer 192.168.11.1

Providing the Images

To list images from the Internet, make sure that you connect Ethernet to a network which provides Internet access (the installer relies on DHCP to configure the IP address and HTTP to download images). After some seconds you should see a list of images appearing.

Alternatively, you can download a Toradex Easy Installer image from our website and unzip/untar it onto an SD Card or USB Flash Drive. Once you plug it into the target the images should appear in the list of available images with an icon indicating that it is an image found on a local storage device.

See the list of images available for download in the OS and Demo Images tab.

Warning: Please insert the SD card in X19 (SD/MMC 4 bit) if you are using Apalis TK1 with Apalis Evaluation Board

Installing the Images

To install an image, use a USB mouse to select and press the "Install (i)" button. You can also use a USB keyboard only: Use the arrows to select the image and press "i" to start the installation. Follow the instructions until installation begins. After the image has been successfully installed you should see the following message on your screen:

At this point, all data have been stored on internal flash and caches have been flushed (synced). It is not required to click on any of these three buttons, it is perfectly fine to just reset or turn off the system.

Also, it is good to remember that if you want to add more sources to Toradex Easy Installer (like adding your own server into it), make sure to hit Feeds button.

A simple test can be done by allowing the Toradex Continuous Integration Server (testing) option.

Load Toradex Easy Installer

The Toradex Easy Installer application runs completely in memory so that the complete internal flash can be erased, (re)partitioned, formatted or written. If your module does not boot to Toradex Easy Installer by default (for instance, it boots to Linux or WinCE instead), you will need to load it in memory from a host computer, using USB OTG in recovery mode.

Note: Please, carefully read the below to understand the setup of how to load TEZI into the module.

Remarks about the recovery mode (USB OTG) approach:

• You need a regular USB to micro USB, or USB to USB-C cable, and a carrier board that provides access to the USB OTG interface.
• There is no need to prepare an SD card or USB stick, you just need to run a loading script from your PC.
• It works with the computer on module in any software state, including a module with a corrupted bootloader or root filesystem.
• You just need access to the hardware. Access to the bootloader or operating system is not strictly required, though it may simplify putting the module in recovery-mode for some specific SoCs.

Note: The USB OTG approach establishes a connection between your development PC (Host) and the module (Client): A recovery script will be launched from your PC, which will automatically load and execute TEZI in the module. Note: For further clarification, what is saved in the module is irrelevant: TEZI is first saved in the PC, loaded from there and executed on the module's RAM.

Download Toradex Easy Installer

A stable version will be released after roughly six months after a beta is released, only if no issues are reported or open. Otherwise, there will be another beta release fixing any open or reported issues. See the revision history and roadmap for details:

• Toradex Easy Installer Revision History and Roadmap

Stable Release

Beta Release

Attention: Apalis iMX8 V1.0A is an early access product, it does not boot from the internal eMMC and therefore it isn't supported by the Toradex Easy Installer.

Use the latest version from the table below:

Unzip the Zip file in a local directory on a Windows or Linux host.

Nightly Release

Nightly builds are available from our artifacts server.

1. Navigate to the corresponding SoM release directory.
2. Right-click the directory, a sub-menu will appear.
3. Click on Download. A menu named Download Folder will show up.
4. Select the Archive Type.
5. Click on Download.

See our illustration below as an example:

Load Toradex Easy Installer From USB OTG

Enter recovery mode:

• iMX Recovery Mode, for SoMs based on NXP i.MX SoCs.
• Txx Recovery Mode, for SoMs based on NVIDIA Tegra SoCs.

After entering recovery mode, go to the folder unzipped from the file you downloaded at the beginning of the article and use one of the following scripts on the host machine to download and run the Toradex Easy Installer through USB (this does not write the Toradex Easy Installer to flash, it only loads it into the module's memory. You will have to redo these steps if you power off your module.):

• Windows: recovery-windows.bat
• Linux: recovery-linux.sh

Note: Apalis TK1 does not have a script for Windows. If you want to load Toradex Easy Installed on an Apalis TK1 module, refer to the next method.

If downloading gets stuck or fails with an error, try starting over from the recovery mode article. We have seen an issue with some USB 3.0 controllers during enumeration: If you use a USB 3.0 capable device, try connecting a USB 2.0 hub between the USB OTG port and your host.

Note: During the recovery process the module connected via USB re-enumerates three times. This might cause multiple device detections on Windows. It also does not work well through virtualization since the individual re-enumerated USB devices get not routed through to the virtual machine guest automatically.

Please refer to the Production Programming for Linux article in order to learn more about the best methods to use Toradex Easy Installer for Production Programming.

Detailed Manual

The Toradex Easy Installer application runs completely in memory so that the complete internal flash can be erased, (re-)partitioned, formatted or written to. The image to be flashed can be obtained over the Internet (via Ethernet), from a USB Flash Drive or an SD card.

Security Statement

The Toradex Easy Installer allows for connecting to the module by, amongst other things, un-protected VNC as well as a serial console that provides root access without a password. Please connect Toradex modules running the Toradex Easy Installer only to safe networks, especially during production.

Getting the Images

Toradex provides ready-made images which can be downloaded directly using Toradex Easy Installer's Internet capabilities or as zip/tar files which can be extracted to a USB Flash Drive/SD Card. You can also install your own images as long as you package them in the Toradex Easy Installer format - see the Configuration Files tab for more information about it.

Note: If you build an image with our Yocto based BSP you can find an image in the Toradex Easy Installer format under build/deploy/images/MACHINE/IMAGE-MACHINE-TIMESTAMP-Tezi_VERSION-DATE.tar. You can untar this file to an USB stick and follow the section "From the Local Media".

From the Toradex Image Servers

The Toradex Easy Installer runs a DHCP client on the Ethernet port. As soon as the image gets an IP address assigned, the module will try to download a list of images from the Toradex image server (using HTTP). In case this fails (e.g. due to missing DNS server or standard Gateway) an error will be shown. Make sure that your DHCP provides a complete Network configuration which allows Internet access. To force a new DHCP request you can unplug and replug the Ethernet cable.

From the Local Media

The Toradex Easy Installer continuously monitors external devices. As soon as the Kernel detects a new device, the installer will try to mount all partitions and scan for images. The images will be detected by the description JSON file named image.json (see Image Format below). After scanning all directories the media will get unmounted so that users can safely unplugging the device after scanning. If the user unplugs the device, the images will disappear from the list of available images. Since only metadata are read at this time, it is required to keep the media plugged in in case an image from that media shall be installed.

Supported file systems are ext2/3/4, FAT and NTFS.

• USB Flash Drives: USB Flash Drive (USB mass storage device class) devices connected to the USB Host or OTG port
• SD Card: SD cards plugged in any standard SD card port are supported.

The Links to download Toradex Easy installer images are available in the Load Toradex Easy Installer tab.

From a Local Web Server

You can set up any local web server in the same network as the computer on module to provide images locally via the network. There should be a JSON file named image_list.json that contains the path to all Toradex Easy installer images and their respective image.json files. See our own server as an example:

• image_list.json example

You will also need to enable a custom feed using your IP address and path to the image_list.json file, as illustrated further down on feeds.

A comprehensive example useful during production is also provided below in the section Unattended Flashing Over Ethernet, where you can skip manually adding your custom server address.

From a Local Web Server Announced via Zeroconf

Starting with Tezi 2.0b4 the Toradex Easy Installer is able to use Zeroconf to find an image server feeds on the local network. You need to set up a web server that self announces itself via Zeroconf. Combined with autoinstall this allows to automatically install images from a local server without any manual intervention.

To announce a Toradex Easy Installer image server add an AVAHI service to /etc/avahi/services with the following content:

 tezi.service
<?xml version="1.0" standalone='no'?><!--*-nxml-*-->
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name replace-wildcards="yes">Custom Toradex Easy Installer Feed</name>
  <service>
    <type>_tezi._tcp</type>
    <port>80</port>
    <txt-record>name=Custom Toradex Easy Installer Feed</txt-record>
    <txt-record>path=/path/image_list.json</txt-record>
    <txt-record>enabled=1</txt-record>
    <txt-record>https=0</txt-record>
  </service>
</service-group>

When setting the parameter autoinstall: true in your image.json stored on the server, the image will automatically be installed.

Note: All boards running the Toradex Easy Installer being connected to a network with a Zeroconf server and an image set up for autoinstall, will begin to install such an image automatically. You should avoid doing this during development if you share a network with colleagues that also might be booting their boards running the Toradex Easy Installer.

Usage

By default, the Toradex Easy Installer displays on VGA, parallel RGB and HDMI/DVI-D (mirror mode) with a resolution of 640x480 (VGA display timings). Additionally, the GUI can be accessed via VNC, either over Ethernet (IP address depends on your DHCP server) or via USB Device virtual Ethernet Link (RNDIS) on IP 192.168.11.1. The GUI can be controlled by any USB keyboard/mouse or via VNC. If an unattended installation is required an auto install mode is available too (see chapter Auto Installation).

Install (i)

After selecting the image you wish to install, the "Install" button starts the installation. If the image is obtained through a network, some metadata will get downloaded first (such as Release Notes, License text, prepare and wrap-up scripts). After accepting License and Release Notes, the block devices will be prepared (partitioned/formatted) as specified and the data to be written will be downloaded and unpacked in one step. Since this step is done in one step (multiple commands connected through pipes) the image size can exceed the modules main memory capacity.

Note: In case any step during Installation fails, an error message will be shown and the option to go back to the main menu will be shown. At this point, it is likely that the Toradex Easy Installer is no longer stored on the internal flash (e.g. due to repartitioning). Hence it is recommended to retry flashing the same image or install the Toradex Easy Installer so another retry can be made later.

At this point, all data are stored on internal flash and caches are flushed (synced). It is not required to click on any of this three buttons, it is perfectly fine to just reset or turn off the system.

Refresh (r)

This button will reload the image list obtained over the network. It might be useful if you use custom feed servers that you frequently update or that you are using for testing purposes.

Feeds (f)

This button allows you to enable or add more sources for Toradex Easy Installer images in the form of feed servers. On the standard image, it’s possible to enable Toradex's testing repositories. You can also add your own feed server with your custom images by using the input form in the feeds window.

Click on the Feeds button, you can test by allowing the Toradex Continuous Integration Server (testing) for example.

Mass Storage (u)

This button allows exporting the internal flash as USB mass storage (eMMC based devices only). This can be used after flashing an image to transfer additional files manually or examine the data written to internal flash. Currently, this exports three disks: The eMMC main user partition (read/write) and the two eMMC boot partitions (read-only).

Note: This is only available if RNDIS has been disabled.

RNDIS (n)

RNDIS provides a USB Device virtual Ethernet Link (RNDIS). The USB RNDIS mode is enabled by default which allows users without a display to still use the Toradex Easy Installer. The module will run a DHCP server on the link so that the host computer connected to the module will receive an IP address automatically. The module has the IP on 192.168.11.1 assigned statically.

Depending on your Windows version it might be necessary to manually install the driver. Via Device Manager, right-click and select "Update Driver...", choose the "Microsoft Corporation" "Remote NDIS Compatible Device" driver.

Erase Flash (c)

Erase flash erases all modules internal flash. The Toradex config block is automatically recreated after the operation.

For eMMC devices it uses blkdiscard and the eMMC controller is notified to discard data of all blocks, hence the complete device will appear as empty (all zeros).

For raw NAND devices, the whole flash is erased, including wear leveling information.

Exit (Esc)

Reboots the module.

License

Shows the License information for the Qt-based UI. Note that external utilities are part of the Toradex Easy Installer which are licensed under a different Licenses. Refer to the files stored under /usr/share/common-licenses/ and /usr/share/common-licenses/license.manifest for an overview.

Auto Installation

To automatically install an image, the image can be marked as "auto install" image using the autoinstall property in the image.json file. If that property is set to true the image will be flashed to the module automatically and unattended. This can be useful for production programming. Any image can carry the autoinstall property. If multiple regular images have the property set to true the outcome will depend on the order of how images get processed. There is no guaranteed order, so it is recommended to only use one local media with only one image having the autoinstall property set to true.

To allow automatically updating the Toradex Easy Installer, those images are treated somewhat differently: All Toradex Easy Installer images have the isinstaller property set to true. If the autoinstall property is set to true too, this image will be processed before any other images from the same media. The Toradex Easy Installer will first check the image version against the version number of the running version. If the image is newer, the installer image will be installed first and the system automatically rebooted. Once the newer version of the Toradex Easy Installer is running, the version check will make sure that the installer image is not processed a second time. If there is a regular image with autoinstall property set to true available, this will be installed now. This allows to automatically upgrade the Toradex Easy Installer before an image gets installed, which is useful when a image has a newer config format and hence requires a newer Toradex Easy Installer.

Note: The Toradex Easy Installer does not automatically install a Toradex Easy Installer, if the version is older or equal.
To force automatic installation anyway, the following line needs to be modified in the image.json file:
"isinstaller": false,.

Auto Reboot

After flashing has finished, the same dialog as with regular flashing will be shown. This is useful for the operator to know that the image has been successfully installed. Note that although there are options to interact, there is no interaction needed: The operator can safely turn off the module at that point. If an automatic reboot is required, the wrapup_script can be extended with the reboot command:

 wrapup.sh
...
reboot -f
exit 0

Writing into a removable medium (SD/USB/SATA)

If your wrapup.sh script is located in a removable medium such as an SD card or a USB stick (as opposed to being retrieved from the network), such medium is mounted by default in read-only mode. If you want to use the script to write into the medium, you should remount it first:

 wrapup.sh
...
mount -o remount,rw /run/media/src

# Write operations here

exit 0

Note: Note that if you want to write into the medium and plan to auto-reboot the system afterward by means of a reboot -f command, you should first unmount it to avoid data corruption. This is however problematic, since the wrapup script is in the mounted partition already. Make sure you sync your data before reboot.

Upgrading Toradex Easy Installer

If an image is not compatible with the current running Toradex Easy Installer (the config_format is higher than the supported format), then the image won't be considered for automatic installation. One can provide a new version of the Toradex Easy Installer alongside with the autoinstall property set to true too. If the currently running Toradex Easy Installers version is older than the provided installer (determined using the version and isinstaller property`), then the new Toradex Easy Installer will be installed first. This behavior allows to automatically upgrade the Toradex Easy Installer before installing the final image. It is useful if a newer installer is required to install the image.

This screenshot shows this situation: The grayed out image requires a newer Toradex Easy Installer. Happily, there is a 1.5 version available. Both images can safely carry the autoinstall property since the Toradex Easy Installer only updates itself if the version is newer then the current version.

Speed improvements flashing Linux images

The main part of Linux images (the boots/rootfs files) is compressed using the LZMA2 algorithm (xz files). The format offers relatively high decompression speed and high compression ratio. However, if the image is read from a high bandwidth source the flashing process is limited by the decompression speed (CPU). The decompression utility xz does not offer multi-threaded decompression, hence it is limited to a single CPU. On a Cortex A7@1GHz (Colibri iMX7) the average decompression speed has been measured to be around 8.4MB/s.

Using xz is a good compromise if the image is downloaded over the Internet or otherwise relatively slow connection. Local media such as SD cards or USB flash drive offer much higher bandwidth. It is often faster to store the image uncompressed as a tar file in those cases. Measurements have shown up to 3 times faster flash times (e.g. 7s instead of 21s to extract/write a 130MB root file system). Currently, the OpenEmbedded image class does not offer to create uncompressed images. To convert a regular image to an uncompressed image, simply decompress the *.rootfs.tar.xz and *.boots.tar.xz files using xz -d and make sure the filename properties in the images descriptor file image.json points to the unpacked *.tar files.

Further speed improvements might be obtainable by using pre-built file system images and the raw file writing capabilities of Toradex Easy Installer. This method has not been evaluated by Toradex yet.

Unattended flashing over Ethernet

The Toradex Easy Installer can be used to flash images from an HTTP web server. Using a configuration file as described in the Configuration Format chapter in the Configuration Files tab the Toradex Easy Installer can read the images from a custom/local URL.

Note: Without a local media there is currently no way to provide the Installer with a custom URL. There exists a workaround documented further below.

Example configuration

The requirements on the PC side are:

• Linux PC (e.g. Ubuntu)
• dnsmasq (for DNS approach below)
• nginx
• Host side IP address 192.168.10.1 (can be changed)
• Tested with Toradex Easy Installer 1.4 (earlier versions may work as well)

Make sure you have a nginx configuration that looks as follows:

 /etc/nginx/sites-available/default
server {
   listen 80 default_server;
   listen [::]:80 default_server;
   root /var/www/html;
   index index.html index.htm index.nginx-debian.html;
   server_name _;
   location / {
       try_files $uri $uri/ =404;
   }
}

Make sure that /etc/nginx/sites-enabled/default links to the file /etc/nginx/sites-available/default:

sudo ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default

Now you can create a image list JSON file that looks as follows (example for Apalis TK1):

 /var/www/html/image_list.json
{ 
 "config_format": 1, 
 "images": [ 
   "apalis_tk1/image.json" 
 ] 
} 

Make a directory /var/www/html/apalis_tk1 to store your Tezi image along with all required files. Set the autoinstall flag to true:

 image.json
{
   "autoinstall": true,
...
}

Make sure that you restart nginx:

sudo systemctl restart nginx

Once the Toradex Easy Installer boots it should automatically flash the image provided on your web server. If you need log information, add them to prepare.sh and wrapup.sh. You can, for example, use the nc command for sending log files over Ethernet.

Custom Image Server without Local Media

The Toradex Easy Installer always tries to load an image_list.json from the hard-coded URL http://tezi.toradex.com/image_list.json. Using a custom DNS server one can redirect tezi.toradex.com to a local production PC.

Redirecting DNS can be easily done using Dnsmasq. This example shows how to use Dnsmasq as a DHCP and DNS server to serve the module an IP address and provides a custom DNS server pointing tezi.toradex.com to the production PC as well:

 /etc/dnsmasq.conf
interface=<network interface>
dhcp-range=192.168.10.50,192.168.10.150,12h # Use different IPs if needed
address=/tezi.toradex.com/192.168.10.1 # Use IP address of your network interface

Make sure you restart Dnsmasq:

sudo systemctl restart dnsmasq

Note: Make sure you set your host IP to 192.168.10.1 or to the IP you configured under address in dnsmasq.conf. Verify that no other DHCP or DNS server is running on your system or local network.

Once the Toradex Easy Installer boots it should connect using HTTP to the IP specified to download the image list and consequently install the image from the local web server.

Configuration Files

The Toradex Easy Installer makes use of JSON files. If required, the files can be edited using a plain text editor. However, care must be taken not to violate the JSON specification. To make sure the JSON file is still well formatted an online JSON validator can be useful (e.g. jsonlint.com).

Image Format

The image is described in a JSON image file. Toradex provides images with a proper JSON image file. However, depending on the use case you might need to alter the JSON image file e.g. to add an additional partition. The easiest way is to take an existing image.json file and alter it accordingly.

This chapter lists the available properties and how they get interpreted by the Toradex Easy Installer.

The JSON consists of a single root dictionary with several mandatory properties (*=Mandatory). An image can define its configuration format. Newer configurations support more features but require a newer Toradex Easy Installer version.

Block Devices

Each blockdev entry has a name and either a partitions or content node or both. In case using partition table and (raw) content, the Toradex Easy Installer will first create the partition table and then write the content according to the specification. Make sure that partition table created and data written do not conflict!

Partition

If partitions are specified, the installer will create an MBR/DOS-style partition table. Currently, only primary partitions are supported. All partition will be aligned to 4 megabyte boundaries (8192 blocks). A partition specification knows the following properties:

MTD Devices

Each blockdev entry has a name and either a content, ubivolumes or winceimage node.

UBI volume

WinCE image

The WinCE image section allows writing a WinCE image in the sparse file format to raw NAND (uses the utility flash-wince).

Common

Content

For block devices, content can either be raw data (dd-style) or a file system.

For MTD device, content can only be raw data (uses Linux nandwrite command).

For UBI volume, content can either be raw data (uses Linux ubiupdatevol command) or ubifs.

Raw Files

*=Mandatory property

Example

This is a typical example derived from a standard Linux image.json file: It creates the usual two partition layout, a FAT partition for the Kernel/Device Trees and an ext3 partition for the root file system. An additional third partition has been added to create a location for user data. The filename or filelist property can be used to pre-install user/application data.

{
    "config_format": 1, 
    "autoinstall": true, 
    "name": "Toradex Embedded Linux BSP using LXDE desktop", 
    "description": "Toradex Embedded Linux BSP using LXDE desktop.", 
    "version": "V2.6.1", 
    "release_date": "2016-10-13", 
    "prepare_script": "prepare.sh", 
    "wrapup_script": "wrapup.sh", 
    "marketing": "marketing.tar", 
    "icon": "toradexlinux.png", 
    "supported_product_ids": [
        "0027", 
        "0028", 
        "0029", 
        "0035"
    ], 
    "blockdevs": [
        {
            "name": "mmcblk0", 
            "partitions": [
                {
                    "partition_size_nominal": 16, 
                    "want_maximised": false,
                    "content": {
                        "uncompressed_size": 4, 
                        "filesystem_type": "FAT", 
                        "filename": "Apalis_iMX6_LinuxImage.bootfs.tar.xz", 
                        "mkfs_options": "", 
                        "label": "BOOT"
                    }
                }, 
                {
                    "partition_size_nominal": 512, 
                    "want_maximised": false,
                    "content": {
                        "uncompressed_size": 300, 
                        "filesystem_type": "ext3", 
                        "filename": "Apalis_iMX6_LinuxImage.rootfs.tar.xz", 
                        "mkfs_options": "", 
                        "label": "RFS"
                    }
                }, 
                {
                    "partition_size_nominal": 512, 
                    "want_maximised": true,
                    "content": {
                        "filesystem_type": "ext3",
                        "label": "DATA"
                    }
                }
            ]
        }, 
        {
            "name": "mmcblk0boot0"
            "content": {
                "filesystem_type": "raw",
                "rawfiles": [
                    {
                        "filename": "SPL",
                        "dd_options": "seek=2"
                    },
                    {
                        "filename": "u-boot.imx",
                        "dd_options": "seek=138"
                    }
                ]
            },
        }
    ]
}

Image List Format

Images loaded from an HTTP server need an index file which points to the individual images. The file name is typically image_list.json, but it can be anything. A local HTTP server needs such an image list file to point to the individual images.

This example points to two images, which are located in the directories Apalis_iMX6_LinuxImage_V2.6.2 and Apalis_iMX6_LinuxConsoleImage_V2.6.2 relative to the location of this index file:

{
  "config_format": 1,
  "images": [
    "Apalis_iMX6_LinuxImage_V2.6.2/image.json",
    "Apalis_iMX6_LinuxConsoleImage_V2.6.2/image.json"
  ]
}

Configuration Format

The Toradex Easy Installer configuration file allows adding additional HTTP image sources. The configuration file needs to be named tezi_config.json and located on the root of any partition on a supported external storage media (SD card or USB flash drive). This allows extending the search locations for image lists beyond the pre-configured Toradex servers, e.g. to distribute images in a local network or over RNDIS.

{
  "config_format": 1,
  "image_lists": [
     "http://192.168.10.2:8008/image_list.json"
  ]
}

Partial Updates

​ This tab shows how to update single components (kernel, device-tree, U-Boot and rootfs) when in development. The Toradex Easy Installer was not designed as a tool that provides partial updates, therefore the following options will be covered: ​

• TFTP/NFS server boot setup: for kernel/device-tree/rootfs development
• Universal Update Utility (uuu): for U-Boot development on i.MX-based modules
• ReCovery Mode (rcm): for U-Boot development on Tegra-based modules ​

TFTP/NFS Server

​ This setup allows for rapid development cycles, since the target board retrieves the kernel and device-tree through the network from a TFTP server and the rootfs from an NFS server, both running on the development PC. To get started with FTFP/NFS server development, follow the links to: ​

• How To Setup Networking for Embedded Linux Application Development
• Boot From a TFTP/NFS Server ​

Universal Update Utility (uuu)

​ This tool (also known as mfgtools 3.0) is provided by NXP and it is used to load U-Boot into the RAM of the module for recovery purposes. You can learn how to set it up and use it, along with some examples, on the official documentation, which is quite good. This is compatible with i.MX-based modules. ​

ReCovery Mode (rcm)

​ This tool, provided by NVIDIA, sends code to a Tegra module in Recovery Mode. The tool can be downloaded from its official repository, which also contains some guides. It is compatible with Tegra-based modules.

Custom Boot

Sometimes special boot parameters need to be passed to Toradex Easy Installer. On all modules, the Toradex Easy Installer tries to boot from SD card first using U-Boots "distroboot" scripts. As a secondary boot device, Toradex Easy Installer will boot from on-module flash, either via custom scripts (for raw NAND based devices) or using "distroboot" script on the first internal partition (for modules using eMMC).

Distro Boot is a default boot script in U-Boot which searches for a script file named boot.scr or boot.scr.uimg in the root and in the folder boot of the SD card. If the script is present, it is loaded from the media and executed. The regular Toradex Easy Installer zip file contains a valid boot.scr, hence it can be unpacked and moved to the root of an SD card. For more details about distroboot refer to the documentation in doc/README.distro of the U-Boot source tree.

To change kernel boot parameter one should use the regular boot.scr file as a template.

There are some custom kernel arguments which are read by the Toradex Easy Installer:

Custom Script For Capacitive Multi-touch 7"

This is an example of a boot script which uses fdt commands to dynamically customize the device tree. In this particular example the already existing but disabled node atmel_mxt_ts is enabled by setting the status property to true. Since Toradex Easy Installer makes use of a FIT image, which contains kernel, device tree and the rootfs (squashfs), bootm start need to be used to split the booting using FIT image into two parts so that the device tree can be altered in between.

 boot.cmd
# Set timings for 7" multitouch
setenv bootargs console=ttymxc0,115200 quiet video=mxcfb0:dev=lcd,FusionF07A,if=RGB666 rootfstype=squashfs root=/dev/ram autoinstall fullscreen ${teziargs}

# Reenable fdt relocation since in place fdt edits corrupt the ramdisk
# in a FIT image...
setenv fdt_high

# Load FIT image from location as detected by distroboot
load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} ${prefix}tezi.itb

bootm start ${ramdisk_addr_r} && bootm loados && bootm ramdisk && bootm fdt

# Enable capacitive multitouch driver
fdt set /soc/aips-bus@02100000/i2c@021a8000/atmel_mxt_ts@4a status okay

bootm prep && bootm go

Then create a U-Boot script image:

mkimage -A arm -O linux -T script -C none -a 0 -e 0 -n "Distro boot script" -d boot.cmd boot.scr

This script placed into the root of an SD card, alongside the Toradex Easy Installer for Colibri iMX6 binaries, will make sure that the Toradex Easy Installer is properly displayed and touch-enabled when using the Capacitive Multi-touch 7" display.

Creating an extra MTD partition on raw NAND Flash

For creating an extra MTD partition you need to pass the new partition as boot parameters for the kernel:

mtdparts=gpmi-nand:512k(mx6ull-bcb),1536k(u-boot1),1536k(u-boot2),1024k(splash),512k(u-boot-env),-(ubi)

This can be done by changing the files boot.scr and boot.sdp.scr.

Troubleshoot

Some possible issues and workarounds are described in this section.

Enumeration Issue during Recovery

The Toradex Easy Installer SPL/U-Boot bootloader re-enumerates as different USB devices during recovery mode. Sometimes this leads to an issue, resulting in an error message like:

Downloading Toradex Easy Installer...
Could not open device vid=0x1b67 pid=0x4fff
 
Downloading Toradex Easy Installer failed...

If you are using the Ixora Carrier Board, make sure that X9 is configured in OTG mode (remove JP2).

If the issue still persists, try a different cable, using a none-USB3 port, or connect a USB hub between your Host and the device.

Serial Console

There is a serial console available on UART1/UART_A. The main UI process is /usr/bin/tezi. A log file which contains all debug output of the UI is available in the file /var/volatile/tezi.log. To show the current content of the log file using the cat command:

cat /var/volatile/tezi.log

To kill the UI, use:

killall tezi

(note this does not clear the framebuffer, hence the last state of the UI will remain visible)

To manually restart the UI use the following command (overwriting the standard input is essential, otherwise Qt re-configures the connected tty which is fatal for the serial console):

/usr/bin/tezi -qws < /dev/null

Download Halts or Aborts

Behind some firewalls download of images might slow down or even stop with an error message:

curl: (56) Recv failure: Connection reset by peer

Some firewalls have issues with TCP window scale option. This can be disabled using

sysctl -w "net.ipv4.tcp_window_scaling=0"

Boot Arguments

The Toradex Easy Installer boot scripts start with a fixed set of Linux kernel parameters. However, it also appends any variables defined in teziargs. Since the Toradex Easy Installer builds on top of Linux, any Linux arguments can be used such as debug to get the full Kernel debug output.

Create Image

There are two entirely different situations:

• Create a custom image of the OS to be installed on the board - e.g. TorizonCore, Yocto-based image, and possibly other OSs - with the aid of Toradex Easy Installer. You can either:
  • Create an image from an existing installation. Follow the article How to Clone Embedded Linux on eMMC Based Toradex Modules.
  • Create an image with OpenEmbedded - the build system used by Yocto - which automatically generates an image in the Toradex Easy Installer format. Follow the article OpenEmbedded (core).
• Create a modified image of Toradex Easy Installer itself, with a modified kernel/device tree or roots. For such a scenario, keep on reading to understand how to do it.

Modify the Toradex Easy Installer Image

To create a modified Toradex Easy Installer image we need the following:

• Latest Toradex Easy Installer
• Extracted tezi.itb
• u-boot-tools installed (apt-get install u-boot-tools)

We first extract the current TEZI configuration:

$ dumpimage -l tezi.itb

This should look similar to this:

FIT description: Toradex Easy Installer for Colibri iMX6
Created:         Fri Oct 19 16:14:21 2018
 Image 0 (kernel@1)
  Description:  Linux Kernel 4.1
  Created:      Fri Oct 19 16:14:21 2018
  Type:         Kernel Image
  Compression:  uncompressed
  Data Size:    5097296 Bytes = 4977.83 KiB = 4.86 MiB
  Architecture: ARM
  OS:           Linux
  Load Address: 0x11000000
  Entry Point:  0x11000000
  Hash algo:    md5
  Hash value:   8c6222f12fcc545df9eb6d06ebd488ab
 Image 1 (ramdisk@1)
  Description:  SquashFS RAMdisk
  Created:      Fri Oct 19 16:14:21 2018
  Type:         RAMDisk Image
  Compression:  uncompressed
  Data Size:    15667200 Bytes = 15300.00 KiB = 14.94 MiB
  Architecture: ARM
  OS:           Linux
  Load Address: unavailable
  Entry Point:  unavailable
  Hash algo:    md5
  Hash value:   eba56bc828c9e3c21604c521e968a541
 Image 2 (fdt@1)
  Description:  Colibri iMX6 Device Tree
  Created:      Fri Oct 19 16:14:21 2018
  Type:         Flat Device Tree
  Compression:  uncompressed
  Data Size:    45520 Bytes = 44.45 KiB = 0.04 MiB
  Architecture: ARM
  Hash algo:    md5
  Hash value:   cd0cc8dcbf9082218ffc4498613cc416
 Default Configuration: 'config@1'
 Configuration 0 (config@1)
  Description:  Toradex Easy Installer for Colibri iMX6
  Kernel:       kernel@1
  Init Ramdisk: ramdisk@1
  FDT:          fdt@1

We now have to create a file tezi.its and add the addresses according to what we received from dumpimage:

Warning: Make sure that the "load" and "entry" address values in the section below are enclosed with < >. For example if the load address was 0x11000000, the line would look like: "load = <0x11000000>; " (without quotation marks)

/dts-v1/;
 
/ {
    description = "U-Boot fitImage for Toradex Easy Installer";
    #address-cells = <1>;
 
    images {
        kernel@0 {
            description = "Linux Kernel";
            data = /incbin/("./zImage");
            type = "kernel";
            arch = "arm";
            os = "linux";
            compression = "none";
            load = <replace with address from dumpimage>;
            entry = <replace with address from dumpimage>;
            hash@1 {
                algo = "md5";
            };
        };
        fdt@0 {
            description = "Flattened Device Tree blob";
            data = /incbin/("./system.dtb");
            type = "flat_dt";
            arch = "arm";
            compression = "none";
            hash@1 {
                algo = "md5";
            };
        };
        ramdisk@0 {
            description = "Ramdisk Image";
            data = /incbin/("./ramdisk");
            type = "ramdisk";
            arch = "arm";
            os = "linux";
            compression = "none";
            hash@1 {
                algo = "md5";
            };
        };
    };
    configurations {
        default = "config@1";
        config@1 {
            description = "Boot Linux kernel with FDT blob + ramdisk";
            kernel = "kernel@0";
            fdt = "fdt@0";
            ramdisk = "ramdisk@0";
            hash@1 {
                algo = "md5";
            };
        };
    };
};

Now we can start to extract all images that we later need to repack:

$ dumpimage tezi.itb -T flat_dt -p 0 -o zImage
$ dumpimage tezi.itb -T flat_dt -p 1 -o ramdisk
$ dumpimage tezi.itb -T flat_dt -p 2 -o system.dtb

Now that we have all parts of the original image available we can replace the ones we want to change (e.g. the devicetree "system.dtb"). After that we can repack the fit image with the command:

$ mkimage -f tezi.its tezi_new.itb

tezi_new.itb can be used as a new Toradex Easy Installer image.