Skip to content

Latest commit

 

History

History
531 lines (410 loc) · 30.7 KB

README.md

File metadata and controls

531 lines (410 loc) · 30.7 KB
Raw

Powershell version of IoT-ADK-Addonkit

Powershell version of the iot-adk-addonkit extends the functionality with further validation / verification steps in the imaging process.

What's new in 6.0

  • Support of Workspace concept : Workspace is a directory with IoTWorkspace.xml file specifying its attributes. This directory structure is similar to earlier iot-adk-addonkit without the tools and templates directory. You can now have multiple workspaces for building different products and use one common tooling directory.
  • Sample Workspace : The addon kit comes with a sample workspace that you can access via the env variable SAMPLEWKS ($env:SAMPLEWKS). You can import oem packages, bsp and products from this workspace into your workspace for your use.
  • Upgrade existing iot-adk-addonkit directory : You can upgrade your existing iot-adk-addonkit directory into a workspace, see Work with Existing Workspace
  • Powershell functions and equivalent cmd functions available for many new features. See Supported Functionality listing.

Get started

The pre-requisite for using this tools are same as the earlier iot-adk-addonkit projects.

Install the following pre-requisites

  • Windows 10 IoT Core Packages
  • Windows Assessment and Deployment Kit including Windows PE add-on for the adk
  • Get your BSP for your platform. See Windows 10 IoT Core BSPs for links to get the BSPs.
  • Certificates - You will need to have these certificates (with private keys) in the local cert store ( either directly installed or loaded from a smart card)
    • Code signing certificate from a CA : Required for signing your drivers for building retail image
    • Code signing EV certificate from a CA : Required to register with Device Update Center and sign payload for submission
    • Security certificates from self : Required for the security features.

Create a basic image

  1. Launch the IoTCorePShell ( Run IoTCorePShell.cmd ). This will launch the tool and also install the test certificates if required and opens the sample workspace present along with the tools by default.

  2. Create a new workspace (say C:\MyWorkspace ) using New-IoTWorkspace

    New-IoTWorkspace C:\MyWorkspace Contoso arm
(or) new-ws C:\MyWorkspace Contoso arm

    The Workspace will be created and opened. It will also import few default packages required in the workspace.

  3. Import the required oem packages using Import-IoTOEMPackage from the sample workspace ($env:SAMPLEWKS). You can either import each package selectively or import all of them.

    # Importing Recovery packages from sample workspace
Import-IoTOEMPackage Recovery.*
(or) importpkg Recovery.*
# Below example imports all packages from the sample workspace
Import-IoTOEMPackage *
(or) importpkg *

  4. Import the required BSP (for example RPi2) using Import-IoTBSP

    # Importing RPi2 bsp from a folder
Import-IoTBSP RPi2 C:\Myfolder\RPi_BSP
(or) importbsp RPi2 C:\Myfolder\RPi_BSP
(or) importbsp RPi2 C:\Downloads\RPi_BSP.zip

# Importing an Intel bsp
Import-IoTBSP APLx64 "C:\Program Files (x86)\Intel IoT\Source-x64\BSP"
(or) importbsp APLx64 "C:\Program Files (x86)\Intel IoT\Source-x64\BSP"

# Importing NXP BSPs found inside the zip or folder
Import-IoTBSP *  C:\BSP\NXPBSP.zip
(or) importbsp *  C:\BSP\NXPBSP_FOLDER
(or) importbsp Sabre_iMX6Q_1GB  C:\BSP\NXPBSP.zip

# Importing QCDB410C BSP packages found inside the zip
## special case - this invokes Import-QCBSP internally
Import-IoTBSP QCDB410C C:\BSP\db410c_bsp.zip
(or) importbsp QCDB410C C:\BSP\db410c_bsp.zip
# the above will import the bsp from sample wkspace and copy the prebuilt cabs to Workspace\Prebuilt directory

    • For Qualcomm BSP, after downloading the zip file, you can extract the prebuilt cabs using

      # Import the QCDB410 BSP and extract the required cabs from the QC zip file
