Skip to content

LISA API

Version: 1.0.0

Status: ⚫⚪⚪

LISA interface for Thunder framework.

(Defined by LISA.json)

Table of Contents

Introduction

Scope

This document describes purpose and functionality of the LISA interface (version 1.0.0). It includes detailed specification about its methods provided and notifications sent.

Case Sensitivity

All identifiers of the interfaces described in this document are case-sensitive. Thus, unless stated otherwise, all keywords, entities, properties, relations and actions should be treated as such.

Acronyms, Abbreviations and Terms

The table below provides and overview of acronyms used in this document and their definitions.

Acronym Description
API Application Programming Interface
HTTP Hypertext Transfer Protocol
JSON JavaScript Object Notation; a data interchange format
JSON-RPC A remote procedure call protocol encoded in JSON

The table below provides and overview of terms and abbreviations used in this document and their definitions.

Term Description
callsign The name given to an instance of a plugin. One plugin can be instantiated multiple times, but each instance the instance name, callsign, must be unique.

References

Ref ID Description
HTTP HTTP specification
JSON-RPC JSON-RPC 2.0 specification
JSON JSON specification
Thunder Thunder API Reference

Description

LISA JSON-RPC interface.

Methods

The following methods are provided by the LISA interface:

LISA interface methods:

Method Description
install Download the application bundle
uninstall Uninstall the application
download Download arbitrary application resource file
reset Delete persistent data stored locally
getStorageDetails Information on the storage usage
getList Gets the list of installed applications
setAuxMetadata Set an arbitrary metadata
clearAuxMetadata Clears a single metadata, removing its key
getMetadata Get application metadata
cancel Cancel asynchronous request
getProgress Estimated progress of a request
lock Lock an application
unlock Unlock an application
getLockInfo Get lock info

install method

Download the application bundle.

Also see: operationStatus

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.url string mandatory Application url
params.appName string mandatory Application name
params.category string mandatory Application category

Result

Name Type M/O Description
result string mandatory Operation handle

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress or other operation pending
ERROR_BAD_REQUEST Invalid params
ERROR_ILLEGAL_STATE App already installed

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.install",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "url": "http://download.com/bundle1.tgz",
    "appName": "Player",
    "category": "Web browser"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "..."
}

uninstall method

Uninstall the application.

Also see: operationStatus

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.uninstallType string mandatory Type of the uninstall to perform

Result

Name Type M/O Description
result string mandatory Operation handle

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress or other operation pending
ERROR_BAD_REQUEST Invalid params

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.uninstall",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "uninstallType": "full"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "..."
}

download method

Download arbitrary application resource file.

Also see: operationStatus

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.resKey string mandatory Key to access given resource file from db entry
params.resUrl string mandatory Url where to download a resource from

Result

Name Type M/O Description
result string mandatory Operation handle

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress or other operation pending
ERROR_BAD_REQUEST Invalid params

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.download",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "resKey": "...",
    "resUrl": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "..."
}

reset method

Delete persistent data stored locally.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.resetType string mandatory Type of the reset to perform

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid params
ERROR_GENERAL Filesystem Error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.reset",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "resetType": "full"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

getStorageDetails method

Information on the storage usage.

Parameters

Name Type M/O Description
params object mandatory ...
params?.type string optional Application type (mime-type)
params?.id string optional Application ID
params?.version string optional Application version

Result

Name Type M/O Description
result object mandatory Storage payload - returned as GetStorageDetails method result
result.apps object mandatory Storage entry - used in results
result.apps.path string mandatory Path in local filesystem
result.apps?.quotaKB string optional Number of used kilobytes of storage
result.apps.usedKB string mandatory Number of used kilobytes of storage
result.persistent object mandatory Storage entry - used in results
result.persistent.path string mandatory Path in local filesystem
result.persistent?.quotaKB string optional Number of used kilobytes of storage
result.persistent.usedKB string mandatory Number of used kilobytes of storage

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid params
ERROR_GENERAL Filesystem Error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getStorageDetails",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "apps": {
      "path": "...",
      "quotaKB": "...",
      "usedKB": "..."
    },
    "persistent": {
      "path": "...",
      "quotaKB": "...",
      "usedKB": "..."
    }
  }
}

getList method

Gets the list of installed applications.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params?.appName string optional Application name
params?.category string optional Application category

Result

