Wiring Editor

From HSYCO
Jump to navigation Jump to search

Manager Wiring Editor Icon.png

The Wiring Editor is a tool to create logical connections (wirings) between HSYCO's inputs and outputs. It can be used, for instance, to quickly and easily make a button turn on/off a light or control a dimmer or an automation or, again, activate a scenario. It provides for a set of functionalities which are often implemented in home automation installation without having to resort to complex programming.

The Wiring Editor is accessible from the Manager or by directly accessing the the "wiring" Project page.

Wiring Editor Interface.png

Inputs and Outputs

An input is something that triggers an event. It can be: a readable I/O Server's datapoint, a User event (e.g. an event triggered by a User button), a scheduler event or a group of inputs.

Inputs are divided into 2 categories:

Binary (0/1)
those whose value can be "0" or "1" (e.g. a button), generally used to activate/deactivate an output or a scenario
Level
those whose value correspond to a general numeric value (e.g. a sensor), used, for instance, to set an output to a specific level.

An inputs group corresponds to the logical "or" of the inputs belonging to the group; i.e. whenever an input belonging to a group triggers an event, the group will trigger an event with same value. Input groups can be used, for instance, to activate a light from two different buttons.

An output is something on which is possible to perform an action. It can be: a writable I/O Server's datapoint, a User event or a group of outputs.

Outputs are categorized as:

On/Off
they accept a value of "0" or "1". As an example, an On/Off output can be an I/O datapoint representing a light, but also a datapoint to arm/disarm an area of a security system
Dimmer
they are generally I/O datapoints to control a dimmable light; accept the values "on", "off" and levels values from "1%" to "100%"
Blind
they are generally I/O datapoints to control blind automations and accept the values "up", "down" and "stop".

An output group connects together a set of outputs. Writing a value to an output group will result in writing that value in all the members of the group. As we will see later, output groups are also used as a target for scenarios.

Default Configuration

When the Wiring Editor is first used, it will display a list of inputs and outputs corresponding to the datapoints of the configured I/O Servers. Generally speaking, whatever is commonly used as input or output will be listed in the respective column.

This table shows the I/O Servers for which inputs and outputs are automatically detected:

I/O Server Inputs Outputs
Domino all input datapoints all output datapoints
Contatto all input datapoints all output datapoints
MyHome light and automation datapoints
KNX all datapoints excluding virtual ones all datapoints including virtual datapoints
HwgIO all input datapoints all output datapoints
Dummy all datapoints

For Domino and Contatto I/O Servers make sure to set the “detectevents” option to "true" in their configuration. This allows for the name of the corresponding module to be displayed in the interface for each datapoint.

All inputs and outputs will have their names set to their datapoint ID and will have no value type defined. The first steps to do before creating wirings are: deleting from the lists all datapoints which will not be used here, adding any additional datapoint not originally included and assign a descriptive name and a value type to all inputs and outputs.

After the first time that an input or an output will be added or removed, HSYCO will no longer automatically update the respective list if, for instance, new I/O Servers are added.

Add a New Input/Output Datapoint

To add a new input or output I/O datapoint, click on the “+” button on the top of the corresponding column: a pop-up will show.

Select “IO Server datapoint” as type and insert the ID of the datapoint to be added, an user-friendly description and specify its value type. Press the “Add” button to add it to the list.

Edit or Remove an Input/Output

From the list, long-press on the item to be edited/removed until a pop-up shows up. To remove it click on the “Delete” button; to edit its name or value type, apply the changes and press "Save".

Create an Inputs/Outputs Group

To create a group click on the “+” button above the list: a pop-up will show. Select “Inputs group” as type, select the members of the group from the drop-down list, enter a name and click on “Add”.

Use a User Button as Input

To use a User button as input for the wiring editor, click on the “+” button on top of the inputs list: a pop-up will show. Select “User button” as type and enter the name parameter of the user button in the ID field.

If the long-press functionality of the button will be used (e.g. to dim a light or to move a blind automation while it is pressed) remember to set the “Repeat” attribute of the user button to “enabled” in the Project Editor.

Use a Scheduler as Input

It is possible to use a scheduler as input, for instance to have a scenario activated at a specific time every day. Click on the “+” button on top of the inputs list and select “Scheduler” as type.

Specify the ID of the scheduler to use, if the scheduler does not exist yet, just add a new ID that will be assigned to the scheduler. Enter a descriptive name and press on the “Add” button.

The new input will appear in the inputs list. To create or modify the scheduler’s rules, long-press on the item in the list until the edit pop-up will show. From here it is possible to change the descriptive name of the scheduler or, by clicking on the “Edit scheduler” link, access to the linked scheduler and modify it. Close the pop-up once done.

Generate a User Event as Output

It is possible to generate a user event as output for a wiring. This allows for the possibility to execute complex actions when the output is activated.

To this end, click on the “+” button on top of the outputs list: a pop-up will show. Select “User event” as type, input the ID of the event to be generated, assign it a name and specify the value type.

Whenever the output will be activated by a wiring a user event with the specified ID will be triggered and can thus be used in EVENTS, JavaScript or Java programming.

Wirings

A wiring represents a logical connection between one or more inputs and one output (which may be a group). It is mainly characterized by its output type, i.e. the value type of the output it acts on, based on which different functions are provided. The activation of a wiring occurs every time one of its inputs triggers an event and, depending on its function, will result in the modification of the output's status.

To create a wiring click on the button labelled as "I ↔ O" on top of the wirings column.

On/Off Wiring

This wiring acts on "On/Off" outputs and provides the following functions:

