OZWNetwork manages the Z-Wave network by using the OpenZWave library (OZW). Its purpose is to handle OZW notifications and initiate OZW commands if needed. More...

#include <OZWNetwork.h>

Inheritance diagram for BeeeOn::OZWNetwork:

Data Structures
class	OZWNode
	OZWNode wraps the ZWaveNode to be able to hold specific data related to the OpenZWave library. More...

Public Member Functions
void	setConfigPath (const std::string &path)
	Set OZW configPath (contains definitions, XML files, etc.). The directory should exist prior to calling OZWNetwork::configure(). More...

void	setUserPath (const std::string &path)
	Set OZW userPath (cache of device definitions). This directory would be created if it does not exist. More...

void	setPollInterval (const Poco::Timespan &interval)
	Set OZW PollInterval option.

void	setIntervalBetweenPolls (bool enable)
	Set OZW IntervalBetweenPolls option.

void	setRetryTimeout (const Poco::Timespan &timeout)
	Set OZW RetryTimeout option.

void	setAssumeAwake (bool awake)
	Set OZW AssumeAwake option.

void	setDriverMaxAttempts (int attempts)
	Set OZW DriverMaxAttempts option.

void	setNetworkKey (const std::list< std::string > &bytes)
	Set OZW NetworkKey option. The key is expected to be 16 bytes long.

void	setStatisticsInterval (const Poco::Timespan &interval)
	Set the interval of reporting OZW statistics.

void	setControllersToReset (const std::list< std::string > &homes)
	Set controllers (list of home IDs) to be reset upon their first appearance in the network.

void	setExecutor (AsyncExecutor::Ptr executor)
	Set asynchronous executor used for asynchronous tasks and events reporting.

void	registerListener (ZWaveListener::Ptr listener)
	Register a ZWaveListener that would be receiving events.

void	onNotification (const OpenZWave::Notification *n)
	Handle incoming OZW notifications in the context of the OZWNetwork instance.

void	onAdd (const HotplugEvent &event) override
	If the event represents a compatible Z-Wave dongle, an appropriate driver is added into the OZW runtime.

void	onRemove (const HotplugEvent &event) override
	If the event represents a compatible Z-Wave dongle, the appropriate driver is removed from the OZW runtime.

void	configure ()
	Initialize OZW library, set options and register self as a watcher for handling notifications. The statistics reporter is started.

void	cleanup ()
	Deinitialize OZW library. Stop the statistics reporter.

Public Member Functions inherited from BeeeOn::HotplugListener
virtual void	onChange (const HotplugEvent &event)

virtual void	onMove (const HotplugEvent &event)

Public Member Functions inherited from BeeeOn::AbstractZWaveNetwork
PollEvent	pollEvent (const Poco::Timespan &timeout) override

Protected Member Functions
void	checkDirectory (const Poco::Path &path)
	Check that the given directory exists and is readable. More...

void	prepareDirectory (const Poco::Path &path)
	Create the directory represented by the given path. If it already exists, it must be writable and readable.

void	fireStatistics ()
	Fire Z-Wave statistics. This is called periodically by the m_statisticsRunner. More...

bool	ignoreNotification (const OpenZWave::Notification *n) const
	Certain notifications coming from OZW are to be ignored because they are uninteresting or known to screw up certain things. This call filters all such notifications.

void	resetController (const uint32_t home)
	Initiate asynchronous reset of controller associated with the given home ID. More...

void	driverReady (const OpenZWave::Notification *n)
	Called when the OZW driver becomes ready to work for the given home ID. The OZWNetwork installs the home ID and if configured, it performs reset of the associated controller.

void	driverFailed (const OpenZWave::Notification *n)
	Called when OZW driver fails to become ready. The associated home ID is uninstalled.

void	driverRemoved (const OpenZWave::Notification *n)
	Called when OZW driver is removed from the system. More...

bool	checkNodeIsController (const uint32_t home, const uint8_t node) const
	Find out whether the given node ID represents a controller of the given home.

void	nodeNew (const OpenZWave::Notification *n)
	Called when the OZW discovered a new Z-Wave node.

void	nodeAdded (const OpenZWave::Notification *n)
	Called when the OZW added a Z-Wave node to its list. More...

void	nodeNaming (const OpenZWave::Notification *n)
	Called when OZW resolves more details about a Z-Wave node. More...

void	nodeProtocolInfo (const OpenZWave::Notification *n)
	Called when OZW resolves properties of a Z-Wave node. More...

void	nodeReady (const OpenZWave::Notification *n)
	Called when OZW believes that the given Z-Wave node is ready for standard operations. More...

void	nodeRemoved (const OpenZWave::Notification *n)
	Called when OZW assumes that a Z-Wave node was removed from the network and thus is unreachable. More...

void	valueAdded (const OpenZWave::Notification *n)
	Called when OZW discoveres a new value associated with a certain Z-Wave node. More...

void	valueChanged (const OpenZWave::Notification *n)
	Called when OZW received data associated with a Z-Wave node's value. Such data are processed by the upper layers. More...

