Help Drivers (BLI PRO)

A PRO BeoLiving Intelligence supports the most used Smart Home systems in the market. Here you will find BeoLiving Intelligence help and usage guides for some of them:

BTicino My Home

Connection

Connection to a BTicino My Home system is made via an Ethernet connection to a My Home Gateway interface. The available interfaces are the MH200N (that acts as a scenario programmer and SCS/LAN Gateway) and F454 (Audio/Video Web Server that also acts as an integration Gateway) BTcino products. It’s worth mentioning that:

  • The MH202 scenario programmer doesn’t work as a SCS/LAN Gateway.
  • BTicino presents his own Gateway as the F455 product, but as explained in his technical sheet it cannot be used as a development Gateway (SDK) for third-party Apps or as an integration Gateway (Vantage drivers, etc.); the Gateway F454 must be used). Both the IP address and the TCP port must be configured on BeoLiving Intelligence. Note that in order to establish a communication, BeoLiving Intelligence must reside in an allowed IP range defined in the My Home project.

Defining Resources

Integration between BeoLiving Intelligence and BTicino consist in interaction implemented via button presses and scenario selection, and two types of dimmer control. Therefore, New Bticino scene button, Bticino button, Bticino dimmer 100 level and Bticino dimmer 10 steps can be defined as resources.

Bticino dimmer 100 level support intensity sets between [0-100]. Bticino dimmer 10 steps only support intensity set between [0-100] by 10 steps level. In this case, a round is implemented in the LEVEL command. Selection between this two types of dimmer resource depends on the capabilites of the BTicino dimmer product to integrate with BeoLiving Intelligence.

There is also Bticino scene button which is deprecated and kept only for backward compatibility.

The address of a button resource is composed of the where part and the what part, separated by a comma.Where is the address of a module or group of devices, and what indicates a scenario or push button identification.

The address of a dimmer resource is the where based in point-to-point interaction, as area part and point of light part (<A><PL>).

Events and commands

Events and commands can be either scenario selection, CEN or dimmer LEVEL changes/sets.

For scenario selection New Bticino scene button resources must be defined (Bticino scene button which is now deprecated and only present for backward compatibility).

New Bticino scene button has PRESS event and command for scene selection.

Bticino button has PRESS, RELEASE, HOLD and HOLD RELEASE events and commands.

Bticino dimmer 10 steps and Bticino dimmer 100 level has LEVEL events and commands.

BeoLink

The BeoLink system provides interaction with NetworkLink products.

This system is included by default in BeoLiving Intelligence, and cannot be removed.

NetworkLink products are identified by their serial number. BeoLiving Intelligence will automatically add all available products to the table of NetworkLink products.

NetworkLink products generate LIGHT and CONTROL BeoLink events after reception of B&O remote control commands.

When an all product standby is performed on BeoLink, an event called ALL STANDBY is also generated on BeoLiving Intelligence. This event has no parameters.

CONTINUE and KEY_RELEASE functionality

Continue functionality refers to the way the products and terminals report a key-press being held for some seconds, i.e. not immediately released.

When a key is pressed and held, the products will report a key press event followed by a single CONTINUE event. When the key is released, a KEY_RELEASE event will be generated.

Several keys of B&O terminals support continuous key presses which are reported in different ways:

  • The 4 colour keys, STEP_UP, STEP_DOWN, WIND and REWIND each report a specific CONTINUE event (e.g. Continue STEP_UP).
  • Other keys send a generic CONTINUE event.
  • Other keys (such as digits) have no continue functionality.

You can use the monitoring tools in order to check for continue functionality on a specific key.

BeoLiving Intelligence will keep track of which was the original key-press that lead to a CONTINUE - KEY_RELEASE sequence, so that you may trigger different macros depending on which key was released.

This is done via the extra fields when defining a BeoLink event.

The typical usage is for a CONTINUE event to start a home-automation action like dimming the lights. The KEY_RELEASE will stop dimming.

For example, in order to execute a macro when the GO key is released, you should define a BeoLink event for the corresponding zone, and for the KEY_RELEASE event. Then choose to also match against the original command, and select GO from the original command list.

Commands to products can emulate terminal commands from Beo4/Beo5 or BeoRemote One.

The available options are:

  • All Standby
  • Cinema mode
  • Master volume adjust
  • Master volume level
  • Picture mute
  • Picture mode
  • Playqueue add Deezer playlist
  • Playqueue add TuneIn station
  • Playqueue add URL
  • Playqueue clean
  • Recall profile
  • Save profile
  • Select channel
  • Select source
  • Send command
  • Send digit
  • Sound mode
  • Speaker group
  • Stand position
  • Standby
  • Volume adjust
  • Volume level

All Standby has no parameters. This command will send all Masterlink and NetworkLink products into standby mode.

Master volume adjust and Master volume level enable controlling the volume of several products at once via Multiroom. The command is sent to a product and all the other products which are streaming from the same master change their volume the same way. Use Master volume adjust for relative control (step up or step down or mute) and Master volume level for absolute control.

Playqueue add Deezer playlist adds a Deezer playlist specified by Deezer playlist Id.

Playqueue add TuneIn station adds a TuneIn station specified by Station name or Station Id.

Playqueue add URL adds an auido file to the Playqueue specified by a URL.

Playqueue clean is self explanatory.

Recall profile activates an existing profile.

Save profile persists an existing profile.

Select channel is used to select a source and channel. If the source has a favourite list defined the delay between the channel digits is taken from it, otherwise a delay of 300 milliseconds is used.

Select source instructs a product to play a source via the multiroom feature. The source can be originated from another product.

Send command enables sending miscelaneous commands related to things like cursor control, menu acces, flow control, etc..

Send digit allows sending and individual digit to the product.

Speaker group allows selecting speaker groups.

Sound mode, Stand position, Picture mode, Picture mute and Cinema mode commands are self explanatory. The available options are product dependent so the product must be online in order to be able to see them. The command Stand position in particular is only available in products with a stand.

Standby is self exaplanatory.

Volume adjust permits to adjust volume relative to the current volume.

Volume level enables absolute volume control. The argument is an integer value from 0 to 90.

Pause between commands

Some products may fail to power up and immediately accept further commands (for example, a source selection followed by a program selection). This may also happen when controlling an external source such as a set-top box, which cannot handle a fast succession of commands.

In these cases, adding a small delay between commands will most likely solve the issue.

Cursor navigation vs. old Beo4 navigation

BeoLink products supporting Beo4 navigation button commands can be configured for using either the new commands (UP, DOWN, LEFT, RIGHT, SELECT and BACK), or the legacy alternatives (STEP_UP, STEP_DOWN, WIND, REWIND, PLAY and EXIT).

You should keep this in mind if constructing macros that simulate menu navigation.

Mobile applications also need to know in which of these modes the product is configured in order to send the right commands.

This configuration is done via the Interfaces screen on BeoLiving Intelligence. If the option is checked, BeoLiving Intelligence will tell the mobile application that the product is controlled via the Beo4 navigation button commands UP, DOWN, LEFT, RIGHT, SELECT and BACK. Otherwise it will instruct the mobile application to use the legacy commands.

Clipsal

The Clipsal programming model defines trigger groups and trigger actions as a way to call lighting scenes. Any scene defined by a trigger group/action pair can be called from BeoLiving Intelligence. Also dimmers and shades can be controlled knowing the corresponding application and group address numbers.

Clipsal resources

Resources correspond to trigger groups. Usually a trigger group is shared by a set of mutually exclusive scenes, each identified by a trigger action within the group.

So the address of Clipsal scene button resources is composed of two numbers, trigger group and action selector, separated by a comma.

For example, 3,6 identifies action selector 6 within trigger group 3.

For dimmers and shades the address is also composed by two numbers, but in this case they are application number and group address.

For example, 56,1 identifies the dimmer or shade with application number 56 (default for lighting) and group address 1.

There are three resource types for shades: Clipsal shade, Clipsal shade toggle and Clipsal shade GPIO. Clipsal shade can interact with a 3 button shutter relay, Clipsal shade toggle with a single button shutter relay and Clipsal shade GPIO with a two button shutter relay.

Conson XP

Connection to a Conson system is done via an XP130 gateway module. This module provides an RS485 interface, so either a RS232 to RS485 converter, or a compatible RS485 USB adapter are needed for connecting to BeoLiving Intelligence.

Conson resources

A resource on a Conson system is an input on a module. A module is identified by a module type plus a link number.