Name Type M/O Description
result object mandatory Applications payload - returned as GetList method result
result.apps array mandatory List of apps
result.apps[#] object mandatory Application entry - used in results
result.apps[#].id string mandatory Application ID
result.apps[#].type string mandatory Application type (mime-type)
result.apps[#].installed array mandatory List of installedApp
result.apps[#].installed[#] object mandatory Installed application variant
result.apps[#].installed[#].version string mandatory Application version
result.apps[#].installed[#].appName string mandatory Application name
result.apps[#].installed[#]?.category string optional Application category
result.apps[#].installed[#].url string mandatory Application url

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid params

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getList",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "appName": "Player",
    "category": "Web browser"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "apps": [
      {
        "id": "com.lgi.app",
        "type": "application/vnd.rdk-app.dac.native",
        "installed": [
          {
            "version": "1.0",
            "appName": "Player",
            "category": "Web browser",
            "url": "http://download.com/bundle1.tgz"
          }
        ]
      }
    ]
  }
}

setAuxMetadata method

Set an arbitrary metadata.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.key string mandatory Metadata key
params.value string mandatory Metadata value

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid params
ERROR_GENERAL Metadata Error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.setAuxMetadata",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "key": "...",
    "value": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

clearAuxMetadata method

Clears a single metadata, removing its key.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.key string mandatory Metadata key

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid params
ERROR_GENERAL Metadata Error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.clearAuxMetadata",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "key": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

getMetadata method

Get application metadata.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version

Result

Name Type M/O Description
result object mandatory Metadata payload - returned as GetMetadata method result
result?.appName string optional Application name
result?.category string optional Application category
result?.url string optional Application url
result.resources array mandatory List of key-value entries
result.resources[#] object mandatory Struct holding key and value
result.resources[#].key string mandatory Key property
result.resources[#].value string mandatory Value property
result.auxMetadata array mandatory List of key-value entries
result.auxMetadata[#] object mandatory Struct holding key and value
result.auxMetadata[#].key string mandatory Key property
result.auxMetadata[#].value string mandatory Value property

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid params

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getMetadata",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "appName": "Player",
    "category": "Web browser",
    "url": "http://download.com/bundle1.tgz",
    "resources": [
      {
        "key": "...",
        "value": "..."
      }
    ],
    "auxMetadata": [
      {
        "key": "...",
        "value": "..."
      }
    ]
  }
}

cancel method

Cancel asynchronous request.

Parameters

Name Type M/O Description
params object mandatory ...
params.handle string mandatory Operation handle

Result

Name Type M/O Description
result string mandatory Operation status

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid handle
ERROR_GENERAL Error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.cancel",
  "params": {
    "handle": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": "Success"
}

getProgress method

Estimated progress of a request.

Parameters

Name Type M/O Description
params object mandatory ...
params.handle string mandatory Operation handle

Result

Name Type M/O Description
result integer mandatory Operation progress

Errors

Message Description
ERROR_INPROGRESS LISA initialization in progress
ERROR_BAD_REQUEST Invalid handle
ERROR_GENERAL Error

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getProgress",
  "params": {
    "handle": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": 0
}

lock method

Lock an application.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params?.reason string optional Reason for lock
params?.owner string optional Owner of lock

Result

Name Type M/O Description
result object mandatory Struct holding handle
result.handle string mandatory Operation handle

Errors

Message Description
ERROR_TOO_MANY_REQUESTS LISA initialization in progress or other operation pending
ERROR_WRONG_PARAMS Invalid params or app not unstalled
ERROR_APP_UNINSTALLING App is currently being uninstalled
ERROR_APP_LOCKED App is already locked

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.lock",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "reason": "active",
    "owner": "awc"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "handle": "..."
  }
}

unlock method

Unlock an application.

Parameters

Name Type M/O Description
params object mandatory ...
params.handle string mandatory Operation handle

Result

Name Type M/O Description
result null mandatory Always null (default: None)

Errors

Message Description
ERROR_WRONG_HANDLE Wrong handle or app not locked anymore

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.unlock",
  "params": {
    "handle": "..."
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": null
}

getLockInfo method

Get lock info.

Parameters

Name Type M/O Description
params object mandatory ...
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version

Result

Name Type M/O Description
result object mandatory Struct holding lock info
result?.reason string optional Reason for lock
result?.owner string optional Owner of lock

Errors

Message Description
ERROR_WRONG_PARAMS Invalid params or app not unstalled
ERROR_WRONG_HANDLE Wrong handle or app not locked anymore

Example

Request

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.getLockInfo",
  "params": {
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "reason": "active",
    "owner": "awc"
  }
}

Notifications

Notifications are autonomous events triggered by the internals of the implementation and broadcasted via JSON-RPC to all registered observers. Refer to [Thunder] for information on how to register for a notification.

The following events are provided by the LISA interface:

LISA interface events:

Notification Description
operationStatus Notifies about currently pending operation status

operationStatus notification

Notifies about currently pending operation status.

Description

Register to this event to be notified about current state of the pending operation

Notification Parameters

Name Type M/O Description
params object mandatory ...
params.handle string mandatory Operation handle
params.operation string mandatory Operation
params.type string mandatory Application type (mime-type)
params.id string mandatory Application ID
params.version string mandatory Application version
params.status string mandatory Operation status
params?.details string optional If error occurred this property contains details on what happened

Example

Registration

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "<callsign>.1.register",
  "params": {
    "event": "operationStatus",
    "id": "myid"
  }
}

Notification

{
  "jsonrpc": "2.0",
  "method": "myid.operationStatus",
  "params": {
    "handle": "...",
    "operation": "Installing",
    "type": "application/vnd.rdk-app.dac.native",
    "id": "com.lgi.app",
    "version": "1.0",
    "status": "Success",
    "details": "..."
  }
}

The client ID parameter is passed within the notification designator, i.e. <client-id>.operationStatus.