Getting started: Home Assistant and TwinCAT

Welcome at this Getting started: ‘Home Assistant and TwinCAT’!

With great opensource projects like Home Assistant and OpenHAB, home automation becomes more and more accessible for everyone interested. Buy yourself a PI and you’re good to go. For your sensors and actuators you could use the the GPIO of the Raspberry PI or go for wireless products with, for example, a ZWAVE or ZIGBEE interface. However when your projects start to grow you’ll find that the GPIO of the PI are limited. And that having a battery in each wireless sensor wasn’t such a great idea after all..

A good alternative here is the use of a PLC. With modular systems like Wago or Beckhoff you have industrial reliability with practical unlimited expansion options. Agreed, the starting costs for a PLC will be higher but the IO modules are not too expensive and you can get yourself good deals on Ebay.

In this post I’ll show how to get started with Home Assistant and TwinCAT, a soft PLC system from Beckhoff.
One of the great things of Beckhoff is that all engineering software is free available. And run-time licenses can unlimited be renewed with 7 days trials.

Used hardware:

For this post I made use of this hardware:

HP server with windows 2012 R2. Acts (among other jobs) as host for Home Assistant.
IPC C6015 from Beckhoff which will be our PLC. The IPC has Windows 10 IOT installed and TwinCAT 3 4022.
EtherCAT bus coupler EK1100
- EL1008 – 8 channel digital input.
  - a button connected to channel 1
- EL2008 – 8 channel digital output.
  - a green led connected to channel 1
- EL3314 – 4 Channel thermouple input (temperature measurement).
  - J-Thermocouple connected to channel 1.

Network

The devices of course need to communicate with each other. The main component here is an ordinary ethernet router with WIFI. The Home Assistent server and the PLC are both physically wired to to router. The users can access the Home Assistant interface using either a wired or wireless ethernet connection. The communication between the bus coupler and the PLC goes over an EtherCAT network. Typically in home networks the router will also be your DHCP server and access point for internet.

Setting up the Home Assistant server

Of course we will need to install Home Assistant. In this case at a Windows system. A good description can be found here. Second step is the installation TwinCAT ADS which is the communication protocol for the communication between the Home Assistant server and the PLC. TwinCAT ADS can be downloaded here. After installing TwinCAT ADS on the server add a route between the server and the PLC.

Step 1: Read a temperature

To read a value from the temperature sensor I’ve created a new PLC project in TwinCAT. I added the hardware and linked channel 1 from the thermocouple input module to the variable ‘ai_RoomTemperature’ in the main program.

To read the sensor value with Home Assistant we can use the ADS platform of Home Assistant. Add the following code to your configuration.yaml:

ads:
  device: 'xxx.xxx.xxx.43.1.1'
  port: 851

sensor:
  - platform: ads
    name: RoomTemperature
    adsvar: MAIN.ai_RoomTemperature
    adstype: int

  - platform: template
    sensors:
      roomtemperaturecelcius:
        friendly_name: "Living room temperature"
        unit_of_measurement: '°C'
        value_template: "{{ states('sensor.RoomTemperature')|float / 10 }}"

In this configuration we configure the ADS integration. Make sure that you specify your unique NET ID. Secondly we add a sensor using the ADS platform, pointing to our added temperature variable of type INT. Located in the MAIN program.

The Beckhoff EL3314 thermocouple module delivers the temperature in integer format in °C multiplied by 10, hence the third step is to convert this value with the template platform to a floating point value in degrees Celsius.

Alternative: if you only have a simple factor you could also make use of the integrated ADS sensor option ‘factor’.

Add the new sensor to the LoveLace UI and here we go:

Step 2: Set a light

The second step is to set a light and controll the brightness. I connected a LED to the digital output at channel 1 and added some variables and code to the PLC main program to control the LED’s brightness:

PROGRAM MAIN
VAR
	ai_RoomTemperature AT %I* : INT;
	
	oLedGreen AT %Q* : BOOL; //Link to digital output.
	LedGreen : BOOL; //Enable bit for LED, linked with HA.
	LedGreenBrightness : UINT; //LED brightness, linked with HA.
	PWMCounter : INT; //PWM counter to set brightness.
END_VAR

PWMCounter := PWMCounter + 1;
IF PWMCounter = 10 THEN PWMCounter := 0; END_IF
IF LedGreen AND PWMCounter › LedGreenBrightness / 255.0 * 10 THEN
	oLedGreen := TRUE;
ELSE
	oLedGreen := FALSE;
END_IF

The code contains a software PWM generator to control the brightness in ten steps. Note that this is really only code for testing purposes and only works properly with a high PLC cycle frequency to prevent visible flickering. In a real application you probably want to use some sort of slave dimmer or even a DMX system.

To setup the LED in Home Assistant extend the Configuration.yaml with the following code:

light:
  - platform: ads
    adsvar: MAIN.LedGreen
    adsvar_brightness: MAIN.LedGreenBrightness
    scan_interval: 10

Utilizing the previously setup ADS platform we add a light entity to the Home Assistant configuration which we can add in the LoveLace UI:

The light brightness is converted to an 8 bit value (0..255). Which makes the set 50% in the UI correspond with the PLC value 127 in ‘LedGreenBrightness’. If the light is switched on the value in ‘LedGreenBrightness’ is in the PLC program translated to a PWM wave on the output oLedGreen.

Step 3: Read a button input

Last example, reading a digital input like a door switch, presence detection or in our case reading a button input. I added one more variable to the MAIN program: ‘iButtonTurnLightOn’ which is linked to the physical input at channel 1.

PROGRAM MAIN
VAR
	ai_RoomTemperature AT %I* : INT;
	
	oLedGreen AT %Q* : BOOL; //Link to digital output.
	LedGreen : BOOL; //Enable bit for LED linked with HA.
	LedGreenBrightness : UINT; //LED brightness linked with HA.
	PWMCounter : INT; //PWM counter to set brightness.
	
	iButtonTurnLightOn AT %I* : BOOL; // Link to digital input.
END_VAR

To read the binary sensor in Home Assistent we will use the ‘Binary Sensor’ platform. Add the following code to Configuration.yaml :

binary_sensor:
  - platform: ads
    adsvar: MAIN.iButtonTurnLightOn

And add the sensor to your LoveLace UI:

Conclusion

I hope this post got you started using Home Assistent and TwinCAT. Making full use of the reliability and flexibility of industrial PLC’s. Some side notes I want to mention:

The ADS communicatie heavily relies on this pyads library. I started off using python V3.8.0. which threw me the exception ‘Could not find module ‘TcAdsDll’. This is a known issue and can for the time being be solved by using Python V3.7.5.
I used a windows server because that what I have available, however according the documentation it should not be a problem running this on a Linux based system.

That was it for now, let me know your thoughts or just show your PLC projects here.

Happy coding!