pmSuspend (Function)

Top  Previous  Next

Architecture:

NX32L

Device support:

All

Firmware version:

1.36.00


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:

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:

Error

Type

ID

Value

Description

False

1

2

1

Wake-up on time.

 

 

 

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.

mode

Description

Blinks every ~10s

Continues after wake-up

Resets on wake-up

0

Automatically selects the lowest possible mode that is able to resume.

(X)

X

 

1

Similar to pmWaitEvent.

X

X

 

2

Lower power consumption than pmWaitEvent.

 

X

 

3

Similar to pmPowerDown.

 

 

X

 

 

 

Returns: DINT

>0

The device was suspended and has woken. Use pmGetWakeSource to get details.

0

This function is not supported.

<0

Failed to suspend. Use pmGetWakeSource to get details.

 

Detailed error codes from pmGetWakeSource for the common errors:

Error

Type

ID

Value

Description

True

0

0

-1

No wake source was selected.

True

0

0

-2

The wake sources do not share a common low power mode.

True

0

0

-3

The mode is not supported on this device.

 

 

 

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;