[HowTo] Example:Creating Virtual devices & Remote Logging

[kambis]

Introduction
I have started 3 weeks ago to work on RaZberry and gained a lot of data out of this forum to understand how to write a user module for a home automation task. As a result I like to share my first automation code for study purposes to others in the hope this could be helpful. I appreciate any comments to learn how to write the code in a better way to reach the same result.

Good to know before starting

1. I have attached to this post the complete userModule source code.
   You need to create the sub-folder ExternalEventLogger in the path
   /opt/z-way-server/automation/userModules/ on the Raspberry-Pi.
   Then copy the files index.js and module.json which are attached to this post
   into this folder and restart then z-way-server.
2. You will find many comments within the index.js code for better understanding. Reading following posts are helpful for better understanding of the .js code:
   1. viewtopic.php?f=3423&t=20489
   2. viewtopic.php?f=3422&t=20497
3. It is important to understand the relationship between the index.js script and the module.json file to get the full overview how this code is working. Reading following posts are helpful for better understanding of the .json file:
   1. viewtopic.php?f=3424&t=20496
   2. viewtopic.php?f=3424&t=20492
4. To understand the code you must be aware of how automation tasks are defined in HA user interface! Please read the document: http://razberry.z-wave.me/docs/zwayDev.pdf
5. My code handwriting is a bit different than the ones normally are seen. Sorry for that and be patient with me, but this way I can read the code faster and I feel it is more organized. Use an advanced IDE like VS2010 to read the code more efficient.
6. The code is full functional and I expect that it works on other systems, but it is not complete and development will go on this. Use it please only as study case and 'as is'. There is no support for this code.

Update (17.07.2014): The automation version on your RPi
Check the version of your installed home automation. If you don't have the folder userModules in the path /opt/z-way-server/automation, then you need to upgrade to the latest development version of the home automation. But be aware that this version is not desired for production environment! It is the latest development status of home automation and it might be unstable. To upgrade to the development version do:

Code: Select all

cd /opt/z-way-server/
rm -Rf automation
git clone https://github.com/Z-Wave-Me/home-automation.git automation
cd automation
git checkout develop

If you prefer not to upgrade to the development version of the home automation, then you can copy the provided code in this post into the folder modules instead of the folder userModules.

The Problem and my Solution
As mentioned in one of my earlier posts, I was not able to define an automation rule for the Fibaro FGFS-101 to send alarm events to a remote server. The needed widget was missing for creating a rule in the SensorValueLogging module. So I decided to write a userModule, which allows me to create manually a virtual device 'on-the-fly' base on the data in the z-way-server log file beside the option to select any existing widget in the system, but grouped, based on their types.

To keep the post short, I avoid to start to explain how I did it and let the reader to investigate himself to figure out how this solution is realized by providing all the code. I hope there is someone who might find this as helpful.
Have fun.

[pz1]

Thank you for providing this to the community. Also great how you updated your earlier threads, so readers don't get stuck in a dead alley there.
This is a nice example for other to follow. I hope I can make use of this myself in the near future.
Thanks for your efforts.

[islipfd19]

This is a great addition. But I found that the module wasn't recognized when I added it to the 'userModules' directory, which didn't exist in my automation directory to begin with. I do have version 1.7.1 installed. What I did is moved the ExternalEventLogging module into the modules directory and refreshed the z-way-ha page.

This module does almost what I need it to do. What I need it a module that polls a switch for it's current status, i.e. pressing the "Update all" button on the expert page when looking at the 'Device control' > 'Switches' page.

I use razberry as a secondary controller to my alarm panel in which I have some automation tasks setup on my alarm companies website. Just a basic, turn external lights on when the sun sets and turn them off when the sun rises. Razberry is unable to detect that the switches get turned on and off using that method. Perhaps when I have time, I can look deeper into this module and "tweak" it to suit my needs.

But if anyone know how to accomplish what I'm trying to do, be my guest and assist

[kambis]

ExternalEventLogging is not part of the any Z-Way versions. It is a userModule, which can be added to the installation manually. You need to unzip the file ExternalEventLogger.zip into the folder
/opt/z-way-server/automation/userModules/
Then, very important: restart the z-way-server, otherwise you won't see this module in the home automation module list.

The ExternalEventLogging module was created to inform an external server when individual changes happen. It is not designed for updating all switches for example. But you may find the code as a good starting point to realize your needs.

As long as you want some few switches to be monitored, you can define a rule for each desired switch in the ExternalEventLogging module. Look in your z-wave-server log file and find out if your desired data appears there at all or not. If you can find the entry of interest, then you need to transfer the nodeID, instance, CommandClass and the data-path to the ExternalEventLogging module and create a new widget using these data. They you have the updates in the system.

If no entries of interest are found in the log file, then you need to configure either the device to send data out to the network or play around with associations (or multi-channel associations) to make the device sending data to the network, when changes happens. But be aware that the device must be capable of such a feature (normally they are).

I hope the data above can help a bit in your discoveries

[islipfd19]

So here's a log snippet from an update command from the expert UI. The difficulty I'm having is formulating the correct js script that actually runs this same command.

