LCN

The lcn integration for Home Assistant allows you to connect to LCN hardware devices.

The integration requires one unused license of the coupling software LCN-PCHK (version >2.8) and an LCN hardware coupler. Alternatively, an LCN-PKE coupler can be used which offers two PCHK licenses. With this setup sending and receiving commands to and from LCN modules is possible.

There is currently support for the following device types within Home Assistant:

Binary Sensor
Climate
Cover
Light
Scene
Sensor
Switch

Please note: Besides the implemented platforms, the lcn integration offers a variety of service calls. These service calls cover functionalities of the LCN system, which cannot be represented by the platform implementations. They are ideal to be used in automation scripts or for the template platforms.

Configuration

To use your LCN system in your installation, add the following lines to your configuration.yaml file. You have to specify at least one IP/port with login credentials for a PCHK host. Consider to store your credentials in a secrets.yaml.

lcn:
  connections:
    - name: myhome
      host: 192.168.2.41
      port: 4114
      username: lcn
      password: lcn

  binary_sensors:
    - name: Kitchen window
      address: myhome.s0.m7
      source: binsensor1

  climates:
    - name: Temperature bedroom
      address: myhome.s0.m7
      source: var1
      setpoint: r1varsetpoint
      min_temp: 17.
      max_temp: 30.
      lockable: true
      unit_of_measurement: °C

  covers:
    - name: Living room cover
      address: myhome.s0.m7
      motor: motor1

  lights:
    - name: Bedroom light
      address: myhome.s0.m7
      output: output1
      dimmable: true
      transition: 5

  scenes:
    - name: Romantic
      address: myhome.s0.m7
      register: 1
      scene: 4
      outputs: [output1, output2, relais1, relais3, relais4]
      transition: 5

  sensors:
    - name: Temperature
      address: myhome.s0.m7
      source: var3
      unit_of_measurement: °C

  switches:
    - name: Sprinkler switch
      address: myhome.s0.m7
      output: relay1

Configuration Variables

connections map Required

List of your connections.

host string Required

IP address of the LCN-PCHK host.

port integer Required

Port of the LCN-PCHK host.

username string Required

password string Required

name string (Optional, default: pchk)

Optional connection identifier. If omitted, the connections will be named consecutively as pchk, pchk1, pchk2, …

sk_num_tries integer (Optional, default: 0)

Segment coupler scans. Increase this number if you have at least one segment coupler in your system.

dim_mode string (Optional, default: steps50)

Dimming mode for connected modules. The operation mode is programmed into the LCN modules by the LCN-PRO software and depends on their firmware. If you experience unexpected dimming behavior, the connection is probably in the wrong operation mode. Possible values: steps50, steps200

binary_sensors map (Optional)

List of your binary sensors.

name string Required

Name of the sensor.

address string Required

Address of the module/group.

source string Required

Sensor source (BINSENSOR, SETPOINT, KEYS).

climates map (Optional)

List of your climate devices.

name string Required

Name of the climate controller.

address string Required

Address of the module/group.

source string Required

Current temperature source (VARIABLE).

setpoint string Required

Setpoint for target temperature (VARIABLE, SETPOINT).

unit_of_measurement string (Optional, default: celsius)

Measurement unit (VAR_UNIT).

min_temp float (Optional)

Minimum target temperature.

Default:

max_temp float (Optional)

Maximum target temperature.

Default:

lockable boolean (Optional, default: false)

Climate control can be locked.

covers map (Optional)

List of your covers.

name string Required

Name of the cover.

address string Required

Address of the module/group.

motor string Required

Motor port (MOTOR_PORT).

reverse_time string (Optional)

Reverse time (REVERSE_TIME, see also Cover).

lights map Required

List of your lights.

name string Required

Name of the light.

address string Required

Address of the module/group.

output string Required

Light source (OUTPUT_PORT, RELAY_PORT).

dimmable boolean (Optional, default: false)

Enable the dimming feature for this light.

transition integer (Optional, default: 0)

Transition (ramp) time in seconds.

scenes map (Optional)

List of your scenes.

name string Required

Name of the scene.

address string Required

Address of the module/group.

