Caution
webOS IoT is supported by webOS OSE 2.4.0.
webOS IoT is supported by webOS OSE 2.4.0.
To create a JS service, you must write the source code and prepare the required configuration files.
For easier understanding, the process to create a 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.in
│ ├── com.example.service.js.perm.json.in
│ ├── com.example.service.js.role.json.in
│ └── com.example.service.js.service.in
├── com_example_service_js.js
├── package.json
Developing a JS service requires the following steps:
Build and flash the webOS IoT image. For detailed information, see Building webOS IoT and Flashing webOS IoT.
Create a project directory (com.example.service.js
) for the sample JS service, and move into the directory.
$ mkdir com.example.service.js
$ cd com.example.service.js
First, define the functionality of the JS service on the source code.
For the sample JS service (com.example.service.js
), you must:
com_example_service_js.js
com.example.service.js
|
|
A brief explanation of the above file:
Line(1) : Load the webos-service module. For more details about webos-service, see webos-service Library API Reference.
Line(2~3) : Load the pmloglib module. For more details about pmloglib, see Using PmLogLib in Node.js.
Line(6) : Register the JS Service.
Line(9~13) : Register the hello
method which responds to a request with a “Hello, JS Service!!” message
Line(16~24) : Register the locale
method. This method gets the value of locale information from the response received by calling settingsservice’s getSystemSettings
method.
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:
README.md
com.example.service.js
Sample README.md
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
This section describes how to prepare the configuration files required to build and test the JS service.
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 the NPM documentation.
For the sample JS service (com.example.service.js
), you must:
package.json
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"
}
To register and execute a service through LS2, it is necessary to create a Service Configuration 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.
This file contains description of the service type and launch command.
<js service name>.service.in
<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’.
|
|
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 used by default). Set the name of the service along with the service path as parameters to the command.
Line(4) : Set as a dynamic service.
This file contains allowed service names for each component and individual security settings for each service name.
<js service name>.role.json.in
<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’.
|
|
A brief explanation of the above file:
allowedNames
- Names that this service is allowed to register. It can be an array of any valid service name strings, empty array [] for none, and empty string "" for an unnamed service.outbound
- Array of services that this service is allowed to send requests to. It can include strings of any valid service names. Use “*” for all, empty array [] for none, and empty string "" for unnamed services. It’s possible to use a wildcard (*) at the end of a string.This file defines what groups are required for this component to function properly.
<js service name>.perm.json.in
<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’.
|
|
A brief explanation of the above file:
com.example.service.js
calls settingsservice’s getSystemSettings
method, add the method’s group name “settings.read” to the client permission file. When “webos-service” module is used, it calls activitymanager’s create
and complete
methods to keep the dynamic service running for 5 seconds. So, add “activities.manage”.This file defines what methods are included into security groups this component provides.
<js service name>.api.json.in
<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’.
|
|
A brief explanation of the above file:
com.example.service.js
are added to this group.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:
CMakeLists.txt
com.example.service.js
|
|
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 IoT 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 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 need to be installed to target device.
Line(23) : Install the LS2 configuration files (/files/sysbus
) to target.
After implementing and configuring the JS service, you must build the service.
webOS IoT 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: <js service name>.bb
Directory: build-webos/meta-webosose/meta-webos/recipes-webos/<js service name>
where <js service name>
is the name of the JS service. For the sample JS service, <js service name>
must be replaced by ‘com.example.service.js’.
|
|
A brief explanation of the above file:
Lines(1~4) : Basic descriptions of the component.
Line(6) : Version of the component. For the webOS IoT component, this field is mandatory.
Line(7) : 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(9) : Inherit common functions of webOS IoT. For all components of webOS IoT, this entry is required.
Line(10) : 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(11) : Instruct OpenEmbedded that the component uses CMake for configuration, which is the preferred choice for webOS components.
Line(12) : To register component as a service and install LS2 configuration files, inherit webos_system_bus
.
Line(14) : Append the list of files and directories that are placed in a package. Add the files under /usr/palm/service/com.example.service.js
directory for packaging.
To build a component that is located on the local system, you must specify the directory information.
webos-local.conf
build-webos
For the sample JS service (com.example.service.js
), you must provide the local path where the source exists.
|
|
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>
. For the value, input "<full path of the project directory>"
Line(3) : The local build directory. The syntax of the property is EXTERNALSRC_BUILD_pn-<component>
. For the value, input "<full path of the project directory>/build/"
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.
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.service.js
After building the service, you must verify its functionality.
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.service.js
├── CMakeLists.txt
├── README.md
├── files
│ └── sysbus
│ ├── com.example.service.js.api.json.in
│ ├── com.example.service.js.perm.json.in
│ ├── com.example.service.js.role.json.in
│ └── com.example.service.js.service.in
├── com_example_service_js.js
├── package.json
├── oe-logs -> /home/username/build/build-webos/BUILD/work/raspberrypi4-webos-linux/com.example.service.js/0.0.1-r0.local0/temp
├── oe-workdir -> /home/username/build/build-webos/BUILD/work/raspberrypi4-webos-linux/com.example.service.js/0.0.1-r0.local0
If you go to oe-workdir/deploy-ipks/raspberrypi4
, you can see com.example.service.js_0.0.1-r0.local0_raspberrypi4.ipk
file.
com.example.service.js/oe-workdir/deploy-ipks/raspberrypi4
└── com.example.service.js_0.0.1-r0.local0_raspberrypi4.ipk
Copy the IPK file to the target device using the scp
command.
com.example.service.js/oe-workdir/deploy-ipks/raspberrypi4$ scp com.example.service.js_0.0.1-r0.local0_raspberrypi4.ipk root@<target IP address>:/media/internal/downloads
Install the service on the target.
Connect to the target using the ssh
command and install com.example.service.js_0.0.1-r0.local0_raspberrypi4.ipk
.
$ ssh root@<target IP address>
root@raspberrypi4:/sysroot/home/root# cd /media/internal/downloads/
root@raspberrypi4:/media/internal/downloads# opkg install com.example.service.js_0.0.1-r0.local0_raspberrypi4.ipk
Installing com.example.service.js (0.0.1) on root.
Configuring com.example.service.js.
Discover the LS2 configuration files.
To make LS2 daemon scan the LS2 configuration files of the service, use the ls-control
command as follows.
root@raspberrypi4:/media/internal/downloads# ls-control scan-services
telling hub to reload setting and rescan all directories
Run the service.
Since the service is a dynamic service, it is executed when its method is called.
Calling the hello
method:
root@raspberrypi4:/# luna-send -n 1 -f luna://com.example.service.js/hello '{}'
{
"answer": "Hello, JS Service!!",
"returnValue": true
}
Calling the locale
method:
root@raspberrypi4:/# luna-send -n 1 -f luna://com.example.service.js/locale '{}'
{
"message": "You appear to have your locale set to: en-US",
"returnValue": true
}
Verify the execution of the service.
You can use the journalctl
command on the target for debugging the js service. For details on how to use the command, see Viewing Logs.
root@raspberrypi4:/# journalctl | grep exampleJSService
Nov 13 21:05:59 raspberrypi4 le.service.js[1300]: [] [pmlog] exampleJSService LOCALE_CALLBACK {"SERVICE_NAME":"exampleJSService"} get locale response
If you check the result of ls-monitor
immediately after calling the com.example.service.js/hello
method, you can see that the service is executed dynamically.
root@raspberrypi4:/# ls-monitor -l | grep example
868 com.example.service.js /usr/bin/node dynamic K4Nuvsrx
If the service is not used for 5 seconds, it is terminated. Run the ls-monitor
command again after about 5 seconds, and you will see that the service has been terminated.
root@raspberrypi4:/# ls-monitor -l | grep example
Now that you have developed the service and verified its execution, you are ready to add it to the webOS image and then flash it to the target device.
Add the JS service to the packagegroup recipe file.
packagegroup-webos-extended.bb
build-webos/meta-webosose/meta-webos/recipes-core/packagegroups
RDEPENDS_${PN} =
...
RDEPENDS_${PN} = " \
activitymanager \
audiod \
...
com.example.service.js \
${VIRTUAL-RUNTIME_appinstalld} \
...
For more details, see Yocto Project Reference Manual.
Build the webOS image so that it includes the JS service.
build-webos$ source oe-init-build-env
build-webos$ bitbake webos-image
Flash the updated webOS image to the SD card.
Path of webOS image : build-webos/BUILD/deploy/images/raspberrypi4/webos-image-raspberrypi4-master-yyyymmddhhmmss.wic
build-webos/BUILD/deploy/images/raspberrypi4$ sudo dd bs=4M if=webos-image-raspberrypi4-master-yyyymmddhhmmss.wic of=/dev/sdc
For more details, see the Flashing webOS IoT page.
After booting the target device, connect to target with SSH and call com.example.service.js
and check ls-monitor
. You will see that the service is executed as a dynamic type.
root@raspberrypi4:/# luna-send -n 1 -f luna://com.example.service.js/hello '{}'
{
"answer": "Hello, JS Service!!",
"returnValue": true
}
root@raspberrypi4:/# ls-monitor -l | grep example
931 com.example.service.js /usr/bin/node dynamic MUe02Jj1
Contents