openHAB JavaScript Tools by smartheit

This library provides utilities for the openHAB JavaScript Scripting Add-on, being used for projects at smartheit GmbH.

Compatibility

• This library is developed for the openHAB 4.3.x series.
• It depends on openhab == 5.9.0, requiring manual installation on the openHAB 4.3.x series. Run npm i [email protected] inside $OPENHAB_CONF/automation/js to install it.
• Parts of the library require additional code that can't be shipped with the library, but this will be clearly noted below.

Additional Dependencies

• The setLedColor method of the revpi namespace requires:
  • the revpi_leds.sh script to be placed in $OPENHAB_CONF/script.
  • write-access to /sys/devices/platform/leds/leds/*/brightness for the user running openHAB (usually that will be smartheit). This can be achieved through an udev rule. Create a file /etc/udev/rules.d/99-leds.rules with the following content:

    SUBSYSTEM=="leds", KERNEL=="*", ATTR{brightness}=="*", MODE="0644", RUN+="/bin/chown root:smartheit /sys/class/leds/%k/brightness", RUN+="/bin/chmod 0664 /sys/class/leds/%k/brightness"

Development

Dev Environment

You need Node.js, version as stated in .nvmrc, and npm installed. It is required to use this version as well in your development environment, otherwise you could cause trouble.

Maintainers therefore recommend to use a Node.js version manager, e.g. nvm-sh/nvm. After you've installed it, run nvm use to use the correct Node.js version.

openhab-js has several (development) dependencies which are required.

Run npm install to install those dependencies.

Code Style

eslint is being used with the JavaScript semistandard style and some overrides for code linting and formatting.

Run the linter with:

npm run lint

Automatically fix issues with:

npm run lint:fix

TypeScript

Although TypeScript is not used for writing the source code, it is still used for emitting declarations and thereby enabling great IntelliSense when using the library.

Generate the types with:

npm run types

Test the generated definitions for problems:

npm run types:test

Testing

Jest is being used for unit tests, which are placed in the test folder and have the extension .spec.js. Have a look at the Jest Documentation and the existing tests to get an idea how Jest works.

Development TL:DR;

To run the linter, generate & test type definitions, run unit tests, generate JSDoc and build the bundled file, run:

npm run build

Deployment

To deploy this library to the $OPENHAB_CONF/etc/automation/js/node_modules folder of the openHAB server, you have two options.

Deploy as Tarball

Pack the library as tarball:

npm pack

Copy the tarball to the $OPENHAB_CONF/etc/automation/js folder and run npm install smartheit-openhab-tools-x.y.z.tgz.

Deploy as Bundle

Copy the openhab-tools.js file from the dist/@smartheit folder into $OPENHAB_CONF/etc/automation/js/node_modules/@smartheit.