diff --git a/docs/default.htm b/docs/default.htm new file mode 100644 index 00000000..c0808d35 --- /dev/null +++ b/docs/default.htm @@ -0,0 +1,109 @@ + + + +Introduction + + + +
+
+ + + + + +
Logo Introduction
+ + + + +

Purpose

+

OpenZWave is a library which provides an API for applications to access and control a Z-Wave controller connected to the PC via a serial or HID connection.
+
+

+ + + + +

Documentation

+

Although the project is still in too early a stage to produce user documentation, the source code for OpenZWave and OpenZWaveDotNet contains comments that can be converted into HTML documentation.

+

Instructions for how to generate this documentation, as well as other links to information that may be useful to developers using OpenZWave may be found here: OpenZWave Documents
+
+

+
+ + + + +

Project Directory Structure

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
  
configXML files that provide device- and manufacturer-specific information, as well as the Z-Wave command class codes.
cppThe OpenZWave library project.
  cpp/buildMakefiles and Visual Studio project/solution files for building the library under linux, Mac and Windows (VS2008 and VS2010).
  cpp/examplesA minimal console application (MinOZW) that can be built under linux, Mac and Windows. It is a useful example of how to start up the library and can be used to generate a log file (OZWlog.txt) to diagnose startup or other problems with the library and/or Z-Wave devices.
  cpp/hidapiFiles related to implementation of a "Human Interface Device" (HID) connection between the PC and the Z-Wave controller. While many controllers use a serial interface, others (the ThinkStick, for example) use HID via USB.
  cpp/libEssentially empty.
  cpp/srcThe source code for the OpenZWave Library. The top-level code is in this directory; subdirectories contain files to implement the command classes, the value classes and platform-specific code (linux, Mac and Windows).
  cpp/tinyxmlThe TinyXML class code. TinyXML is used to read and write XML files for persistent storage.
documentsDraft documentation for the library and example applications.
dotnetA .NET wrapper for the OpenZWave library.
  dotnet/buildProject/Solution files for building OpenZWaveDotNet under VS2008 and VS2010.
  dotnet/examplesCode for OZWForm, a .NET application that demonstrates use of OpenZWaveDotNet to connect to a controller, read information about nodes, process notifications, etc.
  dotnet/srcThe OpenZWaveDotNet wrapper code.
licenseLicense documents.
+
+ +
+ + diff --git a/docs/general/DoxygenStepByStep.html b/docs/general/DoxygenStepByStep.html new file mode 100644 index 00000000..65471376 --- /dev/null +++ b/docs/general/DoxygenStepByStep.html @@ -0,0 +1,60 @@ + + + + +Creating OpenZWave Documentation + + +
+
+ + + + + +
Logo Doxygen Step-by-Step
+ + + + +

Introduction

+

To produce simple doxygen documentation for the OpenZWave libary, follow the steps below.  Once you've successfully produced the base documentation, you may want to use doxygen's Expert mode to customize the output.

+

Using Doxygen to generate OpenZWave documentation: Step 1

+

Once Doxygen has been downloaded and installed, run Doxywizard.exe. Here is a screen shot of the first step of the Wizard completed.  

+

+

+
    +
  • Make sure the source code directory points to the OpenZWave cpp/src directory on your system.
    +
    +
    • +
  • Select the destination directory of your choice.
    +
    • +
+

Using Doxygen to generate OpenZWave documentation: Step 2

+

The Mode selections allow you to control how much information is generated and to customize the output for a variety of programming languages. 

+

You can reduce the amount of documentation generated by selecting "Documented entities only" and de-selecting the "Include cross-referenced..." check box.  If you are using Doxygen to produce documentation for OpenZWaveDotNet, you might prefer "Optimize for C++/CLI output."

+

a

+


+ Using Doxygen to generate OpenZWave documentation: Step 3

+

The Output step determines what form the generated documentation should take. I generally prefer HTML with a navigation tree, searchable, but others are available.  

+

a

+


+ Using Doxygen to generate OpenZWave documentation: Step 4

+

The Diagrams step determines whether Doxygen will produce class diagrams.  

+

a

+


+ Using Doxygen to generate OpenZWave documentation: Step 5

+

That's it!  Select the Run tab, then Run doxygen to produce the documentation files.

+

a

+

+

That's it! You should now have a version of OpenZWave documentation in your destination directory.  Navigate into the .../html directory and load index.htm to display the top level of the documentation.

+
+
+ +
+ + diff --git a/docs/general/GettingHelp.html b/docs/general/GettingHelp.html new file mode 100644 index 00000000..91d87a78 --- /dev/null +++ b/docs/general/GettingHelp.html @@ -0,0 +1,55 @@ + + + + +Getting Help with OpenZWave + + +
+
+ + + + + +
Logo Getting Help
+ With OpenZWave
+ + + + +