Therefore, the complete addressing for a resource is of the form module,link,input.

Events and commands

Changes on a module’s input generate an event on the Conson bus. This is signaled as a circuit make or break event on BeoLiving Intelligence.

Similarly, BeoLiving Intelligence can send circuit make, break, or pulse (make followed by break) to any input of a module.

Custom HTTP

Due to the common usage in Home Automation devices with a HTTP based REST interface, the Custom HTTP driver is intended to facilitate the integration with these equipments.

Connection

The Connection Settings has the next parameters:

  • Base url : Base URL of destination for each HTTP Request. For each resource that has an endpoint specified, the URL of the request is the concatenation of Base url + endpoint.
  • Headers (OPTIONAL) : Specify the Headers for each HTTP request made by the driver as JSON Object. Eg: {"Header1": "valueX", "Header2": "valueY"}. If this field is left empty the next headers are used by default: {"Accept": "*/*", "Content-Length": "${Length}","Host": "${Host URL}"}.
  • Poll url (OPTIONAL) : If this field is not empty, the driver makes a GET HTTP Request to the Poll url every 60 seconds. The driver state depends if the returned status code is 2XX Success or not. On the other hand, if this field is left empty, the driver state is determined by the last returned status code of a request made. In this case the driver state will be equal to Online if the returned status code is 2XX Success and Offline if not.

Resources

The driver presents 4 (_CUSTOM) resource types. Each one corresponds with a type of HTTP request:

  • GET
  • PUT
  • POST
  • DELETE

Each resource is composed by:

  • Name of the resource.
  • HTTP request type.
  • Address

Resource Address Format

The resource address has the next format ENDPOINT;PAYLOAD, which ENDPOINT will be used as the endpoint url (concatenated next to the Base url value) and PAYLOAD the payload data of the HTTP request. Both the ENDPOINT and PAYLOAD are OPTIONAL. If only PAYLOAD is specified, the usage of ; is MANDATORY. Usage of “;” (semi-colon) on ENDPOINT must be encoded as %3B.

Also, an EMPTY resource address is valid.

Resource address examples
  • /subpath;key=value
  • subpath1/subpath2;{"json": "example"}
  • subpath
  • ;data1=value1&data2=value2

Event and Command

The only COMMAND for each request is the _SEND command which executes the HTTP request.

The only EVENT for each request is the _RESPONSE event which represents the response status code obtained from the HTTP request executed.

Custom strings driver

The Custom strings driver is intended to enable limited communication with unsupported home automation systems.

Use of this driver requires knowledge of the protocol for the external system.

Resources

This driver is based on matching incoming byte strings from the external system, and sending byte strings back to it.

Therefore resources are actual generic strings which can be used used for matching against the incoming byte stream, and for sending to the external system.

There are 3 parameters to each resource:

  • Name of the resource.
  • Whether it should be listed for input matching (INPUT), for sending commands (OUTPUT), or for both (BOTH).
  • A generic character string.

In order to allow for arbitrary byte values, the following encoding is used:

  • Any character except for backslash (\) will be given it’s corresponding value. Non-ASCII (international) characters are interpreted as Unicode UTF-8 byte sequences.
  • Backslash is used as an escape character, which gives special meaning to the character or characters that follow:
    • \\ (double backslash) is interpreted as a single backslash.
    • \r is interpreted as a carriage return character (0x0D). It will be immediately redisplayed as \0D.
    • \n is interpreted as a newline character (0x0A). It will be immediately redisplayed as \0A.
    • \" is equivalent to a double quote ("). This notation is required for import/export of resources in text form.
    • \xx (where x is a hexadecimal digit [0-9, a-f, A-F]) is interpreted as a hexadecimal byte value. E.g. \0A is equivalent to \n.

Any non-printable or non ASCII character entered by the user will be redisplayed as a hexadecimal sequence. Illegal or truncated escape sequences will be marked as errors.

Events and commands

Resources marked for input (or both input + output) will be searched for in all incoming data. As soon as a match is found, the corresponding event will be generated and search will continue after the match.

For example, the input stream AAAB will match AA only once.

If the incoming channel becomes idle, then all partial matches will be discarded.

For example, the input stream 123 (pause) 4 will not match 1234.

Commands are all resources marked as output (or both input + output) and can be transmitted to the channel.

End of line sequence

Use this setting if the protocol messages are delimited by a fixed character sequence. Typical examples are line-oriented protocols which end each message with CR(0x0D) or LF(0x0A) characters.

If an end of line sequence is configured, then BeoLiving Intelligence will know how to split incoming data into complete messages, with the following effects:

  1. Matching of incoming messages now applies to the whole message. Matching part of a message is not possible.
  2. BeoLiving Intelligence now provides capture functionality. Complete messages can be captured and added as resources as with other drivers.
  3. The end of line sequence is automatically appended to all outgoing commands.

To illustrate the different behaviour when defining and end of line sequence, consider the following example:

Consider two resources of type “Custom event and command”:

  • resource A with address = 12
  • resource B with address = 345

When an incoming message 12345\n arrives with no end of line sequence defined, two events will be generated: one matching resource A and another matching resource B.

But, if end of line is set to \n, and the same incoming message arrives, no events will be generated since neither resource matches a complete message. Rather, a new resource will be offered on capture mode with address 12345.

TCP connection maintenance

Read this section if you experience periodic TCP reconnections.

In order to rapidly detect broken TCP connections, BeoLiving Intelligence uses the standard TCP Keepalive probes mechanism: when a TCP connection is idle, probe packets are sent periodically over the connection and an acknowledge is expected. The probe is an empty TCP packet with the request for acknowledge flag set.

This method for detecting active connections is specified in RFC-1122 section 4.2.3.6.

There are products with non-compliant TCP implementations which do not respond to these acknowledge requests. In such cases, HAGW will detect a broken TCP connection and reconnect. This may happen as frequent as every 20 seconds if there is no other data on the communication channel.

If you experience this problem, then you must somehow force some data to be sent back to HAGW periodically, so as to keep the channel active.

For example, you can use a clock event to send a status request to the 3rd party product periodically, or a ping/pong message. On command-line based protocols that echo all characters typed, probably sending a carriage return character is enough for getting characters back to BeoLiving Intelligence.

What to do strongly depends on the protocol of the external system.

DoorBird

BeoLiving Intelligence can interact with DoorBird and BirdGuard units, being capable of opening door lock, turning unit light and fire an event when motion sensor detect activity or doorbell button is pressed on the camera. In order to get video image on the BeoLiving Intelligence from the DoorBird unit, it’s necessary to add the camera on Interfaces Tab and fill the respective fields.

Note: SIP communication with DoorBird units are not yet supported.

Supported DoorBird Devices

  • DoorBird Video Door Station D10x
    • Hardware version 1.00 and above
    • Firmware Version 000098 and above
  • DoorBird Video Door Station D20x
    • Hardware version 1.00 and above
    • Firmware Version 000098 and above
  • BirdGuard B10x
    • Hardware version 1.00 and above
    • Firmware Version 000098 and above

Connection to DoorBird Unit

BeoLiving Intelligence can connect and interact with a DoorBird/BirdGuard unit through the DoorBird LAN-2-LAN API connection.

The Connection Settings parameters are:

  • Host Ip: IP address of DoorBird unit.
  • Login: Username of DoorBird unit.
  • Password: Password corresponded with the username used of DoorBird unit.

Available Resources

The available resources are:

  • OPEN_DOOR: Resource for open door lock. On BeoLiving Intelligence, this resource is mapped as BUTTON resource type. Has a PRESS command for open door lock.
  • LIGHT_ON: Resource for turn the light on of DoorBird unit.
  • MOTION_SENSOR: Resource that fire event when motion sensor on DoorBird unit detects activity.
  • DOORBELL: Resource that fire event when door bell button is pressed on DoorBird unit.

MONTION_SENSOR and DOORBELL are mapped as GPIO resource type on BeoLiving Intelligence. They have two state values {0,1}. Default state value is 0 (no motion detected or door bell pressed). When activity is notified in one of these resources, state changes to 1 and the to 0 (as a pulse). On these resources there is no command execution.

OPEN_DOOR and LIGHT_ON are mapped as BUTTON resource type on BeoLiving Intelligence. The unique command available is the PRESS command, which executes the corresponded action depending on the resource (opens the door or turn the light on).

Resource address doesn’t apply to any resource type. Leave resource address empty.

Get Live Image