Code: Select all

Adding job: SwitchBinary Get
[2014-07-17 05:28:42.755] SENDING (cb 0x10): ( 01 09 00 13 0D 02 25 02 25 10 F8 )
[2014-07-17 05:28:42.767] RECEIVED ACK
[2014-07-17 05:28:42.778] RECEIVED: ( 01 04 01 13 01 E8 )
[2014-07-17 05:28:42.779] SENT ACK
[2014-07-17 05:28:42.780] Delivered to Z-Wave stack
[2014-07-17 05:28:42.792] RECEIVED: ( 01 05 00 13 10 00 F9 )
[2014-07-17 05:28:42.793] SENT ACK
[2014-07-17 05:28:42.794] Job 0x13 (SwitchBinary Get): Delivered
[2014-07-17 05:28:42.796] SETDATA devices.13.data.lastPacketInfo.delivered = True
[2014-07-17 05:28:42.797] SETDATA devices.13.data.lastPacketInfo.packetLength = 5 (0x00000005)
[2014-07-17 05:28:42.798] SETDATA devices.13.data.lastPacketInfo.deliveryTime = 14 (0x0000000e)
[2014-07-17 05:28:42.800] SETDATA devices.13.data.lastPacketInfo = **********
[2014-07-17 05:28:42.802] SendData Response with callback 0x10 received: received by recipient
[2014-07-17 05:28:42.804] SETDATA devices.13.data.lastSend = 19571 (0x00004c73)
[2014-07-17 05:28:42.805] Job 0x13 (SwitchBinary Get): success
[2014-07-17 05:28:42.809] Removing job: SwitchBinary Get
[2014-07-17 05:28:42.820] RECEIVED: ( 01 09 00 04 00 0D 03 25 03 FF 25 )
[2014-07-17 05:28:42.821] SENT ACK
[2014-07-17 05:28:42.825] SETDATA devices.13.data.lastReceived = 0 (0x00000000)
[2014-07-17 05:28:42.826] SETDATA devices.13.instances.0.commandClasses.37.data.level = True

My goal (as discussed in our PM's) is to replace a portion of your module (perhaps the URL portion) and place a basic get status command, the very same one sent from the update button in the UI and have it trigger at a set interval.

[kambis]

Here some points for you, which might be helpful to solve your problem:

• Have a deeper look in the automation rule BatteryPolling in the path
  /opt/z-way-server/automation/modules/BatteryPolling
  There you find how to setup a cron handler and add a cron schedule to periodically
  poll the status of your device.
• As I can see in the log data you provided you need to work with the following data path:
  SwtichStatus=zway.devices[13].instances[0].commandClasses[37].data.level.value
• You will find in the ExternalEventLogger good hints how to bind and retrieve your desired data

Good luck

[islipfd19]

I used the Battery Polling module as a starting point and used the light scene module as a reference, I also think that the SwitchControlGenerator is also a good reference. I attached the js and json file in the zip for you too look at, this obviously is no where near complete, pointers from you or anyone else are appreciated because I'm kind of stuck. I've never written an extensive js file before. I did copy the module module (that I've named SwitchPolling) to the modules folder and as I expected it didn't load correctly when I restart z-way, here's the error. It doesn't reference anything useful at this point.

Code: Select all

[2014-07-17 11:26:13.210] Loading module SwitchPolling from modules/SwitchPolling/index.js
[2014-07-17 11:26:13.212] Scheduling execution of file: automation/modules/SwitchPolling/index.js
[2014-07-17 11:26:13.219] Executing script: /*** SwitchPolling Z-Way HA module *
****************************************** ...
[2014-07-17 11:26:13.351] Notification: error (core): Can not load index.js from modules/SwitchPolling/index.js

Would you like me to create my own thread for this adventure so I don't clutter yours up?

[kambis]

Hi islipfd19,
you have unexpected characters in your module.json line 9, 19, 22, 33 and 36
Delete the lines you don't need and learn more how to write json files by following the posts:

• viewtopic.php?f=3424&t=20496
• viewtopic.php?f=3424&t=20492

I have not taken a look in your index.js code after finding these errors.
Correct first the module.json file and check again if you still have error running the code.

[islipfd19]

Thanks! The JSONedit.exe helped a lot! After looking at a few other json files, I found the sensor polling json module to be the perfect fit for what I needed so I updated it. I'm also using the index.js file from the sensor polling as the base as well. The module.json file seems to be in working order but I'm having a bit of difficulty with the index.js file. I'm sure it's the way I'm calling the functions. I'm either missing something (most likely) or have a typo somewhere where I need a second pair of eye to look for.

[kambis]

Hi islipfd19,

you have syntax error in your index.js file.
The lines 13, 15, 21, 23, 68 and 70 must begin with: < // >
Means, instead of this:

Code: Select all

// 
---------------------------------------------------------------------------- 
// --- Class definition, inheritance and setup // 
---------------------------------------------------------------------------- 

use this:

Code: Select all

// ---------------------------------------------------------------------------- 
// --- Class definition, inheritance and setup 
// ---------------------------------------------------------------------------- 

... and your index.js will execute without error.