com.webos.service.swupdater

Note
com.webos.service.swupdater is available since webOS OSE 2.2.0.

API Summary

The webOS software updater service uses Firmware Over-the-Air (FOTA) updates by communicating with hawkbit. hawkBit is an open source back-end software update solution.

The webOS FOTA service acts as the hawkBit client.

Overview of the API

Before using this service, you need to setup the hawkBit server. For instructions, see hawkBit.

Additionally, few configurations specific to webOS are listed below.

Set hawkBit server information
- The hawkBit server to which swupdater connects can be configured at build time. Here, HAWKBIT_TOKEN means the gateway security token.
  1. $ cd meta-lg-webos/meta-webos/recipes-webos/com.webos.service.swupdater/com.webos.service.swupdater.bb
  2. $ vi com.webos.service.swupdater.bb
  3. EXTRA_OECMAKE = " \
    -DHAWKBIT_ADDRESS=http://<hawkBit server IP address>:<port number> \
    -DHAWKBIT_TOKEN=377b83e10b9f894883e98351875151cb \"
Generate OS upgrade file
1. Check the hash value of libostree commits.
  $ ostree log --repo={OSTREE_REPO} webos-image-master
  (e.g.)
  commit 0d107dfaeadd49b38b11d277b84cf7dea44d00cb4d80522d323f4dedbd26fbd2
  ContentChecksum: 405bddcc7ad6499c6b68582c014e2b305bd5e966e26fea1cead7e042703885ee
  Date: 2019-09-02 14:39:47 +0000
  webos-image-master-20190902143110
  commit 76e074ffdba5ee211679e011be71ccc23bd81139bdc6f72cad2791d2458100d4
  ContentChecksum: dfc7690cda5e59565f5c00099ae3b423571eb0bd1e5408ce408e1702d3137bed
  Date: 2019-09-02 13:19:12 +0000
  webos-image-master-20190902131250
2. Generate static-delta between two commits.
  $ ostree static-delta generate \
  --from=76e074ffdba5ee211679e011be71ccc23bd81139bdc6f72cad2791d2458100d4 \
  --to=0d107dfaeadd49b38b11d277b84cf7dea44d00cb4d80522d323f4dedbd26fbd2 \
  --inline \
  --min-fallback-size=0 \
  --filename=ostree-76e074ff-0d107dfa.delta
  Note: Use the filename format : ostree-{FROM}-{TO}.delta

State Diagram

The figure below shows the state transition diagram of the software updater service. It also shows the APIs that can be called in each state.

Note: All state changes can be subscribed via the getStatus method.

Methods

getStatus

Description

Notifies when there is a change in the state of the software updater service. It adds the caller to the subscriber list.

Parameters

Name	Required	Type	Description
subscribe	Required	Boolean	Subscribe to get notified when the state changes. Possible values are: true - Subscribe for changes. false - Not subscribed.

Name

Required

Type

Description

Required

Boolean

Subscribe to get notified when the state changes. Possible values are:

true - Subscribe for changes.
false - Not subscribed.

Call Returns

Name	Required	Type	Description
subscribed	Required	Boolean	Indicates if subscribed to get notifications. Possible values are: true - Subscribed for changes. false - Not subscribed.
status	Required	String	State of the software updater service. Possible values are: idle - Service is in an idle state downloadReady - Download available downloadStarted - Download started downloadPaused - Download paused installReady - Ready for installation installStarted - Installation started installCompleted - Installation completed failed - Either download or installation failed Note: When the state reaches installCompleted or failed state, it will go to idle state automatically.
softwareModules	Optional	Object array: softwareModule	List of software modules present in the update.
id	Optional	String	The deployment action ID
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Subscription Returns

Name	Required	Type	Description
subscribed	Required	Boolean	Indicates if subscribed to get notifications. Possible values are: true - Subscribed for changes. false - Not subscribed.
status	Required	String	State of the update service. Possible values are: idle - Service is in an idle state downloadReady - Download available downloadStarted - Download started downloadPaused - Download paused installReady - Ready for installation installStarted - Installation started installCompleted - Installation completed failed - Either download or installation failed Note: When the state reaches installCompleted or failed state, it will go to idle state automatically.
softwareModules	Optional	Object array: softwareModule	List of software modules present in the update.
id	Optional	String	The deployment action ID
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Example

# luna-send -i -f luna://com.webos.service.swupdater/getStatus '{"subscribe": true}'

Response:

{
"id": null,
"subscribed": true,
"status": "idle",
"returnValue": true
}
{
"id": "249",
"subscribed": true,
"status": "downloadReady",
"returnValue": true,
"softwareModules": [
{
"type": "os",
"name": "webos-master-official-raspberrypi4",
"version": "1823",
"artifacts": [
{
"size": 0,
"total": 8481392,
"filename": "ostree-ca2b4f1f-704b56bf.delta"
}
]
}
]
}
{
"id": "249",
"subscribed": true,
"status": "installStarted",
"returnValue": true,
"softwareModules": [
{
"type": "os",
"name": "webos-master-official-raspberrypi4",
"version": "1823",
"artifacts": [
{
"size": 0,
"total": 8481392,
"filename": "ostree-ca2b4f1f-704b56bf.delta"
}
]
}
]
}

startDownload

Description

Starts downloading the artifacts in the software modules.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.swupdater/startDownload '{ }'

Response:

{
"returnValue": true
}

cancelDownload

Description

Cancels the download which is currently in progress.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.swupdater/cancelDownload '{ }'

Response:

{
"returnValue": true
}

pauseDownload

Description

Pauses the download which is currently in progress.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.swupdater/pauseDownload '{ }'

Response:

{
"returnValue": true
}

resumeDownload

Description

Resumes the download that is paused.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.swupdater/resumeDownload '{ }'

Response:

{
"returnValue": true
}

startInstall

Description

Installs the downloaded software modules.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.swupdater/startInstall '{ }'

Response:

{
"returnValue": true
}

cancelInstall

Description

Cancels the installation which is in progress.

Parameters

None

Call Returns

Name	Required	Type	Description
returnValue	Required	Boolean	Indicates the status of operation. Possible values are: true - Indicates that the operation was successful. false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.
errorCode	Optional	Number	The error code for the failed operation.
errorText	Optional	String	Indicates the reason for the failure of the operation.

Name

Required

Type

Description

returnValue

Required

Boolean

Indicates the status of operation. Possible values are:

true - Indicates that the operation was successful.
false - Indicates that the operation failed. Check the "errorCode" and "errorText" fields for details.

errorCode

Optional

Number

The error code for the failed operation.

errorText

Optional

String

Indicates the reason for the failure of the operation.

Example

# luna-send -n 1 -f luna://com.webos.service.swupdater/cancelInstall '{ }'

Response:

{
"returnValue": true
}

Objects

softwareModule

Contains the type, name, version, and artifacts of the software module.

Name	Required	Type	Description
type	Required	String	Type of software module. Possible values are: os application
name	Required	String	Name of software module.
version	Optional	String	Version of software module.
artifacts	Required	Object array: artifact	List of artifacts contained in the software module.

artifact

Contains filename and size of artifacts of the software module.

Name	Required	Type	Description
size	Required	Number (int32_t)	Downloaded size.
total	Required	Number (int32_t)	File size.
filename	Required	String	File name.