In order to get live images from DoorBird unit, it’s necessary to add the camera in Interfaces Tab and set the next fields as below:

  • Camera access:

    • Base URL : Equal to http://<doorbird-ip>.
    • Username : Same username used on Connection Settings of DoorBird system in Systems Tab.
    • Password : Same password used on Connection Settings of DoorBird system in Systems Tab.
  • Camera resources path/Video & Images:

    • Low resolution mjpeg : Equal to /bha-api/video.cgi to get mpjpeg stream from DoorBird unit.
    • Low resolution image : Equal to /bha-api/image.cgi to get snapshots from DoorBird unit.

Dynalite

Connection to Dynalite systems can be made via the RS232 interfaces, either using BeoLiving Intelligence RS232 port or via an Ethernet to RS232 interface.

Native Dynalite Ethernet interfaces are not supported in the current software.

Dynalite resources

Resources may be area presets and dimmers.

A preset is identified by an area number plus a preset number in the range 1 to 24, separated by a comma.

Events and commands

A preset selection can be detected by BeoLiving Intelligence as an event. The parameters for the event are the preset number and the bank number.

For setting up a Dynalite control to affect only BeoLiving Intelligence, this control must be assigned an area number not used by any dimmer or actuator.

The available commands are: Preset selection, Switch area off, and Area fade UP / DOWN / STOP.

The parameters for preset selection are area number and preset number.

For area off and area fading, the only parameter is the area number.

Lutron Grafik Eye

Connecting to a Grafik Eye system

All Grafik Eye interfaces are supported: GRX-RS232, GRX-CI-RS232, and GRX-CI-NWK-E. Connection to the RS232 interfaces can be done directly using a 3-wire RS232 cable, or via an Ethernet to RS232 interface.

If using an Ethernet to RS232 interface, set it up for 9600 bps, no parity, no flow control, 1 stop bit.

Connection parameters are TCP port and IP address in case of using a network interface.

The password is only needed if using a direct network connection to GRX-CI-NWK-E. The default password for this interface is ‘nwk’.

Important note: Make sure that you enable scene status feedback and raw feedback on the Lutron interfaces. This is done by setting the DIP switches 6 and 7 to ON on the interface itself.

Resources

Resource types supported:

  • Dimmer, addressed as unit:zone (unit 1 to 8, zone 1 to 8)
  • Shade, addressed as unit:zone
  • Scene button, addressed as unit:scene (unit 1 to 8, scene 0 to 9 and A to G with G corresponding to OFF)

Lutron HomeWorks Interactive

Connecting to a HomeWorks processor

Connections to a HomeWorks processor can be done directly on Ethernet, RS232, or indirectly with an RS232 to Ethernet interface. This last option is only relevant for older HomeWorks generations that had no network interface.

For RS232, hardware flow control is recommended. Be sure to use a fully wired RS232 cable in this case.

Resources

Resources on HomeWorks are keypad buttons (both physical and phantom keypads) and dimmers.

Addressing of resources of the form:

  • processor:link:address:button for keypads
  • processor:link:type:keypad:button for RF keypads
  • processor:link:router:bus:dimmer for H48 dimmer or switch
  • processor:link:type:dimmer for RF dimmer or switch
  • processor:link:router:module:output for RPM or GRX dimmer or switch
  • processor:link:router:bus:dimmer for D48 dimmer
  • processor:link:grx:output for Grafik Eye zones

Events and commands

Events from HomeWorks include button activity and LED activity. Normally you should respond to keypad button press only. The other options are provided for advanced use and need special care.

Commands to HomeWorks are keypad button presses. This is absolutely general since all buttons on HomeWorks are completely programmable.

Setup on the HomeWorks project

For direct network access, a network account must be defined in the addressing section. This account is identified by a user and password. Be sure to enable the necessary permissions for interaction with BeoLiving Intelligence. BeoLiving Intelligence will need access to full keypad monitoring and executing button presses.

Define phantom keypads for integration with BeoLiving Intelligence. BeoLink Gateway can act on any keypad (physical or phantom), but it is recommended to channel commands from BeoLiving Intelligence to HomeWorks via phantom keypads, so the special functionality for integration is not mixed with standard keypad functionality.

LED feedback

Advanced use only: BeoLiving Intelligence can generate events from keypad LED state changes. This is provided only for advanced use, where you want to generate BeoLiving Intelligence events as a consequence of conditional, time-clock, or other autonomous activity in HomeWorks.

  1. Define a state variable (or True/False variable) which you will use in your conditionals or time clock events to signal BeoLiving Intelligence.
  2. Define a phantom keypad on the HomeWorks project, and choose a button for this purpose.
  3. Set the button type to conditional.
  4. Set the LED behaviour to conditional, on (for example) preset 5, type scene.
  5. On Preset 5, add the state variable with a desired value.
  6. Configure BeoLiving Intelligence to respond to the LED of that button going ON or OFF, which will be an indication that the state variable has the specified value.

For example, use the “Time of Day” variable with value “Day”. The LED going ON will generate an event on sunrise, and the LED going off will generate an event at sunset on BeoLiving Intelligence.

Lutron Homeworks QS and Radio Ra2

This driver supports communication with Lutron HomeWorks QS, Lutron Radio RA2 and Lutron Grafik QS systems.

Connecting to a Grafik QS system

Connection to a Grafik QS system is done via a QSE-CI-NWK-E interface, which allows Ethernet and RS232 connectivity.

For RS232 communications, set the same bit rate on the QSE-CI-NWK-E interface and on BeoLiving Intelligence connection settings.

Connection settings for Ethernet are the IP address of the interface and the password. The default password is nwk.

Connection to a Radio RA2 system

Communication with Radio RA2 is done via the Radio RA2 Main Repeater, which allows interaction with the system via 100 programmable virtual buttons (phantom buttons). This device provides both RS232 and Ethernet interfaces.

Connection to the RS232 interface can be done directly using a 3-wire RS232 cable and it is fixed at 9600 bps, no parity, 1 stop bit, 8 data bits, no flow control.

Connection settings for Ethernet consist of: IP address of the Main Repeater (default: 192.168.1.50), login (default: lutron), password (default: integration) and telnet IP port (default: 23).

Connection to a Homeworks QS system

Communication with the Homeworks QS system is done via the Ethernet interface on the Homeworks QS Processor.

Connection settings consist of: IP address of the processor (default: 192.168.1.50), login (default: lutron), password (default: integration) and telnet IP port (default: 23).

Resources

The supported resource types are:

  • Button with LED: buttons on keypads or control units having a LED for status.
  • Button: a keypad or control unit button with no LED.
  • LED: a single LED used for status.
  • Dimmer: a light dimmer.
  • Shade: a single shade.
  • Shade group: a group of shades.
  • Thermostat: a thermostat like Lutron HVAC controller.
  • Lutron QS Scene Button: a button mapped to a single scene which will be selected on press.

Resource address format

Most resource addresses use Integration ID which by default is a number, but can also be a user defined string. Some resources require a sub-address called Component Number.

Lutron QS Scene Button” resources requires a scene number.

Possible scene numbers range from 0 (OFF) to 32, but depend on the scenes actually programmed in the controller.

Button with LED” resources also require a second component number to identify the LED. In many cases, the LED component number is offset 80 above the button component number (and this is the default LED component added during capture).

However, there are many cases in which the LED component number must be explicitly edited.

You may find out the LED component number by checking the LED events in the capture list. Or, you can check the complete list of component numbers for all Lutron keypads and control units in Lutron’s Integration Protocol documentation.

All address formats are suggested as tooltips on the address field.

Resource type Address format Examples
Button with LED Integration ID, Component Number, LED Component Number 1,1,81 or myIID,28,108
Button Integration ID, Component Number 1,1 or myIID,28
LED Integration ID, Component Number 1,1 or myIID,28
Dimmer Integration ID or Int. ID + Component Number 1 or 1,1 or myIID,28
Shade Integration ID 1 or myIID
Shade group Integration ID 1 or myIID
Thermostat Integration ID 1 or myIID
QS Scene Button Integration ID, Component Number, Scene 1,1,1 or myIID,43,1

Availability of events and commands

Lutron supports a lot of different hardware models and combinations.

Not all hardware setups support the whole set of events and commands.

Check the Lutron documentation (Lutron Integration Protocol), or use the monitoring facilities in BeoLiving Intelligence to verify that the hardware actually supports a command or event type.

A typical example is the _MULTI TAP event, which is available on a limited combination of Lutron hardware.

