Menu

Reference

com.webos.service.swupdater

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.

com.webos.service.swupdater state diagram

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

Methods

getStatus

ACG: softwareupdate.operation

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

subscribeRequiredBoolean

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

  • true - Subscribe for changes.
  • false - Not subscribed.

Call Returns

Name

Required

Type

Description

subscribedRequiredBoolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes.
  • false - Not subscribed.
statusRequiredString

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.

softwareModulesOptionalObject array: softwareModule

List of software modules present in the update.

idOptionalString

The deployment action ID

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Subscription Returns

Name

Required

Type

Description

subscribedRequiredBoolean

Indicates if subscribed to get notifications. Possible values are:

  • true - Subscribed for changes.
  • false - Not subscribed.
statusRequiredString

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.

softwareModulesOptionalObject array: softwareModule

List of software modules present in the update.

idOptionalString

The deployment action ID

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

# 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

ACG: softwareupdate.operation

Description

Starts downloading the artifacts in the software modules.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

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

 

Response:

{
    "returnValue": true
}

cancelDownload

ACG: softwareupdate.operation

Description

Cancels the download which is currently in progress. 

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

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

 

Response:

{
    "returnValue": true
}

pauseDownload

ACG: softwareupdate.operation

Description

Pauses the download which is currently in progress. 

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

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

 

Response:

{
    "returnValue": true
}

resumeDownload

ACG: softwareupdate.operation

Description

Resumes the download that is paused. 

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

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

 

Response:

{
    "returnValue": true
}

startInstall

ACG: softwareupdate.operation

Description

Installs the downloaded software modules.

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

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

 

Response:

{
    "returnValue": true
}

cancelInstall

ACG: softwareupdate.operation

Description

Cancels the installation which is in progress. 

Parameters

None

Call Returns

Name

Required

Type

Description

returnValueRequiredBoolean

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.
errorCodeOptionalNumber

The error code for the failed operation.

errorTextOptionalString

Indicates the reason for the failure of the operation.

Example

Example code

# 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

typeRequiredString

Type of software module. Possible values are:

  • os
  • application
nameRequiredString

Name of software module.

versionOptionalString

Version of software module.

artifactsRequiredObject 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

sizeRequiredNumber (int32_t)

Downloaded size.

totalRequiredNumber (int32_t)

File size.

filenameRequiredString

File name.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 and sample code is licensed under the Apache License 2.0.

Contents