Import-QCBSP C:\BSP\db410c_bsp.zip C:\MyWorkspace\Prebuilt -ImportBSP

      C:\MyWorkspace\Prebuilt will be set as BSPPkgDir in the Workspace xml.

  5. Create a new product (MyProduct) based on the imported BSP, say RPi2 in the below example, using Add-IoTProduct

    Add-IoTProduct MyProduct RPi2
(or) newproduct MyProduct RPi2

    This will prompt you for the SMBIOS values to be used in the product. DeviceInventory_MyProduct.xml is also generated which is used to register your device on the DUC portal.

  6. Build all packages using New-IoTCabPackage

    New-IoTCabPackage All
(or) buildpkg all

  7. Build the FFU image for MyProduct product, test configuration using New-IoTFFUImage

    New-IoTFFUImage MyProduct Test
(or) buildimage MyProduct Test

    This will also build the necessary product specific packages and the fm files before starting the image creation.

  8. Build the recovery FFU image using New-IoTRecoveryImage

    New-IoTRecoveryImage MyProduct Test
(or) buildrecovery MyProduct Test

    Note that the device layout should have MMOS partition to be able to create recovery image. See Recovery for more details.

Add your packages to your image

You can add an appx, driver, provisioning package, files and registry settings to your image by creating specific packages for each.

  1. Add a appx package using Add-IoTAppxPackage

    Add-IoTAppxPackage C:\MyTest.appx fga
(or) newappxpkg C:\MyTest.appx fga

    This also adds a feature id APPX_MYTEST in the OEMFM.xml file. You can add this feature to MyProduct using Add-IoTProductFeature

    Add-IoTProductFeature MyProduct All APPX_TEST -OEM
(or) addfid MyProduct All APPX_TEST -OEM

    This will edit both retail and test oeminputxml files under MyProduct to add APPX_TEST feature under OEM node. You also need to make sure that you remove any other application feature id in the oeminputxml file such as IOT_BERTHA.

  2. Add a driver package using Add-IoTDriverPackage

    Add-IoTDriverPackage C:\TestDriver\MyTest.inf
(or) newdrvpkg C:\TestDriver\MyTest.inf

    This will copy all the files in the C:\TestDriver directory and also add a feature id DRIVERS_MYTEST in the OEMFM.xml file. You can add this feature to MyProduct using

    Add-IoTProductFeature MyProduct All DRIVERS_MYTEST -OEM
(or) addfid MyProduct All DRIVERS_MYTEST -OEM

  3. Add a provisioning package using Add-IoTProvisioningPackage

    Add-IoTProvisioningPackage Prov.MySettings
(or) newprovpkg Prov.MySettings

    You can then edit the provisioning customizations.xml file using WCD (icd.exe). Launch ICD.exe and open Prov.MySettings.icdproj.xml file that is generated to add the policies required. If you have created a ppkg file using ICD.exe already, you can import the same using

    Add-IoTProvisioningPackage Prov.MySettings "C:\Users\username\Documents\Windows Imaging and Configuration Designer (WICD)\MySettings\MySettings.ppkg"
(or) newprovpkg Prov.MySettings2 "C:\Users\username\Documents\Windows Imaging and Configuration Designer (WICD)\MySettings\MySettings.ppkg"

    This will add a feature id PROV_MYSETTINGS in the OEMCOMMONFM.xml. You can add this feature to MyProduct using

    Add-IoTProductFeature MyProduct All PROV_MYSETTINGS -OEM
(or) addfid  MyProduct All PROV_MYSETTINGS -OEM

  4. Add a file package using Add-IoTFilePackage

    $myfiles = @(
    ("`$(runtime.system32)","C:\Temp\TestFile1.txt", ""),
    ("\OEMInstall","C:\Temp\TestFile2.txt", "TestFile2.txt")
    )