Events

  • Button with LED, Button
    • PRESS
    • RELEASE
    • HOLD
    • _MULTI TAP: Pressing on the button repeatedly
    • _HOLD RELEASE: Releasing a button after a long press (HOLD)

Commands

  • Button with LED, Button
    • PRESS
    • RELEASE
    • HOLD
    • _MULTI TAP: Pressing on the button repeatedly
    • _HOLD RELEASE: Releasing a button after a long press (HOLD)
  • Dimmer
    • SET: Set the dimmer level, in percentage.
  • Shade
    • RAISE
    • LOWER
    • STOP
    • SET: Set the shade level, in percentage.
  • Shade group
    • RAISE
    • LOWER
    • STOP
    • SET: Set the shade level, in percentage.
    • PRESET: Select one of the defined presets for the shade group
  • Thermostat
    • SET HEAT SP: Set the heat setpoint on the thermostat
    • SET COOL SP: Set the cool setpoint on the thermostat
    • SET MODE: Select the operation mode to OFF, Heat, Cool, Auto and Em.Heat (emergency heat)
    • SET FAN AUTO: Turn fan automatic mode ON or OFF
    • SET SCHEDULE: Turn the schedule ON or OFF
    • SET ECO MODE: Turn echo mode ON or OFF
    • _SET SP: Set cool and heat setpoints on the thermostat
  • Lutron QS Scene Button
    • PRESS: Select scene

Resource State

  • Button with LED
    • STATE: The state of the LED (0 means OFF and 1 ON)
  • LED
    • _STATE: The state of the LED (0 means OFF and 1 ON)
  • Dimmer
    • LEVEL: Level of the dimmer
  • Shade
    • LEVEL: Level of the shade
  • Shade group
    • LEVEL: Level of the shade group
  • Thermostat
    • TEMPERATURE: The current temperature
    • HEAT SP: The current heat setpoint
    • COOL SP: The current cool setpoint
    • MODE: The active mode
    • FAN AUTO: Whether the fan automatic mode is ON or OFF
    • SCHEDULE: Whether the schedule is ON or OFF
    • ECO MODE: Whether the eco mode is ON or OFF
    • _SYSTEM MODE: The current system mode
  • Lutron QS Scene Button
    • STATE: Whether this scene currently selected or not

Known issues: Capture stops working for Grafik controllers

Grafik controllers may stop reporting events in a HomeWorks QS / RadioRa 2 installation. This condition will prevent BeoLiving Intelligence from detecting events and from showing resource capture information.

We found the following procedure will restore a non-communicating Grafik controller:

  1. Verify that the Grafik unit is listed on the integration report (Lutron setup software).
  2. If it does not appear in the report, remove it and add it again to the project and re-check the report. Then upload the project to the HomeWorks / Ra2 controller.
  3. If the problem persists, you may try to reset the Grafik controller to factory defaults: Press and hold scene buttons 1, 3 and 5, and main control arrow down (next to the display) simultaneously, until a message is displayed asking for confirmation. Press OK.

KNX / EIB

BeoLiving Intelligence can interact with KNX systems by means of shared variables (group addresses).

Connection to a KNX system

BeoLiving Intelligence can connect to a KNX system by means of KNX data interfaces.

The supported interfaces are:

  • PEI type 10 (BCU2, with FT 1.2 protocol) over RS232 connection
  • IP tunnelling over Ethernet connection

PEI type 16 serial interfacing is not supported. PEI 10 bit rate is fixed at the default 19200 bps. The IP tunnelling interface could provide or not support for Bus Monitor Mode. In case Bus Monitor Mode is not supported, use Virtual Bus Monitor as a workaround checking the box “Use Virtual Bus Monitor” on Connection Settings.

Note on IP tunnelling: It is usually necessary to disconnect the ETS software from the IP tunnelling interface before BeoLiving Intelligence can connect to the system. Also, after disconnecting ETS, the interface can take several minutes before it accepts a new connection from BeoLiving Intelligence. The same considerations apply when switching back to ETS.

KNX resources

All the interaction between KNX and BeoLiving Intelligence is by means of group addresses. Group addresses have an associated datapoint type which identifies the type of data it holds (e.g. boolean, signed integer, etc.).

It is therefore necessary to define group addresses for all the resources intended for integration with BeoLiving Intelligence.

To be able to integrate KNX with BeoLiving Intelligence resources must be defined in BeoLiving Intelligence. BeoLiving Intelligence resources refer to one or more KNX resources and the way to map between BeoLiving Intelligence and KNX resources is the address.

A BeoLiving Intelligence resource address maps to one, two or three KNX group addresses. Group addresses have the form a/b/c (3 level address) or a/b (2 level). The default is the 3 level addresses, but both formats are accepted.

For resources mapping to two or three KNX resources the address contains group addresses spearated by a ‘:’ character.

For resources with state BeoLiving Intelligence keeps track of whether or not any state was received since the connection began, and sets the ONLINE state to false until some state is received from KNX. If ONLINE state stays false, it probably means the resource address is wrong.

Group address flags in ETS

There are several flags in the setup of KNX resources in an ETS project which determine the behaviour of the resources and their capabilities for integration with BeoLiving Intelligence.

The Communication Flag is the master switch for communication i.e. if this flag is not set, the object cannot be integrated with BeoLiving Intelligence.

The Read Flag enables the object value to be read by BeoLiving Intelligence. If not set, BeoLiving Intelligence can still notice when the value changes but cannot request its value, thus failing to get a correct state after a power failure or a configuration load.

When setting up a resource where the Read Flag is unset, select a resource type without state in BeoLiving Intelligence.

The Write Flag enables the object to be modified from BeoLiving Intelligence. If it is unset events can still be generated on BeoLiving Intelligence but there will be no possible command on the object.

The Transmit Flag enables the group address to send information to BeoLiving Intelligence, if unset the object will not notify events and neither can BeoLiving Intelligence request its state so for Read Flag to work this also must be set.

In BeoLiving Intelligence help and documentation, the abbreviations C, T, R and W are used for Communication, Transmit, Read and Write flags respectively.

Standard and non-standard resources

BeoLiving Intelligence supports two kinds of resources for KNX: standard BeoLiving Intelligence resources, and native KNX resources.

Standard BeoLiving Intelligence resources are: Toggle, Button, Dimmer with and without state, Shade with and without state, Thermostat 1SP, Thermostat 2SP, and GPIO.

Native KNX resource types are: Boolean, 1 byte unsigned integer, 1 byte signed integer, 2 Bytes unsigned integer, 2 Bytes signed integer and 3 bit controlled.

Standard resource types allow for better integration, offering more generic programming capabilities on BeoLiving Intelligence (generic programming), and better display on BeoLiving Intelligence user interfaces (web panel and mobile applications).

As a general rule try to avoid assigning the native resource types, unless you need macros with precise control over these group addresses.

System connection state

The KNX system connection state can be Offline, Connected, Connecting or Online. Offline means the KNX is not reachable. Connecting means the KNX system initialized the connection. Online means an interaction with the KNX system succeeded for at least one command/event/state request.

Resource types

Standard resource types

Resource type Std. type Comment
Toggle BUTTON Switch or any boolean toggle, and keeps track of its current value.
Button BUTTON Button with press, hold and release functionality.
Dimmer without state DIMMER Dimmer with set level functionality, but no feedback.
Dimmer DIMMER Dimmer with feedback of its current level.
Shade without state SHADE Shade with raise, lower and stop functionality, but no feedback.
Shade SHADE Shade with raise, lower, stop and feedback of its current level.
GPIO GPIO Switch, or any boolean value that can be set to true / false. Keeps track of its current value.
Thermostat 1SP THERMOSTAT_1SP Thermostat with a temperature and a setpoint states, and a set setpoint command.
Thermostat 2SP THERMOSTAT_2SP Thermostat with a temperature, a cool setpoint and a heat setpoint states and commands to set both setpoints.

Address

The following table summarizes the supported resource types, the KNX Datapoint Type code, the needed flags and group addresses.

