Develop and Configure

Version added 07-Mar-2018| Modified 12-Apr-2018

Let us explain the process to create a built-in JS service, by 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.

 

Setup Development Environment

To get started, do the following:

  1. Clone the build-webos repository.

    $ git clone https://github.com/webosose/build-webos.git
  2. Install all required components (on Ubuntu).

    $ sudo scripts/prerequisites.sh
  3. Configure the build.

    $ ./mcf -p 0 -b 0 raspberrypi3
  4. Build the webOS image.

    $ make webos-image

This is only a list of the main steps. For detailed information, see Building webOS OSE and Flashing webOS OSE.

 

Define Source Code

Define the source code for the JS service.

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 description of the above file:

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

  • Line(4) : Register the JS Service.

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

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

 

'package.json' File

This file configures the service meta-data and points to the main service file. It is required for packaging (related with Node.js) and must be located in the root directory. For more detail, 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"
}

 

'README.md' File

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

Non-availability of the README.md file can result in an error at build time.
Make sure the 'Summary' subsection is a single line. Even a blankspace 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 shows the blankspace that can cause the error:

Summary
-------
web app sample
(no blankspace)
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

 

LS2 Configuration Files

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

For details on each LS2 configuration file, see the relevant section at Creating JS Service.

 

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> 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 dynamic service.

 

Role File

This file contains allowed service names for each component and inidivdual 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> 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> 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> to be replaced by 'com.example.service.js'.​​

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

 

'CMakeLists.txt' File

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 description 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 target. To install the files to 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) : Installs 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.