Power Management / Standby

Power Management (aka Standby) is a complex subject. Please also refer to the following documents:

• Power Management Service
• TOI Power Control API reference
• CONST_POWER_LOWEST_PROFILE
• VAR_IO_STATE

The portal first creates an instance of a power controller with a call to ToiPlatformService.createPowerControlInstance() . This power controller lets the portal perform power management actions.

powerControl = toi.platformService.createPowerControlInstance(
  toi.consts.ToiPowerControl.ACCESS_REPORT_ONLY);

Applications can choose one of two ways to access this power controller:

ACCESS_REPORT_ONLY

This is the simple, standard way to handle Power Management and Standby functionality. The portal application will be notified when the STB is about to change power profile (as a result of the end-user pressing the Standby button, for example).

ACCESS_REPORT_AND_REQUEST

If your portal needs to switch power profile (e.g., put the STB into standby from the portal code), or override the default behavior of the Standby button, then this is the appropriate mode. Note that this mode needs kreatv-option-powermanagement::power_client_limit=1 (or higher) in the boot image configuration.

ACCESS_REPORT_ONLY works for most common situations, and is the mode used and described in this document.

Power Profile requests

When a change in power profile (standby state) is requested, the KreaTV platform notifies applications via the ToiPowerControl.ON_POWER_PROFILE_REQUESTED and ToiPowerControl.ON_POWER_PROFILE_SELECTED events. Implementing these power profile change requests in response to standby button presses or the auto power down timer is handled by the platform. The portal next adds two listeners for these events, as follows:

powerControl.addEventListener(
  toi.consts.ToiPowerControl.ON_POWER_PROFILE_REQUESTED,
  onPowerProfileRequested);

powerControl.addEventListener(
  toi.consts.ToiPowerControl.ON_POWER_PROFILE_SELECTED,
  onPowerProfileSelected);

In addition, the portal initializes some variables it uses when changing power profile. These are discussed later.

var lowestAcceptableProfile;
var pendingActions = 0;
var mediaPlayerShuttingDown = false;

Handling a Power Profile Request

When the end-user presses Standby on the remote control, or when the auto power down timer expires, the KreaTV platform generates an ON_POWER_PROFILE_REQUESTED event. This event goes out to all running applications (including your portal, and other platform applications), to let them know that a different power profile has been requested.. The arguments in the event include the power profile being requested, and the reason for the profile switching. If the request is acceptable to the application, then the application responds with the requested profile. If the request is not acceptable (the request may be to go into passive standby, but a DVR recording is currently ongoing so the lowest acceptable power profile is then active standby), then the application responds with the lowest power profile it can currently accept.

function onPowerProfileRequested(event) {
  if (powerControl.getCurrentPowerProfile() ==
      toi.consts.ToiPowerControl.PROFILE_ACTIVE &&
        event.reason == toi.consts.ToiPowerControl.REASON_AUTO_POWER_DOWN) {
    ...
  }
  powerControl.reportPowerProfile(lowestAcceptableProfile);
}

The portal replies by calling ToiPowerControl.reportPowerProfile() with the lowest power profile it is prepared to accept, in this example it is PROFILE_ACTIVE_STANDBY.

No request is issued when transitioning from Standby to active, since no application will refuse this.

Handling the Profile Selected event

When each of the running applications (your portal, any secondary applications and KreaTV platform services) have reported the lowest profile they can accept, the KreaTV platform determines the lowest profile which is acceptable to all applications. It then informs all the applications of this selection with an event, ToiPowerControlPowerProfileSelectedEvent . Upon receiving this event, the portal should perform any actions it needs to do before transitioning to the chosen power profile (such as shutting down a running media player, saving current data, waiting for a download to complete, etc).

Once the portal has completed it's actions (more on this in a moment), it calls ToiPowerControl.reportPowerProfileActionsComplete() . When every application has called this function, there is nothing left to do and the KreaTV platform then carries out the change to the selected power profile.

Actions