Resource type DPT Address Group Address Needed Flags Comment
Toggle DPT 1.001 a/b/c or a/b/c:d/e/f a/b/c and d/e/f CRTW Some Toggle resources have value and status object in the same GA (a/b/c) or in a different GA (a/b/c and d/e/f). So in the last case, it's possible to specify the resource address as a/b/c:d/e/f [ 1 ]
Button DPT 1.001 a/b/c a/b/c CTW  
Dimmer without state DPT 5.001 a/b/c a/b/c CTW Dimmer value object GA.
Dimmer DPT 5.001 a/b/c:d/e/f a/b/c and d/e/f CTW (a/b/c) and CRT (d/e/f) Dimmer value object GA (a/b/c) and value status object (d/e/f). [ 1 ]
Shade without state DPT 1.007 and 1.008 a/b/c:d/e/f a/b/c and d/e/f CTW (both a/b/c and d/e/f) Shade 'StopStep UpDown' object GA (a/b/c) and 'Move UpDown' object GA (d/e/f).
Shade DPT 1.007, 1.008 and 5.001 a/b/c:d/e/f:g/h/i a/b/c, d/e/f and g/h/i CTW (a/b/c), CTW (d/e/f) and CRT (g/h/i) Shade 'StopStep UpDown' object GA (a/b/c), 'Move UpDown' object GA (d/e/f) and status object GA (g/h/i). [ 1 ]
GPIO DPT 1.001 a/b/c or a/b/c:d/e/f a/b/c and d/e/f CRTW Some GPIO resources have value and status object in the same GA (a/b/c) or in a different GA (a/b/c and d/e/f). So in the last case, it's possible to specify the resource address as a/b/c:d/e/f [ 1 ]
Thermostat 1SP DPT 9.001 a/b/c:d/e/f:g/h/i a/b/c and d/e/f CRT (a/b/c), CTRW (d/e/f) a/b/c is the temperature GA and d/e/f the setpoint temperature GA.
Thermostat 2SP DPT 9.001 a/b/c:d/e/f:g/h/i a/b/c, d/e/f and g/h/i CRT (a/b/c), CTRW (d/e/f) and CTRW (g/h/i) a/b/c is the temperature GA, d/e/f the heat setpoint temperature GA and g/h/i the cool setpoint temperature GA.
Boolean DPT 1.xxx a/b/c a/b/c CTW  
1 byte unsigned integer DPT 5.xxx a/b/c a/b/c CTW  
1 byte signed integer DPT 6.xxx a/b/c a/b/c CTW  
2 bytes unsigned integer DPT 7.xxx a/b/c a/b/c CTW  
2 bytes signed integer DPT 8.XXX a/b/c a/b/c CTW  
3 bit controlled 3.007 / 3.008 a/b/c a/b/c CTW  

Events

Event Argument Resource type Description
PRESS   Button Button press
RELEASE   Button Button release
HOLD   Button Button hold, depends on setup. Typically means holding a button for 200 ms or more.
SET Number All non standard Generated when the value is set.
SET_NON_ZERO   All non standard Generated when the value is set to a non zero one.

The value ranges for the native KNX resources are as follows:

Resource type Range
Boolean 0 .. 1
1 Byte unsigned integer 0 .. 255
1 Byte signed integer -128 .. 127
2 Bytes unsigned integer 0 .. 65535
2 Bytes signed integer -32768 .. 32767
3 Bit Controlled 0 .. 15 (0 to 7 setp size, add 8 for increase instead of decrease)

Commands

Command Argument Resource type Description
PRESS   Toggle Swaps the resource value
PRESS   Button Button press
RELEASE   Button Button release
SET 1..100 Dimmer, Dimmer without state Sets the level of the dimmer to a percentage
RAISE   Shade, Shade without state Starts raising the shade
LOWER   Shade, Shade without state Starts lowering the shade
STOP   Shade, Shade without state Stops shade motion
SET Boolean GPIO Sets the level of the GPIO
SET Resource range All non standard Sets the value of the resource.
SET SETPOINT [ 2 ] Thermostat 1SP Sets the setpoint to the given temperature
SET COOL SP [ 2 ] Thermostat 2SP Sets the cool setpoint to the given temperature
SET HEAT SP [ 2 ] Thermostat 2SP Sets the heat setpoint to the given temperature

Resource State

Resource type State Type Description
Toggle, GPIO STATE 0..1 Current value
Dimmer LEVEL 0..100 Current level in percentage
Shade LEVEL 0..100 Current level in percentage
Thermostat 1SP, Thermostat 2SP TEMPERATURE [ 2 ] Current ambient temperature.
Thermostat 1SP SETPOINT [ 2 ] Setpoint current value.
Thermostat 2SP HEAT SP [ 2 ] Heat setpoint current value.
Thermostat 2SP COOL SP [ 2 ] Cool setpoint current value.
Toggle, GPIO, Dimmer, Shade, Thermostat 1SP, Thermostat 2SP ONLINE true, false Indicates whether or not the other resource states reflect the state on KNX for the given address.

Importing and exporting KNX resources

KNX resources can be loaded from an ETS project using: 1) Group Address CSV export; and 2) OPC export (ESF).

  1. Group Address CSV export. On the Group Addresses view, right click over Group Addresses (root of the group addresses tree) and select the “Export Group Addresses” option to open the Export Group Address popup. Once in the popup select CSV as output format, “1/1 - Name/Address” as CSV format and comma as CSV separator.

  2. OPC export (ESF). On the main menu bar under “Extras” select “Export OPC” and leave the type unchanged (EIB session files (esf)). This is the preferred method, as it provides more complete information for importing into BeoLiving Intelligence.

On BeoLiving Intelligence’s resources screen, use the Import Resources button for adding resources from the ETS export file.

Khimo

This driver supports communication with the Khimo system.

Khimo provides remote access to BeoLiving Intelligence providing access to commands and status information of each zone.

This driver is automatically created by the BeoLiving Intelligence when Remote Access is enabled.

Lauritz Knudsen, IHC/Schneider, LexControl

IHC/LexControl programming model consists of physical input and output devices plus function blocks. Function blocks implement the programming of the system, and the interface between the programming and the actual components is done by linking physical input signals to function block inputs. Actuators can also be handled directly (dimmers and shades).

Importing resources from LK project file

The configuration tool for the controller (LK Visual) saves all the programming and setup in an XML file with extension .VIS.

Use the Import Resources feature on BeoLiving Intelligence resources screen in order to import the resources from the VIS file into each zone.

The Visual project file is absolutely necessary, since there is no way to inspect all of the events occurring on the controller. Therefore, monitoring information will only be available for already defined resources.

It is also possible to extract the list of resources from the LK controller. This works by downloading the Visual project file from the LK contoller itself, and is equivalent to loading the project file manually.

The supported resource types are:

  • Airlink inputs
  • Dataline inputs
  • Function block inputs:
  • Function block output
  • Dataline output
  • Airlink dimmers
  • Wired shutter
  • Wireless shutter

Events

The following list indicates which IHC activities generate a BeoLiving Intelligence event:

  • AirLink inputs and Dataline inputs:
    • PRESS: Input set to True.
    • RELEASE: Input set to False.
  • Airlink dimmers:
    • _RAISE: Internal variable airlink_dimmer_increase set to True.
    • _LOWER: Internal variable airlink_dimmer_decrease set to True.
    • _STOP: Internal variable airlink_dimmer_increase or airlink_dimmer_decrease set to False.
  • Shutters:
    • RAISE: Shutter being raised. On a dataline (wired) shutter, this corresponds to the first dataline_output within the shutter being set to True. On an Airlink shutter it corresponds to the shuttter’s airlink_shutter_up variable being set to True.
    • LOWER: Shutter being lowered. On a dataline shutter, this corresponds to the second dataline_output within the shutter being set to True. On an Airlink shutter it corresponds to the shutter’s airlink_shutter_down variable being set to True.
    • STOP: After RAISE or LOWER, the corresponding ID being set to False.

Commands

BeoLiving Intelligence commands produce the following IHC activity:

  • AirLink inputs and Datline inputs:
    • PRESS: Set value to True.
    • RELEASE: Set value to False.
    • TAP: logical pulse (True followed by False).
  • Function block inputs and outputs, Dataline outputs:
    • SET: Set value to variable.
    • PULSE: Logical pulse (True followed by False).
    • TOGGLE: Set opposite of current value.
  • Airlink dimmers:
    • _RAISE: Set internal variable airlink_dimmer_increase being set to True.
    • _LOWER: Set internal variable airlink_dimmer_decrease being set to True.
    • _STOP: after _RAISE or _LOWER, set the corresponding variable to False.
    • SET: Set dimmer level, in percentage. This corresponds to setting the dimmer’s airlink_dimming internal variable to the given value.
  • Shutters:
    • RAISE: Raise shutter. In a dataline shutter, this corresponds to setting the first dataline_output within the shutter to True. On an airlink shutter it corresponds to setting the shutter’s airlink_shutter_up variable to True.
    • LOWER: Lower shutter. In a dataline shutter, this corresponds to setting the second dataline_output within the shutter to True. On an airlink shutter it corresponds to setting the shutter’s airlink_shutter_down variable to True.
    • STOP: After RAISE or LOWER, set the corresponding variable to False.