Need Help?

+

Since the OpenZWave library is still in early stages of development, you should not be surprised if it doesn't work as you might expect (despite our continuing efforts to stamp out bugs and add features). 

+

In particular, given the wide variety of Z-Wave devices and the fact that the developers of OpenZWave do not have access to the full protocol, certain portions of the code have not been tested with actual devices, so some problems are (unfortunately) inevitable. However, with more users testing the library with new Z-Wave devices, we should be able to identify and eliminate any faulty assumptions or logical (or careless) errors.

+

Based on the questions raised in the OpenZWave forum (link), here are some pointers to getting your questions answered.

+

I.  Generate and Review the Documentation

+

Although OpenZWave doesn't have user documentation as yet, the source code has been commented in a way that will allow an external program, Doxygen, to produce HTML documentation for the library.  Here is a description of how to generate this documentation.

+

II.  Isolate the Problem Using the MinOZW or OZWForm Examples

+

Some users' issues with OpenZWave have proven to be related to either their own (calling) code or a misunderstanding about how the library is supposed to work.  The documentation (see I above) should help reduce misunderstandings.  And reproducing the problem using small changes to the example code will help other developers and users try to replicate the issue.  Once you can reproduce the problem, post a forum message identifying:

+
    +
  1. The nature of the problem (what's wrong?)
    2. +
  2. What changes you made to MinOZW or OZWForm to replicate the issue (if they're substantial, you may want to attach the modified source code file(s) to your post)
    3. +
  3. What hardware is involved (in particular, the Z-Wave controller attached to the PC and the device/node in question)--manufacturer and model number
    4. +
  4. Where the problem is evident in an OZWlog.txt file (and attaching the log file to your post--see below)
    5. +
+

III.  The OpenZWave Execution Log: OZWlog.txt

+

The OpenZWave library generates an execution log whenever it is run. (The library has been designed to allow this feature to be turned off, but at this early stage in development it should always be produced.)  The log file can be very helpful in diagnosing problems with OpenZWave.  It identifies the startup steps, communication between the OpenZWave library and the controller (and, through the controller, with the various nodes on the Z-Wave network).  It can help identify whether there is a problem with the library, the controller or a Z-Wave node).

+

So, if you're having a problem, try the following:

+
    +
  1. Stop the OpenZWave application (if one is running)
    2. +
  2. Locate and delete any copies of the zwcfg*.xml file. (The actual file name will have the Z-Wave network's HomeID in place of the '*' in the file name.)  This will cause the OpenZWave library to identify each node on the network as "New" and poll each device for its capabilities, settings, etc.
    3. +
  3. Run the application using OpenZWave until the problem occurs.
    4. +
  4. Exit the program and review the OZWlog.txt file that was created. Are there any unusual errors on startup?  Do the Z-Wave devices report the capabilities (command classes handled) that you expect?  Do the static, session and dynamic values look right?  Can you identify where execution went "off track" (sent a new command? unexpected response received? no response received to a command?)?
    5. +
  5. Review of the log file may help you identify what went wrong with your code (or what's wrong with the OpenZWave library).
    6. +
  6. If you can't figure out what's going wrong from the review of the log and the other suggestions outlined on this page, consider posting a message to the discussion forum and attach a copy of the OZWlog.txt file.  But keep in mind, it is often very helpful to have a "clean" log file to work with...one that shows the nodes in the network as "New," and not as "Known."  (See Step 2 above.)
    7. +
+
+
+ +
+ + diff --git a/docs/general/Index.htm b/docs/general/Index.htm new file mode 100644 index 00000000..96cae1c1 --- /dev/null +++ b/docs/general/Index.htm @@ -0,0 +1,40 @@ + + + +Other OpenZWave Documents + + + +
+
+ + + + + +
Logo OpenZWave Information
+ + + + +

The following pages provide additional information about the ZWave protocol and the OpenZWave library.

+

General

+

Getting Help with OpenZWave

+

Generating OpenZWave Documentation

+

OpenZWave Architecture and Use

+

Notification Messages and Sequence

+

The Z-Wave Protocol

+

 

+

Z-Wave Devices

+

 

+

External Links to Other Z-Wave Information

+

 

+
+ +
+ + diff --git a/docs/general/MakingDocumentation.html b/docs/general/MakingDocumentation.html new file mode 100644 index 00000000..5bb92394 --- /dev/null +++ b/docs/general/MakingDocumentation.html @@ -0,0 +1,42 @@ + + + + +Creating OpenZWave Documentation + + +
+
+ + + + + +
Logo Creating OpenZWave
+ Documentation
+ + + + +

Introduction

+

OpenZWave is still under development, and new features, bug fixes and interface changes are being made on a frequent basis.  So it's premature to focus too much energy on producing user documentation at this point.  However, several users have asked whether there is documentation available.

+

So here is a guide to producing your own version of the documentation (such as it is).

+

Doxygen-style comments

+

Much of the source code for the OpenZWave library and the OpenZWaveDotNet wrapper has been documented via comments in the .h header files associated with these projects.  So, if you're working with OpenZWave in a development environment (which most users will be, since only source code is available at this point), you can find many functions documented in these files.

+

The format of the comments is designed to allow an external program, called Doxygen, to produce documentation (for example, a series of .html files) by scanning the project files, interpreting these comments and producing the .html code to organize and display the documentation in a sensible manner. So, to produce the most up-to-date copy of the documentation, a user can run Doxygen on the project folder in question (OpenZWave or OpenZWaveDotNet).

+

Getting and Using Doxygen

+

The Doxygen program can be downloaded from http://www.doxygen.org.  Versions of Doxygen are available for Windows, linux and Mac operating systems (as well as source code).

+

Once Doxygen has been downloaded and installed you can produce documentation by running Doxywizard.exe.  If you're new to Doxygen, here are some step-by-step instructions for creating OpenZWave documentation.

+

Other Documentation Sources

+

In addition to the documentation that can be generated with Doxygen, there are a variety of other sources of information on OpenZWave and on the ZWave protocol more generally. Some of these are linked here.

+

+

 

+
+ +
+ + diff --git a/docs/general/Notifications.html b/docs/general/Notifications.html new file mode 100644 index 00000000..6f800a8c --- /dev/null +++ b/docs/general/Notifications.html @@ -0,0 +1,279 @@ + + + +Notification Messages and Sequence + + + +
+
+ + + + + +
Logo Notification Messages
+ and Sequence
+ + + + +

Purpose

+

Several questions from developers using the OpenZWave library + have suggested confusion about the meaning of notifications sent by the + library. This document is intended to + clarify and document the notifications sent by the library and to indicate what + information is “known” at the time the notifications are sent. This will, hopefully, assist developers in + designing the actions to take upon receipt of each notification.
+
+

+ + + + +

Format

+

The table + presented below lists notifications in the order they might typically be + received, and grouped into a few logically related categories.  Of course, given the variety of ZWave controllers, devices and network configurations the + actual sequence will vary (somewhat).  The descriptions below the notification name (in square brackets) + identify whether the notification is always sent (unless there’s a significant error in the network or software) or potentially sent during the execution + sequence.
+
+
+

+ + + + +

Driver Initialization Notification

+

The notification below is sent when OpenZWave has successfully connected to a physical ZWave controller.
+
+

+ + + + + +
DriverReady
+ [always sent]		 Sent when the driver (representing a connection between OpenZWave and a Z-Wave controller attached to the specified serial (or HID) port) has been initialized.
+
+ At the time this notification is sent, only certain information about the controller itself is known: +
    +
  • Controller Z-Wave version
    • +
  • Network HomeID
    • +
  • Controller capabilities
    • +
  • Controller Application Version & Manufacturer/Product ID
    • +
  • Nodes included in the network
    +
    +
    • +
+ + + + +

Node Initialization Notifications

+

As OpenZWave starts, it identifies and reads information + about each node in the network. The + following notifications may be sent during the initialization process.
+
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NodeNew
+ [potentially + sent]		 Sent when + a new node has been identified as part of the Z-Wave network.  It is not sent if the node was identified + in a prior execution of the OpenZWave library and + stored in the zwcfg*.xml file.
+
+ At the + time this notification is sent, very little is known about the node + itself...only that it is new to OpenZWave. This message is sent once for each new node + identified.
  
NodeAdded
+ [always sent (for each node associated with the controller)]		Sent + when a node has been added to OpenZWave’s list of + nodes.  It can be triggered either as + the zwcfg*.xml file is being read, when a new node + is found on startup (see NodeNew notification + above), or if a new node is included in the network while OpenZWave is running.
+
+ As with NodeNew, very little is known about the node at the time + the notification is sent…just the fact that a new node has been identified + and its assigned NodeID.
  +
NodeProtocolInfo
+ [potentially sent]		Sent + after a node’s protocol information has been successfully read from the + controller.
+
+ At the time + this notification is sent, only certain information about the node is known:
+
    +
  • Whether it is a “listening” or “sleeping” device
    • +
  • Whether the node is capable of routing messages
    • +
  • Maximum baud rate for communication
    • +
  • Version number
    • +
  • Security byte
    • +
+
NodeNaming
+ [potentially sent]		Sent + when a node’s name has been set or changed (although it may be “set” to “” or + NULL).
ValueAdded
+ [potentially sent]		Sent + when a new value has been associated with the node.
+
+ At the time + this notification is sent, the new value may or may not have “live” data + associated with it. It may be + populated, but it may alternatively just be a placeholder for a value that + has not been read at the time the notification is sent. +
NodeQueriesComplete
+ [always + sent (for each node associated with the controller that has been successfully + queried)]		Sent + when a node’s values and attributes have been fully queried. + At the + time this notification is sent, the node’s information has been fully read at + least once.  So this notification might + trigger “full” display of the node’s information, values, etc. + If this + notification is not sent, it indicates that there has been a problem + initializing the device.  The most + common issue is that the node is a “sleeping” device.  The NodeQueriesComplete notification will be sent when the node wakes up and the query process + completes. +

+
+ + + + +

Initialization Complete Notifications

+

As + indicated above, when OpenZWave starts it reads + certain information from a file, from the controller and from the + network.  The following notifications + identify when this initialization/querying process is complete.
+
+

+ + + + + + + + +
AwakeNodesQueried
+ [always sent]		Sent + when all “listening”—always-on—devices have been queried successfully.  It also indicates, by implication, that + there are some “sleeping” nodes that will not complete their queries until + they wake up. + This + notification should be sent relatively quickly after start-up. (Of course, it depends on the number of + devices on the ZWave network and whether there are + any messages that “time out” without a proper response.)
AllNodesQueried
+ [potentially + sent]		Sent + when all nodes have been successfully queried. +

+ This notification + should be sent relatively quickly if there are no “sleeping” nodes. But it might be sent quite a while after + start-up if there are sleeping nodes and at least one of these nodes has a + long “wake-up” interval. +
+ + + + +

Other Notifications

+

In addition + to the notifications described above, which are primarily “initialization” + notifications that are sent during program start-up, the following + notifications may be sent as a result of user actions, external program + control, etc.
+
+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueChangedSent + when a value associated with a node has changed. + Receipt of + this notification indicates that it may be a good time to read the new value + and display or otherwise process it accordingly.
ValueRemovedSent + when a value associated with a node has been removed.
GroupSent + when a node’s group association has changed.
NodeRemovedSent + when a node has been removed from the ZWave network.
NodeEventSent + when a node sends a Basic_Set command to the + controller.  This + notification can be generated by certain sensors, for example, motion + detectors, to indicate that an event has been sensed.
PollingEnabledSent + when node/value polling has been enabled.
PollingDisabledSent + when node/value polling has been disabled.
DriverResetSent to + indicate when a controller has been reset.  This notification is intended to replace the potentially hundreds of + notifications representing each value and node removed from the network.
+
+ +
+ + diff --git a/docs/images+css/Doxywizard1.JPG b/docs/images+css/Doxywizard1.JPG new file mode 100644 index 00000000..89fc3e88 Binary files /dev/null and b/docs/images+css/Doxywizard1.JPG differ diff --git a/docs/images+css/Doxywizard2.JPG b/docs/images+css/Doxywizard2.JPG new file mode 100644 index 00000000..1c8473d4 Binary files /dev/null and b/docs/images+css/Doxywizard2.JPG differ diff --git a/docs/images+css/Doxywizard3.JPG b/docs/images+css/Doxywizard3.JPG new file mode 100644 index 00000000..87478b21 Binary files /dev/null and b/docs/images+css/Doxywizard3.JPG differ diff --git a/docs/images+css/Doxywizard4.JPG b/docs/images+css/Doxywizard4.JPG new file mode 100644 index 00000000..b29d7658 Binary files /dev/null and b/docs/images+css/Doxywizard4.JPG differ diff --git a/docs/images+css/Doxywizard5.JPG b/docs/images+css/Doxywizard5.JPG new file mode 100644 index 00000000..e7e06408 Binary files /dev/null and b/docs/images+css/Doxywizard5.JPG differ diff --git a/docs/images+css/OpenZWave.css b/docs/images+css/OpenZWave.css new file mode 100644 index 00000000..82472795 --- /dev/null +++ b/docs/images+css/OpenZWave.css @@ -0,0 +1,28 @@ + /* Font Definitions */ +.Heading1 { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 24pt; +} +.Heading2 { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 11pt; + font-weight: bold; +} +.BodyText { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 11pt; +} +.FooterText { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 7pt; +} + +.TableText { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 9pt; + padding: 5pt 5pt 5pt 5pt; +} +.TableBullet { + font-family: Verdana, Arial, Helvetica, sans-serif; + font-size: 9pt; +} diff --git a/docs/images+css/image003.gif b/docs/images+css/image003.gif new file mode 100644 index 00000000..aeea7cc5 Binary files /dev/null and b/docs/images+css/image003.gif differ