CLI Developer Guide

Creating web app

The first step to creating a web app is copying essential files from a template. The webOS TV CLI provides web app templates as below:

  • Basic web app template: A template of a general web app that displays the "Hello World" message on a screen

  • Hosted web app template: A template of a hosted web app

The webOS TV CLI also provides the JS service and config file (appinfo.json) templates. JS service template is a general service template that is running as a background service on webOS TV. Config file template provides the necessary file for the webOS TV app that specifies metadata of the web app, such as an app ID, app name, and related resources.

Use the ares-generate command to create a web app or a JS service. You can also create a web app, JS Service, an appinfo.json file, and icon images from the templates with the ares-generate command.

Listing templates

The webOS TV CLI provides several templates. Execute the following command to check the available templates for your web app.

ares-generate --list

basic          Web App          -  (default) basic web app for webOS TV
hosted_webapp  Web App          -  hosted web app for webOS TV
webappinfo     Web App Info     -  appinfo.json for web app
js_service     JS Service       -  js service for webOS TV
jsserviceinfo  JS Service Info  -  services.json, package.json for JS service
packageinfo    Package Info     -  packageinfo.json for webOS package

Using a template

The following sections describe how to get each type of web app template.

Creating a web app

The basic web template provides a "Hello World" app with the minimum essential files for webOS TV. This template is useful when using other UI frameworks.

Execute the following command to create a web app to the ./sampleApp directory.

ares-generate -t basic sampleApp

The following table describes the files of a web app that templates provide:

Directory / File Description
webOSTVjs-x.x.x The webOS TV library directory. The webOS TV-specific library to call LS API. See webOSTV.js for the detailed description of the webOS TV library.
appinfo.json The web app configuration file. The appinfo.json file includes metadata of the web app. This file must exist when packaging the web app. See appinfo.json for the detailed description of the appinfo.json file.
 icon.png The icon image file. See App Resources for the detailed description of the icon.png file.
largeicon.png The large icon image file. See App Resources for the detailed description of the largeicon.png file.
index.html The web app's main page. This page only shows "Hello World" text on a screen.

Creating a hosted web app

The hosted web app template provides a hosted web app that contains a redirect URL with the minimum essential files for webOS TV.

Execute the following command to create a hosted web app to the ./hostedSampleApp directory.

ares-generate -t hosted_webapp hostedSampleApp

The following table describes the files of a hosted web app that the template provides:

Directory / File Description
appinfo.json The web app configuration file. The appinfo.json file includes metadata of the web app. This file must exist when packaging a web app. See appinfo.json for the detailed description of the appinfo.json file.
 icon.png The icon image file. See App Resources for the detailed description of the icon.png file.
largeicon.png The large icon image file. See App Resources for the detailed description of the largeicon.png file.
index.html The web app's main page that contains the redirect URL.

Creating a JS service

The JS service template provides a sample JS service running as a background service on webOS TV. The sample JS service responds to simple messages for a service request.

Execute the following command to create a JS service from the template (js_service).

ares-generate -t js_service sampleService

The following table is a basic description of the files of the sample JS service:

File Description
helloworld_service.js The sample JS service code that provides several simple commands. These commands are specified in the services.json file to use them.
package.json The configuration file of NPM. For more information, see https://docs.npmjs.com/getting-started/using-a-package.json
services.json The configuration file defines what commands the service provides on the webOS bus. For more information, See services.json.

Creating an appinfo.json file from template

The webappinfo template provides an appinfo.json file with sample values. If you are building a new web app without templates or using the existing web app which was not made from templates, you should add the appinfo.json file into your app. This file holds the app's name, ID, app type, icon image, and the main page information to the file.

Execute the following command to create the appinfo.json file template (webappinfo).

ares-generate -t webappinfo webApp

The webOS TV CLI provides the appinfo.json file template as below.

{
  "id": "com.domain.app",
  "version": "0.0.1",
  "vendor": "My Company",
  "type": "web",
  "main": "index.html",
  "title": "new app",
  "icon": "icon.png",
  "largeIcon": "largeIcon.png"
}

Deploying web app

This article describes how to package, install, and execute a web app on the emulator or webOS TV for deploying purposes. The commands, ares-package, ares-install, ares-setup-device, and ares-launch are used to deploy web applications. See webOS TV CLI Introduction for the detailed description.

Packaging a web app for deploying

The first step is creating a package file (.ipk) for your app. Use the ares-package command to create a package file.

Before executing the packaging command, you need to check the required files. An appinfo.json file must exist when packaging the app. The ares-package command finds and reads the appinfo.json file from the app directory. The appinfo.json file has required fields such as main and icon. For this reason, the icon image file and main page file also must exist in the correct path.