Resource State

  • Function-block inputs and outputs, Dataline outptus:
    • STATE: The state of the variable (True or False).
  • Airlink dimmers:
    • LEVEL: Current dimmer level (value of the dimmer’s airlink_dimming variable).

Nest thermostat

Connection to Nest REST API

In order to connect BeoLiving Intelligence to a Nest thermostat, a PIN code is required.

A link labeled Get PIN code for BeoLink NEST driver is available on the Systems page when setting up a Nest thermostat. This link will redirect you to Nest web site for obtaining the PIN after authenticating with your Nest login.

Note: Each PIN code can be used for authorization only once. If Apply button in Systems page is pressed twice with the same PIN code, connection with Nest will be reset and a new PIN code must be generated.

Resources

The supported resource types are:

  • Thermostat SP1: thermostat with single set point (for heating or cooling).
  • Thermostat SP2: thermostat with two set points (for heating and cooling).
  • Home/Away: button with feedback to interact with the away state of a home.
  • Rush Hour: GPIO to indicate rush hour.
  • Smoke + CO Alarm: a non standard resource type that reflects Nest’s Smoke + CO Alarm (Nest Protect) state.

While adding or editing resources, it is normal for the connection status icon to blink.

Once finished with resource edition, it may take up to 30 seconds for the connection to settle and for all resource states to synchronize.

Resource address

Nest thermostat device ID is used as a resource address. Since it’s quite hard to find it, it’s advised to register your thermostat into your Nest account and capture thermostats automatically by pressing Import resourcesLoad resource from connected system.

Commands, events and states

  • Thermostat SP1
    • Set setpoint: sets temperature set point of a thermostat or captures event on a given level.
    • Set mode: sets system mode to home/away or captures event on a given state.
    • System mode: captures system mode event (home/away).
    • State variables:
      • TEMPERATURE: The current temperature.
      • SETPOINT: The current setpoint.
      • MODE: The current mode: Heat, Cool or Off.
      • _FAN TIMER ACTIVE: Indicates whether or not the fan is active.
  • Thermostat SP2
    • Set heat SP: sets heating set point of a thermostat or captures event on a given level.
    • Set cool SP: sets cooling set point of a thermostat or captures event on a given level.
    • Set mode: sets system mode to home/away or captures event on a given state.
    • System mode: captures system mode event (home/away).
    • State variables:
      • TEMPERATURE: The current temperature.
      • HEAT SP and COOL SP: The current heat and cool setpoints respectively.
      • MODE: The current mode: Heat, Cool, Auto or Off.
      • _FAN TIMER ACTIVE: Indicates whether or not the fan is active.
  • Home/Away
    • Home: sets the corresponding home away status to home.
    • Away: sets the corresponding home away status to away.
    • Toggle: toggles the corresponding home away status.
  • Rush Hour:
    • State variables:
      • STATE: Indicates whether or not a rush hour is taking place.
  • Smoke + CO Alarm:
    • State variables:
      • _IS_ONLINE: True when the Smoke CO Alarm is online.
      • _BATTERY_HEALTH: The battery health status, can be ok or replace.
      • _CO_ALARM_STATE: The CO alarm state, one of ok, warning or emergency.
      • _SMOKE_ALARM_STATE: The smoke alarm state, one of ok, warning or emergency.
      • _UI_COLOR_STATE: The Protect LED color, useful for detecting problems without checking all the above state variables, can be one of gray, green, yellow or red.

OpenWeatherDriver

This driver access current weather data for any location including over 200,000 cities.
It gets information from OpenWeather’s API and leaves it available for use by the BeoLiving Intelligence.

Resources

The supported resource types are:

  • _CURRENT_WEATHER: current weather data.
  • _WEATHER_FORECAST_3HRS: forecast for the next 3 hours.
  • _WEATHER_FORECAST_24HRS: forecast for the next 24 hours.

Resource address format

The resource address consists of a string that represents the coordinates of the location from which you want to get information about the weather.
The format is: latitude:longitude (e.g. -34.896579:-56.071827)

Resource State

  • _CURRENT_WEATHER
    • _Temperature: temperature at the moment (Celsius).
    • _Min_Temperature: Minimum temperature at the moment (Celsius).
    • _Max_Temperature: Maximum temperature at the moment (Celsius).
    • _Humidity: Percentage of humidity.
    • _Pressure: Atmospheric pressure (hPa).
    • _WindSpeed: Wind speed (m/s).
    • _WindDirection: Wind direction, degrees (meteorological).
    • _Cloudiness: Percentage of cloudiness.
    • _Rain: True if it is rainning, false otherwise.
    • _RainLevel3Hrs: Rain volume for the next 3 hours (milimeters).
    • _Snow: True if it is snowing, false otherwise.
    • _SnowLevel3Hrs: Snow volume for the next 3 hours (milimeters).
  • _WEATHER_FORECAST_3HRS
    • _Temperature: temperature at the moment of calculation (Celsius).
    • _Min_Temperature: Minimum temperature at the moment of calculation (Celsius).
    • _Max_Temperature: Maximum temperature at the moment of calculation (Celsius).
    • _Humidity: Percentage of humidity.
    • _Pressure: Atmospheric pressure (hPa).
    • _WindSpeed: Wind speed (m/s).
    • _WindDirection: Wind direction, degrees (meteorological).
    • _Cloudiness: Percentage of cloudiness.
    • _Rain: True if it will rain, false otherwise.
    • _RainLevel3Hrs: Rain volume for the next 3 hours (milimeters).
    • _Snow: True if it will snow, false otherwise.
    • _SnowLevel3Hrs: Snow volume for the next 3 hours (milimeters).
  • _WEATHER_FORECAST_24HRS
    • _Min_Temperature: Min daily temperature (Celsius).
    • _Max_Temperature: Max daily temperature (Celsius).
    • _Humidity: Percentage of humidity.
    • _Pressure: Atmospheric pressure (hPa).
    • _WindSpeed: Wind speed (m/s).
    • _WindDirection: Wind direction, degrees (meteorological).
    • _Cloudiness: Percentage of cloudiness.
    • _Rain: True if it will rain, false otherwise.
    • _RainLevel3Hrs: Rain volume (milimeters).
    • _Snow: True if it will snow, false otherwise.
    • _SnowLevel3Hrs: Snow volume (milimeters).

Philips Hue

This driver supports communication with a Philips Hue bridge, allowing to control lights and lighting groups.

Connecting to the system

Connection to the system is done via a REST connection with the Philips Hue bridge. The following configuration is needed:

  1. Bridge host: The IP address or host name of the bridge.
  2. Bridge port: The port number where the bridge is waiting for connections (the suggested default should be correct).
  3. Bridge user: This user is automatically created when the button Create Philips HUE user on bridge is pressed, as described below.
  4. New color turns dimmers on: If this flag is set, and a new color is picked for a dimmer that is turned off, then the dimmer will be turned on with the new selected color.
  5. Poll interval: The number of seconds to wait between status requests.

If system connection can’t be established specifying Hue Bridge Hostname on Bridge host, bad configuration or absence of the DNS server on the BeoLiving Intelligence LAN could be the responsible issue. Try using the IP address of the Bridge. Default Hostname of Hue Bridge is Philips-hue.

The Philips Hue driver polls every light and group on the bridge each Poll interval seconds for status updates. If the system has a low number of resources, then this parameter may be set to a small value, although anything below 5 is not recommended.

If the Bridge user is not defined or is invalid, then you can create a new one by pressing the link button on the bridge and then pressing the Create Philips HUE user on bridge within 30 seconds. If the action is successful, then a new user will be assigned.

Available resources

The Philips Hue driver supports commanding the lights, groups and scenes that are available for the configured user.

Both lights and groups are mapped to the DIMMER Standard Resource type, and allow full control of every state variable, such as brightness, hue or color coordinates.

Also, as a DIMMER, they provide the SET LEVEL command which acts on the brightness and on state variables. As a simple example, setting the level to 100 implies setting “on” to true and “bri” to 255 on the Philips Hue bridge.

The scene is mapped to a BUTTON Standard Resource type, and the button PRESS recalls the scene on the Philips Hue bridge.

