com.webos.service.power2
API Summary
Allows client applications to power-on, power-off, and perform other power-related operations on the device.
Overview of the API
By using this service, a client application can control the power state of the device.
Note: Power states are device-specific, and these states will be added in further revisions to this document.
Using the APIs provided by this service, client application do the following:
- Set the device in different power states:
- setState(), getState()
- reboot()
- shutdown()
- Register for state change transitions and confirm the transitions where applicable:
- registerStateTransition()
- respondStateTransitionAck()
- Set a wake lock on the device
- acquireWakeLock ()
- releaseWakeLock()
- Specify power-on reason
- setPowerOnReason()
- getPowerOnReason()
Check descriptions of specific methods to get relevant details.
Methods
setState
Description
Sets the state of the device.
This method forcefully sets the state and ignores the sequential flow of power states. This means that the client is not prompted for acknowledgement, even if you have registered for state change notifications (using registerStateTransition() method).
Note: This method can also reboot or shutdown the device. However, it is advisable to use the specific methods provided for these purposes.
Parameters
Name | Required | Type | Description |
---|---|---|---|
state | Required | String | State to be set. |
reason | Required | Number | The event that caused the state change. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Set the state to ACTIVE due to wake on LAN via external device network
# luna-send -n 1 luna://com.webos.service.power2/setState '{
"state":"ActiveState",
"reason":1
}'
Response:
{
"returnValue": true
}
getState
Description
Obtains the currently set state.
Parameters
Name | Required | Type | Description |
---|---|---|---|
subscribe | Optional | Boolean | Subscribe for notifications on state changes.
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
state | Required | String | Current state. |
subscribed | Required | Boolean | Indicates whether subscribed. |
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
state | Required | String | Current state. |
Example
Example: Subscribe for state change
# luna-send -n i luna://com.webos.service.power2/getState '{
"subscribe":true
}'
Response:
{
"state": "ActiveState",
"subscribed": true,
"returnValue": true
}
registerStateTransition
Description
Clients can register to get notified when the state changes from a specified state. For example, if registered to get notifications on state “ACTIVE”, you will get notified when state changes from “ACTIVE” to any other state.
Some transitions require acceptance (acknowledgement) from all clients who register to this state. For this check the respondStateTransitionAck() method.
Note: It is a subscription method. Subscription is notified when specified state change happens. setState method can be used for state change forcefully.
Parameters
Name | Required | Type | Description |
---|---|---|---|
state | Required | String | State for which to register. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
clientId | Required | String | Identity of the client. |
subscribed | Optional | Boolean | Always returns true. |
state | Required | String | Current state of the device. |
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
state | Required | String | Registered state. |
nextState | Required | String | Processing possible next state. |
token | Required | String | Session token. |
Example
Example: Register for transitions of the ACTIVE state
# luna-send -n i luna://com.webos.service.power2/registerStateTransition '{
"state":"ActiveState"
}'
Response:
{
"clientId":"com.webos.lunasend-954",
"subscribed":true,
"state":"ActiveState",
"returnValue":true
}
Subscription:
{
"state":"ActiveState",
"nextState":"PowerOffState",
"token":"6UixZdy.4"
}
respondStateTransitionAck
Description
For clients that have registered for state change notifications, some state transitions require acceptance (acknowledgement) of all clients who register for this state :
- If all subscribers approve (ACK), the state change occurs.
- If even one subscriber rejects (NACK), the state does not change.
- Clients who have not subscribed to that state are not required to vote.
- No user input is considered as acceptance of the state change.
Parameters
Name | Required | Type | Description |
---|---|---|---|
state | Required | String | Registered state. |
ack | Required | Boolean | Client vote. Possible values are:
|
token | Required | String | Session token generated in response to the registerStateTransition() method. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Accept the state transition
# luna-send -n 1 luna://com.webos.service.power2/respondStateTransitionAck '{
"ack":true,
"state":"ActiveState",
"token":"6UixZdy.4"
}'
Response:
{
"returnValue": true
}
setPowerOnReason
Description
Specify the reason that caused the device to be powered on.
Parameters
Name | Required | Type | Description |
---|---|---|---|
reason | Required | String | The event that caused the device to be powered. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Set the reason to power-on the device
# luna-send -n 1 luna://com.webos.service.power2/setPowerOnReason '{
"reason":"remoteKey"
}'
Response:
{
"returnValue": true
}
getPowerOnReason
Description
Gets the last reason set for powering-on the device.
Parameters
Name | Required | Type | Description |
---|---|---|---|
subscribe | Required | Boolean | Subscribe for notifications on any changes.
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
subscribed | Required | Boolean | Indicates whether subscribed to get notifications. |
reason | Required | String | Indicates the power on reason. |
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Subscription Returns
Name | Required | Type | Description |
---|---|---|---|
reason | Required | String | Power-on reason. |
Example
Example: Subscribe for new device power-on reasons
# luna-send -n 1 luna://com.webos.service.power2/getPowerOnReason '{
"subscribe":true
}'
Response:
{
"reason": "remoteKey",
"subscribed": true,
"returnValue": true
}
acquireWakeLock
Description
Allows the device to remain powered on for a specific time period, after which the lock is released.
Note: No other state change operation can be executed during this time period.
Parameters
Name | Required | Type | Description |
---|---|---|---|
clientId | Required | String | Identity of the client. |
timeout | Required | Number | The duration (in seconds) to hold the lock. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Acquire lock for 60 seconds
# luna-send -n 1 luna://com.webos.service.power2/acquireWakeLock '{
"clientId":"com.webos.lunasend-5726",
"timeout":60
}'
Response:
{
"returnValue": true
}
releaseWakeLock
Description
Instantly releases the wake lock for the client.
Parameters
Name | Required | Type | Description |
---|---|---|---|
clientId | Required | String | Identity of the client who has acquired the lock. |
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Release the wake lock
# luna-send -n 1 luna://com.webos.service.power2/releaseWakeLock '{
"clientId" : "com.webos.lunasend-1110"
}'
Response:
{
"returnValue": true
}
reboot
Description
Reboots the device with in timeout after acknowledged from registered client. LunaInterfacePMSRoot:TimeOut is configured in /var/PMS/pms.conf file as 15mins by default. Timeout is in HH:MM:SS format
Note: Client will be prompted for acknowledgement if registered for state change notifications.
Parameters
Name | Required | Type | Description |
---|---|---|---|
reason | Required | String | The event that caused the device to be reboot. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Reboot the device after OTA update
# luna-send -n 1 luna://com.webos.service.power2/reboot '{
"reason" : "ota"
}'
Response:
{
"returnValue": true
}
shutdown
Description
Shuts down the device.
Note: Client will be prompted for acknowledgement if registered for state change notifications.
This shutdown API will work differently for ose. If it is in ActiveState, it may go garage state base if it met preconditions i.e wifi on and SSID. (garageSSID can be configured in /var/PMS/pms.conf). Shuts down the device with in timeout after acknowledged from connection manager service(Precondition not met). LunaInterfacePMSRoot:TimeOut is configured in /var/PMS/pms.conf file as 15mins by default. Timeout is in HH:MM:SS format
Parameters
Name | Required | Type | Description |
---|---|---|---|
reason | Required | String | The event that causes the device to be shutdown. Possible values are:
|
Call Returns
Name | Required | Type | Description |
---|---|---|---|
returnValue | Required | Boolean | Indicates the status of operation. Possible values are:
|
errorCode | Optional | Number | The error code for the failed operation. |
errorText | Optional | String | Indicates the reason for the failure of the operation. See the API Error Codes Reference for more details. |
Example
Example: Shutdown the device using the remote control
# luna-send -n 1 luna://com.webos.service.power2/shutdown '{
"reason" : "remoteKey"
}'
Response:
{
"returnValue": true
}
API Error Codes Reference
Error Code | Error Text | Error Description |
---|---|---|
1 | errorPower2Busy | com.webos.service.power2 is busy |
2 | errorInvalidJsonFormat | Invalid JSON format |
3 | errorClientNotRegistered | The client is not registered |
4 | errorCleintAlreadyRegistered | The client is already registered |
5 | errorResponseTooLate | The response is too late |
6 | errorTimerNotRunning | The timer is not running |
7 | errorUnknown | Unknown error |