Add-IoTFilePackage Files.Configs $myfiles

    This will add a feature id FILES_CONFIGS in the OEMCOMMONFM.xml. You can add this feature to MyProduct using

    Add-IoTProductFeature MyProduct All FILES_CONFIGS -OEM
(or) addfid MyProduct All FILES_CONFIGS -OEM

  5. Add a registry package using Add-IoTRegistryPackage

    $myregkeys = @(
    ("`$(hklm.software)\`$(OEMNAME)\Test","StringValue", "REG_SZ", "Test string"),
    ("`$(hklm.software)\`$(OEMNAME)\Test","DWordValue", "REG_DWORD", "0x12AB34CD"))
Add-IoTRegistryPackage Reg.Settings $myregkeys

    This will add a feature id REG_SETTINGS in the OEMCOMMONFM.xml. You can add this feature to MyProduct using

    Add-IoTProductFeature MyProduct All REG_SETTINGS -OEM
(or) addfid MyProduct All REG_SETTINGS -OEM

  6. You can build the above packages using buildpkg command discussed earlier and create an FFU using buildimage command.

Adding open source Powershell

If you require Powershell, it is recommended to add the latest Powershell available in the github in your images and you can do this easily with Import-PSCoreRelease.

    Import-PSCoreRelease 7.0.0

This will download the powershell zip from the github and import the files into the workspace. It will also add a feature id OPENSRC_POWERSHELL in the OEMFM.xml. You can add this feature to MyProduct using

    # Add IOT_POWERSHELL for WinRM
    Add-IoTProductFeature MyProduct All IOT_POWERSHELL
    # Add Open source Powershell
    Add-IoTProductFeature MyProduct All OPENSRC_POWERSHELL -OEM
    (or) addfid MyProduct All OPENSRC_POWERSHELL -OEM

Adding security packages

In order to enable security features such as Secure boot, Bitlocker and Device guard, you will require specific certificates to be created and accessible from the machine where the image is built. See Turnkey Security on IoT Core for the details on these security features and Windows Secure Boot Key Creation and Management Guidance for managing certificates.

For testing purposes, following commands are provided to create and install the certs in your machine.

  1. Create OEM Certs using New-IoTOEMCerts

    New-IoTOEMCerts

    This will prompt you to enter password for the certs that are created. The created certificates are in the workspace certs folder and the pfx files with the private keys are in the certs\private folder.

  2. Install the pfx files required for the signing process during the security package creation, using Install-IoTOEMCerts

    Install-IoTOEMCerts

  3. If you already have the certs to use for security packages, you can import them using Import-IoTCertificate

    # PlatformKey and KeyExchangeKey mandatory for SecureBoot
Import-IoTCertificate $env:SAMPLEWKS\Certs\OEM-PK.cer PlatformKey
Import-IoTCertificate $env:SAMPLEWKS\Certs\OEM-UEFISB.cer KeyExchangeKey
# DataRecoveryAgent mandatory for Bitlocker
Import-IoTCertificate $env:SAMPLEWKS\Certs\OEM-DRA.cer DataRecoveryAgent
# Update mandatory for Device Guard
Import-IoTCertificate $env:SAMPLEWKS\Certs\OEM-PAUTH.cer Update
Import-IoTCertificate $env:SAMPLEWKS\Certs\OEM-UMCI.cer User

  4. You can now create the security packages using Add-IoTSecureBoot,Add-IoTDeviceGuard and Add-IoTBitLocker

     # Create Secure boot package
Add-IoTSecureBoot -Test
# Create Device guard package
Add-IoTDeviceGuard -Test
# Create Bitlocker package
Add-IoTBitLocker

    (or) you can create them all using Add-IoTSecurityPackages

    Add-IoTSecurityPackages

  5. Now that the new security packages are created, include the Security features SEC_BITLOCKER,SEC_SECUREBOOT_TEST and SEC_DEVICEGUARD_TEST in the oeminputxml file.

    Add-IoTProductFeature MyProduct All SEC_BITLOCKER -OEM
