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 firsts creates an instance of a power controller with a call to ToiPlatformService::createPowerControlInstance() . This power controller lets the portal perform power management actions.

// get powerControl instance
this.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

The mode is the usual way to handle power control in applications. When using this mode, the platform notifies power profile changes to the application by using the ToiPowerControl::ON_POWER_PROFILE_REQUESTED and ToiPowerControl::ON_POWER_PROFILE_SELECTED events. Triggering these power profile change requests in response to standby button presses or the auto power down timer is handled by the platform.

ACCESS_REPORT_AND_REQUEST

The mode is available for applications that need to have full control over when and how these power profile changes happen. When an application is running in ACCESS_REPORT_AND_REQUEST mode, the platform relays all responsibility for initiating power profile switches, meaning that it is the application who must request the different power profiles in response to standby button operation or after a period of inactivity. When the ToiPowerControl::ON_AUTO_POWER_DOWN_TIMER_EXPIRED event happens, it will inform applications to initiate the power profile changes request in ACCESS_REPORT_AND_REQUEST mode.

The portal next adds two listeners for the ON_POWER_PROFILE_REQUESTED and ON_POWER_PROFILE_SELECTED events, as follows:

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

Lastly, the portal initializes some variables it uses when changing power profile:

this.powerLowestAcceptableProfile =
  toi.consts.ToiPowerControl.PROFILE_ACTIVE_STANDBY;
this.powerPendingActions = 0;
this.mediaPlayerShuttingDown = false;

Handling a Power Profile Request

The ON_POWER_PROFILE_REQUESTED event will occur when the KreaTV platform requests a power profile change, as a result of the user pressing Standby on the remote control, or when the auto power down timer expires. This event goes out to all running applications (including your portal, and other platform applications). The arguments 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.

onPowerProfileRequested: function(event) {
  if (this.powerControl.getCurrentPowerProfile() ==
      toi.consts.ToiPowerControl.PROFILE_ACTIVE &&
      event.reason == toi.consts.ToiPowerControl.REASON_AUTO_POWER_DOWN) {
    this.do("ShowAutoPowerDown");
    return;
  }
  this.powerControl.reportPowerProfile(this.powerLowestAcceptableProfile);
},

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. The example portal will start and stop the media player streaming when transitioning in and out of standby, as follows:

onPowerProfileSelected: function(event) {
  switch (event.profile) {
  case toi.consts.ToiPowerControl.PROFILE_ACTIVE:
    if (this.mediaPlayer.getState() !=
        toi.consts.ToiMediaPlayerBase.STATE_PLAYING) {
      // wake up media player
      this.do("ChangeChannel", this.currentChannelIndex);
    }
    this.onPowerActionComplete();
    break;
  default:
    // shut down media player. As this takes some time, add a pending
    // power action
    if (this.mediaPlayer.getState() != this.mediaPlayer.STATE_IDLE) {
      this.powerPendingActions++;
      this.mediaPlayerShuttingDown = true;
      this.mediaPlayer.close();
      // as soon as mediaplayer is closed it decrements the pending
      // actions counter
    }
    else {
      this.onPowerActionComplete();
    }
  }
},

The media player does not instantly open or close, so the media player state change listener is used. This listener is called when the media player completes its state change. After closing, when the media player has reached STATE_IDLE, the listener calls onPowerActionComplete()

case toi.consts.ToiMediaPlayerBase.STATE_IDLE:
case toi.consts.ToiMediaPlayerBase.STATE_STOPPED:
case toi.consts.ToiMediaPlayerBase.STATE_FAILED:
  if (this.mediaPlayerShuttingDown) {
    // media player has shut down, report actions complete
    this.onPowerActionComplete();
    this.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.

onPowerActionComplete: function() {
  if (this.powerPendingActions > 0) {
    this.powerPendingActions--;
  }
  if (this.powerPendingActions === 0) {
    // no more pending async actions, time to report that all actions
    // have been completed and power profile change can take place
    this.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.