Deprecated commands

As of version 1.4.19116 and on, the command _SET TRANSITION TIME is no longer available. For setting a dimmer with fade time, the _TIMED SET command should be used.

Lutron Grafik QS

Connecting to a Grafik QS system

Connection to a Grafik QS system is done via a QSE-CI-NWK-E interface, which allows for Ethernet and RS232 connectivity.

For RS232 communications, set the same bit rate on the QSE-CI-NWK-E interface and on BeoLiving Intelligence connection settings.

Connection settings for Ethernet are the IP address of the interface and the password. The default password is ‘nwk’.

Defining Grafik QS resources

The resources you need to define are control units and accessory controls (e.g. keypads) with which you need to interact. Each is defined by a serial number which can be found on a label on each product, or from the control units bus status information, or by inspecting BeoLiving Intelligence monitoring information.

Grafik QS events and commands

Events from a Grafik QS system can be lighting scene changes on control units, or key presses.

Possible commands are scene changes on control units.

Lutron Radio RA

Connection to a Radio RA system

Communications with Radio RA is done via the Radio RA RS232 interface. Use a full RS232 cable between Radio RA and BeoLiving Intelligence. Hardware flow control is used, so a 3-wire connection will not work.

Alternatively, you can use an Ethernet to RS232 interface and connect via BeoLiving Intelligence network port. In this case, it is important to configure the Ethernet to RS232 interface to use hardware flow control, 9600 bps, no parity, 1 stop bit.

The only connection setting available is the TCP port number and IP address in case connecting via Ethernet.

Resources

The supported resource types are:

  • Master Button LED: LED on a Master Control.
  • Phantom Button Dimmer: a light dimmer.
  • Phantom Button Shade: a single shade.
  • Phantom Button Switch: a light switch.
  • Phantom Button Toggle: a single button.
  • Phantom LED: programmable LED.

Resource address format

Most resource addresses in Radio RA are based on Master Control Number, Zone Number and Button Number.

Master Control Number is a number between 1 and 12, which is displayed in the Radio RA RS232 interface when Master Control is used. Zone Number is a number between 1 and 32. Button Number is a number between 1 and 17; where 16 and 17 are normally “all on” and “all off” respectively.

The address depends on the resource type:

  • Master Button LED: Master Control Number and a LED number separated by a colon :. The LED number ranges from 1 to 15.
  • Phantom Button Dimmer: Zone Number.
  • Phantom Button Shade: Button Number excluding 16 and 17.
  • Phantom Button Switch: Button Number.
  • Phantom Button Toggle: Button Number.
  • Phantom LED: Button Number excluding 16 and 17.

Commands

  • Master Button LED
    • SET: Set the LED state (0 means OFF and 1 ON)
  • Phantom Button Dimmer
    • SET: Set the dimmer level, in percentage.
  • Phantom Button Shade
    • RAISE
    • LOWER
    • STOP
  • Phantom Button Switch
    • TOGGLE
    • SET
  • Phantom Button Toggle
    • PRESS

Resource State

  • Master Button LED
    • STATE: The state of the LED (0 means OFF and 1 ON)
  • Phantom LED
    • STATE: The state of the LED (0 means OFF and 1 ON)

Smart-House

Connection to a Smart-House system

Connection to a Smart-House system is made via an Ethernet connection to a Smart-House controller.

Both the IP address and the TCP port must be configured on BeoLiving Intelligence.

Remark: when loading different configurations it may be necessary to reboot the Smart-House system to reestablish connection with it.

Defining Resources

Resources can be

  • dupline input channels,
  • dupline output channels or
  • functions of type sequence.

Interaction between BeoLiving Intelligence and the Smart-House system is implemented via changes in the status of channels and the start / stop of sequences.

Dupline channel addresses are of the form A1: an uppercase letter (A to Z) followed by a digit (1 to 8).

Functions are identified by a single number.

Events and commands

Events can be a dupline channel set, a dupline channel reset, a sequence start or a sequence stop.

Commands to a Smart-House system are set, reset or pulse a dupline channel and start or abort a sequence.

SmartHouse SH2

Connection to a SmartHouse SH2 system

Connection to a SmartHouse SH2 system is done via a Modbus interface. The following configuration is needed:

  • Host: The IP address or host name of the device.
  • Port: The port number where the device is waiting for connections (default: 23).

Remark: when loading different configurations it may be necessary to reboot the Smart-House system to reestablish connection with it.

Resources

The supported resource types are:

  • Button: buttons and digital inputs.
  • Dimmer: a light dimmer.
  • Shade: a single shade.

Resource address format

Resource addresses use relative Modbus address.

SmartHouse configuration tool, (SH Tool) can save the Modbus configuration map into a CSV file (this is found in the Program setup menu). The relevant entries in the CSV file are the lines containing the keywords function status or movement position.

The following is an example line in the generated Modbus map CSV file:

,(Fx) Root - Light function_Function status,HREG,400711,unsignedShort,

The 6 digit number 400711 is the absolute Modbus address. The relative Modbus address is absolute address without the 3-digit prefix. In this case, it is 711.

All address formats are suggested as tooltips on the address field.

Resource type Address format Examples
Button Function status 1
Dimmer Function status 1
Shade Function status, Movement position 1,1

Commands and events

  • Button
    • PRESS: Toggles button state.
    • ON: Sets resource state to one or captures event on given state.
    • OFF: Sets resource state to zero or captures event on given state.
  • Dimmer
    • SET: Sets dimmer level (in percentage) or captures event on set level.
  • Shade
    • RAISE: Moves shade to upper position.
    • LOWER: Moves shade to lower position.
    • STOP: Stops shade on current position.
    • SET: Sets shade level (in percentage) or captures event on set level.

Tekmar

This driver supports communication with tekmar thermostats.

Connecting to a tekmar system

Connection to a tekmar system is done through tekmarNet4 Gateway 482 Serial Interface.

Resources

The supported resource types are:

  • Cooler and Heater: Thermostat that supports Heating and Cooling (HeatSetpoint and CoolSetpoint operations).
  • Heater: Thermostat that only supports Heating (HeatSetpoint operation).
  • Slab control: Thermostat that supports Slab heating (SlabSetpoint operation).
  • Setback switch: Button with LED, LED is on when setback is enabled and pressing the button switches setback state.
  • Setpoint device: Thermostat that supports only one setpoint (SetpointDevice operation).

Resource address format

All thermostats addresses are the tekmar addresses. The Setback switch resource has no address and only one is allowed for the system.

Addressess in tekmar depend on the wiring, so if wiring is modified, BeoLiving Intelligence resource addresses must be updated accordingly.

There is no one to one mapping between BeoLiving Intelligence resources and tekmar thermostats, one tekmar thermostat can handled through more than one BeoLiving Intelligence device. For example if your tekmar thermostat has two setpoints for Cooling and Heating and also has a Slab control, you should define a Cooler and Heater thermostat and a Slab control in BeoLiving Intelligence.

If you don’t know what addresses are defined in tekmar you can use the “Load resource from connected system” button under “Import resources” on resources setup. This will provide all the connected devices addresses, but won’t help with their capabilities. If you don’t know your tekmar thermostats capabilities or for example, you have a thermostat with slab and one without and don’t know which address is which, you can add all the listed resources in the resource import list, and then find out by trying (in the example, define slab for both and test which works).

Twitter

This driver supports communication with Twitter Stream and Public API, allowing to post Twitter status messages, fire events and reply a message when the desired word is found in tweets of the Twitter Social Network.

Connecting to the system

Connection to the Twitter Stream and Public API is done via a REST connection. The only thing needed for establish a connection with the APIs is the PIN CODE. The steps to get the PIN CODE are:

  1. Click the link and login with your Twitter account.
  2. Copy the PIN code in BeoLiving Intelligence Connection setting
  3. Press Apply.
  4. Connection Process Finished.

Resources

The supported resource types are:

  • _TRACK_FILTER: Search for Tweets containing specific words.

  • _TWEET: Post a status message on Twitter.

Events

  • _TRACK_FILTER:
    • _MATCH: Fired when the resource address is matched on the Twitter Stream.

Commands

  • _TRACK_FILTER:
    • _REPLY: Used for reply to a Tweet. The command fields are:
      • _Message: Message string to reply.
      • _User: The user to reply.
      • _Id: id of the tweet of _User to reply.
  • _TWEET
    • _SEND_STATUS: Used for Tweet. The command field is:
      • _Message: Message string to Tweet.