Add-IoTProductFeature MyProduct All SEC_SECUREBOOT_TEST -OEM
Add-IoTProductFeature MyProduct All SEC_DEVICEGUARD_TEST -OEM

  6. You can build the above packages using buildpkg command discussed earlier and create an FFU using buildimage command.

Building a retail image

To build an retail image, you will need to retail sign all your packages and then create the FFU image.

  1. Configure the code signing certificate for retail signing in the Workspace xml

    <!--Specify the retail signing certificate details, Format given below -->
<RetailSignToolParam>/s my /i "Issuer" /n "Subject" /ac "C:\CrossCertRoot.cer" /fd SHA256</RetailSignToolParam>

    You could also specify the certificate by the thumbprint

    <!--Specify the retail signing certificate details, Format given below -->
<RetailSignToolParam>/s my /sha1 "thumbprint" /fd SHA256</RetailSignToolParam>

  2. Enable retail signing with Set-IoTRetailSign

    Set-IoTRetailSign On
(or) retailsign On

    This will set the sign tool parameter to the certificate specified as RetailSignToolParam in the Workspace xml. You will also see the prompt highlighting that the Retail mode is on.

  3. Rebuild all your packages with

    New-IoTCabPackage All
(or) buildpkg all

    Note : If you are using security packages, ensure to generate the retail version of the packages (without -Test flag) and include the corresponding feature id in the RetailOEMInput.xml file.

  4. If you have prebuilt bsp cab packages, re-sign them using Redo-IoTCabSignature

    Redo-IoTCabSignature <srccabdir> <dstcabdir>
(or) re-signcabs <srccabdir> <dstcabdir>

    Set the BSPPkgDir setting to the dstcabdir in the product settings xml for retail configuration.

  5. Build the image for retail configuration.

    New-IoTFFUImage RPiRecovery Retail
(or) buildimage RPiRecovery Retail

    This will also build the necessary product specific packages and the fm files before starting the image creation.

  6. Build the Retail recovery FFU image with

    New-IoTRecoveryImage RPiRecovery Retail
(or) buildrecovery RPiRecovery Retail

Work with existing workspace

Steps to upgrade your existing iot-adk-addonkit project directory.

  1. Launch the IoTCorePShell ( Run IoTCorePShell.cmd ). This will launch the tool and also install the test certificates if required and opens the sample workspace present along with the tools by default.

  2. Run the migration command for the existing repo dir say C:\Myproject\iot-adk-addonkit, using Redo-IoTWorkspace

    Redo-IoTWorkspace C:\Myproject\iot-adk-addonkit
(or) migrate C:\Myproject\iot-adk-addonkit

    This command will generate the workspace xml file and product specific settings file that is required for rest of the scripts to work. The SMBIOS data for the product will be set to default and you will be required to update them to the proper values. For Qualcomm based products, the SMBIOS values from the SMBIOS.cfg will be used.

  3. The tools and templates directory under your repo is not required anymore. These can be deleted ( note that the above command does not delete these folders, but moves them to a ToDelete folder).

  4. Open this workspace using Open-IoTWorkspace and start using this as a new workspace described above.

    Open-IoTWorkspace C:\Myproject\iot-adk-addonkit\IoTWorkspace.xml
(or) open-ws C:\Myproject\iot-adk-addonkit\IoTWorkspace.xml

Work with Device Update Center

Steps to register your device on the device update center and publish updates are given below.

  1. Register with the Device Update Center portal. You will require an EV cert for this process.
  2. Configure the EV cert used in the Device Update Center in the Workspace. 
        <!--Specify the ev signing certificate details, Format given below -->
    <EVSignToolParam>/s my /i "Issuer" /n "Subject" /fd SHA256</EVSignToolParam>
  3. Create a product 
    Add-IoTProduct SampleA RPi2
