Author Topic: Debugging Techniques  (Read 9886 times)

Offline RichardTSchaefer

  • Moderator
  • Master Member
  • *****
  • Posts: 10091
  • Karma: +764/-143
Debugging Techniques
« on: April 06, 2013, 09:24:30 am »

During development I often put notifications on the Condition(s) I am testing. Since I use the Vera Alerts plugin for Notifications ... this Speaks to me every time the specified Condition is satisfied. You can also have a dummy action to turn on or off the light in the room you are working and/or have the Condition trigger a scene that toggles the light off than on.

Another trick is I often use a different device as an Input. For a Trigger a real light switch works as a nice input Trigger ... because you can turn it on and off from the Vera control web page ... and check the results of your logic. If you need to simulate a device that has a changing Device Property ... use a dimmer ... the value range may be different than your existing Device Property ... so you may have to change some set-points in your logic ... but you can change the input by changing the light level in your Vera control web page to exercise your logic.
NOTE: To do this ... delete your existing Input ... do not rename it ... or it will rename all references in the conditions.  Then Save.  Then Refresh the browser then go  back to the PL device and add your dummy input ... using the same Name


When your logic is not working as expected the following will log what the Program Logic plugins are doing.

Turn On Debug for the specic PLEG or PLTS device.
In the Advanced Tab set the Debug variable to 1. Then the big red Save.

Start recording vera log:
    http://YourVeraIPAddress/cgi-bin/cmh/log.sh?Device=LuaUPnP
Exercise your Logic demonstrating the failure. Then save the log file.

To review your log locally ... edit the log and delete the line near the top that says:
Code: [Select]
pageScroll();
 
That will stop the auto scrolling to the bottom ... allowing you time to review the log.
Drag and drop the file onto your favorite Web Browser.

If you want me to review it, then send me the Log ... telling me what happened  and what you expected. Also send the report file.

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques
« Reply #1 on: April 17, 2014, 07:05:07 pm »
Richard,

I am not an experienced user of Lua or PLEG, but have 50 years of programming experience with a couple of dozen languages and I managed team of 70 software engineers with a $80M budget.  So I know something about starting up from scratch with a new language, and I could probably suss my way through it given enough time.  But I am just trying to get a couple of simple things going without becoming an expert. 

It is clear to me that many of the difficulties reported in the Forum would be obviated if there were explicit instructions for capturing the log files from Vera so experience and inexperienced users could easily tell what is going on, i.e., the logs need to be utterly accessible. 

The instructions that you have provided while useful, and perhaps even complete, to an experienced user assume a good deal of knowledge that many trying to get started will find leaves large gaps.  It does not mean we are incapable, but just inexperienced at things you take for granted.  It is the classic start up problem.  Once you have "hello, world", Dennis Ritchie's, famous salute, going then the rest follows quickly.

I am aware that writing good documentation is very tough and time consuming. 
But an explicit step-by-step that would get the Vera log into a text file in my local machine for viewing would pay dividends many times over to all of us.

Offline futzle

  • Beta Testers
  • Master Member
  • *****
  • Posts: 3260
  • Karma: +192/-9
Re: Debugging Techniques
« Reply #2 on: April 17, 2014, 08:40:44 pm »
If we're going to play the "I spent X years dong Y" card, then I should pre-declare that I used to write user documentation for a living for a software company you've all heard of.  I now develop software at the same company and I routinely deal with eight languages on a day-to-day basis and about a dozen more on rare occasions.  (Of course, this counts for nothing except to suggest how susceptible I am to the Dunning-Kruger effect.)

The instructions that you have provided while useful, and perhaps even complete, to an experienced user assume a good deal of knowledge that many trying to get started will find leaves large gaps.  It does not mean we are incapable, but just inexperienced at things you take for granted.

Over in psychology-land, they call this the gap between the Curse of Knowledge and the False-consensus effect.  The writer of the documentation glosses over something "obvious", incorrectly assuming that anyone will have the necessary skill.  The reader of the documentation doesn't know how to perform that step, and incorrectly assumes that everyone else would have stumbled at the same point, faulting the documentation.

Where does the fault lie?  It doesn't matter.  The crucial thing is for both parties to work to bridge the gap.  Here is the process we would follow in my day job:

1. The writer of the documentation produces a series of steps, and numbers them.  Each step contains only one imperative verb.
2. The reader of the documentation tries to perform the steps, and when they get stuck, they report which step they were on, what they expected to see and what they actually saw.
3. The writer and reader figure out what the miscommunication was, and arrive at a new, possibly more detailed, series of steps.
4. Goto 1.

