Skip to content

A3KSA/s7-knx

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

83 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Issues MIT License


Logo

S7-KNX

Gateway for communicating between Siemens S7 PLCs and KNX
· Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage

About The Project

This project was made to allow interactions between Siemens S7 PLCs and the KNX bus.

(back to top)

Built With

  • NodeJS

(back to top)

Getting Started

Prerequisites

You need NodeJS and NPM to run this project. Tested with node v18.19.0 and v20.11.0 (current LTS)

See NodeJS-inst-url

Installation

  1. Clone the repo
    git clone https://github.com/A3KSA/s7-knx.git
  2. Install NPM packages
    npm install
  3. Set up your .env
     KNX_IP=192.168.1.100
     KNX_PORT=3671
     KNX_ADDRESS=15.15.15
     KNX_MIN_DELAY=10
     KNX_MANUAL_CONNECT=false
     DEBUG='s7-knx:*'
     SEND_AT_START=false
     S7_READ_INTERVAL=100
     S7_IP=10.10.6.159
     S7_DB=10
     S7_START_OFFSET=2
    
  4. Set up your S7 project with the given UDT and DB
  5. Start
    npm start

(back to top)

Usage

The configuration is made through the env variable. Since this project require dotenv, you can create a .env file with the above variable and it will be imported automatically.

The SEND_AT_START (send actual S7 value directly to the bus at launch) is not currently supported but will be in the future.

For the gateway to work, you need to use the given user data type in the resources folder. You can also find an exemple DB. The DB should always start with an Int specifiyng the DB size.

You can use the following code in your S7 project to update it dynamically :

   AUF   "KNX"
   L DBLG
   T     "KNX".DB_SIZE

UDT description

You need a row in the PLC's DB for each telegram. For the moment there is a generic UDT and one for the DPT232.

The UDT define the structure with the necessary data and variable for a telegramm to be sent or received.

Generic UDT

Line Description Exemple
GA KNX Group Address 0107064
Type KNX Datapoint type 1
READ_ONLY If true, it is not sent to KNX false
WRITE_ONLY If true, it is not read from KNX false
SEND_REQ Request sending to KNX true
SEND_ACK Acknowledge of the sending request false
val_bool Value from KNX if set to type 1 true
val_int Int value from KNX if type 5 10
val_real Real value from KXN if type 9, 14 42.5

UDT for KNX DPT 232 (RGB)

Line Description Exemple
GA KNX Group Address 0107064
Type KNX Datapoint type 1
READ_ONLY If true, it is not sent to KNX false
WRITE_ONLY If true, it is not read from KNX false
SEND_REQ Request sending to KNX true
SEND_ACK Acknowledge of the sending request false
byte_0 Red hex value FF
byte_0 Green hex value 06
byte_0 Blue hex value AA

Group Address (GA)

The group address in KNX is represented with slash : 01/07/064. The max value for a GA is 15/07/255, in the db it will be represented as 1507255. Always add the missings 0 so the gateway know how to translate the main/middle/sub value (00/00/000).

SEND_REQ and SEND_ACK

Setting the SEND_REQ to true will tell the gateway to send the value to KNX even if the value asn't changed. The gateway then set SEND_ACK to true to tell the PLC it was sent. It is the PLC responsability to set those two flags to false at the next cycle.

Data type and conversion

Datapoint KNX size KNX Type S7 Equivalent S7 Size Type Supported
DPT1 1 bit Up/Down... Bool 1 bit 1 Yes
DPT2 1 bit Control Bool 1 bit 1 Yes
DPT3 4 bit dimming/blind 8 bit No
DPT4 8 bit Character 8 bit No
DPT5 8 bit UInt Unsigned value UInt 16 bit 5 Yes*
DPT6 8 bit Int Signed value Int 16 bit No
DPT7 16 bit UInt Unsigned value UInt 16 bit No
DPT8 16 bit Int Signed value Int 16 bit No
DPT9 16 bit float Float Real 32 bit 9 Yes*
DPT10 24 bit time Time DWord 32 bit No
DPT11 24 bit date Date DWord 32 bit No
DPT12 32 bit UInt Unsigned value UDint 32 bit No
DPT13 32 bit Int Signed value DInt 32 bit 13 Yes
DPT14 32 bit float Float Real 32 bit 14 Yes
DPT15 32 bit Unsigned value UDInt 32 bit No
DPT16 14 byte 14 char string String 640 bit No
DPT17 8 bit UInt Scene number 8 bit No
DPT18 8 bit UInt Scene control 8 bit No
DPT19 8 byte date & time Date and time LWord No
DPT232 3 byte RGB 3 byte 232 Yes
  • The value from the PLC should not exceed the size of the KNX DPT.

Since a complete word is used in the PLC for each variable, we will store them in a full word for simplicity. A feature to cap the max value in the gateway to prevent error should be added in the next version.

(back to top)

Roadmap

  • Add support for multiple KNX connection
  • Add the SEND_AT_START feature
  • Limit value that could be out of range and throw necessary message
  • Add new type
  • Improve logging (debug, trace, info...)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Zacharie Monnet - zacharie.monnet@automation3000.ch

Project Link: https://github.com/A3KSA/s7-knx

(back to top)