LK ICS2 GW CLIENT NODERED

Interface for LK ICS2, floor heating room temperature regulator. https://www.lksystems.se/en/produkter/lk-golvvarme/produktsortiment/rumsreglering/ics.2-tradforbundentradlos/

This SW is currently a Modbus TCP gateway and MQTT client, developed in Node-red primarily targeting raspberry pi 3, should work on any raspberry version or Linux PC.

Should work with Raspberry PI RS485 HAT or any generic RS485 to USB or UART converter

Ready to use Raspberry image: v0.1.0

INSTALL - Generic

Note: For raspberry see Raspberry install

1. Install node-red

2. Checkout this repo in home folder (i.g. ~/LK_ICS2_GW_CLIENT_NODERED)

3. replace node red files with symlinks:

   cd ~/.node-red
   rm package.json package-lock.json settings.js
   ln -s ../LK_ICS2_GW_CLIENT_NODERED/package.json
   ln -s ../LK_ICS2_GW_CLIENT_NODERED/package-lock.json
   ln -s ../LK_ICS2_GW_CLIENT_NODERED/settings.js   

   Note: in ~/.node-red/settings.js dark theme has been set and flowfile is now set to:

   - flowFile: "flows.json",
   + flowFile: "../LK_ICS2_GW_CLIENT_NODERED/flows.json",   

4. To be able to run the TCP GW on standard modbus port 502

   • Add the following to: /lib/systemd/system/nodered.service

     # Allow binding to priviledged ports, ig 502 for modbus
     CapabilityBoundingSet=CAP_NET_BIND_SERVICE
     AmbientCapabilities=CAP_NET_BIND_SERVICE
     #NoNewPrivileges=true

   • run this command:

     sudo setcap 'cap_net_bind_service=+ep' $(eval readlink -f `which node`)

5. Install npm package dependencies listed in packages.json (requires a node-red restart)

   cd ~/.node-red/
   npm install
   systemctl restart nodered   

   Alternatively Install the node packages / modules from inside the node-red web editor ():

   • node-red-contrib-modbus
   • node-red-contrib-xlsx-to-json
   • @node-red-contrib-themes/theme-collection (for use of dark theme)
   • node-red-dashboard
   • node-red-node-ui-list
   • node-red-node-ui-table
   • node-red-node-serialport

   Note: can also alternatively be installed individually from command line (requires a node-red restart)

   cd ~/.node-red/
   npm install [package name]
   systemctl restart nodered   

configuration

• LKICS2 dashboard: http://lkics2.local:1880/ui

  • One tab for watching read values
  • One tab for admin:
    • set Modbus device
    • adding polling registers
    • mqtt settings
    • saving config changes to SD card
    • writing to registers

• node-red web editor: http://lkics2.local:1880 (used for code changes)

Raspberry PI

Raspberry install

1. Either download the pre-built img file or see: Raspberry setup from scratch
2. Either flash with Raspberry Pi Imager
3. Or manually flash with dd, i.g.:

dd if=LKICS2-raspios-bullseye-armhf-lite.img of=/dev/mmcblk0

4. Follow Raspberry PI wifi config
5. Update the code from github, ssh into the PI and:

   cd LK_ICS2_GW_CLIENT_NODERED
   git pull

Raspberry PI wifi config

wifi can be set up in many different ways:

• In imager flashing tool advanced menu: ctrl+shift+x

• Use raspi-config commandline tool i.e. from ssh or hooking up to dispaly and keyboard.

• After flashing the raspberry image to SD card, mount the SD card and edit /etc/wpa_supplicant/wpa_supplicant.conf, add wifi info i.g:

  country=SE
  network={
    ssid="your ssid"
    psk="your wifi password"
    key_mgmt=WPA-PSK
  }

  Make sure to set your correct country code, see ISO Country Code.

• It is also possible to put wifi config on boot partition and it will be copied automatically on boot, see: https://www.raspberrypi.com/news/another-update-raspbian/

  If a wpa_supplicant.conf file is placed into the /boot/ directory, this will be moved to the /etc/wpa_supplicant/ directory the next time the system is booted, overwriting the network settings; this allows a Wifi configuration to be preloaded onto a card from a Windows or other machine that can only see the boot partition.

Raspberry setup from scratch

1. Download standard raspios image, i.g. https://downloads.raspberrypi.org/raspios_lite_armhf/images/raspios_lite_armhf-2022-01-28/2022-01-28-raspios-bullseye-armhf-lite.zip
2. Follow node-red on raspberry install guide: https://nodered.org/docs/getting-started/raspberrypi
3. Continue with: Install generic, step 2

Troubleshooting

• Raspberry Wifi - make sure to set country code in wifi config. If still not working check that wifi is not blocked and manually unblock

  pi@LKICS2:~/ $ rfkill list
  0: phy0: Wireless LAN
    Soft blocked: yes
    Hard blocked: no
  
  pi@LKICS2:~/ $ sudo rfkill unblock wifi

• QEMU blank screen with spice: select view --> text consoles --> text console

Links

• www.lksystems.se
• Raspberry PI Documentation

TODO

• Update Documentation, add HW modbus info e.t.c.
• Refactor - cleanup model for readability e.t.c.
• Convert PI installation to read only mounted filesystem (for dependability and lifetime of SD-card)
• Implement writing registers by mqtt
• implement dynamic UI setting of unitid/slaveid and baudrate e.t.c.
• UI improvements

DEVELOPMENT

Development in docker

Note: This is much faster than developing in QEMU or on target. The docker environment is set up to run the python emulator and use it in the config file.

From the git repo folder, i.e. ~/LK_ICS2_GW_CLIENT_NODERED

1. Build container: docker build -t lkics2/node-red .
2. Create container: docker run -it -p 1880:1880 -v [absolute path to LK_ICS2_GW_CLIENT_NODERED]:/LK_ICS2_GW_CLIENT_NODERED --name lkics2-nodered lkics2/node-red
   Notes:
   • This will mount the git repo as /LK_ICS2_GW_CLIENT_NODERED inside docker
   • change volume path to where you have the git repo checked out.
   • If container already exists use start and exec commands below instead, or first remove the container: docker rm lkics2-nodered

• to start existing container: docker start -ai lkics2-nodered
• to start a new shell on a running instance of the container: docker exec -it lkics2-nodered /bin/bash
• to get logs from the container: docker logs lkics2-nodered

Python modbus emulator for testing

• install python3 modules dependencies (i.g. using pip install):
  • pyserial
  • pymodbus
  • openpyxl
• Start emulator with: python ModbusRtuEmulator.py [--updateconfig] [--debug] (see --help, emulator can update config file with correct serial terminal device)

Homeassistant docker for testing

It is very easy and quick to use homeassistant docker image for verification, follow: https://www.home-assistant.io/installation/linux/#install-home-assistant-container

Howto run raspberry image under qemu for local dev on PC

Note: this is slow, consider using Development in Docker instead!

1. Follow this guide: https://linuxconfig.org/how-to-run-the-raspberry-pi-os-in-a-virtual-machine-with-qemu-and-kvm
2. Download qemu raspberry kernel image: https://github.com/dhruvvyas90/qemu-rpi-kernel