Number of scene register (0..9).

scene integer Required

Number of scene (0..9).

outputs list (Optional)

List of ports (OUTPUT_PORT, RELAY_PORT).

transition integer (Optional, default: None)

Transition (ramp) time in seconds.

sensors map (Optional)

List of your sensors.

name string Required

Name of the sensor.

address string Required

Address of the module/group.

source string Required

Sensor source (VARIABLE, SETPOINT, THRESHOLD, S0_INPUT, LED_PORT, LOGICOP_PORT).

unit_of_measurement string (Optional, default: native)

Measurement unit (VAR_UNIT).

switches map (Optional)

List of your switches.

name string Required

Name of the switch.

address string Required

Address of the module/group.

output string Required

Switch source (OUTPUT_PORT, RELAY_PORT).

LCN Addresses

LCN hardware devices connected to the LCN bus are called modules. LCN modules are addressed by their numeric id in the range (5..254).

Modules can be arranged in segments. Segments can be addressed by their numeric id (5..128) or 0 (= no segment exist) or 3 (= target all segments).

LCN Modules within the same segment can be grouped by their group id (5..254) or 3 (= target all groups.)

The LCN integration allows the connection to more than one hardware coupler. In this case, it has to be specified which hardware coupler should be used for addressing the specified module.

Whenever the address of a module or a group has to be specified, it can be addressed using one of the following syntaxes:

Example for modules:

connid.s000.m007
connid.s0.m7
s0.m7
0.7

Example for groups:

connid.s000.g007
connid.s0.g7
s0.g7
0.g7

Leading zeroes in the segment id or module/group id can be omitted. If the connection_id is omitted, the first connection defined in the configuration will be used.

LCN Constants

The platforms and service calls use several predefined constants as parameters.

Ports

Constant	Values
OUTPUT_PORT	`output1`, `output2`, `output3`, `output4`
RELAY_PORT	`relay1`, `relay2`, `relay3`, `relay4`, `relay5`, `relay6`, `relay7`, `relay8`
MOTOR_PORT	`motor1`, `motor2`, `motor3`, `motor4`, `outputs`
LED_PORT	`led1`, `led2`, `led3`, `led4`, `led5`, `led6`, `led7`, `led8`, `led9`, `led10`, `led11`, `led12`
LOGICOP_PORT	`logicop1`, `logicop2`, `logicop3`, `logicop4`
BINSENSOR_PORT	`binsensor1`, `binsensor2`, `binsensor3`, `binsensor4`, `binsensor5`, `binsensor6`, `binsensor7`, `binsensor8`

The MOTOR_PORT values specify which hardware relay or outputs configuration will be used:

Motor	Relay on/off	Relay up/down
`motor1`	`relay1`	`relay2`
`motor2`	`relay3`	`relay4`
`motor3`	`relay5`	`relay6`
`motor4`	`relay7`	`relay8`

Motor	Output up	Output down
`outputs`	`output1`	`output2`

Variables and Units

Constant	Values
VARIABLE	`var1`, `var2`, `var3`, `var4`, `var5`, `var6`, `var7`, `var8`, `var9`, `var10`, `var11`, `var12`, `tvar`, `r1var`, `r2var`
SETPOINT	`r1varsetpoint`, `r2varsetpoint`
THRESHOLD	`thrs1`, `thrs2`, `thrs3`, `thrs4`, `thrs5`, `thrs2_1`, `thrs2_2`, `thrs2_3`, `thrs2_4`, `thrs3_1`, `thrs3_2`, `thrs3_3`, `thrs3_4`, `thrs4_1`, `thrs4_2`, `thrs4_3`, `thrs4_4`
S0_INPUT	`s0input1`, `s0input2`, `s0input3`, `s0input4`
VAR_UNIT	`native`, `°C`, `°K`, `°F`, `lux_t`, `lux_i`, `m/s`, `%`, `ppm`, `volt`, `ampere`, `degree`
TIME_UNIT	`seconds`, `minutes`, `hours`, `days`
RELVARREF	`current`, `prog`
REVERSE_TIME	`rt70`, `rt600`, `rt1200`

States:

Constant	Values
LED_STATE	`on`, `off`, `blink`, `flicker`
LOGICOP_STATE	`not`, `or`, `and`
KEY_STATE	`hit`, `make`, `break`, `dontsend`

Keys:

Whenever a key has to be provided, it is defined by a joint string consisting of the table identifier (a, b, c, d) and the corresponding key number. Examples: a1, a5, d8.

Platforms

Binary Sensor

The lcn binary sensor platform allows the monitoring of the following LCN binary data sources:

Binary hardware sensors
Lock state of regulator setpoints
Lock state of keys

The binary sensor can be used in automation scripts or in conjunction with template platforms.

Climate

The lcn climate platform allows the control of the LCN climate regulators. This platform depends on the correct configuration of the module’s regulators, which has to be done in the LCN-PRO programming software. You need to specify at least the variable for the current temperature and a setpoint variable for the target temperature. If the control is set lockable, the regulator can be turned on/off.

If you intend to leave the regulation to Home Assistant, you should consider using the Generic Thermostat in conjunction with LCN Sensor and LCN Switch.

Cover

The lcn cover platform allows the control of LCN relays and output ports which have been configured as motor controllers.

Only for the module with firmware earlier than 190C:
The configuration allows the optional definition of reverse time. This is the time which is waited during the switching of the motor currents. The reverse time should only be defined when using the MOTOR_PORT value OUTPUTS. For all other configuration, the reverse time has to be defined in the LCN Pro software. For the reverse time, you may choose one of the following constants: RT70 (70ms), RT600 (600ms), RT1200 (1,2s).

If you are using the module's output ports for motor control, ensure that you have configured the output ports as motor controllers in the LCN Pro software! Otherwise, the output ports are not mutually interlocked and you run the risk of destroying the motor.

Light

The lcn light platform allows the control of the following LCN ports:

(Dimmable) output ports
Relays

Scene

The lcn scene platform allows the activation of previously programmed LCN scenes.

Sensor

The lcn sensor platform allows the monitoring of the following LCN data sources:

Variables
Regulator setpoints
Thresholds
S0 inputs
LED states
Logic operation states

The sensor can be used in automation scripts or in conjunction with template platforms.

Ensure that the LCN module is configured properly to provide the requested value. Otherwise, the module might show unexpected behavior or return error messages.

Switch

The lcn switch platform allows the control of the following LCN ports:

Output ports
Relays

Services

In order to directly interact with the LCN system, and invoke commands which are not covered by the implemented platforms, the following service calls can be used. Refer to the (Services Calls)[/docs/scripts/service-calls] page for examples on how to use them.

Service output_abs

Set absolute brightness of output port in percent.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`output`	No	Output port of module	OUTPUT_PORT
`brightness`	Yes	Absolute brightness in percent	0..100
`transition`	Yes	Transition (ramp) time in seconds	0..486

Example:

service: output_abs
data:
  address: myhome.0.7
  output: output1
  brightness: 100
  transition: 0

Service output_rel

Set relative brightness of output port in percent.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`output`	No	Output port of module	OUTPUT_PORT
`brightness`	Yes	Relative brightness in percent	-100..100
`transition`	Yes	Transition (ramp) time in seconds	0..486

Example:

service: output_rel
data:
  address: myhome.0.7
  output: output1
  brightness: 30

Service output_toggle

Toggle output port.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`output`	No	Output port of module	OUTPUT_PORT
`transition`	Yes	Transition (ramp) time in seconds	0..486

Example:

service: output_toggle
data:
  address: myhome.0.7
  output: output1
  transition: 0

Service relays

Set the relays status. The relays states are defined as a string with eight characters. Each character represents the state change of a relay (1=on, 0=off, t=toggle, -=nochange).

Example states: t---001-

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`state`	No	Relay states as string

Example:

service: relays
data:
  address: myhome.0.7
  state: t---001-

Service led

Set the LED status.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`state`	No	LED state as string	LED_STATE

Example:

service: led
data:
  address: myhome.0.7
  led: led6
  state: blink

Service var_abs