(or) newproduct SampleA RPi2
    You will find an device inventory file IoTDeviceModel_<product>.xml. Use this file to register your device model in the DUC portal. If you change the SMBIOS fields or install a different IoTCore Kit version, you can regenerate this file using 
    Export-IoTDeviceModel SampleA
(or) exportidm SampleA
  4. Once the device model is registered in the portal, you can download CUSConfig.zip file from the portal. You can then import this file into the product configuration using 
    Import-IoTDUCConfig SampleA "C:\Users\MyUser\Downloads\CUSConfig.zip"
(or) importcfg SampleA "C:\Users\MyUser\Downloads\CUSConfig.zip"
    This will create a CUSConfig folder in the Product\Packages directory and also update the oeminput xml files.
  5. Rebuild the image with the CUSConfig included. This will be the base shipping image for your device model. 
    New-IoTFFUImage SampleA Retail
(or) buildimage SampleA Retail
  6. When you have new update to create, modify/update the OEM package contents and increment the BSP_VERSION 
    Set-IoTCabVersion 10.0.1.0
(or) setversion 10.0.1.0
  7. Rebuild your packages and build your ffu image with the updated packages. Validate this FFU for functionality. You can then export the update package using 
    Export-IoTDUCCab SampleA Retail
(or) exportpkgs SampleA Retail
    This will create a cab file under $env:BUILD_DIR\<product>\<Config>\$env:BSP_VERSION
  8. You can upload this cab in the DUC portal.

Supported powershell commands

The supported commands are listed below in logical groups.

Workspace commands

Function Name Alias Description
New-IoTWorkspace new-ws Creates new workspace
Open-IoTWorkspace open-ws Opens existing workspace
Redo-IoTWorkspace migrate Converts legacy iot-adk-addonkit directory into a workspace
Import-IoTOEMPackage importpkg Imports OEM package from Sample workspace
Import-IoTProduct importproduct Imports Product from Sample workspace
Import-IoTBSP importbsp Imports BSP from the given folder / zip file or sample workspace
New-IoTOEMCerts - Creates new OEM specific certificates
Install-IoTOEMCerts - Installs oem pfx files in the certs\private folder
Import-IoTCertificate - Imports the certificate for security functions
Copy-IoTOEMPackage copypkg Copies OEM package between workspaces
Copy-IoTProduct copyproduct Copies product between workspaces
Copy-IoTBSP copybsp Copies BSP between workspaces
Add-IoTAppxPackage newappxpkg Creates Appx OEM package and adds featureID to OEMFM.xml
Add-IoTDriverPackage newdrvpkg Creates Driver OEM package and adds featureID to OEMFM.xml
Add-IoTCommonPackage newcommonpkg Creates common (file/reg) OEM package and adds featureID to OEMCOMMONFM.xml
Add-IoTFilePackage addfile Adds a file package and adds the featureID to OEMCOMMONFM.xml
Add-IoTRegistryPackage addreg Adds a registry package and adds the featureID to OEMCOMMONFM.xml
Add-IoTProvisioningPackage newprovpkg Adds provisioning oem package and adds the featureID to OEMCOMMONFM.xml
Add-IoTBSP newbsp Adds new bsp based on a template
Add-IoTProduct newproduct Adds new product based on the OEMInputSamples from BSP
Add-IoTSecurityPackages - Adds security packages for the product
Add-IoTDeviceGuard - Adds device guard package
Add-IoTSecureBoot - Adds secureboot package for the product
Add-IoTBitLocker - Adds bitlocker package for the product
Add-IoTProductFeature addfid Adds feature id to the product's oeminput xml file
Remove-IoTProductFeature removefid Removes feature id from the product's oeminput xml file
Add-IoTCEPAL addcepal Preview: Adds CEPALFM.xml into the Test and Retail OEMInput.xml files for product. See CE Migration for more details
Import-IoTCEPAL importcepal Preview: This command copies $FlatReleaseDirectory\CEPAL_PKG into the workspace and generates CEPALFMFileList.xml. See CE Migration for more details
Import-PSCoreRelease importps This command imports Open source Powershell release from github into the workspace
Add-IoTZipPackage addzip This command adds all file contents in the zip file into a file package in the workspace
Add-IoTDirPackage adddir This command adds all file contents in the directory into a file package in the workspace

