Search by Tags

Toradex Easy Installer

 

Note: Please try our new Toradex Easy Installer - feedback welcome!
Please note that Toradex Easy Installer will be the default pre-installed Software for Colibri iMX6, Colibri iMX7, Apalis iMX6, Apalis T30, Apalis TK1 and all newer modules in the future. These changes will be communicated through PCNs for each product. You will find the PCNs in the revision history section of our product pages

The Toradex Easy Installer is a Linux-based application that provides a graphical selection of Operating System images that users may choose to install onto the internal flash memory of Toradex modules in an extremely simple way.




Toradex Easy Installer is also suitable for fully automated volume production programming as it allows for no-touch installation of custom images.


 

Partner Demo Images

Among the options presented in Toradex Easy Installer, there are partner demo images available for evaluation of different technologies and solutions. Please check the Partner Demo Images for more information or go to a specific partner demo image page from the table below:

           Partner Demo Image Supported Modules Summary Overview
Built with Qt Qt Company Boot to Qt Software Stack Apalis iMX6
Colibri iMX6
Colibri iMX7
Colibri iMX6ULL
Light-weight, Qt-optimized, full software stack for embedded Linux systems
MVTec Embedded vision MVTec Software GmbH MVTec Embedded Vision HPeek Demo Apalis iMX6
Apalis TK1
The essence of MVTec HALCON's key features and performance, ease of use in Machine Vision
Mender & Toradex Mender.io Mender Easy Installer Colibri iMX7 Secure and robust Over The Air update manager solution for connected embedded Linux devices
DiSTI GL Studio easy installer DiSTI Corporation DiSTI GL Studio Easy Installer Colibri iMX6 DiSTI's technology of GL Studio showcased in a UI with the look and feel of automotive design
TES 3D Surround View TES Eletronic Solutions TES 3D Surround View Apalis iMX6 3D representation of a vehicle driver assistance system based on the input of cameras, GPU optimized
ITTIA DB SQL for Device Data Management Demo ITTIA ITTIA DB SQL for Device Data Management Colibri iMX6
Colibri iMX6ULL
Interactive relational database utilities and management system for intelligent embedded systems

Toradex Embedded Linux Images

Toradex provides an Embedded Linux BSP, including OS image releases. For further details, please visit the Linux software cover page. The list of images available from Toradex Easy Installer are provided below:

Toradex Embedded Linux Stable Releases

OS Image Supported Modules/Download Link Summary Overview
Tux Linux LXDE Image Apalis T30
Apalis iMX6
Colibri iMX6
Colibri iMX7 Solo 256MB/Dual 512MB
Colibri iMX7 Dual 1GB (eMMC)
Angstrom LXDE desktop environment image

Toradex Embedded Linux Beta Releases

OS Image Supported Modules/Download Link Summary Overview
Tux Linux LXDE Image Apalis TK1
Apalis TK1 Mainline
Apalis T30
Apalis iMX6
Colibri iMX6
Colibri iMX6ULL (only for devices with 512MB NAND flash)
Colibri iMX7 Solo 256MB/Dual 512MB
Colibri iMX7 Dual 1GB (eMMC)
Angstrom LXDE desktop environment image
Tux Linux Console Image Colibri iMX6ULL Linux Image without graphical user interface
Tux Linux For Tegra Image Apalis TK1 Ubuntu GNOME desktop environment based on NVIDIA L4T
Tux Jetpack Linux For Tegra Image Apalis TK1 Ubuntu GNOME desktop environment based on NVIDIA L4T with NVIDIA support for a set of tools to develop Artificial Intelligence and Computer Vision applications

Toradex Windows Embedded Compact Images

Toradex provides a Windows Embedded Compact (WEC) BSP, including OS image releases. For further details, please visit the Windows Embedded Compact (WEC) software cover page. The list of images available from Toradex Easy Installer are provided below:

Toradex WEC Stable Releases

