Z-Way Home Automation User Interface Documentation

Chapter 1: The Z-Way HA User Manual

You can access the User Interface 'z-way-ha' using the URL:

http://YOURIP:8083/z-way-ha

The following sections describe the 'Z-Way-HA' from the user's point of view. The Z-Way-HA User Interface is an AJAX-based user interface available for web browsers. At the moment, it supports Google Chrome, Firefox, and Apple Safari only, but not Microsoft Internet Explorer.

The functions of the Z-Way-HA UI are:

• Show all device functions of the Z-Way based Smart Home systems as widgets.
• Allow to activate and manage automation modules that make use of the widgets and may generate new widgets.

The User Interface offers four function groups:

• Dashboard: Important widgets are shown in the dashboard. The section 'widgets' in the 'Preferences' allows defining what widget is shown in the Dashboard.
• Widgets: The widget section allows access to all widgets of the Home Automation System. They are grouped by 'Rooms', 'Type', and 'Tags'. The 'Preferences' allow managing rooms, types, and widgets, and assigning certain widgets to these groups.
• Notifications: Clicking on the notifications button opens a dialog showing all notifications generated by the system and the modules. Notifications will stay in this list until they are individually confirmed.
• Preferences: The preferences tab opens a dialog with different setup options.
  • General: Allows setup and management of profiles.
  • Rooms: Allows setup and management of rooms.
  • Widgets: Allows managing widgets.
  • Automation: Allows managing the modules of the Javascript based automation engine.

1.1 Widgets

The widget section allows managing all widgets that are automatically created from devices included into the Z-Wave or Third-party Wireless Control System, plus widgets generated from Automation Modules.

A widget does not necessarily represent a physical device but a function of a device. This means that one single device can create multiple widgets. For Z-Wave devices, every function (switch, battery, sensor value) and every channel in a multichannel environment generates a widget. The widget is not technology dependent, but the initial name and the unique ID of the generated widget refer to the attributes of the physical device. The pattern for the ID is:

ZWayVDev_[Node ID]:[Instance ID]:[Command Class ID]:[Scale ID]

The Node ID refers to the node ID of the physical device corresponding to this widget. The instance is the instance or zero in case there are no multiple instances. The command class ID refers to the command class that generated the function of the widget. Some command classes offer multiple sensor values differentiated by their scale ID (e.g., Celsius or Fahrenheit). For command classes without multiple scales (e.g., battery value), this value is always zero.

The line below the main menu offers three options for grouping the widgets:

• By Room: The UI can define rooms, and in the room definitions, widgets can be assigned to rooms. Each widget can be assigned only to one room. The line below shows all rooms currently defined. Clicking on a room shows all widgets assigned to that room. To manage rooms, refer to the Preferences section.
• By Type: All Widgets belong to one specific type. At the moment, the following types are defined and supported by the Z-Way-HA UI:
  • sensorBinary: A binary sensor, only showing on or off.
  • sensorMultilevel: The type, the value, and the scale of the sensor are shown.
  • switchBinary: The device can be switched on and off.
  • switchMultilevel: The device can be switched on and off plus set to any percentage level between 0% and 100%.
  • switchRGBW: This device allows setting RGB colors.
  • switchControl:
  • toggleButton: The device can only be turned on. This is for scene activation.
  • thermostat: The thermostat shows the setpoint temperature plus a dropdown list of thermostat modes, if available.
  • battery: The battery widget shows the percentage of charging capacity left.
  • camera: A camera will show the image and can be operated.
  • fan: A fan can be turned on and off.
• By Tag: The system allows generating user-defined tags and assigning these tags to widgets. The only predefined tag is 'dashboard', used to select all widgets shown in the dashboard. The line below shows all tags currently defined. Clicking on tags shows all widgets assigned where that tag is assigned. Tags can be freely defined when managing a certain widget.

The line below shows all types where devices exist. Device types cannot be managed on the UI but will be shown automatically when new widgets are generated.

1.2 Notifications

Left beside the Notification button, the number of notifications is shown. Clicking on the string 'Notification' opens a dialog box with the notification string. Notifications are generated by the system (error message) or by application modules. 'Hide' deletes the message.

1.3 Preferences

Clicking on 'Preferences' opens a dialog with four sub-menus, as shown in Figure 1.1. On the upper side, there is an '❌' to close the dialog. Once a sub-menu is opened, on the upper left side, the '◀️' returns to the sub-menu overview.

