Develop and Configure

Version added 07-Mar-2018| Modified 14-Oct-2018

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

For easier understanding, the process to create a built-in JS service is explained using the example of a service named com.example.service.js that has the following methods:

  • hello - Calling this method on the target gives response as "Hello, JS Service!!".

  • locale - Calls methods of another service and gets a value from it.

The directory structure of com.example.service.js must be as follows:

com.example.service.js$
├── CMakeLists.txt
├── README.md
├── files
│   └── sysbus
│       ├── com.example.service.js.api.json
│       ├── com.example.service.js.perm.json
│       ├── com.example.service.js.role.json.in
│       └── com.example.service.js.service.in
├── com_example_service_js.js
├── package.json

com.example.service.js is created as a dynamic service. Therefore, we do not have to create a Systemd configuration file.

Prerequisites

Before you begin developing the built-in JS service, you must:

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

  • Create a project directory (com.example.service.js) for the sample JS service.

$ mkdir com.example.service.js

Source Code

First, define the functionality of the JS service on the source code.

For the sample JS service (com.example.service.js), you must:

  • Create and update the file : com_example_service_js.js

    • Directory : com.example.service.js

var Service = require('webos-service');
 
// Register com.example.service.js
var service = new Service("com.example.service.js");
 
// A method that always returns the same value
service.register("hello", function(message) {
    message.respond({
        answer: "Hello, JS Service!!"
    });
});
 
// Call another service
service.register("locale", function(message) {
        console.log("locale callback");
        service.call("luna://com.webos.settingsservice/getSystemSettings", {"key":"localeInfo"}, function(m2) {
                var response = "You appear to have your locale set to: " + m2.payload.settings.localeInfo.locales.UI;
                console.log(response);
                message.respond({message: response});
        });
});

A brief explanation of the above file:

  • Line(1) : Load the webos-service module. For more details about webos-service, see webos-service API Reference.

  • Line(4) : Register the JS Service.

  • Line(7~11) : Register the hello method which responds to a request with a "Hello, JS Service!!" message

  • Line(14~21) : Register the locale method. This method gets the value of locale information from the response received by calling settingsservice.

README.md

This file provides general information of the JS service and it must be located in the root directory. For the sample JS service (com.example.service.js), you must:

  • Create and update the file : README.md

    • Directory : com.example.service.js

If the REAMD.md file is missing, a build error occurs.
Make sure the 'Summary' subsection is a single line. Even a blank space before the 'Description' section is considered a part of the summary and can cause the build to fail. 
Here is a snippet of the README.md file that will not cause a build error. Any whitespace character in the red-colored line would cause a build error.

Summary
-------
js service sample
(no blank space)
Description
-----------
Summary
-------
js service sample

Description
-----------
js service 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)
 
## Building
 
    $ cd build-webos
    $ source oe-init-build-env
    $ bitbake com.example.service.js
 
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

Configuration Files

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

package.json

This file configures the service metadata and points to the main service file. It is required for packaging (related with Node.js) and must be located in the project root directory. For more details, see Creating JS services.

For the sample JS service (com.example.service.js), you must:

  • Create and update the file : package.json

    • Directory : com.example.service.js

{
  "name": "com.example.service.js",
  "version": "1.0.0",
  "description": "Hello JS Service Sample",
  "main": "com_example_service_js.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "LG Electronics",
  "license": "Apache 2.0"
}

LS2 Configuration Files

To register and execute a service through LS2, it is necessary to create a Service file, a Role file, and Permission files. You must create a "files/sysbus" directory in your project so that the configuration files are installed in the right place on the target.

Service Configuration File

This file contains description of the service type and launch command.

  • Create and update the file : <js-service-name>.service.in

    • Directory : <js-service-name>/files/sysbus

where <js-service-name> is the name of the JS service. For the sample JS service, <js-service-name> is to be replaced by 'com.example.service.js'.

[D-BUS Service]
Name=com.example.service.js
Exec=@WEBOS_INSTALL_BINDIR@/run-js-service -n @WEBOS_INSTALL_WEBOS_SERVICESDIR@/com.example.service.js
Type=dynamic

A brief explanation of the above file:

  • Line(3) : The service can be run with JS service launcher script 'run-js-service'.  The '-n' option means to use Node.js engine.(Currently, -n option is default). Set the name of the service along with the service path as parameters to the command.

  • Line(4) : Set as a dynamic service.

Role File

This file contains allowed service names for each component and individual security settings for each service name.

  • Create and update the file : <js-service-name>.role.json.in

    • Directory : <js-service-name>/files/sysbus

where <js-service-name> is the name of the JS service. For the sample JS service, <js-service-name> is to be replaced by 'com.example.service.js'.

{
    "appId":"com.example.service.js",
    "type": "regular",
    "allowedNames": ["com.example.service.js"],
    "permissions": [
        {
            "service":"com.example.service.js",
            "outbound":[
                "*"
            ]
        }
    ]
}

Client Permission File

This file defines what groups are required for this component to function properly. In this example, the service is set to "public" to give it permission to call the public methods.

  • Create and update the file : <js-service-name>.perm.json

    • Directory : <js-service-name>/files/sysbus

where <js-service-name> is the name of the JS service. For the sample JS service, <js-service-name> is to be replaced by 'com.example.service.js'.​

{
    "com.example.service.js": [
        "public"
    ]
}

API Permission File

This file defines what methods are included into security groups this component provides. In this example, all the methods are included in the "public" group. 

  • Create and update the file : <js-service-name>.api.json

    • Directory : <js-service-name>/files/sysbus

where <js-service-name> is the name of the JS service. For the sample JS service, <js-service-name> is to be replaced by 'com.example.service.js'.​​

{
    "public": [
        "com.example.service.js/*"
    ]
}

CMakeLists.txt

This file is required to build the source code using CMake and it must be located in the root directory.

For the sample JS service (com.example.service.js), you must:

  • Create and update the file : CMakeLists.txt 

    • Directory : com.example.service.js

cmake_minimum_required(VERSION 2.8.7)
project(com.example.service.js NONE)
set(CMAKE_BUILD_TYPE Debug)
 
include(webOS/webOS)
 
webos_modules_init(1 6 3)
webos_component(0 0 1)
 
set(INSTALL_DIR ${WEBOS_INSTALL_WEBOS_SERVICESDIR}/${CMAKE_PROJECT_NAME})
#install necessary files to destination directory
install(DIRECTORY . DESTINATION ${INSTALL_DIR}
        USE_SOURCE_PERMISSIONS
        PATTERN "*~" EXCLUDE
        PATTERN "CMake*" EXCLUDE
        PATTERN "build*" EXCLUDE
        PATTERN "oe-*" EXCLUDE
        PATTERN "*.lock" EXCLUDE
        PATTERN "*.in" EXCLUDE
        PATTERN "files" EXCLUDE
        PATTERN "README.md" EXCLUDE)
 
webos_build_system_bus_files()

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.service.js" as the project name for indicating various filenames and pathnames. The file extension type allows CMake to skip unnecessary compiler checks.

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

  • Line(7) : Specify the "cmake-modules-webos" version.

  • Line(8) : Specify "webos_component" with the component version to use webOS variables for the standard system paths. It commonly follows three digit versioning scheme.

  • Line(10) : The built-in js services must have source code, package.json, and services.json files for each service name in /usr/palm/services/ under the target. To install the files to the target, set /usr/palm/services/com.example.service.js as the path.

  • Line(12~21) : Install the required file to /usr/palm/services/com.example.service.js. Exclude the files that do not have to be installed to target device. 

  • Line(23) : Install the LS2 configuration files (/files/sysbus) to target.

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