[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

Set up Shimless RMA Mode

1. Run the following script 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

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

$ 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

2. 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 propogate the change.
$ stop cros_healthd
$ start cros_healthd 

Build and Install the Extension

1. Enter the diagnostics-extension subdirectory:

cd diagnostics-extension

2. Modify permission and externally_connectable attribute of 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 fiile to the DUT:

$ scp cros-sample-telemetry-extension/diagnostics-extension/build.crx $DUT://mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.crx
$ chmod 777 /mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.crx

Build and Install the App

1. Build app by running the following commands:

$ cd diagnostics-app
$ npm ci
$ npm run build_iwa

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

2. Deploy the app files to DUT

$ scp cros-sample-telemetry-extension/diagnostics-app/dist/iwa/sample-iwa.swbn $DUT://mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.swbn
$ chmod 777 /mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.swbn

Install and run the Diagnostics App

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.