Set the absolute value of a variable or setpoint. If value is not defined, it is assumed to be 0. If unit_of_measurement is not defined, it is assumed to be native.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`variable`	No	Variable name	VARIABLE, SETPOINT
`value`	Yes	Variable value	any positive number
`unit_of_measurement`	Yes	Variable unit	VAR_UNIT

Example:

service: var_abs
data:
  address: myhome.0.7
  variable: var1
  value: 75
  unit_of_measurement: %

Ensure that the LCN module is configured properly to provide acces to the defined variable. Otherwise the module might show unexpected behaviors or return error messages.

Service var_rel

Set the relative value of a variable or setpoint. If value is not defined, it is assumed to be 0. If unit_of_measurement is not defined, it is assumed to be native.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`variable`	No	Variable name	VARIABLE, SETPOINT, THRESHOLD
`value`	Yes	Variable value	any positive or negative number
`unit_of_measurement`	Yes	Variable unit	VAR_UNIT

Example:

service: var_rel
data:
  address: myhome.0.7
  variable: var1
  value: 10
  unit_of_measurement: %

Ensure that the LCN module is configured properly to provide access to the defined variable. Otherwise the module might show unexpected behavior or return error messages.

Service var_reset

Reset value of variable or setpoint.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`variable`	No	Variable name	VARIABLE, SETPOINT

Example:

service: var_reset:
data:
  address: myhome.0.7
  variable: var1

Ensure that the LCN module is configured properly to provide access to the defined variable. Otherwise the module might show unexpected behavior or return error messages.

Service lock_regulator

Locks a regulator setpoint. If state is not defined, it is assumed to be False.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`setpoint`	No	Setpoint name	SETPOINT
`state`	Yes	Lock state	true, false

Example:

service: lock_regulator
data:
  address: myhome.0.7
  setpoint: r1varsetpoint
  state: true

Service send_keys

Send keys (which executes bound commands). The keys attribute is a string with one or more key identifiers. Example: a1a5d8 If state is not defined, it is assumed to be hit. The command allows the sending of keys immediately or deferred. For a deferred sending the attributes time and time_unit have to be specified. For deferred sending, the only key state allowed is hit. If time_unit is not defined, it is assumed to be seconds.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`keys`	No	Keys string
`state`	Yes	Keys state	KEY_STATE
`time`	Yes	Deferred time	0..
`time_unit`	Yes	Time unit	TIME_UNIT

Examples:

Send keys immediately:

service: send_keys
data:
  address: myhome.0.7
  keys: a1a5d8
  state: hit

Send keys deferred:

service: send_keys
data:
  address: myhome.0.7
  keys: a1a5d8
  time: 5
  time_unit: s

Service lock_keys

Locks keys. If the table is not defined, it is assumed to be table a. The key lock states are defined as a string with eight characters. Each character represents the state change of a key lock (1=on, 0=off, t=toggle, -=nochange). The command allows the locking of keys for a specified time period. For a time period, the attributes time and time_unit have to be specified. For a time period, only table a is allowed. If time_unit is not defined, it is assumed to be seconds.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`table`	Yes	Table with keys to lock
`state`	No	Key lock states as string	KEY_STATE
`time`	Yes	Time period to lock	0..
`time_unit`	Yes	Time unit	TIME_UNIT

Examples:

Lock keys forever:

service: lock_keys
data:
  address: myhome.0.7
  table: a
  state: 1---t0--

Lock keys for a specified time period:

service: lock_keys
data:
  address: myhome.0.7
  state: 1---t0--
  time: 10
  time_unit: s

Service dyn_text

Send dynamic text to LCN-GTxD displays. The displays support four rows for text messages. Each row can be set independently and can store up to 60 characters (encoded in UTF-8).

Service data attribute	Optional	Description
`address`	No	LCN address
`row`	No	Text row 1..4
`text`	No	Text to send for the specified row

Example:

service: dyn_text
data:
  address: myhome.0.7
  row: 1
  text: "text in row 1"

Service pck

Send arbitrary PCK command. Only the command part of the PCK command has to be specified in the pck string.

Service data attribute	Optional	Description	Values
`address`	No	LCN address
`pck`	No	PCK command

Example:

service: pck
data:
  address: myhome.0.7
  pck: PIN4