Connect
Ask Community
Ask the community
Ask Community
  • Home
  • ROM Enrollment with System Agent

ROM Enrollment with System Agent

General Steps

The steps listed here are a high level overview of the process to complete ROM enrollment with Hexnode UEM. Specific examples to achieve this is explained in the next section.

Hexnode UEM must be enabled with the system agent when –

  • Software updates must be deployed.

    • Step – 1: Generate ROM Configuration File

    • Generate the ROM Configuration file from your Hexnode UEM console and download the file. You will get a hex_rom_config.txt file.

    Step – 2: Add Hexnode UEM App as a Pre-built Application

    • The Hexnode UEM app must be added as a system app(priv-app). The app must not be signed by the vendor. If the app is signed, Hexnode UEM app will not be able to update itself unless each update is signed by the vendor. So, it is recommended to leave the Hexnode UEM app with the default signature. Download the latest version of the app here – Hexnode UEM.apk.

    Step – 3: Add Hexnode System Agent App as a Pre-built Application

    • The Hexnode System Agent app must be added as a system app(priv-app). The app must not be signed by the vendor. If the app is signed, Hexnode System Agent app will not be able to update itself unless each update is signed by the vendor. So, it is recommended to leave the Hexnode System Agent app with the default signature. Download the latest version of the app here – Hexnode System Agent.apk.

    Step – 4: Declare Necessary Permissions for Hexnode UEM app and the System Agent App

    • The Hexnode UEM and System Agent app must be granted all the necessary permissions to function on the device, without requiring the end user to manually grant them during runtime. Android provides a python script – privapp_permissions.py; to generate the privapp-permissions.xml file for priv-apps. Placing this generated file in /frameworks/base/data/etc/ will ensure that the permissions are auto-granted.
    • As an example, the following lists the permissions required by the Hexnode UEM app.

    Step – 5: Allow Dangerous Permissions Silently

    • The app must be able to get all possible permissions without user interaction. When the device boots up, Hexnode UEM should have all possible permissions allowed. To do this, the dangerous permission exceptions must be declared. If the permissions were granted using the

    Notes

    • For detailed steps, see the detailed explanation later in the doc.
    • All permissions that must be auto-granted can be given here, based on the compliance requirements.

    Step – 6: Device Owner Permissions

    • The Hexnode UEM app must be provided device owner permissions. The following must be added to device_policies.xml file.

    • The following must be added to device_owner_2.xml file.

    • Both of these files must be present in the /system folder once the build is complete.

    Step – 7: Place Hexnode Configuration File

    • Place the hex_rom_config.txt file in /system. The file must be accessible by the Hexnode UEM app.

    Step – 8: Draw over Other Apps

    • Allow Hexnode UEM app to draw over other apps if possible.

    Step – 9: Launcher Permissions

    • Optional step. Please ensure that Hexnode UEM app is allowed to act as a launcher, if the device is intended for use as a kiosk.

    Step – 10: Provide Root Permissions

    • Optional step. If root access is required, provide root privileges to Hexnode UEM app.

    Step – 11: Build the ROM

    • Build the ROM and flash the ROM on the devices. The devices must boot up and directly open the Hexnode UEM app.

    Detailed Steps

    The steps provided here have been specifically tested in device with Android version and build. The file systems and partitions mentioned might be specific to these devices or builds.

    To be performed by a Hexnode admin.

    Step – 1: Generate ROM Configuration File.
    • From the Hexnode UEM console, generate the ROM configuration file and download it. You should obtain a file named hex_rom_config.txt. If the downloaded file has a different name, please rename the file to hex_rom_config.txt. Also, download the latest version of the Hexnode app – Hexnode UEM.apk. Pass the generated file, the Hexnode UEM application and this document to the device vendor.

    To be performed by the device vendor before building the ROM.

    Step – 2: Add Hexnode UEM app as a pre-built application.
    1. In your source move to the apps directory.
      Path –

    2. Create a folder with the name hexnodemdm
    3. Move to the folder hexnodemdm.
      Path –

    4. Place the Hexnode UEM app in the hexnodemdm folder. The latest app can be downloaded from this link – Hexnode UEM.apk.
    5. Create a file named Android.mk in the same directory.
    6. Add these lines to the file Android.mk and save it.

    7. Move to the product directory.
      Path –

    8. Find the file named handheld_system.mk.
    9. Edit the file handheld_system.mk and mention the module name hexnodemdm under PRODUCT_PACKAGES list.
    10. Save the file.
    Step – 4: Allow Permissions Silently

    The Hexnode UEM app must be provided specific permissions to access the Hexnode Configuration file downloaded in Step – 1, and several other permissions so that the application can function as intended.

    1. Generate permissions required by apk to be included in privapp-permissions.xml by executing:

    2. Running this command should list all the permissions required by the application. If nothing appears, begin the build process (steps provided in later sections of the document). Once the build completes, rerun the script, specifying the path of the APK in the output directory. This will list the required permissions. Copy these permissions listed.
    3. Navigate to –

    4. Add the permissions inside privapp-permissions package tag. As an example, if the permissions that were listed were – android.permission.DELETE_PACKAGES, android.permission.INSTALL_PACKAGES, and android.permission.MOUNT_UNMOUNT_FILESYSTEMS, the following lines should be added –

    5. Build the ROM again and all necessary permissions must be granted to the application.
    Detailed Steps – Android 9+

    To be performed by a Hexnode admin.

    Step – 1: Generate ROM Configuration File.
    • From the Hexnode UEM console, generate the ROM configuration file and download it. You should obtain a file named hex_rom_config.txt. If the downloaded file has a different name, please rename the file to hex_rom_config.txt. Also, download the latest version of the Hexnode app – Hexnode UEM.apk. Pass the generated file, the Hexnode UEM application and this document to the device vendor.

    To be performed by the device vendor before building the ROM.

    Step – 2: Add Hexnode UEM app as a pre-built application.
    1. In your source move to the apps directory.
      Path –

    2. Create a folder with the name hexnodemdm
    3. Move to the folder hexnodemdm.
      Path –

    4. Place the Hexnode UEM app in the hexnodemdm folder. The latest app can be downloaded from this link – Hexnode UEM.apk.
    5. Create a file named Android.mk in the same directory.
    6. Add these lines to the file Android.mk and save it.

    7. Move to the product directory.
      Path –

    8. Find the file named handheld_system.mk.
    9. Edit the file handheld_system.mk and mention the module name hexnodemdm under PRODUCT_PACKAGES list.
    10. Save the file.
    Step – 3: Declare Necessary Permissions.
    1. Move to the folder etc.
      Path –

    2. Find the file named privapp-permissions-platform.xml.
    3. Edit the file and add the following lines –

    4. Save the file privapp-permissions-platform.xml.
    Step – 4: Allow Permissions Silently
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Pixel 4a 5G, the folder is /device/google/bramble/

    2. Create a file named default-permissions-sample.xml.
    3. Edit the file and add the following lines –

    4. Save the file default-permissions-sample.xml.
    Step – 5: Device Owner Permissions
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Pixel 4a 5G, the folder is /device/google/bramble/

    2. Create a file named device_policies.xml. Add the following lines and save the file.

    3. Create a file named device_owner_2.xml in the same directory and add these lines.

    4. Save the files.
    Step – 6: Place the ROM Config File
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Pixel 4a 5G, the folder is /device/google/bramble/

    2. Place the hex_rom_config.txt file inside this folder that was obtained from Step – 1.
    Step – 7: Inject Rom Config, Device Owner and the Permission Files
    For Android 11 –
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Pixel 4a 5G, the folder is /device/google/bramble/

    2. Find the configuration files – aosp_<device_model>.mk and device_<device_model>.mk. If these files are not present, follow the steps for Android 12 given below.

      3. For a Pixel 4a 5G, the files are named aosp_bramble.mk and device_bramble.mk.

    3. Add the following lines to both of these files.

    4. Save the files.
    5. Edit your init.rc file.

      6. Path –

    6. Add the following lines under post-fs-data.

    For Android 12 –
    1. Move to the folder product. Path –

    2. Find the files base_system.mk and base_product.mk. If these files are not present, follow the steps for Android 11 provided above.
    3. Add the following lines in base_system.mk.

    4. Add the following lines in base_product.mk.

    5. Save the files.
    6. Edit your init.rc file.

      7. Path –

    7. Add the following lines under post-fs-data.

    Step – 8: Draw over Other Apps
    • Allow the Hexnode UEM app to draw over other apps if possible. The method to do this is different for each vendor.
    Step – 9: Launcher Permissions
    • Optional step. Please ensure that Hexnode UEM app is allowed to act as a launcher, if the device is intended for use as a kiosk.
    Step – 10: Provide Root Permissions
    • Optional step. If root access is required, provide root privileges to the Hexnode UEM app.
    Step – 11: Build your ROM
    • Once these steps are completed, build your ROM and flash it on a test device.

    Testing and Troubleshooting

    The following cases must be tested to ensure that the ROM Enrollment is successful.
    Illegal entries error while building ROM.

    The PRODUCT_COPY_FILES action on default-permission-sample.xml may return an illegal entry error. In such cases, change the initial file location to base_product.mk or base_system.mk, make necessary changes to the file and retry the build.

    Hexnode UEM is not automatically started at device boot.

    The Hexnode UEM app must be automatically started and the app must run in full screen as soon as the device boots up. If the app does not open, sufficient permissions are not provided. Please check if all permissions are provided.

    Detailed Steps: Android 7+

    To be performed by a Hexnode admin.

    Step – 1: Generate ROM Configuration File.
    • From the Hexnode UEM console, generate the ROM configuration file and download it. You should obtain a file named hex_rom_config.txt. If the downloaded file has a different name, please rename the file to hex_rom_config.txt. Also, download the latest version of the Hexnode app – Hexnode UEM.apk. Pass the generated file, the Hexnode UEM application and this document to the device vendor.

    To be performed by the device vendor before building the ROM.

    Step – 2: Add Hexnode UEM app as a pre-built application.
    1. In your source move to the apps directory.
      Path –

    2. Create a folder with the name hexnodemdm
    3. Move to the folder hexnodemdm.
      Path –

    4. Place the Hexnode UEM app in the hexnodemdm folder. The latest app can be downloaded from this link – Hexnode UEM.apk.
    5. Create a file named Android.mk in the same directory.
    6. Add these lines to the file Android.mk and save it.

    7. Move to the product directory.
      Path –

    8. Find the file named core.mk.
    9. Edit the file core.mk and mention the module name hexnodemdm under PRODUCT_PACKAGES list.
    10. Save the file.
    Step – 3: Declare Necessary Permissions.
    1. Move to the folder etc.
      Path –

    2. Find the file named privapp-permissions-platform.xml.
    3. Edit the file and add the following lines –

    4. Save the file privapp-permissions-platform.xml.
    Step – 4: Allow Permissions Silently
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Google Pixel(Pixel 1), the folder is /device/google/sailfish/

    2. Edit the file named default-permissions.xml.
    3. Add the following lines –

    4. Save the file default-permissions.xml.

    Notes

    • You can add additional permissions that must be automatically granted.
    Step – 5: Device Owner Permissions
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Google Pixel (Pixel 1), the folder is /device/google/sailfish/

    2. Create a file named device_policies.xml. Add the following lines and save the file.

    3. Create a file named device_owner_2.xml in the same directory and add these lines.

    4. Save the files.
    Step – 6: Place the ROM Config File
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Google Pixel(Pixel 1), the folder is /device/google/sailfish/

    2. Place the hex_rom_config.txt file inside this folder that was obtained from Step – 1.
    Step – 7: Inject Rom Config, Device Owner and the Permission Files
    1. Move to the folder <model_name>.This can be in a core folder on the device where the default permissions for apps such as Phone, Messages, etc. are stored.

      2. Path –

      Example – For Google Pixel(Pixel 1), the folder is /device/google/sailfish/

    2. Find the configuration files – device-<device_model>.mk and device-common.mk.

      3. For a Google Pixel (Pixel 1), the files are named device-sailfish.mk and device-common.mk.

    3. Add the following lines to both of these files.

    4. Save the files.
    5. Edit your init.rc file.

      6. Path –

    6. Add the following lines under post-fs-data.

    Step – 8: Draw over Other Apps
    • Allow the Hexnode UEM app to draw over other apps if possible. The method to do this is different for each vendor.
    Step – 9: Launcher Permissions
    • Optional step. Please ensure that Hexnode UEM app is allowed to act as a launcher, if the device is intended for use as a kiosk.
    Step – 10: Provide Root Permissions
    • Optional step. If root access is required, provide root privileges to the Hexnode UEM app.
    Step – 11: Build your ROM
    • Once these steps are completed, build your ROM and flash it on a test device.