As a writer of documentation, I would always have to assume a certain level of knowledge of my users.  I'm going to say: "Open your browser", not "Press the Spotlight icon then type 'Safari' and press Return" because the latter is actually less helpful, particularly to Windows users.  I'm going to say: "Edit the file in a text editor", not "Right-click on the file, select 'Open with...' and choose 'Notepad'" for the same reason.  Too much detail is as much of a turn-off as too little.  (Digression: here on the forum where I earn $0 an hour for my work and where I assume that users are more motivated, I'll sometimes set them homework to achieve a task, by deliberately not spelling out something that I think they can learn for themselves.  If you dislike this you can complain to my manager.)

So, with the above process in mind, and understanding that it's an iterative process:

Richard: Number your steps.  Users like numbered steps, and it gives them something to refer to.
quinn: Assuming that you followed Richard's steps, where did you get stuck?  It's not obvious to Richard; remember that he has the Curse of Knowledge.

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques
« Reply #3 on: April 18, 2014, 05:10:58 pm »
I am sorry to have stimulated a comment like that of futzle's and apologize to all for having done so.

My intention was to point out the obvious need for better access to debugging in Vera, which I recognize is not really Richard's responsibility, but which would be improved by something as simple as clear RexBeckett-like instructions on how to get to the Vera logs quickly into an accessible text file.

Incidentally, for others just starting with PLEG, or as I am, just trying to decide whether to abandon Zwave altogether, I have found pretty good documentation for getting your first PLEG running: 

http://www.vesternet.com/blog/2014/04/guides-to-vera-pleg-and-plts-plugins
« Last Edit: April 18, 2014, 05:28:25 pm by quinn »

Offline knewmania

  • Sr. Member
  • ****
  • Posts: 255
  • Karma: +0/-0
Re: Debugging Techniques
« Reply #4 on: April 18, 2014, 07:27:47 pm »
My intention was to point out the obvious need for better access to debugging in Vera, which I recognize is not really Richard's responsibility, but which would be improved by something as simple as clear RexBeckett-like instructions on how to get to the Vera logs quickly into an accessible text file.

You may benefit from the log instructions outlined in the Wiki:

http://wiki.micasaverde.com/index.php/Logs

One of the great things about this forum and the Wiki, is that if you identify areas that may be lacking you can contribute and everyone benefits.
« Last Edit: April 18, 2014, 07:54:23 pm by knewmania »
Vera 2. UI 1.5.622 / Vera 3. UI 1.7.760

Offline GoingGreen

  • Jr. Member
  • **
  • Posts: 68
  • Karma: +0/-0
Re: Debugging Techniques
« Reply #5 on: April 18, 2014, 08:02:00 pm »
Richard,

I am aware that writing good documentation is very tough and time consuming. 

As a tech writer that spent nearly 30 years at the trade I can vouch for this. The corollary is that even if good documentation is available many users disdain using it, preferring to slog their way through all the issues. I once surveyed other professional writers and found to my dismay that even professional writers abjure reading their manuals. Psychologists put this phenomenon down to the penchant we have for rugged individualism. It does feel good to wrestle a problem to the ground using only perseverance and grit, but we are faced with so many issues to solve these days that the wisest course is to spend time studying good documentation and doing tutorials.

Users are filled with wildly unrealistic expectations. No document can cover every contingency. For the writer, the task is to try to predict the most common user stumbling points. After a product is released, writers can lean on the support experts for advice. I guess what I am saying is the documentation program has to be a many faceted effort with engineers, writers, illustrators, editors, tech support people and users all having a role in the effort. 
« Last Edit: May 06, 2014, 06:04:44 am by GoingGreen »

Offline RichardTSchaefer

  • Moderator
  • Master Member
  • *****
  • Posts: 10091
  • Karma: +764/-143
Re: Debugging Techniques
« Reply #6 on: April 18, 2014, 10:08:07 pm »
What's funny is that since I wrote this I created a LOG command button and UI that allows you to you set the debug setting (1 of 3 options) and pops open a Log window ... that has a manual/autoscroll feature.

It can't be much easier now ... point and click!
 
I also created the Status report that allows you to see the state of all of your inputs and conditions ... to help understand the logic.

« Last Edit: April 18, 2014, 10:10:08 pm by RichardTSchaefer »

Offline AgileHumor

  • Hero Member
  • *****
  • Posts: 984
  • Karma: +51/-27
  • KISS
Re: Debugging Techniques
« Reply #7 on: April 19, 2014, 12:31:03 am »
@Richard, while I think you've made great progress, there is a lot to learn when taking on PLEG.  I think it's more than you realize being the writer of this amazing software.  And every feature you add (i.e. status reports) just points everyone to the next bottleneck in the learning process.

@quinn, the website for VesterNet website was down, but the titles look very much like the PLEG getting starting guides in this forum written by Rex:
http://forum.micasaverde.com/index.php/board,48.0.html


I've learned to accept that PLEG is more powerful than the documentation can keep pace.   




WMC Leviton:18xVPE06,8xVRS15,3xVRP03-W,2xVRR15,4xVRCS4,2xVRCS2,VP00R,8xVRS15 Aeon:5xDSC06106,4xDSC24,4xDSC25,12xDSB29,2xDSC11,4xDSB54,DSB05,3xDSA22,DSA38,2xDSA03202B,DSB09104,HEM Other:3xYale,12xHSM100v3,7xSP103,45604,WDHA-12,SSA2USR,EVLCD1T,6xWWA02A,7xIPC-HFW2100,URTSI,Hue,Russound,OpenSprinker

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques and Start with PLEG
« Reply #8 on: April 19, 2014, 02:18:52 am »
First, my objective in getting involved here was just to get enough information about Vera/Z-wave to decide whether it was something that would work in a large and expensive house that my wife and I are building on a remote coast in New Zealand.  I was doing a feasibility pass in which I wanted to invest as little time as possible to make the determination.

Second, I apologize again for getting people's dander up.   I did not intend to do so.

Third, @Richard, since writing my plea, I have gotten a PLEG example going and discovered the Log and Report capabilities build into the PLEG device.  Your solution to log access is perfect!!  That is the good news.  The bad news is that I had to struggle to find it and I was on the verge of abandoning Z-wave for a hardwired home automation solution.  As far as I can tell it is not mentioned in Rex's document.

Fourth, @AgileHumor, yes I am aware of the forum thread on logging and at one time even got through the csh and other installs that made it work.  But what a struggle!  It is far from convenient or easy.  I spent 10 years on the faculty at UC when Bill Joy was a graduate student there, and greatly admired Csh, Vi, Berkley Unix and like software IN 1978.  But is grossly user unfriendly by modern standards, actually written when the guys at Xerox Park were just cooking up the GUI interface that Jobs and Gates subsequently copied.  Incidentally, had one of the Vesternet documents not done a partial step-by-step, I might not have kept trying with my Z-wave feasibility efforts.

Fifth, I have written and attached a document, called "Step-by-Step to Your First PLEG Device" that I hope will help "newbies" like me bypass a bunch of the guess work of starting up.  I would be happy to send the docx original to anyone who would like to correct it and/or put it in a place where it might be useful to other.  At the moment it is a bit too large.

Offline futzle

  • Beta Testers
  • Master Member
  • *****
  • Posts: 3260
  • Karma: +192/-9
Re: Debugging Techniques
« Reply #9 on: April 19, 2014, 02:37:35 am »

I am sorry to have stimulated a comment like that of futzle's and apologize to all for having done so.

Haha, yes, I deserved that. I, too, apologize for having allowed my buttons to have so easily been pressed. Your point is well taken: so many support mechanisms rely on this hard-to-catch log with no easy mechanism for getting just that one plugin's messages. Ideally MCV would supply a syslog-style system for plugins to specify a severity and class of message, and then a way to view all of the logs from the web UI. The Info Viewer plugin is great, but that it has to be installed at all is a disincentive.

Offline Brientim

  • Sr. Hero Member
  • ******
  • Posts: 2497
  • Karma: +78/-7
Re: Debugging Techniques
« Reply #10 on: April 19, 2014, 02:49:16 am »
@quinn so what, so far is your conclusion given the information you have now?

I think keeping the distinction between using Vera to support a large deployment, as compared to z-wave being used as there are other platforms that could be used as alternatives.

There are some very big deployment of z-wave but that does not mean it is suitable in other cases. However, it is tending to be currently the preferred... Thus, what have you concluded so far?

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques
« Reply #11 on: April 19, 2014, 05:40:34 pm »
Quote
@quinn so what, so far is your conclusion given the information you have now?

In my experience, once you have one example working (like my simple PLEG) things accelerate and you can rapidly progress.  Functionality can grow exponentially.

I am still not sure that Z-wave will be reliable enough for daily trouble free use for people who just want it to work, but I have experimented enough that I am 90% sure that I can do what I need to do and can maintain it with an acceptable level of effort.

Can it ever be made as accessible to ordinary folks as say text processing has become?  Yes, theoretically, but that would take developing a mass market as happened in the 80's with PC's and a massive user interface effort, which is not likely given the size that the market is likely to be.

To compare Vera/Z-wave with wired systems, say C-bus or whatever proprietary wired system, is not entirely fair.  C-bus is installed and maintained by experts, as are all the other proprietary systems.  I suspect that if Z-wave installations were done the same way with consistent single-manufacturer hardware Z-wave reliability would approach that of wired systems.  And then there is the cost.  We were quoted $NZ 200K to do a fairly complete wired home automation system in our new house.

At least that is what I hope, because I'm pushing on with Z-wave.  If I can get Richard's auto off/motion detect controller working with a couple of variants that I think it needs, I will be certain that I can meet my primary goals.

The process has been very time consuming though.  Vera's own documentation is fragmented, incomplete, poorly maintained, and un-unified, and they are handicapped by not having control of the peripherals.  In my experience, the email support is excellent, but that is also is slow and often imprecise.  Much of the information is in the forum, but that requires hours of searching.  A mechanism where guys like Rex and Richard could post current versions or summaries of the forum content would increase efficiency, but those guys are already overloaded.  I am not sure that I understand futzle's suggestion, but it sounds like something that should be considered.

Too many words in this comment.  Sorry about that.  I'm like Mark Twain, "I would have written a short letter, but I did not have time, so I wrote a long one."
« Last Edit: April 19, 2014, 05:48:59 pm by quinn »

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques
« Reply #12 on: April 26, 2014, 01:22:17 am »
I have implemented a version "Simulate Smart Switch", a published PLEG example, http://rts-services.com/Vera/Plugin/PLEG/example/smartswitch.html.

The problem I am having in trying to debug and understand it is that the Status report does not seem to be updating.  Here is a report that has remained unchanged since about 12:42 despite the fact that I have Reloaded, Triggered the motion detector and modified the PLEG numerous times for over 5 hours.

Attached is the status report obtained at 1700 hours with a single trigger or condition having changed value despite all my fooling around which included triggering the motion detector.

I must be missing something.  Can anyone help.

Offline RexBeckett

  • Beta Testers
  • Master Member
  • *****
  • Posts: 3891
  • Karma: +482/-12
Re: Debugging Techniques
« Reply #13 on: April 26, 2014, 04:08:21 am »
PLEG doesn't think you have a valid license. Is this correct? Did it post any errors on the UI message area (blue, top-centre)? 

If PLEG is enforcing the free-use limits, it will restrict you to five Inputs and five Conditions.

Offline quinn

  • Newbie
  • *
  • Posts: 19
  • Karma: +2/-3
Re: Debugging Techniques
« Reply #14 on: April 26, 2014, 05:41:55 pm »
Thanks, Rex, for responding.

The Status report states that I am not registered, but I was under the impression that I had 30 days full use.  However, I have no problem with registering.  If I can get PLEG to work, it will be more than worth it. 

This morning the Status report appears to have started working again.  I don't know why.  There must be some kind of reset that I could have done.  The only thing I know about that happens automatically is the repair at 2:00. (As far as I could tell from the Log, was reporting the changing variables and times when Status had stopped working.)  I am running Win7, Vera3, Pleg 6.7, and IE.

I was having trouble getting the on-off-on function to work.   As you can see from the attachment to the previous post, I had changed the time constants in Richard's Smart Switch Simulator to make it easier to test.  I recall that you previously commented to someone regarding a similar problem and you pointed out that the on-off-on action had to occur in a window from 30 to 60 seconds.  I did not understand it at the time, but could track it down and read it again.

At about the time Status stopped working, I just implemented one of your MultiSwitches to replace the light switch for the on-off-on and off-on-off functions to see if I could isolate that function from the Actions.

But the primary issue here is not that my implementation of the PLEG is not working but rather that the diagnostic tool stopped working and I could find no way to restart it.  Any help would be appreciated.

[By the way, I have several suggestions for the Pleg Basics document (which is generally excellent) and would be happy to forward them to you if there is a way.]