[Tutorial] Shimless RMA

Prerequisites

1. Clone the repo here: https://github.com/GoogleChromeLabs/cros-sample-telemetry-extension
2. Put the device must be in developer mode, follow instructions here
3. The device root file system must have write permission enabled (Run /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification on your DUT)

Set up Shimless RMA Mode

1. Run the following script on your DUT to enter RMA Mode

$ mkdir -p /mnt/stateful_partition/unencrypted/rma-data
$ touch /mnt/stateful_partition/unencrypted/rma-data/state
$ chown rmad /mnt/stateful_partition/unencrypted/rma-data/state
$ mkdir -p /var/lib/rmad/.test
$ start rmad # or restart rmad if rmad is already started

Set up 3p Diagnostics environment on your DUT

1. Enable OS flags by appending to the file /etc/chrome_dev.conf on DUT:

$ vim /etc/chrome_dev.conf

...
################################################################################
# This file should only be modified by hand by developers on their local
# dev-mode devices; do not check in changes to it or write code that modifies
# it. Permanent changes to Chrome's configuration, including conditionally-set
# flags, should be made in session_manager (see chrome_setup.h).
#
# To edit this file rootfs write protection must be removed:
# https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md#disable-verity
################################################################################
--enable-features=IsolatedWebAppDevMode,ShimlessRMA3pDiagnosticsDevMode,,ShimlessRMA3pDiagnosticsAllowPermissionPolicy

2. Change cros_healthd init config to run using test chromeos-config by appending the --test_cros_config flag:

$ vim /etc/init/cros_healthd.conf

...
# Run the daemon.
exec /usr/bin/cros_healthd --test_cros_config

3. Override the device OEM to Google

$ cp -r /run/chromeos-config/v1 /run/chromeos-config/test
$ printf %s 'Google' > /run/chromeos-config/test/branding/oem-name
# Note: You must stop then restart cros_healthd here, running restart will not propagate the change.
$ stop cros_healthd && start cros_healthd 

Build and Deploy the Extension

1. Enter the diagnostics-extension subdirectory in cros-sample-telemetry-extension repo:

cd diagnostics-extension

2. Modify permission and externally_connectable attribute in public/manifest.json to match the IWA ID. Alternatively, you can copy paste the below file content:

$ vim public/manifest.json

{
  "name": "Chrome OS Diagnostics Companion Extension",
  "version": "1.9.0",
  "description": "The companion extension for the ChromeOS Diagnostics App.",
  "manifest_version": 3,
  "chromeos_system_extension": {},
  "icons": {
    "16": "images/favicon-16x16.png",
    "32": "images/favicon-32x32.png",
    "48": "images/favicon-48x48.png",
    "128": "images/favicon-120x120.png",
    "192": "images/favicon-192x192.png"
  },
  "permissions": [
    "os.telemetry",
    "os.attached_device_info",
    "os.diagnostics",
    "os.events",
    "os.telemetry.serial_number",
    "os.telemetry.network_info"
  ],
  "background": {
    "service_worker": "sw.js"
  },
  "externally_connectable": {
    "matches": [
      "isolated-app://pt2jysa7yu326m2cbu5mce4rrajvguagronrsqwn5dhbaris6eaaaaic/*"
    ]
  }
}

3. Build the extension files:

$ npm ci
$ npm run build

4. Package the extension into .crx format:

$ /usr/bin/google-chrome --pack-extension=./build --pack-extension-key=private_key.pem

5. Deploy the extension files to the DUT:

$ export DUT="Your-DUT-hostname"
$ scp build.crx $DUT://mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.crx
$ ssh $DUT chmod 777 /mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.crx  # Make sure the file is visible

Build and Deploy the App

1. Enter the diagnostics-app subdirectory in cros-sample-telemetry-extension repo:

$ cd diagnostics-app

2. Build app by running the following commands:

$ npm ci
$ npm run build_iwa

You should see the file sample-iwa.swbn at cros-sample-telemetry-extension/diagnostics-app/dist/iwa.

3. Deploy the app files to DUT

$ export DUT="Your-DUT-hostname"
$ scp dist/iwa/sample-iwa.swbn $DUT://mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.swbn
$ ssh $DUT chmod 777 /mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.swbn  # Make sure the file is visible

Install and run the Diagnostics App on your DUT

1. Enter shimless RMA page by restarting UI:

$ restart ui

2. Open the diagnostics app by pressing alt + shift + D

3. Review and accept permissions to see the app window.