Depending on the power profile selected (that is, the one being transitioned to), the portal may wish to perform certain actions before the profile change is actually carried out. For example, if the selected profile is PROFILE_PASSIVE_STANDBY the example portal stops the media player streaming. If PROFILE_ACTIVE is selected (the STB is leaving Standby and becoming active) then the example portal starts the media player again:

function onPowerProfileSelected(event) {
  switch (event.profile) {
    case toi.consts.ToiPowerControl.PROFILE_ACTIVE:
        // tune to the current channel
        ...
      // acknowledge the profile state change
      onPowerActionComplete();
      break;
    default:
      if (mediaPlayer.getState() !=
          toi.consts.ToiMediaPlayerBase.STATE_IDLE) {
        // start media player shutdown
        pendingActions++;
        mediaPlayerShuttingDown = true;
        mediaPlayer.close();
      }
      else {
        onPowerActionComplete();
      }
  }
}

The media player does not instantly open or close. The example portal adds a media media player state change listener, which gets called each time the media player completes a state change. Most of these are uninteresting, unless mediaPlayerShuttingDown has been set to true. When the media player has reached STATE_IDLE (or failed), there is no more shutting down activities to be performed, so the listener calls onPowerActionComplete()

function onMediaPlayerStateChanged(event) {
  if (!mediaPlayerShuttingDown) {
    return;
  }
  switch (event.state) {
    case toi.consts.ToiMediaPlayerBase.STATE_IDLE:
    case toi.consts.ToiMediaPlayerBase.STATE_STOPPED:
    case toi.consts.ToiMediaPlayerBase.STATE_FAILED:
      onPowerActionComplete();
      mediaPlayerShuttingDown = false;
      break;
  }
}

The onPowerActionComplete() function decrements its counter of the number of actions (the portal might have media recorders also shutting down, for example) and when all actions are complete, calls the ToiPowerControl.reportPowerProfileActionsComplete() function.

function onPowerActionComplete() {
  console.log("onPowerActionComplete()");
  if (pendingActions > 0) {
    pendingActions--;
  }
  if (pendingActions === 0) {
    powerControl.reportPowerProfileActionsComplete();
  }
}

Wake-up timer

If a wake-up timer is desired, call powerControl.setWakeupTimeout() with a value in seconds, before calling reportPowerProfileActionsComplete(). Several applications may set a wake-up timer (the scheduler will do this if there are scheduled recordings, for example). Note: the wake-up timer closest in time will be chosen, and the rest discarded. This means that it is possible for your portal to be woken up earlier than expected. See the TOI API on setWakeupTimeout() for more info.

Don't forget to remove the listeners and release the powerControl instance in the portal unload code. For more information on Power Management in general, see the Power Management Service documentation.

Auto Power Down Timer

A configuration object, cfg.power.apd.timeout, can be set to trigger an event when the user has not pressed any remote control or front panel buttons for some time. The KreaTV platform resets a counter each time the user interracts with the STB. If the counter reaches the cfg.power.apd.timeout value (in seconds), then the platform will send a power profile change request, with the reason REASON_AUTO_POWER_DOWN. The portal should now show a dialog box, offering the user the option to cancel (or disable) the auto power down feature. If no user response is received in a reasonable time (~10 seconds?) the portal can proceed with the shutdown. If the user elects to cancel the auto power down activity, call ToiPowerControl.reportPowerProfile() with the profile PROFILE_ACTIVE. The normal power management activities apply from this point on (the selected call, and reporting actions complete).

Auto power down can be disabled by setting the value of the timer to 0. Note however that it is not permitted to supply the end user with software which has this feature disabled by default.

Additional notes

Listeners on Information Service objects

If you use an Infocast server, when the STB wakes up from passive standby it is not certain that the same configuration objects are still being transmitted from the Infocast server. To prevent the portal from using potentially stale data, the value of objects transmitted over the network will be reset to an empty string as the platform starts up again. If the portal has subscribed to changes on any of these objects, this resetting of the object will trigger the listener function. In addition, a short moment later a current value may be received from Infocast server, and the listener will be triggered again, this time with the configuration object holding the received data.