I don’t see a problem using a specific binding in the User’s Guide. It is one of the more popular bindings (based on the number of threads I see here). However, ideally I think it would be best to choose a binding that doesn’t require special hardware for the tutorial. Users who do not have hardware yet, or have chosen some other type of hardware may be put off if the tutorial is mainly focused on zwave. It also makes it difficult for users to follow along with the tutorial with their own setup.
However, I also see that there will be some parts of the tutorial (e.g. automatic discovery) that may not be possible with a non-hardware required binding.
Also, the more I think about it the more I think that using a defined Demo config as the main (not necessarily only) example that is discussed throughout the tutorial will:
- help us ensure that the Demo example is complete
- provide a point of reference for the reader to refer to as they go through the tutorial, particularly given that very few will likely read the whole thing in order
- help guide us as we write the tutorial
- give new comers a relatively complete and fully described and explained integrated example to build upon
If we were to do that I think the table of contents could look something like this:
1 Introduction
1.1 What is openHAB 2?
* Origin and History
* Dependence on ESH
* Differences between OH 1 and OH 2 (very high level, not technical)
1.2 Architecture (maybe not here, maybe later)
* event driven
* message bus
* device abstraction
* initial framework to refer back to in rest of the tutorial
* Drawings! Visual map of the architecture which we can repeat with certain parts highlighted in
later sections to help those who are more visual than textual learners
1.3 Basic Concepts (may be better as 1.2.1?)
* Bindings and Addons
* Things and Items
* Sitemap
* Rules and Scripting
* Persistence
* NOTE: This section should be high level and the emphasis is to be on what they are for, what
they do, and how they work together, details go in Chapter 3. This is the introduction, it should
help orient but not yet bury the reader with detail.
1.4 Introduction to the Demo Config
* Paragraph or so explaining what the Demo config is for
NOTE: The rest of the sections need to be written with the assumption that this section has not been
read. Therefore the main focus here is to orient the user, not actually tell them how to do anything yet
2 Installation and Configuration
2.1 Prerequisites
* Oracle Java
* Hardware: RAM, CPU, etc.
2.2 Installation
* Include paragraph describing the two flavors of OH 2, offline and online
* How to install bindings for online mode (offline to be included in sections below)
2.2.1 Debian Linux (raspbian, Ubuntu, Mint, et al)
* apt-get install
* list of important files and folders locations
* paragraph about the fact that it is running under user openhab:openhab and potential problems
(e.g. needs to be added to dialout group or gpio group, issues with exec binding, etc). Not too
detailed or specific, just a taste.
* manually installing bindings
2.2.2 Linux Manual Install
* tar -xvf ...
* list of important files and folders locations
* how to set it up to start as a service
* optional additional steps the user may want to take (e.g. create openhab user, adding to
groups, etc)
* manually installing bindings
2.2.3 OS X
2.2.4 Windows
2.2.5 Designer Installation (if procedures are different per OS, move this section to 2.2.1,
2.2.2, 2.2.3, and 2.2.4)
2.3 openHAB 2 Configuration
* Location of config files
* OH settings (e.g. polling periods, security, etc)
* Logging settings
* Ports and how to change them
3 Working with openHAB 2
3.1 The Demo Config
* Where to get it
* Its structure and purpose
* A brief description of what it does (lighting, hvac, alarm sensors, etc)
* What bindings are required to run the demo
3.2 Using Designer
* Load a config
* Dealing with headless servers (SAMBA, etc)
* Navigating in Designer
* Important key combos (e.g. `<ctrl><space>, <ctrl><s>`, etc)
3.3 Adding and Configuring Things and Items
* syntax
* how to organize into multiple files
* naming schemes
* breakdown of the parts of an Item definition with full discussion of each part (labels
with %s syntax for state, dynamic icons, multiple bindings, the different Item types,
the different states, discussion about how, for example, a Color Item can receive
ON/OFF or Dimmer states and the implication of that). Where possible pull in (if it
can be done so automatically through Jekyll) or reference the documentation hosted
on ESH to avoid too much duplication of documentation.
* the concept of proxy Items
* manual verses auto-discovered
* Groups, when and why
* examples from the Demo with explanation (include at least a proxy item, a single
binding, an Item with multiple bindings, dynamic icons, etc) showing all the discussed
concepts together
3.4 Sitemaps
* syntax
* elements
* nesting
* dynamic
* override label and icon defined on Item, when you would want to do this and when you wouldn't
* advantages/disadvantages of using Groups on the sitemap
* webviews
* charts
* etc.
* examples from the demo of each of the above with explanation
3.5 Persistence
* What is it good for
* Format of configuration
* How to use Groups to make setting up persistence easier
* example from the Demo
* discussion of multi-tiered persistence (e.g. use MapDB for all Items for restoreOnStartup,
rrd4j for numerical Items that need to be charted and/or get access to recent historical data,
use MySQL for Items that need to be analyzed or you need more configurable charts)
3.6 Rules and Scripts
3.6.1 Rules DSL
* Event based, not state based
* Multi-threaded and implications of that
* Link Xtext syntax documentation with an explanation for where the Rules DSL is different
(e.g. no arrays, no classes, etc.)
* Rules syntax, naming rules, triggers, etc.
* Examples from the Demo
* Design Patterns (discussion, link to 4 for examples)
* Timers verses Thread::sleep
* locking
* lambdas (in the context of Timers and forEach, global lambdas probably goes in the
advanced guide), the main point is that the Timer lambda has a full copy of the rule's
context and you cannot use a var inside a forEach lambda.
* examples from the Demo with explanation (Theory of Operation)
* Actions discussion with discussion of built in actions
* Organizing rules files
* What needs to be imported? How to find it?
* How to use Java within the DSL? How to learn the syntax and apply Java examples
* Working with Numbers, BigDecimal, and primitives and doing math, how to round and
truncate floating point numbers
* Working with DateTime, now, and DateTimeItem
* Store as much state as possible in Items
* If your rules get too complex or ugly, consider a change in approach of a different engine
3.6.2 JSR233 Jython
* Same as 3.6.1 except for Jython
* advantages/disadvantages
3.6.3 JSR 233 JavaScript
* Same as 3.6.2
3.6.4 Debugging
* logging statements in rules
* which logs have what info
* how to turn on/off debug or trace logging
* how to interpret exceptions
* troubleshooting workflow (is the binding installed and running -> is the rule triggering ->
what line is failing, if trouble shooting a binding, move as much as possible into a rule to
get more feedback, etc)
* common problems and solutions
* How to ask for help on the forum: describe what you want OH to do, how you are trying to do
it, post Items, Rules, Sitemap, and Logs, and use the forum's code formatting feature when
posting code.
4 Examples
4.1 Design Patterns
* Proxy Items
* Loop and Group
* Time of Day/Year Tracking
4.2 Lighting Examples
4.3 HVAC Examples
4.4 Irrigation Examples
4.5 Alarm Examples
...
* Examples should take on a standardized form and include - all Items, rules, sitemap, and
persistence and bindings where applicable. There should be a description of what the example
does, the actual code, and then a Theory of Operation section which walks through the example's
event flow in English.
* There should be examples from all of the different rules engines that are built into OH 2, not just
the Rules DSL
* Maybe examples should be completely separate
* If possible at a minimum the Design Pattern examples should also be incorporated into the Demo
Notes:
-
Much of the bullet points above come from my experience with OH 1. Ignore anything that doesn’t make sense for OH 2 and add anything I missed.
-
Persistence in the OH 1 documentation often gets ignored. I myself put off looking at it until long after I got my first working environment. I think this is a problem and want to make sure we treat persistence as a first class citizen on par with Rules and Sitemap.
-
I want to also make sure that we treat Designer as more than just optional. Section 3 should be presented with the assumption that the users are using Designer and include a section about how to use Designer.
-
We should continue to emphasize we are talking about OH 2 so probably should always add the two when referencing OH 2.
-
I’d move the installation of bindings up to the installation section
-
I do not think it is a bad thing to be opinionated about certain things when explaining “best practices”. For example, I think saying “you should break up your Items into multiple files and organize your files by function rather than location” is perfectly appropriate to put in the guide because even though it is an opinion, there are strong arguments for why it is a good idea and it gives new users a good standard to start with which they can then ignore when they become more experienced.
-
I think the JSR233 stuff deserves discussion in the tutorial as first approaches to rules writing
-
I’m open to moving many of the bullet points above to the advanced guide. Section 4 as well. The above is really just a brain dump.
-
There should be lots of links from the Tutorial to the advanced guide and reference documentation where applicable.