void	nodeQueried (const OpenZWave::Notification *n)
	Called when OZW finishes discovering of a Z-Wave node. At this moment, we are sure to know all dynamic information about the node (including values definitions). More...

void	awakeNodesQueried (const OpenZWave::Notification *n)
	Called when OZW believes that all awaken node have been queried fully. Here we analyze some stats about nodes (queried, failed, total, etc.). More...

void	allNodesQueried (const OpenZWave::Notification *n)
	Called when OZW believes that all nodes have been queried fully. This call is similar to awakeNodesQueried(). We perform some statistics collection and update certain nodes if needed. More...

void	startInclusion () override
	Start the inclusion mode on the primary controller(s). More...

void	cancelInclusion () override
	Cancel the inclusion mode if active. More...

void	startRemoveNode () override
	Start the removal mode on the primary controller(s). More...

void	cancelRemoveNode () override
	Cancel the removal mode if active. More...

void	interrupt () override
	Cancel the current OZW command and interrupt an active pollEvent() call.

void	postValue (const ZWaveNode::Value &value) override
	Post the given value into the Z-Wave network. The call is non-blocking and there is no direct feedback about a successful progress. It is possible to check successful change by watching polling for events. More...

std::string	valueForList (const OpenZWave::ValueID &valueID, const int value)

Protected Member Functions inherited from BeeeOn::AbstractZWaveNetwork
void	notifyEvent (const PollEvent &event)

Protected Member Functions inherited from BeeeOn::Loggable
void	setupLogger (Poco::Logger *logger=0) const

Poco::Logger &	logger () const

	Loggable (const ClassInfo &info)

	Loggable (const std::type_info &info)

Static Protected Member Functions
static bool	matchEvent (const HotplugEvent &event)
	Determine hotplugged devices compatible with the OZWNetwork. The property tty.BEEEON_DONGLE is tested to equal to "zwave".

static void	ozwNotification (OpenZWave::Notification const n, void context)

static std::string	homeAsString (uint32_t home)
	Helper method to print the home ID.

static ZWaveNode::CommandClass	buildCommandClass (const OpenZWave::ValueID &id)
	Helper method to build a CommandClass instance directly from the OZW ValueID instance.

Static Protected Member Functions inherited from BeeeOn::Loggable
static Poco::Logger &	forMethod (const char *name)

static Poco::Logger &	forClass (const ClassInfo &info)

static Poco::Logger &	forClass (const std::type_info &info)

template<typename T >
static Poco::Logger &	forInstance (const T *i)

static void	configureSimple (Poco::Logger &logger, const std::string &level)

static void	logException (Poco::Logger &logger, const Poco::Message::Priority priority, const Poco::Exception &e, const char *file, size_t line)

Friends
class	OZWCommand

Additional Inherited Members
Public Types inherited from BeeeOn::HotplugListener
typedef Poco::SharedPtr < HotplugListener >	Ptr

Public Types inherited from BeeeOn::ZWaveNetwork
typedef Poco::SharedPtr < ZWaveNetwork >	Ptr

Detailed Description

OZWNetwork manages the Z-Wave network by using the OpenZWave library (OZW). Its purpose is to handle OZW notifications and initiate OZW commands if needed.

The OZW library has multiple configuration options. Some are set internally to some sane values (unimportant for the BeeeOn gateway), others can be changed by OZWNetwork properties.

To initialize, the OZWNetwork::configure() is to be used. The method is called automatically by DI. The deinitialization is implemented via OZWNetwork::cleanup() (also called by DI).

The OZWNetwork is able to handle multiple Z-Wave dongles (according to OZW). It assigns dongles via the hotplug mechanism. It recognizes dongles with property tty.BEEEON_DONGLE == "zwave". Currently, only dongles connected via tty are supported.

Everytime when a Z-Wave dongle is detected via OZWNetwork::onAdd(), the OZW library is notified and starts a thread for the driver. Drivers are removed on hot-unplug via OZWNetwork::onRemove() or when the OZWNetwork::cleanup() is called.

The OZWNetwork utilizes AsyncExecutor for performing asynchronous tasks that must not be performed from the OZW notification handler function.

Member Function Documentation

void OZWNetwork::allNodesQueried ( const OpenZWave::Notification * n )

protected

Called when OZW believes that all nodes have been queried fully. This call is similar to awakeNodesQueried(). We perform some statistics collection and update certain nodes if needed.

All nodes marked as non-queried that are not failing are updated and the event EVENT_UPDATE_NODE is emitted to upper layers.

Finally, the EVENT_READY will be delivered to upper layers.

See Also: ZWaveNode::setQueried(); ZWaveNetwork::pollEvent(); PollEvent::EVENT_UPDATE_NODE; PollEvent::EVENT_READY

void OZWNetwork::awakeNodesQueried ( const OpenZWave::Notification * n )

protected

Called when OZW believes that all awaken node have been queried fully. Here we analyze some stats about nodes (queried, failed, total, etc.).

All nodes of the associated home ID are checked whether they are awake. The awake nodes marked as not-queried are updated and the event EVENT_UPDATE_NODE is emitted to upper layers.

