Is this page helpful?

Toradex Easy Installer Configuration Files

Introduction

The objective of this article is to present the configuration files and properties that allows for customization of the Toradex Easy Installer JSON files.

About Tezi Configuration Files

The Toradex Easy Installer uses JSON files for configuration, which can be edited with a text editor. Ensure compliance with the JSON specification, and use an online JSON validator like jsonlint.com for validation.

Image Format Properties

This section explains the properties used in Toradex Easy Installer's JSON image files. Toradex provides images with pre-defined JSON files, but customization is possible.

Property	Type	Description
config_format(*)	Integer	Image configuration format
autoinstall	Boolean	Automatically install upon image detection (default: false)
name(*)	String	Image name displayed in the list
description	String	Image description (tooltip)
version	String	Image version (mostly informational)
release_date	String	ISO 8601 date format, only informational
u_boot_env	String	U-Boot environment file for writing. Use a text file with variable/value pairs. This file must contain the full U-Boot environment, it will not be merged with any default environment while being written. Instead, it will overwrite the default values. For more information, please access best practices
prepare_script	String	Linux shell script executed before installation with input parameters. It is executed in the Toradex Easy Installer (TEZI) environment, where the root filesystem is a RAMFS. This means that any data written to it will be lost after a reboot. To write data to the filesystem that will persist after image installation, you need to mount the filesystem which is installed to the target's flash memory.
wrapup_script	String	Linux shell script executed after successful installation with input parameters. It is executed in the Toradex Easy Installer (TEZI) environment, where the root filesystem is a RAMFS. This means that any data written to it will be lost after a reboot. To write data to the filesystem that will persist after image installation, you need to mount the target filesystem.
error_script	String	Linux shell script executed on installation failure. Shown in error popup with debugging info
icon	String	Filename of the image icon (typically PNG, 40x40)
license	String	Filename of HTML file containing the image license agreement. Requires customer agreement
license_title	String	Title displayed in the license agreement dialog
marketing	String	Filename of tar file with images shown during installation
releasenotes	String	Filename of HTML file containing image release notes. Shown in a dialog
releasenotes_title	String	Title displayed in the release notes dialog
supported_product_ids(*)	List of Strings	List of supported Product IDs
blockdevs(*)	List of Block Devices	List of block devices to flash (eMMC-based devices, see below)
mtddevs(*)	List of MTDs	List of MTD devices (Linux memory technology device subsystem) for raw NAND-based devices (see below)
isinstaller	Boolean	Special property marking the image as the Toradex Easy Installer itself

* Mandatory properties

info

Enabling the autoinstaller option may require removing the license file. This is necessary because the license acceptance dialog can interfere with the autoinstallation process.

Mandatory Properties

1. Configuration Format (config_format):

   Configuration Format	Minimum Toradex Easy Installer Version	Reason
   1	1.0 or newer
   2	1.4 or newer	New Features
   3	2.0b3 or newer	New Features (container provisioning)
   4	2.0b6 or newer	Bugfixes (i.MX8 u-boot environment)
   5	5.6.0 or newer	Add offset to Raw Files properties

2. Block Devices (blockdevs): Each blockdev entry has a name and either partition or content node or both. In case of using a 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 the partition table created and the data written do not conflict!

   **Property**           | **Type**              | **Description**
   -----------------------|-----------------------|------------------------------------------------------------------------------------------------
   `name`(*)              | String                | Name of the block device to write to (as it appears under /dev/).
   `erase`                | Boolean               | Discards all data on block device before writing (preserves Toradex Config Block on boot partition).
   `table_type`           | 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.

   * Mandatory properties

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

   Property	Type	Description
   want_maximised	Boolean	Maximize partition size if multiple partitions share this setting. Distributes remaining space evenly.
   partition_size_nominal	Integer	Minimal partition size in megabytes.
   offset_in_sectors	Integer	Fixed partition offset in sectors (usually 512 bytes for eMMC).
   content	Dictionary of Content	Content to be written to this partition (see below).
   partition_type	String	Hexadecimal value for partition type (auto-determined if not specified based on filesystem_type in content). No leading "0x." Defaults to "00" (empty).
   active	Boolean	Set as active/bootable flag (default: false).

