Developing Built-in Web Apps

To create a built-in web app, you must write the source code and prepare the required configuration files.

For easier understanding, the process to create a built-in web app is explained using the example of a web app named com.example.app.web that responds with the string “Hello, Web Application!!”.

The directory structure of com.example.app.web must be as follows:

com.example.app.web
├── CMakeLists.txt
├── README.md
├── appinfo.json
├── icon.png
├── index.html
└── webOSjs-0.1.0
    ├── LICENSE-2.0.txt
    └── webOS.js

Developing a built-in web app requires the following steps:

Before you begin

  • Build and flash the webOS OSE image. For detailed information, see Building webOS OSE and Flashing webOS OSE.

  • Create a project directory (com.example.app.web) for the sample web app, and move into the directory.

    $ mkdir com.example.app.web
    $ cd com.example.app.web

Step 1: Implement the Web App

Source Code

You can develop a web app using standard web technologies.

Web apps built for webOS devices can also provide enhanced functionality by leveraging the APIs provided by webOS services. Let us understand this with a sample code that prints a hello message and also prints the current time on the log.

Prerequisite (when calling LS2 API in the web app)
Download the webOS library file from webOSjs-0.1.0.zip and decompress it to the project root directory. This library is required to call LS2 API.

For the sample web app (com.example.app.web), create the index.html file in the project root directory.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
<!DOCTYPE html>
<html>
<head>
<style type="text/css">
body {
    width: 100%;
    height: 100%;
    background-color: #202020;
}
div {
    position:absolute;
    height:100%;
    width:100%;
    display: table;
}
h1 {
    display: table-cell;
    vertical-align: middle;
    text-align:center;
    color: #FFFFFF;
}
</style>
<script src="webOSjs-0.1.0/webOS.js" charset="utf-8"></script>
<script type="text/javascript">
//sample code for calling LS2 API
var lunaReq= webOS.service.request("luna://com.webos.service.systemservice",
{
    method:"clock/getTime",
    parameters:{},
    onSuccess: function (args) {
        webOS.info("GETTIME_SUCCESS", {"APP_NAME": "example web app"}, "UTC : " + args.utc);
    },
    onFailure: function (args) {
        webOS.error("GETTIME_FAILED", {"APP_NAME": "example web app"}, "errorText : " + args.errorText);
    }
});
</script>
</head>
<body>
    <div>
        <h1>Hello, Web Application!!</h1>
    </div>
</body>
</html>

A brief explanation of the above file:

  • Line(23) : Include the webOs library.

  • Line(25~36) : Call systemserivce/clock/getTime method. If the response is successful, print “UTC” to log file. (/var/log/messages). For details, refer to Using PmLog in JavaScript.

README.md

This file provides general information of the web app. For the sample web app (com.example.app.web), you must:

  • Create and update the file: README.md
  • Directory: com.example.app.web
Caution
  • If the README.md file is missing, a build error occurs.
  • Make sure the ‘Summary’ section is a single line. Even any whitespace at the line above the ‘Description’ section is considered a part of the summary and can cause the build to fail.

Sample README.md

Summary
-------
web app sample

Description
-----------
web app sample

How to Build on Linux
---------------------

## Dependencies

Below are the tools and libraries (and their minimum versions) required to build sample program:

* cmake (version required by cmake-modules-webos)
* gcc
* glib-2.0
* make
* cmake-modules-webos

## Building

    $ cd build-webos
    $ source oe-init-build-env
    $ bitbake com.example.app.web

Copyright and License Information
=================================
Unless otherwise specified, all content, including all source code files and
documentation files in this repository are:

Copyright (c) 2018 LG Electronics, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0

Step 2: Configure the Web App

This section describes how to prepare the configuration files required to build and test the built-in web app.

appinfo.json

Apps are required to have metadata before they can be packaged. This metadata is stored in a file called appinfo.json, which is used by the webOS device to identify the app, its icon, and other information that is needed to launch the app. For the sample web app (com.example.app.web), you must:

  • Create and update the file: appinfo.json
  • Directory: com.example.app.web
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": "com.example.app.web",
  "version": "0.0.1",
  "vendor": "My Company",
  "type": "web",
  "main": "index.html",
  "title": "Web app sample",
  "icon": "icon.png",
  "requiredPermissions": ["time"]
}

A brief explanation of the above file:

  • Line(2) : The ID for the app.

  • Line(5) : The type of the web app.

  • Line(7) : The title to be shown on the Home Launcher.

  • Line(8) : The icon to be shown on the Home Launcher. Make sure the icon file is available in the project root directory. You can use your own icon.png (80*80) file or attached icon.png.

  • Line(9) : Specify the group to which the external service’s method called by the app belongs. Because systemservice’s getTime method belongs to “time” group, put “time” in this property. To check the group of each method, use ls-monitor command with “-i” option.

For more details, see appinfo.json.

CMakeLists.txt