Build commands

Function Name Alias Description
Set-IoTCabVersion setversion Stores the version in the IoTWorkspace.xml
New-IoTCabPackage buildpkg Creates .cab files
New-IoTProvisioningPackage buildppkg Creates .ppkg files
New-IoTFIPPackage buildfm Creates FIP packages and merged FM files
New-IoTFFUImage buildimage Creates regular FFU
New-IoTRecoveryImage buildrecovery Creates recovery FFU
New-IoTWindowsImage newwinpe Creates custom winpe with bsp drivers / recovery scripts
Test-IoTRecoveryImage verifyrecovery Verifies if the wim files in the recovery ffu are proper
New-IoTInf2Cab inf2cab Creates cab file for the given inf file

Environment commands

Function Name Alias Description
Set-IoTEnvironment setenv Sets environment settings based on the config values in IoTWorkspace.xml
Convert-IoTPkg2Wm convertpkg Converts pkg.xml files to wm.xml files
Get-IoTProductFeatureIDs gpfids Gets features IDs supported in the IoTCore OS
Get-IoTProductPackagesForFeature gpfidpkgs Gets OS packages corresponding to features ID
Get-IoTWorkspaceProducts gwsproducts Gets the list of product names in the workspace
Get-IoTWorkspaceBSPs gwsbsps Gets the list of BSP names in the workspace

Device Update Center commands

Function Name Alias Description
Export-IoTDeviceModel exportidm Exports the IoT Device Model for DUC registration
Import-IoTDUCConfig importcfg Imports the CUSConfig.zip into the product directory
Export-IoTDUCCab exportpkgs Exports the update cab for DUC upload

FFU commands

Function Name Alias Description
Mount-IoTFFUImage ffum Mounts the FFU image
Dismount-IoTFFUImage ffud Dismounts the FFU image
Export-IoTFFUAsWims ffue Exports the EFIESP/MainOS/Data partitions as Wims
New-IoTFFUCIPolicy ffus Scans the MainOS partition and generates CI policy (initialpolicy.xml)
Get-IoTFFUDrives ffugd Returns a hashtable of the drive letters for the mounted partitions

Signing/Test commands

Function Name Alias Description
Set-IoTSignature setsignature Sets the Certificate info used for signing
Set-IoTRetailSign retailsign Sets/resets use of the retail code signing certificate
Test-IoTSignature - Tests if the file is signed for the given config
Test-IoTCabSignature - Tests if the Cab package and its contents are signed for the given config
Test-IoTPackages tpkgs Tests all packages and its contents are signed, for the given product / config
Test-IoTFeatures tfids Tests if all feature ids are defined, for the given product / config
Add-IoTSignature signbinaries Signs files with the cert set via Set-IoTSignature
Redo-IoTCabSignature re-signcabs Resigns cab and its contents using Add-IoTSignature
Test-IoTCerts tcerts Checks if the certs in the workspace folder are all valid

Class documentation

Class Name Factory Method Description
IoTDeviceLayout New-IoTDeviceLayout Class for managing Device Layout xml
IoTFMXML New-IoTFMXML Class for managing Feature Manifest xml
IoTProvisioningXML New-IoTProvisioningXML Class for managing Provisioning XML (Customisations.xml)
IoTWorkspaceXML New-IoTWorkspaceXML Class for managing Workspace xml
IoTOemInputXML New-IoTOemInputXML Class for managing OEMInput.xml
IoTProductSettingsXML New-IoTProductSettingsXML Class for managing IoT Product settings xml
IoTWMXML New-IoTWMXML Class for managing windows manifest xml
IoTWMWriter New-IoTWMWriter Class for writing windows manifest xml
IoTProduct New-IoTProduct Class for managing IoT Product configuration