1.3.1 General

The dialog shows different profiles. At the moment, there are no further options and actions available except naming the profiles and giving them a Name.

On the lower left corner, there are a '➖' and a '➕'. Clicking on the '➕' adds a new profile; '➖' deletes the profile highlighted on the left-hand side. A filter can be applied to find certain profiles.

On factory default, only the 'default' profile is available.

1.3.2 Rooms

The dialog 'Rooms' offers four submenus. On the lower left corner, there are a '➖' and a '➕'. Clicking on the '➕' adds a new room; '➖' deletes the room highlighted on the left-hand side. A filter can be applied to find certain rooms.

General: Clicking on the 'Edit'-Button allows editing the Room setup. The name can be chosen by the user. Clicking on the icon image opens a file chooser dialog to pick a new icon. Clicking on the device button opens a new dialog where devices can be assigned to this room. The left-hand side shows the available devices (not assigned to any room). Picking the device is done by 'drag and drop'. Devices on the right-hand side are assigned to the room.

Temperature Preference: This dialog is not used at the moment.

Auto Mode: This dialog is not used at the moment.

Devices: This is a shortcut to the device assignment dialog, also accessible in the 'General' sub-menu.

1.3.3 Widgets

The widgets menu allows managing the widgets generated by the Home Automation system. All widgets are listed with their names on the left-hand side. A filter can be applied to find certain widgets.

The name of the widget is auto-generated by the system but can be changed. The ID of the widget is unique and shown below the name entry. The device type is shown.

The tag section allows adding new tags defined by the user. Defined tags are listed and can be deleted by clicking on the 'x' symbol.

A checkbox defines if the widget is shown on the dashboard.

1.3.4 Automation

This section allows managing the automation modules of the Automation system. On the left-hand side, there is a list of all defined module instances. Refer to the automation section ?? for the relationship between module definitions and instances of modules.

On the lower left corner, there are a '➖' and a '➕'. Clicking on the '➕' adds a new module instance; '➖' deletes the module instance highlighted on the left-hand side. A filter can be applied to find certain module instances.

Clicking on the module instance name or the '➕' button opens a dialog menu on the right-hand side. When a new module instance is created, the first option is to pick one of the available modules.

The list of modules consists of a set of modules that are part of the system's scope of delivery. Additionally, the list will show all modules defined by the users.

All setups of modules consist of a module-specific part (upper part) and a generic part (lower part), that allows to:

• Define a name.
• Define a description of the instance.
• Enable or disable the module.

Important predefined modules are:

• Bind Devices: This module implements the association function known from Z-Wave. Compared to the Associations in Z-Wave that are stored in the devices, the bind function settings are stored in the gateway but can bind devices of different wireless technologies or widgets created.
• Load custom JS Code: This allows activating an own piece of Javascript.
• Load custom JS File: This allows activating an own piece of Javascript loaded from a file.
• Group devices: Groups several devices together and adds a new widget.
• Sensor Polling: Z-Way itself will not poll devices but relies on unsolicited status updates to keep the UI information updated. Certain sensor values should be updated periodically. If different sensors need to be polled in different intervals (e.g., meter less frequently than actual power draw), multiple instances of the modules need to be defined.
• Sensors Values Logging: This module allows reporting sensor values to a cloud service. The values are either written into a JSON file or sent over the Internet. In this case, a receiving URL can be defined.
• Trap events from Remote And Sensors: Generates new widgets on the fly for Remote Switch Controls and other devices sending control commands to the controller.

Other modules include:

• Always On: Keeps a device on regardless of switching command.
• Auto Off: Turns off a device after a defined time.
• BatteryPolling: Polls all battery devices for charging level.
• Camera: Controls an IP camera.
• LightScene: Defines light scenes.
• NotificationSMSru: Allows sending SMS notifications.
• OpenRemoteHelpers: Adapts to the solution from openremote.org.
• OpenWeather: Polls weather data from the Internet.
• RGB: Creates an RGB device based on three different dimmers.
• RoundRobinScenes: Activates scenes in Round Robin.
• SecurityNotifications: Notifies on changes of sensors and switches state.
• SwitchControlGenerator: Generates new widgets on the fly for Remote Switch Controls and other devices sending control commands to the controller.
• ZWaveGate: Creates virtual devices from Z-Wave Devices.

1.4 Dashboard

The dashboard shows all widgets selected as 'in dashboard' in the widget dialog of the Preferences section.