How is your experience with the OutSystems Community?
thermal-guard
Mobile icon

Thermal Guard

Stable version 1.0.0 (Compatible with OutSystems 11)
Uploaded
 on 18 Nov (8 hours ago)
 by 
0.0
 (0 ratings)
thermal-guard

Thermal Guard

Documentation
1.0.0

ThermalGuard – Device Thermal State Plugin

1. Overview

ThermalGuard is an OutSystems 11 mobile plugin that allows mobile applications to retrieve the device's current thermal status using the native Android PowerManager API.

It helps applications understand the thermal condition reported by the Android operating system and make informed decisions based on the device's thermal state.

The plugin provides two client actions:

  • CheckThermalStateAvailability – Checks whether the device supports the Android thermal status API.

  • GetCurrentThermalState – Retrieves the device's current thermal status.

Important: ThermalGuard retrieves the thermal status reported by Android. It does not measure the device's physical temperature in degrees Celsius.

2. Features

  • Retrieves the current Android thermal status.

  • Checks whether thermal status information is supported.

  • Provides both a readable thermal state and its numeric status code.

  • Uses the native Android PowerManager API.

  • Does not require additional Android permissions.

  • Lightweight Cordova plugin implementation.

  • Supports on-demand thermal status checks.

3. Requirements

RequirementDetails
PlatformOutSystems 11
Application typeMobile
Operating systemAndroid
Minimum Android versionAndroid 10 (API 29)
Native technologyAndroid PowerManager API
Plugin technologyApache Cordova
PermissionsNone required
LicenseMIT

The plugin is Android-only. It does not provide iOS support.

4. Plugin Configuration

Add the following configuration to the OutSystems mobile application's Extensibility Configuration:

{
  "plugin": {
    "url": "https://github.com/murali838/cordova-plugin-thermal-state.git"
  }
}

After configuring the plugin, rebuild the mobile application to include the native implementation.

5. Available Client Actions

5.1 CheckThermalStateAvailability

Description

Checks whether the device supports the Android thermal status API.

The plugin checks whether the Android version is API 29 or higher.

Inputs

No inputs required.

Outputs

OutputData TypeDescription
IsAvailableBooleanIndicates whether the device supports the thermal status API.
ErrorMessageTextContains the error details if the availability check fails.

Usage

Call this action before retrieving thermal status to verify API availability.

Expected behavior

  • Android 10 or higher: IsAvailable = True

  • Android versions below Android 10: IsAvailable = False

5.2 GetCurrentThermalState

Description

Retrieves the current thermal status reported by the Android operating system using the native PowerManager API.

Inputs

No inputs required.

Outputs

OutputData TypeDescription
ThermalStateTextReadable thermal status name.
ThermalStateCodeIntegerNumeric thermal status code returned by Android.
IsSuccessBooleanIndicates whether the thermal status was retrieved successfully.
ErrorMessageTextContains error details if the operation fails.

Usage

Call this action to retrieve the device's current thermal condition.

The action returns both a readable state and its corresponding numeric code.

6. Thermal Status Reference

Android provides the following thermal status values:

CodeStateDescription
0NONENo thermal throttling is currently reported.
1LIGHTLight thermal throttling is reported.
2MODERATEModerate thermal throttling is reported.
3SEVERESevere thermal throttling is reported.
4CRITICALCritical thermal throttling is reported.
5EMERGENCYEmergency thermal condition is reported.
6SHUTDOWNThermal condition has reached the shutdown level.

These values represent the thermal status reported by Android, not a temperature measurement.

7. Implementation Example

A typical implementation can follow these steps:

Step 1 – Check API availability

Call CheckThermalStateAvailability.

  • If IsAvailable is True, proceed to the next step.

  • Otherwise, display an appropriate message indicating that the device does not support the API.

Step 2 – Retrieve the thermal status

Call GetCurrentThermalState.

Step 3 – Process the result

Check IsSuccess before using the returned values.

Use ThermalState or ThermalStateCode to determine the device's current thermal condition.

Example output

{
  "ThermalState": "MODERATE",
  "ThermalStateCode": 2,
  "IsSuccess": true,
  "ErrorMessage": ""
}

The values above illustrate a sample response.

8. Potential Use Cases

ThermalGuard can be used in mobile applications to:

  • Display the device's current thermal condition.

  • Reduce resource-intensive operations when higher thermal states are reported.

  • Adjust background processing based on thermal conditions.

  • Help developers investigate device performance under different thermal conditions.

  • Provide thermal-status information for diagnostics and monitoring screens.

These are potential application scenarios; the plugin itself only retrieves the current thermal status.

9. Limitations and Notes

  • Android-only implementation.

  • Requires Android 10 (API 29) or higher.

  • Retrieves the current thermal status on demand.

  • Does not provide continuous thermal monitoring or thermal-status change listeners.

  • Does not return the actual device temperature in Celsius or Fahrenheit.

  • Does not control device cooling or thermal throttling.

  • Does not guarantee that every thermal status level will be observed during testing, as Android reports the status based on device conditions.

10. Testing

The plugin was integrated and tested in an OutSystems 11 mobile application on a physical OnePlus 13 device.

The following thermal states were successfully observed during testing:

Thermal StateCodeResult
NONE0Passed
MODERATE2Passed

The availability check also returned successfully on the tested device.

Other thermal status levels have not been individually verified.

11. License

ThermalGuard is released under the MIT License.

12. Author

Created by: Murali Manoharan V

Plugin Repository:
https://github.com/murali838/cordova-plugin-thermal-state

Asset: ThermalGuard – Device Thermal State Plugin