WoR Imager / PE customization

Pre-finalization script

The imager supports running a custom batch script called prefinalize.cmd just before it's about to finish the installation process.

This script must be put in a directory called scripts in the main directory of the application.

Always check if the target platform has all the tools / features that the script may need. For instance, WoR-PE users will likely not have a network adapter connected during that part of the setup.

Getting details about the installation

The tool passes installation details to the script through a list of environment variables:

  • WOR_APP_DIR - application directory
  • WOR_DISK_INDEX - the index of the target disk
  • WOR_DISK_NAME - the name of the target disk
  • WOR_DISK_TYPE - the media type of the target disk
  • WOR_DISK_SIZE - the disk size in GB
  • WOR_DISK_BOOTPARTITION - boot partition letter without backslash (e.g. X:)
  • WOR_DISK_WINDOWSPARTITION - Windows partition letter without backslash
  • WOR_DEVICE_TYPE - device BSP model. Can be RPi3-ARM64, RPi4-ARM64 or any other value for unsupported devices.
  • WOR_IMAGE_NAME - the name of the Windows image
  • WOR_IMAGE_ARCH - the architecture of the image
  • WOR_IMAGE_BUILDNUMBER - the build number of the image (e.g. 19041)
  • WOR_IMAGE_SPBUILDNUMBER - the service pack build number (e.g. 1, 2, 3, 4 in case of build 19041)
  • WOR_INSTALLOPTIONS_USELZXCOMPRESSION - the installation was compressed with LZX (Compact). Can be False or True.
  • WOR_INSTALLOPTIONS_PARTITIONSCHEME - the partition scheme used. Can be GPT or MBR.
  • WOR_INSTALLOPTIONS_MEMORYLIMIT - the RAM limit applied in the Boot Configuration Data (BCD). Can be 0 for no memory limit or a value expressed in MB.
  • WOR_INSTALLOPTIONS_RECOVERYENABLED - the Windows Recovery Environment (WinRE) was enabled and properly configured. Can be False or True.
Passing info to the tool

The script can send events to the tool through the Standard Output (stdout).

The events must follow this format: WoR-Event|Type|Data

Type can be:

  • LogTrace, LogDebug, LogInfo, LogWarn, LogError, LogFatal - print a message in the log window with the specified severity.
  • Progress - report a progress percent value.

Data can be:

  • In case of a Log* event, a string.
  • In case of a Progress event, an unsigned integer between 0 and 100.

The vertical bar character (|) is used as a separator for the event arguments and thus cannot be used in a log message string.

Examples of events:
WoR-Event|LogInfo|Hello world
WoR-Event|Progress|60

The entire installation process will fail if the script returns with a non-zero exit code.

Batch script example
::
:: Pre-Finalize script template for the Windows on Raspberry Imager
::
@echo off

::
:: Download and install the PiMon hardware monitor
::
set piMonDownloadUrl=https://github.com/driver1998/PiMon/releases/latest/download/PiMon.zip
set piMonDownloadPath=%WOR_DISK_WINDOWSPARTITION%\PiMon.zip
set piMonDestPath=%WOR_DISK_WINDOWSPARTITION%\Program Files\PiMon

call :RaiseEvent Progress, 0
call :RaiseEvent LogInfo, "Downloading PiMon..."

bitsadmin /transfer myDownloadJob /download /priority normal "%piMonDownloadUrl%" "%piMonDownloadPath%" || goto :error

call :RaiseEvent Progress, 30
call :RaiseEvent LogInfo, "Installing PiMon..."

mkdir "%piMonDestPath%" || goto :error
tar -xC "%piMonDestPath%" -f "%piMonDownloadPath%" || goto :error

call :RaiseEvent Progress, 60
call :RaiseEvent LogInfo, "Creating desktop shortcut..."

call :CreateShortcut "%piMonDestPath%\PiMon.exe", "%WOR_DISK_WINDOWSPARTITION%\Users\Public\Desktop\PiMon.lnk"

call :RaiseEvent Progress, 90
call :RaiseEvent LogInfo, "Cleaning up..."

del "%piMonDownloadPath%"

call :RaiseEvent Progress, 100

goto :end

