pimatic v0.9 info

[sweetpi]

The new beta version v0.9 will be released in early June. This new version will require a manual
update, because it will only work on Node.js version 4 or newer.

There are some breaking changes for users and developers:

Rule System

• We introduced ECA rules: The rule syntax changes from if conditions then actions to
  when events and if condition then actions, where the and if condition part is optional.
• Rules will not be automatically triggered at startup anymore.

Devices editing

• Devices can be edited in the gui using forms, generated from the config schemas.
• Devices can be updated, added and removed at runtime without restart.
• There is a new auto-discovery feature, where plugins can scan for supported devices and present
  a list of discovered devices to the user.

Plugins configuration

• Plugins configuration can be edited in the gui using forms, generated from the config schemas.

Changes for developers

• We have updated our core dependencies. Most notable:
  • bluebird 2 to bluebird 3 Breaking Changes
  • CoffeeScript from 1.8 to CoffeeScript 1.10 Breaking Changes
  • express 3 to express 4 Breaking Changes
  • lodash 2.4 to lodash 3.10 Breaking Changes

Installing pimatic v0.9 prereleases (for testing only)

• Do not update your existing version. Start with a new installation instead.

• Install Node.js v4 using your preferred method. It is recommended to install the latest LTS release. For all Raspberry Pi models including Pi 3, choose the ARMv7 build.

• Make sure you use npm version 2: sudo npm install -f npm@2

• mkdir pimatic-beta && npm install pimatic@beta --prefix pimatic-beta

• Copy your config from your old configuration to your beta installation.

• Startup pimatic as usual.

  pimatic v9 does convert the config (for example adopt the rule syntax) automatically.
  So make a backup if you try the new version and want to go back.

ECA Rules in detail

With pimatic v0.9 we introduce Event Condition Action (ACE) Rules to distinguish between triggering
events and additional conditions to check.

Rules can contain one or more when-parts. The simplest rule form has only a when-Part

when events then actions

As previously events can be one or more predicates joined by logical operations (and and or).
If the expression events is false and a predicate in events changes so that events
becomes true, then the actions will be executed.

In addition rules can contain one or more and if-parts:

when events and if conditions then actions

If the expression events comes true the conditions are checked in additional and the actions are only executed if conditions is true. However if a predicate in conditions changes the rule evaluation is not triggered.

More then one when-part can be defined with separated and if-parts:

when events 1 and if conditions 1
or when events 2 and if conditions 2
then actions

Checklist for plugin developers

Check your plugin projects for pending pull requests

A significant effort has been undertaken to support plugin developers with the transition to Pimatic 0.9. As part of this effort pull requests have been filed with the minimal code changes required to run the plugin code with pimatic 0.9. Note, however, further changes may be required as outlined below.

Coffeescript changes

CoffeeScript 1.9 did introduce one breaking changes affecting almost all pimatic plugins:

Changed strategy for the generation of internal compiler variable names. Note that this means that @example function parameters are no longer available as naked example variables within the function body.

If you use for example @config as constructor parameter, you must use @config for every variable
access inside the constructor. Example

Node.js v4 API changes

If you use native plugins make sure these are compatible with Node.js v4.

Device implementations

If your plugin defines devices make sure that your devices define a destroy function. This function
will be called if the user deletes the device. In your destroy function make sure that you:

• Remove all event listeners you may have registered
• Clear all timeouts or intervals you ma have set with setTimeout or setInterval Example
• Dispose all other resources you may have requested.
• Call super() at the end of your destroy function.

After destroy was called the property @_destroyed is set to true. You may use this property to
check in running action if the device was destroyed while performing the operation.

If the config of a device is changed it will be technically destroyed and a new device with the same if will be created.
So no special handling for config changes is required.

Config schemes

Check that you device and plugin config schemes are handled well by the new plugin setting editor and device editor in the mobile-frontend.

Update you peer-dependencies

You can either release one version support pimatic v0.8 and v0.9 or release separate versions.
If your plugin supports both pimatic v0.8 and v0.9 then change you peerDependencies to:

  "peerDependencies": {
     "pimatic": ">=0.8.0 <1.0.0"
  }

If you want to release a separate version for pimatic v0.9 then create a new git branch v0.9.x
and set your peerDependencies to

  "peerDependencies": {
     "pimatic": "0.9.*"
  }

and publish the v0.9 package with beta tag set to npm: npm publish --tag beta. The beta tag can
be dropped after the release of pimatic v0.9.

Device auto-discovery

You may add a auto-discovery implementation to your plugin. In pimatic v0.9 the user can press the Discover Devices button on the Settings / Devices panel in the mobile-frontend. The DeviceManager will then emit a discover event.
Plugins should listen to this event and search for devices. If a device is found the plugin can call
deviceManager.discoveredDevice with a (incomplete) config for the discovered device. In addition the plugin
can provide a discover message with additional information for the user:

Example:

  class MyPlugin extends env.plugins.Plugin

    init: (app, @framework, @config) =>

      @framework.deviceManager.on('discover', (eventData) =>
        @framework.deviceManager.discoverMessage(
          'pimatic-myplugin', 'Press a button on your remote'
        )

        # search for devices
        @myDiscoverStart()
        @myOnDiscover( (info) =>
          config = {
            class: 'HomeduinoRFSwitch'
            # additional config options
          }
          @framework.deviceManager.discoveredDevice(
            'pimatic-myplugin', 'Device Name', config
          )
        )

        setTimeout(@myStopDiscover, eventData.time)
      )

For an example implementation see pimatic/pimatic-ping@a44db7a

[sweebee]

What is the benefit of or/and if/when? like in:

when trigger: pir1 is present and light1 is turned off then turn light1 on
when trigger: pir1 is present and if light1 is turned off then turn light1 on
when trigger: pir1 is present and when light1 is turned off then turn light1 on

when [trigger: pir1 is present or trigger: home is closed] and light1 is turned on then turn light1 off
when [trigger: pir1 is present or if trigger: home is closed] and light1 is turned on then turn light1 off
when [trigger: pir1 is present or when trigger: home is closed] and light1 is turned on then turn light1 off