Packaging web app

Specify a directory of your app to be packaged when executing the ares-package command. Execute the following command to start packaging your app in the sampleApp directory.

ares-package ./sampleApp

Creating package com.yourdomain.app_0.0.1_all.ipk in ./

Packaging web app with JavaScript service

Specify a directory of your app first, and then specify your services using the ares-package command. Execute the following command to package your app of the sampleApp directory and your service of sampleService.

ares-package ./sampleApp ./sampleService

Creating package com.yourdomain.app_0.0.1_all.ipk ./
note

To package your app and service into one ipk file, specify your service name that begins with the app ID. For example:

  • App ID: "com.yourdomain.app"
  • Service ID: "com.yourdomain.app.myService"

Now you can see that the package file exists in the directory from which you execute the command.

Installing a web app on target device

You need to install the created package file on a target device. Use the ares-install command to see the list of target devices before installing your app. You can also modify the setting for the device using the ares-setup-device command.

note

From webOS TV 3.0, you can test your app on the actual device using the Developer Mode app. For more information, see Developer Mode App.

Listing target devices

Use the ares-setup-device command to check the name of the device, platform type, description, and SSH access address of the target device. Execute the following command to view the list of target devices.

ares-setup-device --list

name        deviceinfo               connection    profile
---------   --------------------     ------------  --------
emulator    developer@127.0.0.1:6622 ssh           tv
tv          prisoner@10.123.45.67    ssh           tv

The emulator is included in the default device list. Also, the ares-setup-device command shows device lists in detail with -F, --listfull options. See the following command.

ares-setup-device --listfull

[
  {
    "profile": "tv",
    "name": "tv",
    "deviceinfo": {
        "ip": "10.123.45.67",
        "port": "9922",
        "user": "prisoner"
    },
    "connection": [
        "ssh"
    ],
    "details": {
        "platform": "starfish",
        "privatekey": "tv_webos",
        "passphrase": "ares-setup-device --full",
        "description": "new device"
    }
  },
  {
    "profile": "tv",
    "name": "quot;emulator",
    "deviceinfo": {
        "ip": "127.0.0.1",
        "port": "6622",
        "user": "developer"
    },
    "connection": [
    "ssh"
    ],
    "details": {
        "platform": "starfish",
        "privatekey": "webos_emul",
        "description": "LG webOS TV Emulator"
    }
  }
]

Setting target device

The default loopback address needs to be changed to the remote host address if using the emulator on the remote computer for testing your app. The following example describes how to set the host address of the emulator to the target device:

ares-setup-device --modify emulator --info "host=10.177.231.137"

Re-check the device list to confirm if the host address of the target device has been modified.

ares-setup-device --list

name     deviceinfo                    connection  profile
-------- ----------------------------- ----------  -------
tv       prisoner@10.123.45.67         ssh         tv
emulator developer@10.177.231.137:6622 ssh         tv

There is another way to change the target device's information with the interactive mode of the ares-setup-device command. The following command shows how to change a target's host address in interactive mode. Run the ares-setup-device command without any option. The ares-setup-device command shows a target device list and starts interactive mode as below.

ares-setup-device

name     deviceinfo               connection  profile
-------- ------------------------ ----------  --------
tv       prisoner@10.123.45.67    ssh         tv
emulator developer@127.0.0.1:6622 ssh         tv

** You can modify the device info in the above list, or add new device.
? Select
> add
  modify
  remove

If you do not want to change the previous value, press the enter key without any value. For more detailed information about the ares-setup-device command usage, see webOS TV CLI Introduction.

Installing a web app

Make sure that your target device is running. Execute the following command to install the package file on the target. Input the name of the target and package file as parameters.

ares-install --device emulator ./com.yourdomain.app_0.0.1_all.ipk

Installing package com.yourdomain.app_0.0.1_all.ipk
Success

After installing your app, you should verify the app installation completed. Execute the following command to check the ID list of apps installed on the target. Make sure that your app ID exists in the result.

ares-install --device emulator --list

...
com.yourdomain.sampleapp

Removing a web app

Use the --remove option of the ares-install command to remove your app. Enter the ID of the installed application using parameters. Execute the following command to remove your app installed on the target, as shown in the following example.

ares-install --device emulator --remove com.yourdomain.app

Removed application com.yourdomain.app

Launching a web app on target device

Use the ares-launch command to launch or close your web app installed on the target device. This section describes how to launch or close your web app.

Launching web app

Select the target device name and the app ID from the device and the app list, used during the installation phase, and enter them as parameters before executing the command as shown below:

ares-launch --device emulator com.yourdomain.app

Launched application com.yourdomain.app

After executing the above command, you need to check whether the sample app started on the target device or not.

Closing web app

