Configuration Files
Introduction
The Toradex Easy Installer makes use of JSON files and, 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
This chapter lists the available properties and how they get interpreted by the Toradex Easy Installer.
Each Easy Installer compatible image is described in a JSON image file. Toradex provides images with a proper JSON image file. Yet, 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.
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 |
| 3 | 2.0b3 or newer |
| 4 | 2.0b6 or newer |
| 5 | 5.6.0 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. Note that local storage will be mounted read-only by default. Returning an exit code other than 0 will show an error message with all text the script printed to standard output/error. A failed execution of this script will trigger the error_script. |
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 | Filename of the Icon shown in front of the image (typically a PNG with a dimension of 40x40). |
license | String | Filename 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. |
releasenotes | String | Filename of a HTML file containing image release notes. When specified, a dialog will be shown with the release notes content. |
releasenotes_title | String | Title to show in the release notes dialog. |
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 that 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 that marks the image as being the Toradex Easy Installer itself. |
*: Mandatory property
Block Devices
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 (>=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. |
*: Mandatory property
Partition
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 | 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 megabytes. |
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. |
*: Mandatory property
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, the maximum available size will be used. |
content | Dictionary of Content | Content which should get written in this UBI volume (see below). |
*: Mandatory property
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 | 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 property
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) and 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/fat/ubifs/raw (defaults to raw). |
label | String | File system label used when creating the file system (ext3/ext4/fat only). |
mkfs_options | String | Extra options passed to the mkfs command (ext3/ext4/fat 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. Config version 3 supports a tuple with three elements: srcfile:destdir:unpack. If destdir is not set, the file will be copied to /, if unpack is set to 'true', and the srcfile is a zip/tar.gz/tar.xz/tar.bz2, it will be extracted into destdir. Configuration format 3 or newer is needed to use this format, or you shall use 'srcfile' only for older Configuration formats. |
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(/zst for config version 3 and higher) 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). |
offset | Number | Byte offset where filename is being written. If negative it counts from the end of the partition. dd_options "bs" and "seek" are not allowed if this is set. (make sure to use "config_format": 5, using this property to ensure Easy Installer is capable of handling it). |
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 that 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"
]
}