Finally, the EVENT_READY will be delivered to upper layers.

See Also: ZWaveNode::setQueried(); ZWaveNetwork::pollEvent(); PollEvent::EVENT_UPDATE_NODE; PollEvent::EVENT_READY

void OZWNetwork::cancelInclusion ( )

overrideprotectedvirtual

Cancel the inclusion mode if active.

See Also: OZWCommand::cancelIf()

Implements BeeeOn::ZWaveNetwork.

void OZWNetwork::cancelRemoveNode ( )

overrideprotectedvirtual

Cancel the removal mode if active.

See Also: OZWCommand::cancelIf()

Implements BeeeOn::ZWaveNetwork.

void OZWNetwork::checkDirectory ( const Poco::Path & path )

protected

Check that the given directory exists and is readable.

Exceptions

FileAccessDeniedException if the directory is not readable

void OZWNetwork::driverRemoved ( const OpenZWave::Notification * n )

protected

Called when OZW driver is removed from the system.

This happens usually when a Z-Wave dongle is removed or its controller is being reset.

void OZWNetwork::fireStatistics ( )

protected

Fire Z-Wave statistics. This is called periodically by the m_statisticsRunner.

See Also: OZWNetwork::setExecutor(); OZWNetwork::registerListener(); OZWNetwork::setStatisticsInterval()

void OZWNetwork::nodeAdded ( const OpenZWave::Notification * n )

protected

Called when the OZW added a Z-Wave node to its list.

An instance of ZWaveNode is maintained for every such node. At this stage we might have not enough information about that node.

void OZWNetwork::nodeNaming ( const OpenZWave::Notification * n )

protected

Called when OZW resolves more details about a Z-Wave node.

At this stage, we know identification details about the Z-Wave node. Such information are maintained in the associated ZWaveNode instance.

See Also: ZWaveNode::setProductId(); ZWaveNode::setProduct(); ZWaveNode::setProductType(); ZWaveNode::setVendorId(); ZWaveNode::setVendor()

void OZWNetwork::nodeProtocolInfo ( const OpenZWave::Notification * n )

protected

Called when OZW resolves properties of a Z-Wave node.

After this call, the associated ZWaveNode instance would have information about the features supported by that Z-Wave node.

See Also: ZWaveNode::setSupport()

void OZWNetwork::nodeQueried ( const OpenZWave::Notification * n )

protected

Called when OZW finishes discovering of a Z-Wave node. At this moment, we are sure to know all dynamic information about the node (including values definitions).

The event EVENT_UPDATE_NODE will be delivered to upper layers having updated information about a node. The associated ZWaveNode instance is marked to be queried by this call.

The OZW persistent configuration cache is written here.

See Also: ZWaveNode::setQueried(); ZWaveNetwork::pollEvent(); PollEvent::EVENT_UPDATE_NODE

void OZWNetwork::nodeReady ( const OpenZWave::Notification * n )

protected

Called when OZW believes that the given Z-Wave node is ready for standard operations.

The event EVENT_NEW_NODE will be delivered to upper layers having information about a new available node for further work.

Note that, the Z-Wave node might not be discovered fully at this stage. However, ig the node is already known by the upper layers, the node can be directly used without waiting for more details which might take quite a long time.

See Also: ZWaveNetwork::pollEvent(); PollEvent::EVENT_NEW_NODE

void OZWNetwork::nodeRemoved ( const OpenZWave::Notification * n )

protected

Called when OZW assumes that a Z-Wave node was removed from the network and thus is unreachable.

The event EVENT_REMOVE_NODE will be delivered to upper layers with information the node removal.

The OZW persistent configuration cache is written here.

See Also: ZWaveNetwork::pollEvent(); PollEvent::EVENT_REMOVE_NODE

void OZWNetwork::ozwNotification	(	OpenZWave::Notification const *	n,
		void *	context
	)

staticprotected

The OpenZWave library uses a notification loop to provide information about the Z-Wave network. A notification represents e.g. detection of a new device, change of a value, Z-Wave dongle initialization, etc.

void OZWNetwork::postValue ( const ZWaveNode::Value & value )

overrideprotectedvirtual

Post the given value into the Z-Wave network. The call is non-blocking and there is no direct feedback about a successful progress. It is possible to check successful change by watching polling for events.

Exceptions

Poco::NotFoundException	- when home or node are not registered
Poco::NotFoundException	- when the command class is not registered with the node
Poco::InvalidArgumentException	- when value cannot be set or is invalid
Poco::NotImplementedException	- for unsupported value types

Implements BeeeOn::ZWaveNetwork.

void OZWNetwork::resetController ( const uint32_t home )

protected

Initiate asynchronous reset of controller associated with the given home ID.

The controller reset is invoked via the m_executor instance. During the reset procedure, the driverRemoved() would be called for the given home ID.

void OZWNetwork::setConfigPath ( const std::string & path )

Set OZW configPath (contains definitions, XML files, etc.). The directory should exist prior to calling OZWNetwork::configure().