2. MTD Devices (mtddevs): 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`                | 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.

   * Mandatory properties

1. UBI volume (ubivolumes):

   **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, the maximum available size will be used.
   `content`              | Dictionary of Content | Content which should get written in this UBI volume (see below).

   * Mandatory properties

1. WinCE image (winceimage): 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                | Filename 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).

   * Mandatory properties

1. Content (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) and for UBI volume, content can either be raw data (uses Linux ubiupdatevol command) or ubifs.

   Property	Type	Description
   filesystem_type	String	Type of file system (defaults to raw). Options: ext2 (1.4+), ext3, ext4, fat, ubifs, raw.
   label	String	Label for ext3/ext4/fat file systems.
   mkfs_options	String	Additional options for the mkfs command (ext3/ext4/fat).
   filename	String	File name to write into the file system. Automatic extraction for zip/tar.gz/tar.xz/tar.bz2 files.
   filelist	List of Strings	List of file names to copy into the file system. Supports tuple format (srcfile:destdir:unpack) in config v3+.
   uncompressed_size	Number	Uncompressed size of all files in megabytes (used for the progress bar).
   rawfiles	List of Raw Files	List of files to write using block-wise copy mode (dd) for raw file systems.

2. Raw Files (rawfiles)

   Property	Type	Description
   filename	String	File name for blockwise copy. Supports compression detection (zip/gz/xz/bz2/lzo/zst for config v3+).
   dd_options	String	Additional options for the dd command (raw on block devices).
   nandwrite_options	String	Additional options for the nandwrite command (raw on NAND devices).
   product_ids	List of String	Product IDs for which this file will be copied (all supported if empty).
   size	Number	Uncompressed file size in megabytes (used for progress bar).
   offset	Number	Byte offset for filename write. Negative values count from partition end. (Requires "config_format": 5)
   rawfiles	List of Raw Files	List of files to write using block-wise copy mode (dd) for raw file systems.

Example

This example derived from a standard Linux image.json file, from Verdin iMX8M Plus Tezi folder: 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.

Verdin-iMX8MP_ToradexEasyInstaller_5.7.2+build.14/image.json

{
    "config_format": "4",
    "autoinstall": false,
    "name": "Toradex Easy Installer",
    "description": "Toradex Easy Installer for verdin-imx8mp machine",
    "version": "5.7.2+build.14",
    "release_date": "2023-02-22",
    "wrapup_script": "wrapup.sh",
    "icon": "tezi.png",
    "isinstaller": true,
    "supported_product_ids": [
        "0058",
        "0061",
        "0063",
        "0064",
        "0066"
    ],
    "blockdevs": [
        {
            "name": "emmc",
            "partitions": [
                {
                    "partition_size_nominal": 128,
                    "want_maximised": false,
                    "content": {
                        "label": "BOOT",
                        "filesystem_type": "FAT",
                        "mkfs_options": "",
                        "filelist": [
                            "tezi.itb",
                            "boot-tezi.scr",
                            "overlays.txt"
                        ],
                        "uncompressed_size": 44.980247497558594
                    }
                }
            ]
        },
        {
            "name": "emmc-boot0",
            "erase": true,
            "content": {
                "filesystem_type": "raw",
                "rawfiles": [
                    {
                        "filename": "imx-boot",
                        "dd_options": "seek=0"
                    }
                ]
            }
        }
    ]
}

Image List Format

For images loaded from an HTTP server, use an index file (typically image_list.json) to point to individual images. It contains:

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 (tezi_config.json) allows adding additional HTTP image sources, 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. It includes:

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"
  ]
}