-
Notifications
You must be signed in to change notification settings - Fork 124
JSON fields
This page describes the JSON formatted fields used in the various meta-files for an OS. Together, they describe the installation requirements for each OS to be installed by PINN. For a summary, please see the summary table below.
This is the main meta-file that is required for each OS. At startup, PINN will scan the /os folder of PINN's boot drive and attached USB drives for folders containing os.json. It will read this file to find any OSes that are suitable to be installed in the current model of Raspberry Pi, according to the "supported_models" field. Each OS that is suitable is listed in the main installation screen according to its Group. The name and description of each OS is shown. It is also required for remote internet installations, but it is only read at installation time (see os_list.json.
This is the name that the OS will be referred as and will be displayed in the installation menu.
This is an important field as it is used as the default basename of other OS installation files, such as the icon filename, the main tar files, and some configuration files. Therefore it should be fairly short and consistent. It is best not to include spaces, but if any are necessary, they will be converted to underscores when used in a filename. It should be the same as the os_name in os_list.json.
This contains a short description of the OS. Please make it as short as possible, because there is limited space on the installation menu to display it.
The icon must be a 40x40 png file. The icon name is normally found by appending ".png" to the base os name and searching in the same location as the os.json file itself. It can be located elsewhere using this field to provide a URL, but this requires the user to have an internet connection when installing. The icon filename must match the os_name and name fields)
Date of release in "YYYY-MM-DD" format. If an OS is available from various sources (Sd card, USB, various internet repositories etc), PINN will use the release date to pick the latest one. If the same release date is available from different sources, local versions will be preferred over any remote versions for speed of installation.
A list of partial model names that are suitable. Each supported model string is compared against the current Raspberry Pi Model number to see if it is included as a sub-string. If it is, it is marked as being suitable. The user can override this using the show_all parameter in PINN to show all OSes regardless of suitability.
a decimal number representing a set of bit flags to indicate which RPI models were suitable. This is no longer used. Use supported_models instead.
a list of hex numbers representing the revisions of RPI models that were suitable. This is no longer used. Use supported_models instead.
Indicates if partition_setup.sh is suitable for installing a backup (true/false/"update").
If this field is absent or set to false, PINN will not be able to backup the OS. This may be due to an unsupported filesystem, or an unsuitable partition_setup.sh script. To ensure the OS can be backed up, set this to true, but you must first be sure that the partition_setup.sh script is suitable. This script is run both on first installation AND after a backup is restored. Some OSes need partition_setup.sh to customise some aspects of the OS for multi-boot, but this only needs to be done once, not after being restored from a backup. The script can guard against this by looking for the "restore" environment variable and adjusting its behaviour. Setting "supports_backup" to true indicates this has been done.
Nevertheless, an older installed OS that didn't support backup previously, may have a newer version of partition_setup.sh that does support it. So for this reason, PINN can also look in the partition_setup.sh script for "#supports_backup in PINN" comment on its second line to see if it can upgrade the current partition_setup.sh script to support backup and thus backup an existing installation. In these cases, "supports_backup": "update" can be set.
Sum of partition_size_nominal of all partitions in MiB. When installing multiple OSes to a drive, the nominal_sizes of each OS are summed to see if they will fit on the available space. The nominal size is normally a bare minimum size for installation, which typically only has about 400MB free space. This may not be sufficient to upgrade the OS or run it efficiently.
Checksum of partition_setup.sh file, or URL of remote checksum file. As partition_setup.sh is a script, it could be modified to do unwanted actions. To guard against this, the hash of the script can be stored in os.json and the script will be prevented from running if it does not match.
Version of this release. This is just for information.
Version of kernel used. Just for information
This provides the location of a webpage which will be displayed for further information on this OS, when the info button is clicked.
Default user name.
Default password.
Offset of disk table (RISCOS only)
As the list of available OSes has increased, it has become increasingly harder to navigate them. The Group field provides a category to group similar OSes together for ease of viewing. The main groups used are (General/Minimal/Education/Media/Utility/Games)
Sum of the partition tar file sizes (in bytes), excluding any metafiles. This allows PINN to provide an estimate of installation time when installing.
tbd
A list of structured information, one for each partition
Name of partition (pay attention to OS limitations of case and length)
The type of filesystem to be created: "raw","fat","ext4","ntfs","partclone","unformatted","swap"
Minium size in MiB of partition to create
false = partition will be partition_size_nominal in size. True = Remaining free space will be added equally
Size of tarball (in MiB) before compression |
Hex code of partition type for parted. (Only needed to override the default)
Specifies a particular partition number for a partition
Force a position to a specific offset in sectors from the beginning of the disk
true = no tarball exists for this partition
true = Requires a specific partition label
Checksum of partition's main file (.tar.xz), or URL of remote checksum file |
Marks the partition as active in the MBR
Any additional options required when formatting the partition
This file lists the main
Describes the OS
feature_level (integer) o
a decimal number representing a set of bit flags to indicate which RPI models were suitable
location of icon.png file (file name must be the same as the os_name and name fields)
Sum of partition_size_nominal of all partitions in MiB
a list of hex numbers representing the revisions of RPI models that were suitable
Date of release in "YYYY-MM-DD" format
A list of partial model names that are suitable
Location of marketing.tar file (tar of slides in /slides_vga)
location of os.json file
Name of the OS (no spaces) (same as name)
location of partition_setup.sh script
location of partitions.json
list of URLs of tar file for each partition in order
| Key | Type | os | os_list | partitions | Use |
|---|---|---|---|---|---|
| "description" | string | m | m | Describes the OS | |
| "feature_level" | integer | o | o | (deprecated) a decimal number representing a set of bit flags to indicate which RPI models were suitable | |
| "icon" | url | o | m | location of icon.png file (file name must be the same as the os_name and name fields) | |
| "marketing_info" | url | m | Location of marketing.tar file (tar of slides in /slides_vga) | ||
| "nominal_size" | integer | m | m | Sum of partition_size_nominal of all partitions in MiB | |
| "os_info" | url | m | location of os.json file | ||
| "os_name" | string | m | Name of the OS (no spaces) (same as name) | ||
| "name" | string | m | Name of the OS (no spaces) (same as os_name) | ||
| "partition_setup" | url | o | location of partition_setup.sh script | ||
| "partitions_info" | url | m | location of partitions.json | ||
| "sha512sum/sha256sum/sha1sum/md5sum" | string | o | Checksum of partition_setup.sh file, or URL of remote checksum file | ||
| "release_date" | string | m | m | Date of release in "YYYY-MM-DD" format | |
| supported_hex_revisions" | Quoted csv | o | o | (deprecated) a list of hex numbers representing the revisions of RPI models that were suitable | |
| "supported_models" | string list | m | m | A list of partial model names that are suitable | |
| "tarballs" | url list | m | list of URLs of tar file for each partition in order | ||
| "version" | string | o | Version of this release | ||
| "kernel" | string | o | Version of kernel used | ||
| "url" | url | o | location of webpage for further info on this OS | ||
| "username" | string | o | Default user name | ||
| "password" | string | o | Default password | ||
| "riscos_offset" | integer | o | Offset of disk table (RISCOS only) | ||
| "group" | string | o | Category to group OS into on PINN menu (General/Minimal/Education/Media/Utitlity/Games) | ||
| "supports_backup" | boolean/string | m | Indicates if partition_setup.sh is suitbale for installing a backup (true/false/"update") | ||
| "download_size" | integer | o | Sum of the partition tar file sizes (in bytes) , excluding any metafiles. | ||
| "partitions" | Struct list | m | A list of structured information, one for each partition | ||
| { | |||||
| "label" | string | m | Name of partition (pay attention to OS limitations of case and length) | ||
| "filesystem_type" | string | m | "raw","fat","ext4","ntfs","partclone","unformatted","swap" | ||
| "partition_size_nominal" | integer | m | Minium size in MiB of partition to create | ||
| "want_maximised" | boolean | m | false = partition will be partition_size_nominal in size. True = Remaining free space will be added equally | ||
| "uncompressed_tarball_size" | integer | m | Size of tarball (in MiB) before compression | ||
| "partition_type" | string | o | Hex code of partition type for parted. Only needed to override the default) | ||
| "requiresPartitionNumber" | integer | o | Specifies a particular partition number for a partition | ||
| "offset_in_sectors" | integer | o | Force a position to a specific offset in sectors from the beginning of the disk | ||
| "emptyfs" | boolean | o | true = no tarball exists for this partition | ||
| "requires_label" | boolean | o | true = Requires a specific partition label | ||
| "sha512sum/sha256sum/sha1sum/md5sum" | string | o | Checksum of partition's main file (.tar.xz), or URL of remote checksum file | ||
| "active" | boolean | o | Marks the partition as active in the MBR | ||
| "mkfs_options" | string | o | Any additional options required when formatting the partition | ||
| } |