:: CreateShortcut SourceFile, DestinationLink
:CreateShortcut 
echo Set oWS = WScript.CreateObject("WScript.Shell") > CreateShortcut.vbs
echo sLinkFile = %2 >> CreateShortcut.vbs
echo Set oLink = oWS.CreateShortcut(sLinkFile) >> CreateShortcut.vbs
echo oLink.TargetPath = %1 >> CreateShortcut.vbs
echo oLink.Save >> CreateShortcut.vbs
cscript CreateShortcut.vbs
del CreateShortcut.vbs
goto :end

::
:: Built-in functions
::

:: RaiseEvent Type, Data
:RaiseEvent
echo WoR-Event^|%~1^|%~2
goto :end

:error
exit /b %errorlevel%

:end
exit /b 0

Configuration file

Changing the configuration file may lead to issues! You shouldn't modify this file unless you really know what you're doing.

Windows on Raspberry Imager / PE installer stores its configuration in the settings.ini file which gets created on startup in case it doesn't exist.

There are a few additional parameters that can be set, depending on the platform:

WoR Imager options

DismPath

Default value: null

Description: Specify a custom path to DISM (the directory must include "dismapi.dll", "dism.exe" and their dependencies). This can be useful if the default version fails to service the image for any reason.

MinDiskSizeCompression

Default value: 7

Description: minimum disk size (GB) required for a compressed installation

MinDiskSizeFullInstall

Default value: 14

Description: minimum disk size (GB) required for a normal (non-compressed) installation

SkipEditionBuildNumCheck

Default value: 0

Possible values:

  • 0 : false
  • 1 : true

Description: bypass minimum Windows build number enforcement (19041 on RPi 4 and 18362 on RPi 3). Issue reports with this flag set will be ignored!

SkipWinPeEditions

Default value: 1

Possible values:

  • 0 : false
  • 1 : true

Description: avoid selecting WinPE editions by default (as is the case with ESDs from Microsoft)

SkipWelcomePage

Default value: 0

Possible values:

  • 0 : false
  • 1 : true

Description: skip the Welcome page

DiskIndex

Default value: null

Description: set the index of the target disk drive. Setting this value along with DiskSize and DeviceType will skip the "Select device" page.

No validation is done to check whether or not the disk actually exists.

DiskSize

Default value: null

Description: set the size of the target disk drive. Setting this value along with DiskIndex and DeviceType will skip the "Select device" page.

No validation is done to check whether or not the disk has the specified size.

DeviceType

Default value: null

Possible values:

  • RPi3-ARM64 : Raspberry Pi 2/3, CM3
  • RPi4-ARM64 : Raspberry Pi 4/400

Description: set the Raspberry Pi model. Setting this value along with DiskIndex and DiskSize will skip the "Select device" page.

ImageFilePath

Default value: null

Description: set the path to the Windows image file. Setting this value will skip the "Select image" page, assuming the image is valid and no errors occur.

DriversPath

Default value: null

Possible values:

  • path to an extracted driver package
  • path to a ZIP-archived driver package

Description: set the path to the drivers package. Setting this value will skip the "Select drivers" page.

No validation is done if a directory is specified instead of a ZIP archive.

UefiPath

Default value: null

Possible values:

  • path to an extracted UEFI (boot) package
  • path to a ZIP-archived UEFI (boot) package

Description: set the path to the UEFI firmware package. Setting this value will skip the "UEFI firmware" page.

No validation is done if a directory is specified instead of a ZIP archive.

SkipConfigurationPage

Default value: null

Possible values:

  • 0 : false
  • 1 : true

Description: skip the Configuration page. When WizardBasicMode=1, this value can be forcefully set to 0 to show the page.

CopyUefiDirectories

Default value: 0

Possible values:

  • 0 : false
  • 1 : true

Description: allow copying the directories in the UEFI package. This is disabled by default because the "overlays" directory has a DT overlay that might break Bluetooth functionality due to it changing the UART pin muxing.

Example:

This config will allow a device of any size:

[WoR Configuration File]
MinDiskSizeCompression=0
MinDiskSizeFullInstall=0

Note: the setup will fail if the Windows image takes more space than available.

WoR-PE package options

The included settings file may override some of the default values below.

HideEmptyDrives

Default value: 0

Possible values:

  • 0 : false
  • 1 : true

Description: hide empty drives that show up as having no capacity (e.g. removable card readers with one or more empty slots)

PreferredImageEditionId

Default value: null (defaults to first index)

Possible values example:

  • Core for Home edition
  • Professional for Pro edition

Description: set the preferred image edition ID at the "Select image" page. If the edition exists and no user input occurs in 15 seconds, this will be the installed image.