Toggle
to invert the value of the output when activating a single input. The option "on" specifies when to activate the wiring: if set to "1" or "0" the wiring will be activated when the input triggers an event with the specified value; if set to "change" the wiring will be activated at each input event
2-Ways
to control the output using 2 inputs: one for the "on" command and the other for the "off" command
Push-button
to control the output with a single input used as push-button: the output will be activated only when the input is active (e.g. while the button is kept pressed), the following options can be specified:
Delay: set the delay period, in seconds, after which the command is sent to the output. If the input is active for a period shorter than the delay, no command will be sent
Hold: set the maximum time, in seconds, after which the output is deactivated
Direct
to have the output follow the state of an input

Dimmer Wiring

This wiring acts on "Dimmer" outputs and provides the following functions:

Cycle
to control the dimmer with a single input: a short activation of the input (e.g. short press on a button) will send on/off commands, while a long one (e.g. keeping a button held down) will dim up or down
2-Ways
to control the dimmer using 2 binary inputs: one for the "on" command (short activation) and to dim up (long activation) and the other for the "off" command (short activation) and to dim down (long activation)
3-Ways
to control the dimmer using 3 binary inputs: one to dim up, one to dim down, and the last one to toggle the on/off commands
Level
to send a level command to the dimmer. It can be used to have the dimmer following the value of a level input or to set the dimmer to a fixed level when activating a binary input. The "ratio" option can be used to specify the multiplicative factor to apply to the value of the input. Use this option for adjustments between different scales or to set the fixed level if the wiring activation is triggered by a binary input

Blind Wiring

This wiring acts on "Blind" outputs and provides the following functions:

Cycle
to control the blind automation with a single binary input: a short activation of the input (e.g. short press on a button) will activate the blind (with direction up or down depending on the current position) and will keep the blind to roll until the end is reached or the input is activated again. Keeping the input active for longer than a second (e.g. keeping a button held down) will activate the blind until the input is released. If the "Manned" option is checked the output will be activated only while the input is active, i.e. to move a blind automation it will be required to keep the input button held down; the functionalities activated by short activations of the input will be disabled.
2-Ways
to control the blind using 2 inputs: one for the "up" command and the other for the "down" command. A short activation of the input will keep the blind to roll until the end is reached or the input is activated again, while keeping the input active for longer than a second will activate the blind until the input is released. As before, the "Manned" option disables the short-activation functions
3-Ways
to control the blind using 3 inputs: one to send the "up" command, one to send the "down" command, and the last one to stop the movement of the blind

Scenario Wiring

A scenario wiring is used to set an output (most likely an output group) to a pre-recorded state when an input is activated. Follow these steps to create a scenario:

  • Most probably you will want to create a scenario involving more than one device, thus we need to create a group with all the outputs we want to act on. It can be an heterogeneous group: its output members can have different value type. For instance a common “exit” scenario will act on all lights and blinds in the house. If you want to create a scenario involving only an output, ignore this step
  • Set the output(s) to the state you want to record. For instance, for the “exit” scenario, turn off all the lights and dimmers and close the blinds.
  • Create a scenario wiring by choosing the activating input and the target output. If a scheduler is selected as input, it is possible to select wether to activate the scenario when the scheduler is activated (On) or when it is deactivated (Off). This is to ease the process of having two different scenarios associated to the same scheduler: one for its activation and one for its deactivation.

When the scenario wiring is created, the current status of the output(s) is recorded and displayed in a pop-up. To edit the recorded state of the output(s), access the edit panel of the wiring with a long-press and click on "Record" when the output(s) are set to the new wanted state.

Using the Interface

A click on any of the items in the three columns (inputs, outputs or wirings) will show all the elements connected to it. For instance, to see which wirings are acting on an output, click on the output itself: the wirings column will show only the wiring acting on it and the inputs column only the inputs activating those wirings. To reset the interface click on the output again.

Expert/Basic Mode

By default the wiring editor is set to “expert mode”, i.e. all the provided functionalities are enabled. It is possible to disable the possibility of adding, editing and deleting I/O datapoint inputs and outputs to avoid the risk of having the user acting on sensible datapoints. To this end, go to HSYCO's Settings > System > Extra and add the parameter "wiringExpertMode" and set its value to "false".

The user will still be allowed to create groups, but only from the already available inputs and outputs.

Backups

To create a backup of the current configuration click on the icon Wiring Editor Backup.png in the bottom-left corner: a pop-up will show. Click on the “Backup now” button then enter a name for backup to be created.

The backups list will show all the saved backups ordered by date.

To load a previously saved backup, click on the corresponding item in the list and give a confirmation.

Inputs/Outputs Configuration Files

To ease the process of filtering the input and output I/O datapoints to be listed in the wiring editor, it is possible to list the datapoints’ IDs in configuration files to be added in a folder named "wiring" located in the root folder of HSYCO:

whitelist.in.txt: list of the IDs of all the inputs to be added

whitelist.out.txt: list of the IDs of all the outputs to be added

blacklist.in.txt: list of the IDs of all the inputs not to be added

blacklist.out.txt: list of the IDs of all the outputs not to be added

The blacklist files are to be used to have the Wiring Editor list all inputs/outputs automatically detected except for the specified ones.

It is possible to have the whitelist files automatically filled with all the automatically discovered inputs and outputs. To this end just place an empty file in the "wiring" folder named “whitelist.in.txt” and/or “whitelist.out.txt”.

The changes made to these configuration files will only have effect on restart.

The blacklist files have higher priority w.r.t. the whitelist files, i.e. if an ID is listed in both files, the corresponding datapoint won’t appear in the wiring editor.