Usage of resources:

  • _TRACK_FILTER:
    • Add _TRACK_FILTER resources with the words to search in their respective addresses. The driver will search for tweets that contain any resource address of the system. The address value of the resource corresponds to the phrase definition of the Track Filter. Each phrase must be between 1 and 60 bytes inclusive and should not contain commas. When the driver matches a resource address in the tweet stream, it fires an event _MATCH type specifying the text of the Tweet, the respective Tweet id and the User related.
    • _MATCH as Event Macro: To fire a Macro when a _MATCH Event is fired its necessary that the Event contains the next fields:
      • _User: Equal to “$user
      • _Id: Equal to “$id” Not doing the below steps on the _MATCH Event will not fire Macros.
    • Usage of _REPLY command: To configure BeoLiving Intelligence for reply to an specific status message of any User, its necessary to:
      1. Create a _TRACK_FILTER resource with the message to answer in the resource address.
      2. Create a Macro with a _MATCH Event with the next fields:
        • _User: Equal to “$user
        • _Id: Equal to “$id
      3. In the same Macro create a _REPLY Command with the next fields:
        • _Message: The Message to respond.
        • _User: Equal to “$user
        • _Id: Equal to “$id
  • _TWEET: Add a “_TWEET” resource to be able to post status messages on Twitter. The address in this resource has no meaning.

NOTES:

  • Its MANDATORY to have the BeoLiving Intelligence time synchronised from the Internet for the usage of Twitter Driver.
  • After add/erase/modify resources, to apply the changes in the search its necessary to click in the Force Resource Synchronization in the Connection Settings of BeoLiving Intelligence Twitter Driver. Also, when a match is fired, the driver checks if has been any modification in the resources and if its so, upgrades the search parameters.

Vantage

Connection to a Vantage system

Communication with a Vantage system is done through an InFusion Dim Controller. This device has both RS232 and Ethernet interfaces.

Connection to the RS232 interface can be done directly using a fully wired RS232 cable and it is fixed at no parity, 1 stop bit, 8 data bits. Make sure to configure bit rate and flow control as needed.

Connection settings for Ethernet are the IP address of the InFusion Dim Controller and its telnet port.

Resources

To program the InFusion Dim Controller, the PC tool Design Center is needed. It lets you define all components of your Vantage system, where each one has an address called vid (Vantage Identification Number).

On BeoLiving Intelligence you can define as resources the following items:

  • a button on any control
  • a task

To define a resource, you need to know the Button or Task vid, which must be entered in the address field.

Events and commands

An event corresponds to a Button press or release.

Supported commands are:

  • Button press and release
  • Button press
  • Button release
  • Task activation (press, hold, release)

Velux

This driver provides communication with Velux systems through Ethernet interfaces.

Connection to a Velux system

Communication with a Velux system is achieved via the Velux gateway, which provides an Ethernet interface.

Connection settings for Ethernet consist of: IP address of the Velux gateway (default: 192.168.0.2), and port number (default: 51200).

Defining resources

The only supported resource type is the “Velux Scene Button” which allows selection of a scene defined in the Velux gateway through its PRESS command.

The address of a “Velux Scene Button” is the scene identification number of the scene that will be activated on PRESS.

Requesting scenes from Velux gateway

All the scenes defined in the Velux gateway can be added automatically as BeoLiving Intelligence resources by selecting Import resources in the resources page, an then Load resources from connected system.

Resources added automatically from the Velux gateway will be named using the scene label already defined.

amBXDriver

This driver allows to create resources that represents “spaces” which can run any Light-Scene in a “slot”.

Resources

The supported resource type is:

  • _amBX_space: Represents an available “space”.

Resource address format

The resource address represents the space number. It consists of an integer from 0 to 31.

Resource State

  • _amBX_space
    • LEVEL: An integer form 0 to 100. This argument is mapped to amBX_brightness.
    • _SLOT: An integer form 0 to 24. This argument is mapped to amBX_slot.

Resource actions

  • _SET: Sets the brightness for the space.
  • _SELECT_SLOT: Sets the active Light-Scene for the space to be the one present in the slot passed as the command argument.

Global Cache iTach IP2CC

This driver supports communication with a Global Cache iTach IP2CC, allowing to control relay closures.

Connecting to the system

Connection to the system is done via Ethernet interface. For achieving this, the following parameters should be provided:

  1. Host: The IP address or host name of the device.
  2. Port: The port number where the device is waiting for connections.

The Global Cache iTach IP2CC driver polls each relay every second for status updates.

Available resources

The Global Cache iTach IP2CC driver supports commanding the relays that are added as resources.

Relays are mapped to the BUTTON Standard Resource type, and allow full control of it.

After power loss relay closures will be in open state.

Global Cache iTach IP2IR

This driver supports communication with a Global Cache iTach IP2IR system, allowing to control IR controlled devices.

Connecting to the system

Connection to the system is done via Ethernet. The following parameters should be provided:

  1. Host: The IP address or host name of the device.
  2. Port: The port number where the device is waiting for connections (the suggested default will probably be correct).

Available resources

This driver is based on sending strings to the external system. Therefore a resource is a generic string.

There are 3 parameters to each resource:

  • Name of the resource.
  • Resource type.
  • A resource address, which is a string representation of the IR command.

IR Commands

Control of IR devices is accomplished through use of the sendir command, which could be captured by using Global Cache IR capturing software iLearn, or by getting it from Global Cache’s Control Tower, a cloud-based IR database.

An IR command (infrared transmission), is created by sending an IR timing pattern to the iTach. This pattern is a collection of on and off states modulated with a carrier frequency, which is present during the on state.

Sendir has the following structure:

sendir,connectoraddress,ID,frequency,repeat,offset,on1,off1,on2,off2….,onN,offN

where N is less than 260 number pairs.

For example TV Standby command in B&O IR format looks like this:

sendir,1:1,1,460571,1,1,96,1356,96,1356,96,7120,96,1356,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,2796,96,4243,96,2796,96,1356,96,2796,96,5686,96,15023

Global Cache iTach IP2SL

This driver supports communication with a Global Cache iTach IP2SL, allowing to control RS232 serial devices.

Connecting to the system

Connection to the system is done via Ethernet. The following parameters should be provided:

  1. Host: The IP address or host name of the device.
  2. Port: The port number where the device is waiting for connections (the suggested default will probably be correct).

There are two types of TCP connections:

  1. Direct Ethernet connection for communication: should be used for normal communication.
  2. Direct Ethernet connection for configuration: should be used if RS232 port configuration is not known or needs to be changed. RS232 settings will be sent to the device after pressing “Apply” button. After Apply button is pressed, change TCP connection to Direct Ethernet connection for communication.

Available resources

This driver is based on matching incoming byte strings from the external system, and sending back byte strings to it.

Therefore resources are generic strings used for matching from, and for sending to the external system.

There are 3 parameters to each resource:

  • Name for the resource.
  • Whether it should be available for matching (INPUT), for sending (OUTPUT), or for both input and output (BOTH).
  • A generic character string.

In order to allow arbitrary byte values, the following encoding is used:

  • Any character except for backslash (\) will be given it’s corresponding value. Non-ASCII (international) characters are interpreted as Unicode UTF-8 byte sequences.
  • Backslash is used as an escape character, which gives special meaning to the character or characters that follow:
    • \\ (double backslash) is interpreted as a single backslash.
    • \r is interpreted as a carriage return character (0x0D).
    • \n is interpreted as a newline character (0x0A).
    • \xx (where x is a hexadecimal digit [0-9, a-f, A-F]) is interpreted as a hexadecimal byte value. E.g. \0A is equivalent to \n.

Any non-printable or non-ASCII character entered by the user will be shown as hexadecimal sequences. Illegal or truncated escape sequences will be marked as errors.

Events and commands

Resources marked for input (or both input + output) will be searched for in all incoming data. As soon as a match is found, the corresponding event will be generated and search will continue after the match.

If the incoming channel becomes idle, then all partial matches will be discarded.

Commands are all resources marked as output (or both input + output) that can be transmitted to the channel.

End of line sequence

An end of line sequence can be defined at the channel configuration.

Being non empty implies a working mode in which events are delimited by it, matching only when the complete message is equal to a defined event.

Defining end of line allows discovery of resources by using the “capture” button on the resources page, for each received string ending with the end of line sequence, an unknown resource will show up using it as address.

Also the end of line is appended to commands before sending them to the external system.