Enter the names of the target device and app using parameters to close the currently running app, just as in launching the app.

ares-launch --device emulator --close com.yourdomain.app

Closed application com.yourdomain.app

Debugging web app

The webOS TV SDK provides Web Inspector and Node Inspector for debugging web apps and JS services.

Debugging web app

You can monitor the execution information of web apps or JS services running on the target device with Web Inspector and Node Inspector. For this, you need to create a package file (.ipk) without minifying. This section describes how to create a package file and execute Web Inspector and Node Inspector for debugging.

Packaging a web app for debugging

The ares-package command reduces and merges the source code when creating the package file (.ipk). The ares-package command adjusts and shrinks variable names and line spacing. However, these minifying jobs make debugging difficult.

For this reason, you should not carelessly reduce and merge the source code to debug apps and JS services. It becomes difficult to check the information if the source code is reduced or the files are merged. Do not run the minifying task, using the --no-minify option for debugging as below.

ares-package --no-minify sampleApp

Creating package com.yourdomain.app_0.0.1_all.ipk in ./
note

Since the size of the package files for debugging is larger than that of the basic setup files, use the non-minified package files for debugging purposes only.

Launching Web Inspector

The ares-inspect command provides Web Inspector for debugging apps. The running information of the app is displayed through Web Inspector.

Execute the following command while the app is running:

ares-inspect --device emulator --app com.yourdomain.app --open

If you use the --open option, Web Inspector opens on the default browser of your PC. Note that Web Inspector and Node Inspector work on Chromium-based browsers properly.

To use the Inspector, you need to have Chromium installed, of which the version is compatible with the webOS TV version. The following table shows the compatible Chromium version by webOS TV version and their download links.

webOS TV version Release year of webOS TV Supported Chrome versions for using Inspector
webOS TV 22 2022
  • Latest-version Chrome
webOS TV 6.0 2021
webOS TV 5.0 2020
webOS TV 4.x 2018-2019
webOS TV 3.x 2016-2017
webOS TV 2.0 2015
webOS TV 1.0 2014

You can see Web Inspector as below.

Screenshot of Web Inspector

note

Web Inspector is based on Google Chrome Developer Tools. Refer to the Google Developers for the detailed description of how to use Google Chrome Developer Tools. Some versions of Google Chrome may not support Web Inspector. For more information, refer to FAQ.

Launching Node Inspector

The ares-inspect command provides Node Inspector for debugging JS services. The running information of JS service is displayed through Node Inspector.

Execute the following command while the JS service is working:

ares-inspect --device emulator --service com.yourdomain.app.service --open

You can see Node Inspector as below:

Screenshot of Node Inspector

note

For more information about Node Inspector, refer to the GitHub of Node Inspector.

Testing web app

It supports testing without creating and installing a package file (.ipk) for development convenience.

Testing without app installation

You can test code changes to your web app without packaging, installing, and running the app on a TV device.

The ares-launch --hosted(-H) command allows you to test the code changes easily on the TV. If the --hosted option is used with the directory path, an app with id com.sdk.ares.hostedapp is launched on the device and it opens the files in the directory. From CLI v1.12.0, the auto-reloading function is added, so as soon as you make and save modification to your app files, the app on the TV device is automatically reloaded.

How to ignore specific files from auto-reloading

To exclude certain files with specific extensions or under specific directories from auto-reloading, create a .reloadignore file. This .reloadignore file should be located in the root directory of the app to test, and the file itself will be excluded from packaging of the app.

Add the absolute or relative path of the files or directories to exclude from auto-reloading into the .reloadignore file. Each item will be distinguished by a line feed, and the relative path of items (except for cases starting with **) will converted into an absolute path based on the root directory of the app before being applied.

Even if you modify the .reloadignore file while auto-reloading is on, the modification will apply immediately without needing to terminate and re-run the command.

Example

The following is an example of testing a sample app after creating it using CLI, while skipping the steps for packaging and installation.

# Generate the sample app for test
$ ares-generate APP_DIR
? app id com.domain.app
? title new app
? version 0.0.1
Generating basic in D:webOS_TV_SDKCLIbinAPP_DIR
Success
# Test the sample app on the TARGET_DEVICE without packaging and installation
$ ares-launch -H APP_DIR -d TARGET_DEVICE
Installing package
D:webOS_TV_SDKCLIlibcom.sdk.ares.hostedapp.ipk
Ares Hosted App is now running...
  • APP_DIR is the app's working directory.
  • To terminate, enter Ctrl + C.

The following is an example of a .reloadignore file.