This file is required to generate the standard build files. For the sample web app (com.example.app.web), you must:

  • Create and update the file: CMakeLists.txt
  • Directory: com.example.app.web
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
cmake_minimum_required(VERSION 2.8.7)
project(com.example.app.web NONE)
include(webOS/webOS)
webos_modules_init(1 0 0 QUALIFIER RC4)

set(INSTALL_DIR ${WEBOS_INSTALL_WEBOS_APPLICATIONSDIR}/${CMAKE_PROJECT_NAME})
#install necessary files to destination directory
install(DIRECTORY . DESTINATION ${INSTALL_DIR}
        PATTERN "*~" EXCLUDE
        PATTERN "CMake*" EXCLUDE
        PATTERN "build*" EXCLUDE
        PATTERN "README.md" EXCLUDE
        PATTERN "oe-*" EXCLUDE
        PATTERN "*.lock" EXCLUDE)

A brief explanation of the above file:

  • Line(2) : Specify the project name and the file extension type. In this tutorial, we use “com.example.app.web” as the project name for indicating various filenames and pathnames. The file extension type “NONE” allows CMake to skip unnecessary compiler checks.

  • Line(3) : Include webOS OSE modules for the build.

  • Line(4) : Specify the “cmake-modules-webos” version.

  • Line(6) : The built-in app must have source code, appinfo.json, and icon files for each application name in /usr/palm/applications/ on the target. To install the files to the target, set /usr/palm/applications/com.example.app.web as the path.

  • Line(8~14) : Install the required files to /usr/palm/applications/com.example.app.web on the target. Exclude the files that do not need to be installed to the target device.

Step 3: Build the Web App

After implementing and configuring the web app, you must build the app.

Add the Recipe File

webOS OSE uses OpenEmbedded of Yocto Project to build its components. You must write a recipe that configures the build environment. For more details about the recipe, see Yocto Project Reference Manual.

  • Create and update the file: <web-app-name>.bb
  • Directory: build-webos/meta-webosose/meta-webos/recipes-webos/<web-app-name>

where <web-app-name> is the name of the web app. For the sample web app, <web-app-name> must be replaced by “com.example.app.web”.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
SECTION = "webos/apps"
LICENSE = "Apache-2.0"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/Apache-2.0;md5=89aea4e17d99a7cacdbeed46a0096b10"

WEBOS_VERSION = "1.0.0"
PR = "r0"

inherit webos_component
inherit webos_submissions
inherit webos_cmake
inherit webos_app
inherit webos_arch_indep

FILES_${PN} += "${webos_applicationsdir}"

A brief explanation of the above file:

  • Line(1~3) : Basic descriptions of the component.

  • Line(5) : Version of the component. For the webOS OSE component, this field is mandatory.

  • Line(6) : Revision version of the recipe. Each recipe requires a counter to track its modification history. Make sure that you increment the version when you edit the recipe, unless you only change the value of the WEBOS_VERSION field or comments.

  • Line(8) : Inherit common functions of webOS OSE. For all components of webOS OSE, this entry is required.

  • Line(9) : Instruct OpenEmbedded to use the WEBOS_VERSION value as the component version number. If you develop your component on a local repository, this entry is required.

  • Line(10) : Instruct OpenEmbedded that the component uses CMake for configuration, which is the preferred choice for webOS components.

  • Line(11) : Inherit webos_app, because the component is an app.

  • Line(12) : Inherit webos_arch_indep, because the web app is CPU architecture independent. When inheriting from webos_arch_indep, ensure that your project command in the CMake script specifies NONE as the language, i.e. project(<component> NONE). Otherwise, CMake will attempt to find the C and C++ compilers. Your component may well be built before the toolchain, resulting in a failure to build.

  • Line(14) : ${webos_applicationsdir} indicates /usr/palm/applications. ${PN} is a package name, which is set to com.example.app.web.

Configure the Local Source Directory

To build a component that is located on the local system, you must specify the directory information.

  • Create and update the file: webos-local.conf
  • Directory: build-webos

For the sample web app (com.example.app.web), you must provide the local path where the source exists.

1
2
3
4
INHERIT += "externalsrc"
EXTERNALSRC_pn-com.example.app.web = "/home/username/project/com.example.app.web/"
EXTERNALSRC_BUILD_pn-com.example.app.web = "/home/username/project/com.example.app.web/build/"
PR_append_pn-com.example.app.web =".local0"

A brief explanation of the above file:

  • Line(1) : Inherit “externalsrc” bbclass file.

  • Line(2) : The local source directory. The syntax of the property is EXTERNALSRC_pn-<component>.

  • Line(3) : The local build directory. The syntax of the property is EXTERNALSRC_BUILD_pn-<component>.

  • Line(4) : The appended revision version (PR) for building local source files. The syntax of the property is PR_append_pn-<component>. This property is optional.

Note
We recommend that you add a trailing slash (/) at the end of all local directory paths, as in Line(2) and Line(3).

Build the App

To build the component on the OpenEmbedded environment, enter the following commands on the shell.