OS Image Supported Modules/Download Link Summary Overview
WinCE WEC 7 Apalis/Colibri iMX6
Colibri iMX7 Solo 256MB/Dual 512MB
Windows Embedded Compact 7
WinCE WEC 2013 Apalis/Colibri iMX6
Colibri iMX7 Solo 256MB/Dual 512MB
Windows Embedded Compact 2013

Toradex WEC Beta Releases

OS Image Supported Modules/Download Link Summary Overview
WinCE WEC 7 Apalis/Colibri iMX6
Colibri iMX7 Solo 256MB/Dual 512MB
Windows Embedded Compact 7
WinCE WEC 2013 Apalis/Colibri iMX6
Colibri iMX7 Solo 256MB/Dual 512MB
Windows Embedded Compact 2013

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

Note: Make sure to check the other tabs that explain more features that Toradex Easy Installer has to offer, like autoinstallation.

If you wish to use Toradex Easy Installer on a module where it is not pre-installed, you can download Toradex Easy Installer and use recovery mode (see the Load Toradex Easy Installer tab).

If Toradex Easy Installer is already pre-installed, see Install Images section directly below.

Install Images

You should see a User Interface appearing on DVI-I/HDMI, VGA or on the parallel RGB (Unified Interface Display) port. If you can't use any of these display options, you can access the user interface remotely over the network using VNC. If you still have USB OTG connected the module provides a connection via USB RNDIS. The modules default IP address on USB RNDIS is 192.168.11.1.

To install images directly over 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.


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 this three buttons, it is perfectly fine to just reset or turn off the system.

Offline Deployment

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

Load Toradex Easy Installer

Module Download
Apalis iMX6 Toradex Easy Installer
Apalis T30 Toradex Easy Installer
Apalis TK1 Toradex Easy Installer
Colibri iMX6 Toradex Easy Installer
Colibri iMX6ULL Toradex Easy Installer
Colibri iMX7 Toradex Easy Installer

Toradex Easy Installer Revision History and Roadmap

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

Apalis iMX6

  1. Connect the Carrier Board USB OTG port to your Linux or Windows host machine

    • Apalis Evaluation Board

      Connect X49 or X50 (USBO1_CL/USBO1)

    • Ixora Carrier Board

      Connect to X9 on the underside of the Carrier Board. Be sure to remove JP2 in order to be able to use X9 in OTG Client mode.

  2. Enter recovery mode in one of this two ways:

    • Using hardware mechanism

      • Make sure the board is turned off.
      • Shorten the pads on the picture (e.g with tweezers) or if you have the Apalis iMX6 Mezzanine on the Apalis Evaluation Board, press the Recovery Mode button.


      • Power on the board.

    • Using a command in the bootloader

      • Connect the serial port UART1 of the carrier board with your host computer.

        • Apalis Evaluation Board

          Depending on JP10/12 connect the serial debug console to the lower X28 using a null modem RS-232 cable or X29 using a regular USB cable.

        • Ixora Carrier Board

          Connect the serial debug console to X22 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).

      • Open a terminal on your host computer (115200 baud, 8 data bits, no parity, one stop, no hardware/software flow control).

      • Power cycle the board and immediately press [space] on the terminal

      • If you are using U-Boot you should see the U-Boot banner and the prompt Apalis iMX6 #, in this case, type on the U-Boot command line:

        bmode usb
        
      • If you are using Eboot you should see a menu, in this case, type 'X' to enter the bootloader console, then on the Eboot command line:

        bootfrom usb
        reboot
        
  3. Use one of the following scripts on the host machine to download and run the Toradex Easy Installer through USB:

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

Apalis T30