appinfo.json
tests
**/tmp
**/*.png
  • appinfo.json - The appinfo.json file in the root directory of APP_DIR will be ignored.
  • tests - Directories and files under the tests directory in the root directory of APP_DIR will be ignored.
  • **/tmp - Any tmp directories and files under APP_DIR will be ignored.
  • */.png - Any files with the .png extension under APP_DIR will be ignored.

With this option, however, you cannot test apps that include JS services.

About debugging a web app on VS Code Extension, see Debugging Web App on VS Code Extension.

Testing on the Simulator

The ares-launch command with the --simulator option runs webOS TV Simulator of the specified version and tests the specified app directory.

With the command, the location of the simulator is identified based on the environment variable, LG_WEBOS_TV_SDK_HOME, and the execution file of webOS TV Simulator, of the specified version by the --simulator option, is run.

For how to install and use Simulator, see Simulator Installation and Simulator Developer Guide.

The following is an example of running webOS TV 22 Simulator and testing APP_DIR using CLI.

$ ares-launch --simulator 22 APP_DIR

Finding simulator in /home/user/webOS_TV_SDK/Simulator
Launched webOS_TV_22_Simulator_1.0.0.appimage

Testing on a local server

The ares-server command runs a web server for testing a local file. The web server will run on the given path.

Execute the command to start a web server on your app source directory. You can open your app with the given URL.

ares-server ./source

Local server running on http://localhost:7496

If you want to open with the default browser of your PC directly, use --open option as below:

ares-server ./source --open
note

To terminate the webserver, use Control-C on prompt.

Monitoring resource usage

he function for monitoring the usage of CPU and memory, which has been provided in Beanviser, is added in CLI from v1.12.0.

Using the ares-device-info command with the --resource-monitor (-r) option, you can monitor the usage of CPU and memory at system or process level. You can also set the time interval to get the usage data periodically and save the data in a .csv file.

For details about each option and parameter, see ares-device-info.

Examples

The following are examples of monitoring the usage of CPU and memory at system and process level.

Display system-level CPU & memory usage

This example displays the system-level CPU and memory usage.

# Display resource usage
$ ares-device-info -d DEVICE -r
 
2022-02-17 08:46:13
 
(%)   overall  usermode  kernelmode  others
----  -------  --------  ----------  ------
cpu   2.41     0         1.38        1.03
cpu0  1.05     0         1.05        0
cpu1  1.03     0         1.03        0
cpu2  4.12     0         1.03        3.09
 
(KB)    total    used    free    shared  buff/cache  available
------  -------  ------  ------  ------  ----------  ---------
memory  1023356  245668  458604  1552    319084      727128
swap    0        0       0
 
=================================================================
 
 
# Display resource usage periodically and save them to a CSV file
$ ares-device-info -d DEVICE -r -s resource.csv -t 1
 
Create resource.csv to D:webOS_TV_SDKCLIbin
2022-02-17 08:47:02
 
(%)   overall  usermode  kernelmode  others
----  -------  --------  ----------  ------
cpu   1.37     0         1.37        0
cpu0  1.02     0         1.02        0
cpu1  1.03     0         1.03        0
cpu2  2.04     0         2.04        0
 
(KB)    total    used    free    shared  buff/cache  available
------  -------  ------  ------  ------  ----------  ---------
memory  1023356  245576  458688  1552    319092      727220
swap    0        0       0
 
=================================================================
2022-02-17 08:47:03
 
(%)   overall  usermode  kernelmode  others
----  -------  --------  ----------  ------
cpu   1.02     0         1.02        0
cpu0  3        1         2           0
cpu1  0        0         0           0
cpu2  2.04     0         1.02        1.02
 
(KB)    total    used    free    shared  buff/cache  available
------  -------  ------  ------  ------  ----------  ---------
memory  1023356  245684  458580  1552    319092      727112
swap    0        0       0
 
=================================================================

To terminate the periodic monitoring of resource usage, enter Ctrl + C.

Display process-level CPU & memory usage

This example displays the process-level CPU and memory usage.

# Launch your app before test
$ ares-launch -d DEViCE com.test.resource
Launched application com.test.resource
 
# Display resource usage of running apps and services
$ ares-device-info -d DEVICE -r -l
 
2022-02-17 08:51:51
 
PID   ID                 CPU(%)  MEMORY(%)  MEMORY(KB)
----  -----------------  ------  ---------  ----------
2336  com.test.resource  0.34    8.01       76060
2439  test               0       8.21       77924
 
======================================================================
 
# Display resource usage of specified running app
$ ares-device-info -d DEVICE -r -id com.test.resource
 
2022-02-17 08:52:53
 
PID   ID                 CPU(%)  MEMORY(%)  MEMORY(KB)
----  -----------------  ------  ---------  ----------
2336  com.test.resource  0.34    8.01       76060
 
======================================================================
No Headings