pmSuspend (Function)

This function enters power-saving mode and effectively freezes program execution and waits for one or several of the enabled wake-up events.

It has support for more advanced wake-up sources and low power modes than pmWaitEvent.

To enable a wake-up event, please use the following functions:

•accVibrationSetWakeup

•boardDinSetWakeup

•boardSupplySetWakeup

•canSetWakeup

•clockSetWakeup

•displayKeySetWakeup

•gsmSetWakeup

•msVibrationSetWakeup

•serSetWakeup

Additionally, it is possible to wake after a specified number of seconds.

When the event(s) happens, the program will continue operation from the location it was called, if the low power mode supports it.

Please note that pmSuspend does not affect the digital outputs. The user must, if desired, deactivate the outputs before calling pmSuspend to reduce the power consumed by the outputs.

It is not possible to use pmSuspend while the on-board battery is fast-charging, and therefore it may be necessary to disable the charger by using batChargerEnable.

pmSuspend return codes for the time wake-up source:

Input:

Time : DINT (default: -1)

The device waits a number of seconds.

If Time is -1 or 0, the event will be disabled.

If wake on RTC is enabled, wake on time can not also be enabled.

Mode : SINT (default: 0)

Selects the low power mode to use.

Returns: DINT

Detailed error codes from pmGetWakeSource for the common errors:

Declaration:

FUNCTION pmSuspend : DINT;
VAR_INPUT
  time           : DINT := -1;
  mode           : SINT := 0;
END_VAR;

Example:

//-----------------------------------------------------------------------------
// Example of how to use pmSuspend.
//
//-----------------------------------------------------------------------------
INCLUDE rtcu.inc
 
//  Input variables that can be configured via the configuration dialog (These are global)
VAR_INPUT
  suspend : BOOL; | Set this switch to enable suspend
  absolute_time : BOOL; | Set to true to sleep until the next hour starts, false will sleep for 10 minutes
END_VAR;
 
PROGRAM test;
// These are the local variables of the program block
VAR
  rc    : INT;
  wk    : DINT;
  type, id, val : INT;
  err   : BOOL;
END_VAR;
// The next code will only be executed once after the program starts
  // Disable charger as it prevents suspend.
  batChargerEnable(enable := FALSE);
 
  // Enable wake on DIN 1 rising edge.
  rc := boardDinSetWakeup(pin := 1, rising := TRUE);
  DebugFmt(message:="boardDinSetWakeup: \1", v1 := rc);
 
  // Enable wake on power apply.
  rc := boardSupplySetWakeup(apply := TRUE);
  DebugFmt(message:="boardSupplySetWakeup: \1", v1 := rc);
 
BEGIN
// Code from this point until END will be executed repeatedly
 
  IF suspend THEN
    IF absolute_time THEN
        // Enable wake-up when minute and second are 0, i.e. when the hour starts.
        rc := clockSetWakeup(minute := 0, second := 0);
        DebugFmt(message:="clockSetWakeup: \1", v1 := rc);
       
        // Suspend until an event occurs or until the next hour starts.
        DebugFmt(message:="Calling pmSuspend");
        wk := pmSuspend(time:=-1, mode := 0);      
    ELSE
        // Suspend for 10 minutes or until an event occurs.
        DebugFmt(message:="Calling pmSuspend");
        wk := pmSuspend(time:=600, mode := 0);
    END_IF;
     
    IF wk < 0 THEN
        DebugFmt(message:="pmSuspend failed");
    ELSE
        DebugFmt(message:="pmSuspend succeeded");
    END_IF;
     
    rc := pmGetWakeSource(source:=wk, error:=err, type:=type,id:=id,value:=val);
    DebugFmt(message:="$ttype: \1", v1:=type);
    DebugFmt(message:="$tid: \1", v1:=id);
    DebugFmt(message:="$tval: \1", v1:=val);
    DebugFmt(message:=pmGetWakeSourceString(source := wk));
    IF suspend THEN
        // Wait for a few seconds on error
        Sleep(delay:=5000);
    END_IF;
  END_IF;
END;
END_PROGRAM;