Note: Currently only Linux hosts are supported for the recovery process.

  1. Connect the Carrier Board USB OTG port to your Linux host machine

    • Apalis Evaluation Board

      Connect X49 or X50 (USBO1_CL/USBO1)

    • Ixora Carrier Board

      Connect X9 on the underside of the Carrier Board. Be sure to remove JP2 to be able to use X9 in OTG Client mode.

  2. Enter recovery mode in one of this two ways:

    • Using hardware mechanism

      • Make sure the board is turned off.
      • Shorten the pads on the picture (e.g with tweezers).


      • Power on the board.

    • Using a command in the bootloader

      • Connect the serial port UART1 of the carrier board with your host computer.

        • Apalis Evaluation Board

          Depending on JP10/12 connect the serial debug console to the lower X28 using a null modem RS-232 cable or X29 using a regular USB cable.

        • Ixora Carrier Board

          Connect the serial debug console to X22 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).

      • Open a terminal on your host computer (115200 baud, 8 data bits, no parity, one stop, no hardware/software flow control).

      • Power cycle the board and immediately press [space] on the terminal

      • You should see the U-Boot banner and the prompt Apalis T30 #, type on the U-Boot command line:

        enterrcm
        
  3. Use the following script on the host machine to download and run the Toradex Easy Installer through USB:

    • Linux: recovery-linux.sh

Apalis TK1

Note: Currently only Linux hosts are supported for the recovery process.

  1. Connect the Carrier Board USB OTG port to your Linux host machine

    • Apalis Evaluation Board

      Connect X49 or X50 (USBO1_CL/USBO1)

    • Ixora Carrier Board

      Connect X9 on the underside of the Carrier Board. Be sure to remove JP2 to be able to use X9 in OTG Client mode.

  2. Enter recovery mode in one of this two ways:

    • Using hardware mechanism

      • Make sure the board is turned off.
      • Shorten the pads on the picture (e.g with tweezers).


      • Power on the board.

    • Using a command in the bootloader

      • Connect the serial port UART1 of the carrier board with your host computer.

        • Apalis Evaluation Board

          Depending on JP10/12 connect the serial debug console to the lower X28 using a null modem RS-232 cable or X29 using a regular USB cable.

        • Ixora Carrier Board

          Connect the serial debug console to X22 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).

      • Open a terminal on your host computer (115200 baud, 8 data bits, no parity, one stop, no hardware/software flow control).

      • Power cycle the board and immediately press [space] on the terminal

      • You should see the U-Boot banner and the prompt Apalis TK1 #, type on the U-Boot command line:

        enterrcm
        
  3. Use the following script on the host machine to download and run the Toradex Easy Installer through USB:

    • Linux: recovery-linux.sh

Colibri iMX6

  1. Connect the Carrier Board USB OTG port to your Linux or Windows host machine

    • Colibri Evaluation Board

      Connect X29 or X30 (USB_CL/USB_OTG)

    • Iris Carrier Board

      Connect X12 micro USB (close to the Ethernet connector)

  2. Make sure that no SD card is in the SD card slot

  3. Enter recovery mode in one of this two ways:

    • Using hardware mechanism

      • Make sure the board is turned off.
      • Shorten the pads on the picture (e.g with tweezers).


      • Power on the board.

    • Using a command in the bootloader

      • Connect the serial port UART_A of the carrier board with your host computer.

        • Colibri Evaluation Board

          Depending on JP17/19 (and JP20/JP21 if you use a Carrier Board with V3.2 and later) connect the serial debug console to the bottom X25 using a null modem RS-232 cable or X27 using a regular USB cable.

        • Iris Carrier Board

          Connect the serial debug console to X13 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).

      • Open a terminal on your host computer (115200 baud, 8 data bits, no parity, one stop, no hardware/software flow control).

      • Power cycle the board and immediately press [space] on the terminal

      • If you are using U-Boot you should see the U-Boot banner and the prompt Colibri iMX6 #, in this case, type on the U-Boot command line:

        bmode usb
        
      • If you are using Eboot you should see a menu, in this case, type 'X' to enter the bootloader console, then on the Eboot command line:

        bootfrom usb
        reboot
        
  4. Use one of the following scripts on the host machine to download and run the Toradex Easy Installer through USB:

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

