DPSL.js Migration Guide

Objective

As we are encouraging OEMs to call Chrome Extension APIs directly instead of via DPSL.js, this document provides an overview of what is changing for OEMs. In most cases this only requires a method call replacement, since DPSL.js is a thin wrapper around our Chrome Extension APIs.

The telemetry namespace (dpsl.telemetry)

Calls in the chrome.os.telemetry namespace are a 1:1 mapping from dpsl APIs to extension API calls. The only difference is that dpsl catches the case of calling an undefined API (assuming it is undefined because it is not yet released) and throws a MethodNotFoundError.

The table below shows the mapping from dpsl calls to Chrome Extension calls, the returned data is equivalent and the chrome extension APIs are also asynchronous.

The diagnostics namespace (dpsl.diagnostics)

Similar to the telemetry namespace, functions in the diagnostics namespace also map 1:1 to Chrome Extension functions. The only difference is, that dpsl APIs return a Routine object that wraps Chrome Extension APIs for handling diagnostics nicely. OEMs can copy the definition of this wrapper class to their own codebase to have the same experience as with using dpsl.Routine.

Alternatively, OEMs can also interact directly with Chrome Extension calls to control a routine. The return value of every chrome.os.diagnostics.runXYZRoutine is an object that defines the following fields:

// Will be represented as a string in JavaScript, e.g. "ready".
enum RoutineStatus {
  unknown,
  ready,
  running,
  waiting_user_action,
  passed,
  failed,
  error,
  cancelled,
  failed_to_start,
  removed,
  cancelling,
  unsupported,
  not_run
};

// Returned from `chrome.os.runXYZRoutine`.
dictionary RunRoutineResponse {
  // The id will turn into a `number` in JavaScript.
  long id;
  RoutineStatus status;
};

The RoutineStatus tells the OEMs whether the request to start a routine was successful. If the status is “running”, one can assume that the routine has been started successfully. However, for routines that complete very quickly, it is possible that the routine will enter a final state (“passed”, “failed”, or “error”) before the “running” state is observed. The id is a unique identifier used for tracking a specific routine over its lifetime.

To interact with a started routine, OEMs can use the chrome.os.diagnostics.getRoutineUpdate function. It takes an RoutineUpdateRequest object as a parameter and returns a GetRoutineUpdateResponse object. The two objects are defined as follows:

enum RoutineCommandType {
  cancel,
  remove,
  resume,
  status
};

dictionary GetRoutineUpdateRequest {
  long id;
  RoutineCommandType command;
};

enum UserMessageType {
  unknown,
  unplug_ac_power,
  plug_in_ac_power
};

dictionary GetRoutineUpdateResponse {
  long progress_percent;
  // The question mark represents an optional value.
  DOMString? output;
  // The routine status is the same as above.
  RoutineStatus status;
  DOMString status_message;
  // Returned for routines that require user action (e.g. unplug power cable), the
  // question mark represents an optional value.
  UserMessageType? user_message;
};

The following operations can be done via calling chrome.os.diagnostics.getRoutineUpdate, all represented by a different RoutineCommandType:

• Resume a currently waiting routine (e.g. after it needed user input) with “resume”
• Cancel a running routine with “cancel”
• Get the status of a routine with “status”
• Remove a routine (and release its allocated resources) with “remove”

Note: OEMs need to make sure to properly remove routines they manually stopped, since cancel doesn‘t include removal and doesn’t deallocate resources. After canceling a routine it should always be removed.

As mentioned above the dpsl.Routine object encapsulates all this functionality into three methods:

• getStatus: Calling routine update with “status”, returns information about the current routine status
• resume: Resumes a currently waiting routine
• stop: Stops a routine and also removes it (so resulting in two calls to getRoutineUpdate)

The following table shows the mapping from dpsl API calls to Chrome Extension API calls; the input parameters are the same.