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.
It's not necessary to write the entire script in batch. Calling a PowerShell script works fine and is highly recommended.
The tool passes installation details to the script through a list of environment variables:
WOR_APP_DIR
- application directoryWOR_DISK_INDEX
- the index of the target diskWOR_DISK_NAME
- the name of the target diskWOR_DISK_TYPE
- the media type of the target diskWOR_DISK_SIZE
- the disk size in GBWOR_DISK_BOOTPARTITION
- boot partition letter without backslash (e.g. X:)WOR_DISK_WINDOWSPARTITION
- Windows partition letter without backslashWOR_IMAGE_NAME
- the name of the Windows imageWOR_IMAGE_ARCH
- the architecture of the imageWOR_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
.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:
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.
::
:: 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
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 stores its configuration in the settings.ini
file, which gets created on startup.
There are a few hidden additional parameters that can be set:
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.
Default value: 7
Description: minimum disk size (GB) required for a compressed installation
Default value: 14
Description: minimum disk size (GB) required for a normal (non-compressed) installation
Default value: 0
Possible values:
0
: false1
: trueDescription: bypass minimum Windows build number enforcement (19041 on RPi 4 and 18362 on RPi 3). Issue reports with this flag set will be ignored!
Default value: 0
Possible values:
0
: false1
: trueDescription: skip the Welcome page
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.
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.
Default value: null
Possible values:
RPi3-ARM64
: Raspberry Pi 2/3, CM3RPi4-ARM64
: Raspberry Pi 4/400Description: set the Raspberry Pi model. Setting this value along with DiskIndex
and DiskSize
will skip the "Select device" page.
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.
Default value: null
Possible values:
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.
Default value: null
Possible values:
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.
Default value: null
Possible values:
0
: false1
: trueDescription: skip the Configuration page. When WizardBasicMode=1
, this value can be forcefully set to 0
to show the page.
Default value: 0
Possible values:
0
: false1
: trueDescription: 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.
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.