Colibri iMX6ULL

Note: Colibri iMX6ULL 512MB Wi-Fi/Bluetooth are only supported by Toradex Easy Installer 1.3 and newer.

  1. Connect the Carrier Board USB OTG port to your Linux or Windows host machine

    • Colibri Evaluation Board

      Connect X29 or X30 (USB_CL/USB_OTG)

    • Iris Carrier Board

      Connect X12 micro USB (close to the Ethernet connector)

  2. Make sure that no SD card is in the SD card slot

  3. Enter recovery mode in one of this two ways:

    • Using hardware mechanism

      • Colibri Evaluation Carrier Board

        • Make sure the board is turned off.
        • Press and hold the Recovery Mode button.
        • Power on the board while keep pressing the Recovery Mode button for additional 1-2 seconds.
      • Other Colibri Carrier Boards

        • Make sure the board is turned off.
        • Shorten the pads on the picture (e.g with tweezers).

        • Power on the board.
    • Using a command in the bootloader

      • Connect the serial port UART_A of the carrier board with your host computer.

        • Colibri Evaluation Board

          Depending on JP17/19 (and JP20/JP21 if you use a Carrier Board with V3.2 and later) connect the serial debug console to the bottom X25 using a null modem RS-232 cable or X27 using a regular USB cable.

        • Iris Carrier Board

          Connect the serial debug console to X13 using a null modem RS-232 cable and a 10 pin IDC to 9 pin D-sub male connector (DTK or Intel standard).

      • Open a terminal on your host computer (115200 baud, 8 data bits, no parity, one stop, no hardware/software flow control).

      • Power cycle the board and immediately press [space] on the terminal

      • If you are using U-Boot you should see the U-Boot banner and the prompt Colibri iMX6ULL #, in this case, type on the U-Boot command line:

        bmode usb
        
  4. Use one of the following scripts on the host machine to download and run the Toradex Easy Installer through USB:

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

Colibri iMX7

Note: Colibri iMX7 Solo/Dual 256/512MB V1.1A and older are not supported by Toradex Easy Installer.

Note: Colibri iMX7 Dual 1GB V1.1A and newer are using an eMMC flash and are supported by Toradex Easy Installer 1.2, 1.3 and 1.6 or newer.
Toradex Easy Installer 1.4 and 1.5 did now work reliably with these modules.

  1. Connect the Carrier Board USB OTG port to your Linux or Windows host machine

    • Colibri Evaluation Board

      Connect X29 or X30 (USB_CL/USB_OTG)

    • Iris Carrier Board

      Connect X12 micro USB (close to the Ethernet connector)

  2. Make sure that no SD card is in the SD card slot

  3. Enter recovery mode:

    • Colibri Evaluation Carrier Board

      • Make sure the board is turned off.
      • Press and hold the Recovery Mode button.
      • Power on the board while keep pressing the Recovery Mode button for additional 1-2 seconds.
    • Other Colibri Carrier Boards

      • Make sure the board is turned off.
      • Shorten the pads on the picture (e.g with tweezers).


      • Power on the board.

  4. Use one of the following scripts on the host machine to download and run the Toradex Easy Installer through USB:

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

General

If downloading gets stuck or fails with an error, try starting over from step 2. 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: 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.

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.

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

Image Sources

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.

Internet

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.

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 Getting Started section (chapter Install Images).

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 UI 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 graphical user interface 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.

Feeds (f)

This button allows you to enable or add more sources for Toradex Easy Installer images. On the standard image, it’s possible to enable Toradex' testing repositories. You can also add your own feed with your custom images.

Mass Storage (u)

This button allows exporting the internal flash as USB mass storage (eMMC based devices only). One can use this 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 using blkdiscard (eMMC only). The eMMC controller will be notified to discard data of all blocks, hence the complete device will appear as empty (all zeros).

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 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.

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


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 a reboot is required behavior is required, the wrapup_script can be extended with the reboot command:

wrapup.sh
... reboot -f exit 0

Toradex Easy Installer Upgrade

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

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.

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 to not 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.

Configuration Format Minimum Toradex Easy Installer Version
1 1.0 or newer
2 1.4 or newer
Property Type Description
config_format* Integer The image configuration format
autoinstall Boolean Automatically install image upon image detection (defaults to false). For more information refer to the Auto Installation section.
name* String Name of the image (as displayed in the image list)
description String Description of the image (will be shown as ToolTip of the image)
version String Version of the image, mostly informational character except if isinstaller is true, see below
release_date String ISO 8601 date format, only informational character
u_boot_env (>=1.4) String U-Boot environment file to write. Use a regular text file with one variable/value pair per line with an equal sign after the variable name (variable=value). If there is already a valid U-Boot environment on flash, new variables will be added, existing variables overwritten, empty variables deleted and other variables stay untouched. Use configuration format 2 or newer to enforce U-Boot environment file writing support.
prepare_script String File name of Linux shell script which will get executed before the image installs
The script gets 4 input parameters:
$1 - PRODUCT_ID = 4-digit product ID, which is the first 4-digits of the 8-digit product number found in our web shop.
$2 - BOARD_REV = Board revision, in user readable format (e.g. V1.2A). This is derived from the last 4-digits of the 8-digit product number found in our web shop.
$3 - SERIAL = 8-digit serial number as a string with leading zeros if necessary.
$4 - IMAGE_FOLDER = folder where all the files are located. This is relevant only for installations from a local storage.
Returning an exit code other than 0 will abort the installation, show an error message with all text the script printed to standard output/error.
wrapup_script String File name of Linux shell script which will get executed after the image has been successfully installed.
The script gets 4 input parameters:
$1 - PRODUCT_ID = 4-digit product ID, which is the first 4-digits of the 8-digit product number found in our web shop.
$2 - BOARD_REV = Board revision, the last 4-digits of the 8-digit product number found in our web shop.
$3 - SERIAL = 8-digit serial number
$4 - IMAGE_FOLDER = folder where all the files are located. This is relevant only for installations from a local storage.
Returning an exit code other than 0 will show an error message with all text the script printed to standard output/error.
error_script String File name of Linux shell script which will get executed if the installation process fails at any time. When this property is set and the installation process fails, the error popup window will show additional information indicating whether the script was successfully executed or, else, displaying the error output for debugging. The error script is executed in the folder where it is located inside the media partition.
icon String File name of the Icon shown in front of the image (typically a PNG with a dimension of 40x40)
license String File name of a HTML file containing the image license agreement. When specified, the image installation will only continue after the customer agreed to the license agreement.
license_title String Title to show in the license agreement dialog
marketing String File name of a tar file with images which will be shown during installation process
supported_product_ids* List of Strings List of supported Product IDs. This is the first 4-digits of the 8-digit product number found in our web shop. The product ID will be obtained from the Toradex Config Block. If an image is found which does not support the current module type it will be displayed in gray.
blockdevs(*) List of Block Devices List of block devices to flash (for eMMC based devices, see below)
mtddevs(*) List of MTDs List of MTD (Linux memory technology device subsystem) devices (for raw NAND based devices, see below)
isinstaller Boolean This is a special property which marks the image as being the Toradex Easy Installer itself.

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!

Property Type Description
name* String Name of the block device to write to (as it appears under /dev/)
erase (>=1.1) Boolean Discards all data on block device before writing (preserves Toradex Config Block on boot partition).
table_type (>=1.4) String Partition table type (dos (default) or gpt). Use configuration format 2 or newer.
content(*) Dictionary of Content Content which should get written to the raw block device (see Chapter Content)
partitions(*) List of Partitions List of partitions which will get created and written to the block device

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:

Property Type Description
want_maximised Boolean Whether the installer should maximize the partition to the block devices size (if multiple partitions have this property set to true the remaining space will get evenly distributed)
partition_size_nominal Integer The minimal size of the partition in megabyte
offset_in_sectors Integer Fixed partition offset in sectors (typically 512 bytes on eMMC)
content Dictionary of Content Content which should get written to this partition (see below)
partition_type String Hexadecimal value used for partition type (if not specified, this will be automatically determined by the content's filesystem_type property. Don't use leading "0x" or similar notation, just two characters. Defaults to "00" (empty partition).
active Boolean Set the active/bootable flag (defaults to false)

MTD Devices

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

Property Type Description
name* String Name of the MTD device as shown in '/proc/mtd'.
erase (>=1.1) Boolean Erase MTD partition using flash_erase (this also clears erase counters of a UBI partition).
content(*) Dictionary of Content Content which should get written to the raw block device (see Chapter Content)
ubivolumes(*) List of UBI volumes List of UBI volumes to create in this MTD partition.
winceimage(*) Dictionary of WinCE image WinCE image to write into this MTD partition.

UBI volume

Property Type Description
name* String Name of the MTD device as shown in '/proc/mtd'.
type String UBI volume type: static or dynamic (default).
size_kib Integer UBI volume size in kilobytes. If not specified, maximum available size will be used.
content Dictionary of Content Content which should get written in this UBI volume (see below)

WinCE image

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

Property Type Description
image_filename* String File name of the WinCE image to write.
nonfs_size Integer Non-FS size in megabyte (maximum size of the WinCE image).
size Integer The size of the image in megabytes (used for the progress bar).

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.

Property Type Description
filesystem_type String File system to create ext2 (1.4 and newer)/ext3/ext4/swap/fat/ntfs/ubifs/raw (defaults to raw)
label String File system label used when creating the file system (ext3/ext4/fat/ntfs only)
mkfs_options String Extra options passed to the mkfs command (ext3/ext4/fat/ntfs only)
filename String Only if filesystem_type is a file system: File name of file which gets written into the new file system. If the file ending indicates a zip/tar.gz/tar.xz/tar.bz2 it will get automatically extracted into the file system.
filelist List of Strings Only if filesystem_type is a file system: List of file names which get copied into the new file system
uncompressed_size Number The uncompressed size of all files in megabytes (used for the progress bar)
rawfiles List of Raw Files Only if filesystem_type is raw: List of files to write using block-wise copy mode (dd)

Raw Files

Property Type Description
filename String File name of the file which gets copied blockwise to the target device. If the file ending indicates zip/gz/xz/bz2/lzo it will get uncompressed before being written.
dd_options String Extra options passed to the dd command (raw on block devices only)
nandwrite_options String Extra options passed to the nandwrite command (raw on NAND devices only)
product_ids List of String Product IDs on which this file will be copied (all supported Product IDs if empty)
size Number The uncompressed size of this file in megabytes (used for the progress bar)

*=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.

Property Type Description
config_format* Integer The image list format configuration version, currently always 1
images* List of Strings List of images. This can be absolute or relative URLs.

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.

Property Type Description
config_format* Integer The image list format configuration version, currently always 1
image_lists* List of Strings List of image list sources. The absolute URL need to point to an Image List file (see above).
show_default_feed Boolean If set to true the default image feed is fetched and the available images listed in the UI, else the feed is ignored.
show_3rdparty_feed Boolean If set to true the 3rd party image feed is fetched and the available images listed in the UI, else the feed is ignored.
{
  "config_format": 1,
  "image_lists": [
     "http://192.168.10.2:8008/image_list.json"
  ]
}

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).

Distroboot 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:

Parameter Description
autoinstall Automatically install an image which has autoinstall set to true
fullscreen Start the Qt user interface in full-screen mode instead of fixed VGA size
hotplugfb Automatically show Toradex Easy Installer on framebuffer device added at runtime (required when using DRM fbdev)
keyboard=xy Select keyboard layout

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}:${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.

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.