build-webos$ source oe-init-build-env
build-webos$ bitbake com.example.app.web

Step 4: Run and Verify the Web App

After building the app, you must verify its functionality.

  1. Copy the IPK to the target.

    When the build is successful, oe-related directories are created under the project root directory. These directories are linked to the directory where the build output is generated from the actual build-webos sub-directory.

    com.example.app.web
    ├── CMakeLists.txt
    ├── README.md
    ├── appinfo.json
    ├── build
    ├── icon.png
    ├── index.html
    ├── oe-logs -> /home/username/build/build-webos/BUILD/work/all-webos-linux/com.example.app.web/1.0.0-r0.local0/temp
    ├── oe-workdir -> /home/username/build/build-webos/BUILD/work/all-webos-linux/com.example.app.web/1.0.0-r0.local0
    └── webOSjs-0.1.0
        ├── LICENSE-2.0.txt
        └── webOS.js

    If you go to oe-workdir/deploy-ipks/all, you can see com.example.app.web_1.0.0-r0.local0_all.ipk file.

    com.example.app.web/oe-workdir/deploy-ipks/all
    └── com.example.app.web_1.0.0-r0.local0_all.ipk

    Copy the IPK file to the target device using the scp command.

    com.example.app.web/oe-workdir/deploy-ipks/all$ scp com.example.app.web_1.0.0-r0.local0_all.ipk root@192.168.0.12:/media/internal/downloads/
  2. Install the app on the target.

    Connect to the target using the ssh command and install com.example.app.web_1.0.0-r0.local0_all.ipk.

    $ ssh root@192.168.0.12
    root@raspberrypi3:~# cd /media/internal/downloads/
    root@raspberrypi3:/media/internal/downloads# opkg install com.example.app.web_1.0.0-r0.local0_all.ipk
    
    Installing com.example.app.web (1.0.0) on root.
    Configuring com.example.app.web.
    No image conversions needed for com.example.app.web
  3. Discover the LS2 configuration files.

    To make LS2 daemon scan the LS2 configuration files of the app, use the ls-control command as follows.

    root@raspberrypi3:/media/internal/downloads# ls-control scan-services
    
    telling hub to reload setting and rescan all directories
    Note
    For the built-in web app, LS2 configuration files are generated during the build process. To run the app properly, you must make the system scan the newly generated configuration files.
  4. Scan the app.

    To make System and Application Manager (SAM) scan the app, restart SAM using the systemctl command. This step is required so that the app can be added to the app list, which in turn makes the app appear on the Home Launcher.

    root@raspberrypi3:/# systemctl restart sam
    Note
    Rebooting the target after installing the app will have the same effect as running the ls-control and systemctl commands. However, using the commands allows you to continue testing without rebooting.
  5. Run the web app.

    Use the Windows key on keyboard to display the Home Launcher. Click the app icon and you should see the window titled “Web app sample” with the following page:

    web app screen
  6. Verify the execution of the web app.

    • Using SAM

      You can check whether the app is running by using SAM. For more SAM methods, see com.webos.service.applicationmanager.

      root@raspberrypi3:/# luna-send -i -f luna://com.webos.service.applicationmanager/running '{"subscribe":true}'
      {
          "subscribed": true,
          "running": [
              {
                  "id": "com.example.app.web",
                  "webprocessid": "1827",
                  "defaultWindowType": "card",
                  "appType": "web",
                  "processid": "1827"
              }
          ],
          "returnValue": true
      }
    • Using the log file

      You can check the app’s log in /var/log/messages file on the target. Open the file and find “UTC” keyword.

      2019-05-16T02:29:15.322750Z [1517.986582763] user.info WebAppMgr [] com.example.app.web GETTIME_SUCCESS {"APP_NAME":"example web app"} UTC : 1557973755

Step 5: Deploy the Web App

You are now ready to build the webOS image including the web app and flash it to the target device.

Perform the following steps:

  1. Add the web app to the build recipe file.

    • Filename: packagegroup-webos-extended.bb

    • Directory: build-webos/meta-webosose/meta-webos/recipes-core/packagegroups

    • Updates to be made: Add the web app name to RDEPENDS _ $ {PN} =

    ...
    RDEPENDS_${PN} = " \
        activitymanager \
        audiod \
        ...
        com.example.app.web \
        ${VIRTUAL-RUNTIME_appinstalld} \
        ...

    For more details, see Yocto Project Reference Manual.

  2. Build the webOS image using the following commands.

    build-webos$ source oe-init-build-env
    build-webos$ bitbake webos-image
  3. Flash the generated webOS image to the SD card.

    Path to image: build-webos/BUILD/deploy/images/raspberrypi3/webos-image-raspberrypi3-master-yyyymmddhhmmss.rpi-sdimg

    build-webos/BUILD/deploy/images/raspberrypi3$ sudo dd bs=4M if=webos-image-raspberrypi3-master-yyyymmddhhmmss.rpi-sdimg of=/dev/sdc

After rebooting, the web app becomes available on the Home Launcher.

Contents