SystaPi, SystaREST and STouchREST

^Code:
^Checks:
^Repo:

SystaPi, SystaREST and STouchREST

The goal of SystaPi is to make the Paradigma SystaComfort "smart" by providing Rest APIs for integration with home automation systems.
It is developed based on Raspberry Pi, but you should easily get it running on any Linux you like.
The project contains an installation script to setup a Raspberry Pi as SystaPi, which runs the SystaREST server. SystaREST server provides two services, SystaRESTAPI for reading values from the SytsaComfort unit and STouchRESTAPI for writing to the SystaComfort, e.g. selecting the operation mode.
Important Note: The communication protocols use by the SystaComfort unit are not publicly documented! Everything here is based on reverse engineering and will only work for systems that are used by contributors. Therefore, please contribute information from your system!

This project is inspired by this post on the VDR portal Heizungssteuerung: Daten auslesen and I also used some information from the SystaComfortPrometheusExporter.

Build with a Raspberry Pi Zero WH and ENC28J60 Ethernet HAT, the SystaPi fits easily into the housing of the Paradigma SystaComfort.

Project Status
Getting Started
Directory Structure of this Project
Parts List
Installation
The SystaREST API
- findsystacomfort
- start
- stop
- servicestatus
- rawdata
- dashboard
- monitorrawdata
- waterheater
- status
- enablelogging
- disablelogging
The STouchREST API
- connect
- disconnect
- touch
- screen
- debugscreen
- objecttree
- hasbutton
- touchbutton
- hastext
- touchtext
- automation
Contribute
Known Issues
Links

Project Status

This project is updated irregularly or provided with new features.

Latest Release: 3.0 "S-Touch"
Changes on main:
- fix for FakeSTouch UDP password encoding issue
- fix for helpers/update.sh on wrong handling the link to the folder on the boot partition
- stouchrest/objecttree returns now a JSON object
- added two new endpoints stouchrest/hastext and stouchrest/hasbutton for simplified queries of the screen content
Future Development: New releases are always prepared on the main branch. If you want to get a sneak peek on it, check it out and contribute your test results. You can also update your running version to main, by executing helpers/update.sh -b main but you should backup you system before that.
Known Limitations: Compatibility with any SystaComfort software or Raspberry Pi OS versions is not guaranteed. See Known Issues and Contribute for more details.

Getting Started

This quick guide is for using SystaPi just as it is meant to be.

Hardware: Use any Raspberry Pi, best support is given for the Hardware Components that I use.
Installation:
- Recommended: Follow the installation instructions for Linux if you are comfortable with it, as it provides an automated setup script.
- Alternative: Use the Windows / manual installation guide for more control or if you're not using Linux for the setup.
Accessing the API:
- You should then be able to access the SystaREST server's WADL at http://systapi:1337/application.wadl?detail=true (or using the Pi's IP address if hostname resolution isn't working).
- Explore the SystaREST API and STouchREST API sections to understand how to query data and control your system. The curl examples are a good starting point.
- The dashboard (http://systapi:1337/SystaREST/dashboard) provides a web interface to view data.
Home Automation Integration: Use the REST APIs to integrate with your preferred home automation system (e.g., Home Assistant, OpenHAB). Please share your work by opening a discussion on it.

For developers or those wishing to understand the project structure deeply, please see DEVELOPMENT.md, protocols.md and the Contribute sections.

Directory Structure of this Project

^{[Back to Contents]}

SystaPi
├── docs                 # JavaDoc for the SystaRESTServer, best accessed via https://beep-projects.github.io/SystaPi/
├── helpers              # collection of resources that are helpful for reverse engineering the SystaComfort protocol
│                        # or setting up systapi
├── install_systapi.sh   # Script for automatically downloading, flashing and configuring 
│                        # a Micro SD card for running the SystaREST server
├── LICENSE              # License for using and editing this software
├── README.md            # This file
├── resources            # folder for images or other files linked with README.md
├── SystaPi_files        # files required for configuring a Raspberry Pi OS image to run the SystaRESTAPI server
│   ├── cmdline.txt      # file to be placed under /boot/cmdline.txt on the pi. Triggers the execution of firstrun.sh
│   │                    # on first boot (actually the second one, after resizing the image)
│   ├── firstrun.sh      # script for configuring WiFi, keyboard and timezone. You have to configure a few things in here!
│   ├── secondrun.sh     # called after a reboot. Should have network running. Does a full-upgrade of the system, 
│   │                    # installs required packages (dnsmasq, OpenJDK) and the SystaRESTAPI.service
│   └── thirdrun.sh      # called after a reboot. Cleans up after the installation and reboots into the final system
└── SystaRESTServer      # Java based server for providing a REST API for a Paradigma SystaComfort unit
    ├── bin              # precompiled .class files for running the SystaRESTAPI server
    ├── build.sh         # build file for compiling SystaRESTServer
    ├── build_test.sh    # build file for building the JUnit test run at each commit
    ├── lib              # .jar files required for running the server
    └── src              # src files of the server, for everyone who wants to improve this

Parts List

^{[Back to Contents]}

This is what I am using for this project, but any Raspberry Pi with at least one Ethernet interface and a second WiFi or Ethernet interface should do the job. The required size of the Micro SD card depends on the amount of data you want to log. Logging data of one day requires ~100 MB.

Raspberry Pi Zero WH
ENC28J60 Ethernet HAT
Micro SD card >256MB
Micro USB Powersupply 5V / 1A

Of course you also need a Paradigma SystaComfort or Paradigmy SystaComfort II. The following are the paradigma software versions that I succesfully used with SystaPi (#1, #2) or that where reported to work (#3)

	#1	#2	#3
SystaComfort	`V1.14 8.08.14`	`V1.26 10.02.20`	`V1.12 20.05.14`
System	`V2.09.2`	`V2.16.1`	`V2.09.1`
Basis	`V0.23`	`V0.34`	`V0.23`

Installation

^{[Back to Contents]}

For easy installation I have created some scripts that configure the Raspberry Pi OS automatically on a Micro SD card. These scripts are not actively maintained, so they might stop working at some time. If auto configuration fails, step through the files firstrun.sh and secondrun.sh and run the commands manually on your systapi. Your are also welcome to fix the scripts and create a pull request to this repository.

Once the Micro SD card is prepared as described in the next sections, the scripts should do the following on first boot ups of the Raspberry Pi:

resize the Raspberry Pi OS partition to use the full size of the Micro SD card
configure WiFi on interface wlan0
apt full-upgrade the system
install dnsmasq
configure dnsmasq and dhcpd for IP spoofing on interface eth0
(this will make the Paradigma SystaComfort to communicate with systapi instead of SystaWeb)
install OpenJDK 11 from https://www.azul.com/downloads/?package=jdk#download-openjdk
(this is the most current one you can get for the ARMv6 of the Raspberry Pi Zero)
install the systemd service unit SytsaRESTServer.service for automatically starting the SystaRESTServer

SystaComfort

You have to make sure that your Paradigma SystaComfort unit is sending unencrypted data to paradigma.remoteportal.de. If you are one of the unlucky ones, that got a SystaComfort installed with encryption enabled, or the remote portal being disable, you have to get hold of the SystaService software. You can ask Paradigma for that, or your system installer. See also the instructions for setting up the SystaComfortPrometheusExporter english/german

Linux

^{[Back to Contents]}

Expand instructions

For Linux I provide a script that downloads Raspberry Pi OS and flashes it onto a Micro SD card. The script was mainly written out of curiosity to see how that could work. Iit has no added sanity checks and you should use it with care. Check each step, when asked to confirm. If unsure, follow the manual installation guide.

The script will first ask you for required configuration parameters and then download Systapi, configure it and flash it on a sd card. There are no specific checks done on execution, so it is best if you run the script in an isolated environment. The script will create a folder called temp and download all files there. After execution, you might want to delete that folder.

Download the installation script and run it

wget https://github.com/beep-projects/SystaPi/releases/latest/download/getAndConfigureSystaPi.sh
chmod 755 getAndConfigureSystaPi.sh
./getAndConfigureSystaPi.sh

Eject the Micro SD card and insert it into your Raspberry Pi
Don't connect the Raspberry Pi with an Ethernet cable to your Paradigma SystaComfort. If the setup of SystaPi is taking too long, the SystaComfort will autoconfigure an IP address and will not be able to communicate tith SystaPi
Power up the Raspberry Pi
Wait a while (~20 minutes, depending on the number of system updates available) and then try to load the WADL of the server: http://systapi:1337/application.wadl?detail=true For troubleshooting, you can check the progress by checking the logs. After 5 minutes the resize of the partitions and firstrun.sh should be finished, so that you can ssh into the systapi and watch the installation process. Default user is beep with password projects.
```
ssh -x [email protected]
tail -f /boot/secondrun.log
```
Connect the Raspberry Pi with an Ethernet cable to your Paradigma SystaComfort

Windows / manual installation

^{[Back to Contents]}

Expand instructions

Install Raspberry Pi OS following this guide. Raspberry Pi OS Lite is sufficient.
Download SystaPi
Extract the downloaded zip file
Change into the SystaPi_files subfolder of the extracted archive

Open firstrun.sh with a text editor and configure everything in the marked section to your liking. Most probably you want to use something like WPA PSK (Raw Key) Generator and add the generated credentials to the file. If you use the network 192.168.1.x for your local network, you should change the IP_PREFIX to another IP range, to avoid network collisions

#-------------------------------------------------------------------------------
#----------------------- START OF CONFIGURATION --------------------------------
#-------------------------------------------------------------------------------

# which hostname do you want to give your raspberry pi?
HOSTNAME=systapi
#username: beep, password: projects
#you can change the password if you want and generate a new password with
#Linux: mkpasswd --method=SHA-256
#Windows: you can use an online generator like https://www.dcode.fr/crypt-hasing-function
USER=beep
# shellcheck disable=SC2016
PASSWD='$5$oLShbrSnGq$nrbeFyt99o2jOsBe1XRNqev5sWccQw8Uvyt8jK9mFR9' #keep single quote to avoid expansion of $
# configure the wifi connection
# the example WPA_PASSPHRASE is generated via
#     wpa_passphrase MY_WIFI passphrase
# but you also can enter your passphrase as plain text, if you accept the potential insecurity of that approach
SSID=MY_WIFI
WPA_PASSPHRASE=3755b1112a687d1d37973547f94d218e6673f99f73346967a6a11f4ce386e41e
# define the network to use for communication between systapi and SystaComfort
# change if you use the same network range on your wifi network
IP_PREFIX="192.168.1"
# configure your timezone and key board settings
TIMEZONE="Europe/Berlin"
COUNTRY="DE"
XKBMODEL="pc105"
XKBLAYOUT=$COUNTRY
XKBVARIANT=""
XKBOPTIONS=""
# if you want to use an ENC28J60 Ethernet HAT, enable it here
ENABLE_ENC28J60=true

#-------------------------------------------------------------------------------
#------------------------ END OF CONFIGURATION ---------------------------------
#-------------------------------------------------------------------------------

Make sure that the boot-partition of the Micro SD card is accessible via file explorer
Open cmdline.txt from the Micro SD card and copy the root=PARTUUID=-Number over into the cmdline.txt in the SystaPi_files subfolder. If you do not do this step, your pi will not boot!
Copy all files from the SystaPi_files subfolder to boot-partition of the Micro SD card
Copy the SystaRESTServer and helpers folder and all of their contents to the boot-partition.
Eject the Micro SD card and insert it into your Raspberry Pi
Don't connect the Raspberry Pi with an Ethernet cable to your Paradigma SystaComfort. If the setup of SystaPi is taking too long, the SystaComfort will autoconfigure an IP address and will not be able to communicate tith SystaPi
Power up the Raspberry Pi
Wait a while (~20 minutes, depending on the number of system updates available) and then try to load the WADL of the server: http://systapi:1337/application.wadl?detail=true For troubleshooting, you can check the progress by checking the logs. After 5 minutes the resize of the partitions and firstrun.sh should be finished, so that you can ssh into the systapi and whatch the installation process.. Default user is beep with password projects.
```
ssh -x [email protected]
tail -f /boot/secondrun.log
```
Connect the Raspberry Pi with an Ethernet cable to your Paradigma SystaComfort

Troubleshooting the installation

^{[Back to Contents]}

The autoconfig of the Raspberry Pi OS always works fine when I do the commits to the repo. But if development of Raspberry Pi OS goes on, the scripts might break. If you connect the Raspberry Pi to a screen via HDMI, you will see if something gets wrong.
If the pi does not boot, check if you did step 7 in case of a manual installation.
If you do not know where the install script died on the Raspberry Pi, have a look into the /boot folder via ls /boot/*.log. Each script creates a log file, so check firstrun.log, secondrun.log and thirdrun.log, to see where the script failed.
SystaRESTServer is installed as a service on the raspberry pi. systemctl status SystaRESTServer.service will show you if the service is running or died for some reason

The SystaRESTServer

^{[Back to Contents]}

Per default, the SystaREST server is listening on port 1337, you can change this by editing /home/pi/SystaRESTServer/bin/SystaREST.properties. The hostname of the Raspberry Pi is set to systapi. There are two services running by default. The first one is SystaREST for reading values from a SystaComfort unit and the second one is STouchREST which emulates the S-Touch app for providing write access to the SystaComfort unit. The paths and method names on the REST server are implemented case insensitive. The root path for the both services are: systarest, or SystaREST and stouchrest, or STouchREST, or any variation of that. By default you should be able to access the server via http://systapi:1337/. This base URL will be used for the following examples and should work for most network configurations. If not, you have to replace systapi with the IP assigned to your server by the local router. The server provides a WADL of the provided API at: http://systapi:1337/application.wadl?detail=true

The SystaREST API

^{[Back to Contents]}

Expand API description

If a command is called which should retrieve data from the SystaREST, but the communication is not running, start is automatically called, but the reply will be empty until the first data packet is received from the Paradigma SystaComfort. Data packets are sent every minute.

findsystacomfort

GET /SystaREST/findsystacomfort http://systapi:1337/SystaREST/findsystacomfort
Searches the available interfaces for any attached SystaComfort unit.

curl "http://systapi:1337/SystaREST/findsystacomfort"

{
    "SystaWebIP":"192.168.11.1",
    "SystaWebPort":22460,
    "DeviceTouchBcastIP":"192.168.11.255",
    "DeviceTouchBcastPort":8001,
    "deviceTouchInfoString":"SC2 1 192.168.11.23 255.255.255.0 192.168.11.1 SystaComfort-II\u00000 0809720001 0 V0.34 V1.00 2CBE9700BEE9",
    "unitIP":"192.168.11.23",
    "unitName":"SystaComfort-II",
    "unitId":"0809720001",
    "unitApp":8,
    "unitPlatform":9,
    "unitVersion":"1.14.1",
    "unitMajor":114,
    "unitMinor":1,
    "unitBaseVersion":"V0.34",
    "unitMac":"2CBE9700BEE9",
    "STouchAppSupported":false,
    "DeviceTouchPort":-1,
    "DeviceTouchPassword":"null"
}

start

POST /SystaREST/start
start communication with the connected Paradigma SystaComfort

curl -X POST http://systapi:1337/SystaREST/start

stop

POST /SystaREST/stop
stop communication with the connected Paradigma SystaComfort

curl -X POST http://systapi:1337/SystaREST/stop

servicestatus

GET /SystaREST/servicestatus
http://systapi:1337/SystaREST/servicestatus
Returns the status of the SystaREST server

curl "http://systapi:1337/SystaREST/servicestatus"

{
    "connected":true,
    "running":true,
    "lastDataReceivedAt":"Wed-30.06.21-00:00:19",
    "packetsReceived":234,
    "paradigmaListenerIP":"192.168.1.1",
    "paradigmaListenerPort":22460,
    "paradigmaIP":"192.168.1.23",
    "paradigmaPort":8002,
    "loggingData":false,
    "logFileSize":60,
    "logFilePrefix":"SystaREST",
    "logFileDelimiter":";",
    "logFileRootPath":"/home/pi/SystaRESTServer/bin/",
    "logFilesWritten":0,
    "logBufferedEntries":60
}

rawdata

GET /SystaREST/rawdata
http://systapi:1337/SystaREST/rawdata
Returns the raw data received from the Paradigma SystaComfort with added timestamp information.

curl "http://systapi:1337/SystaREST/rawdata"

{
    "timestamp":1623836832,
    "timestampString":"Wed-16.06.21-09:47:12",
    "rawData":[
        250,
        273,
        277,
        736,
        650,
        565,
        -300,
        -300,
        -300,
        0,
        0,
        0,
        332,
        ... (250 entries) ...
    ]
}

dashboard

GET /SystaREST/dashboard
http://systapi:1337/SystaREST/dashboard

Returns a React-based HTML dashboard that displays the received data for the last 24h. On the bottom right of the dashboard, you can start the logging of data (log/stop), delete the log files on the SystaPi (del) and download all saved logs as zip file (zip). Call this function from your browser, to see something like:

monitorrawdata

GET /SystaREST/monitorrawdata
http://systapi:1337/SystaREST/monitorrawdata

Optional parameters:

theme default SystaREST other possible value systaweb

Returns a React-based HTML page for monitoring of the raw data received from the Paradigma SystaComfort. The content of the page should automatically refresh, but be aware that the SystaComfort sends its data only every minute, so parameter changes on the unit will be displayed with some lag. Call this function from your browser, to see something like:

http://systapi:1337/SystaREST/monitorrawdata		http://systapi:1337/SystaREST/monitorrawdata?theme=systaweb

waterheater

GET /SystaREST/waterheater
http://systapi:1337/SystaREST/waterheater
Returns the information for a Home Assistant Water Heater

curl "http://systapi:1337/SystaREST/waterheater"

{
    "min_temp":40.0,
    "max_temp":65.0,
    "current_temperature":71.0,
    "target_temperature":0.0,
    "target_temperature_high":85.0,
    "target_temperature_low":0.0,
    "temperature_unit":"TEMP_CELSIUS",
    "current_operation":"locked",
    "operation_list":[
        "off",
        "normal",
        "comfort",
        "locked"
    ],
    "supported_features":[
    ],
    "is_away_mode_on":false,
    "timestamp":1623675405,
    "timestampString":"Mon-14.06.21-12:56:45"
}

status

GET /SystaREST/status
http://systapi:1337/SystaREST/status
Returns all known fields from the received data.

curl "http://systapi:1337/SystaREST/status"

{
    "outsideTemp":7.9,
    "operationMode":0,
    "operationModeName":"Auto Prog. 1",
    "circuit1FlowTemp":42.9,
    "circuit1ReturnTemp":29.8,
    "circuit1FlowTempSet":44.2,
    "circuit1LeadTime":0,
    "hotWaterTemp":59.3,
    "hotWaterTempSet":50.0,
    "hotWaterTempNormal":50.0,
    "hotWaterTempComfort":60.0,
    "hotWaterTempMax":85.0,
    "hotWaterOperationMode":1,
    "hotWaterOperationModeName":"normal",
    "hotWaterHysteresis":5.0,
    "bufferTempTop":54.6,
    "bufferTempBottom":34.0,
    "bufferTempSet":44.2,
    "logBoilerFlowTemp":21.3,
    "logBoilerReturnTemp":17.9,
    "logBoilerBufferTempTop":-30.2,
    "logBoilerBufferTempMin":30.0,
    "logBoilerTempMin":65.0,
    "logBoilerSpreadingMin":100.0,
    "logBoilerPumpSpeedMin":60,
    "logBoilerPumpSpeedActual":0,
    "logBoilerSettings":19,
    "boilerOperationMode":0,
    "boilerOperationModeName":"off",
    "boilerFlowTemp":37.6,
    "boilerReturnTemp":37.6,
    "boilerTempSet":0.0,
    "boilerSuperelevation":0,
    "boilerHysteresis":5.0,
    "boilerOperationTime":5,
    "boilerShutdownTemp":40.0,
    "boilerPumpSpeedMin":25,
    "circulationTemp":-30.0,
    "circulationPumpIsOn":false,
    "circulationPumpOverrun":3,
    "circulationLockoutTimePushButton":15,
    "circulationHysteresis":5.0,
    "circuit2FlowTemp":-30.0,
    "circuit2ReturnTemp":-30.0,
    "circuit2FlowTempSet":44.2,
    "roomTempActual1":0.0,
    "roomTempSet1":20.0,
    "roomTempActual2":0.0,
    "roomTempSet2":0.0,
    "roomTempSetNormal":20.0,
    "roomTempSetComfort":22.0,
    "roomTempSetLowering":15.0,
    "roomImpact":0.0,
    "roomTempCorrection":0.0,
    "collectorTempActual":0.0,
    "swimmingpoolFlowTemp":0.0,
    "swimmingpoolFlowTeamp":0.0,
    "swimmingpoolReturnTemp":0.0,
    "heatingOperationMode":1,
    "heatingOperationModeName":"normal",
    "heatingCurveBasePoint":35.0,
    "heatingCurveGradient":1.3,
    "heatingLimitTemp":20.0,
    "heatingLimitTeampLowering":10.0,
    "heatingPumpSpeedActual":100,
    "heatingPumpOverrun":10,
    "heatingPumpIsOn":true,
    "heatingCircuitSpreading":20.0,
    "heatingPumpSpeedMin":100,
    "controlledBy":0,
    "controlMethodName":"external temp",
    "maxFlowTemp":70.0,
    "antiFreezeOutsideTemp":2.0,
    "heatUpTime":120,
    "mixerRuntime":2,
    "mixer1IsOnWarm":false,
    "mixer1IsOnCool":false,
    "mixer1State":0,
    "mixer1StateName":"off",
    "underfloorHeatingBasePoint":35.0,
    "underfloorHeatingGradient":1.3,
    "bufferTempMax":95.0,
    "bufferTempMin":0.0,
    "adjustRoomTempBy":0.0,
    "solarPowerActual":0.0,
    "solarGainDay":0.0,
    "solarGainTotal":0.0,
    "relay":2049,
    "chargePumpIsOn":false,
    "boilerIsOn":false,
    "burnerIsOn":false,
    "systemNumberOfStarts":26,
    "burnerNumberOfStarts":394,
    "boilerOperationTimeHours":234,
    "boilerOperationTimeMinutes":58,
    "unknowRelayState1IsOn":false,
    "unknowRelayState2IsOn":true,
    "unknowRelayState5IsOn":true,
    "error":65535,
    "operationModeX":0,
    "heatingOperationModeX":1,
    "timestamp":1640345997,
    "timestampString":"Fri-24.12.21-11:39:57"
}

enablelogging

PUT /SystaREST/enablelogging
enables the logging of each received data element to a delimited log file. To reduce the number of file writes, this function stores entriesPerFile data segments in memory and then writes them into a single file. If logging is not enabled, SystaREST still stores the last entriesPerFile data segments in memory and saves them to the disc as soon as logging gets enabled. This feature shall help to implement triggers for value changes of interest, by also saving data that has been received before the interesting event happened.

Optional parameters:

filePrefix default SystaREST
logEntryDelimiter default ;
entriesPerFile default `60

curl -X PUT "http://systapi:1337/SystaREST/enablelogging?filePrefix=SystaREST&logEntryDelimiter=;&entriesPerFile=1337"

disablelogging

PUT /SystaREST/disablelogging
stop the logging of received data packets. This writes all currently stored data segments to a file and stops the writing to disc.

curl -X PUT http://systapi:1337/SystaREST/disblelogging

The STouchREST API

Expand instructions

The STouchREST API emulates the S-Touch app to interact with the Paradigma SystaComfort system. It provides endpoints for connecting to the device, simulating touch events, retrieving the screen state, and automating sequences of actions.

connect

POST /stouchrest/connect
Establishes a connection to the SystaComfort unit.

curl -X POST http://systapi:1337/stouchrest/connect

Responses:
200 OK: Connection successful.
409 Conflict: Device is already in use or already connected.
401 Unauthorized: Wrong UDP password.
408 Request Timeout: Connection request timed out.
500 Internal Server Error: Unknown error.

disconnect

POST /stouchrest/disconnect
Disconnects from the SystaComfort unit.

curl -X POST http://systapi:1337/stouchrest/disconnect

Responses:
200 OK: Disconnection successful.
500 Internal Server Error: Error occurred during disconnection.

touch

POST /stouchrest/touch
Simulates a touch event at the specified coordinates on the screen.

Query Parameters:
x (int): The x-coordinate of the touch.
y (int): The y-coordinate of the touch.

curl -X POST "http://systapi:1337/stouchrest/touch?x=100&y=200"

Responses:
200 OK: Touch event simulated successfully.

screen

GET /stouchrest/screen
http://systapi:1337/STouchREST/screen
Retrieves the current screen as a PNG image.

curl -X GET http://systapi:1337/stouchrest/screen --output screen.png

Responses:
200 OK: Returns the screen image as a PNG.
500 Internal Server Error: Error processing the image.

debugscreen

GET /stouchrest/debugscreen
http://systapi:1337/STouchREST/debugscreen
Returns an interactive HTML page for debugging touch events on the screen. The HTML shows the current screen and a history of the touch events.

curl -X GET http://systapi:1337/stouchrest/debugscreen

Responses:
200 OK: Returns the HTML page for debugging.
500 Internal Server Error: Error processing the image.

objecttree

GET /stouchrest/objecttree
http://systapi:1337/STouchREST/objecttree
Returns the object tree of the current screen as a JSON object.

curl -X GET http://systapi:1337/stouchrest/objecttree

Responses:
200 OK: Returns the object tree as JSON.

hasbutton

GET /stouchrest/hasbutton
Returns true if the display of the FakeSTouch has a DisplayButton object with the given id in its objecttree.

curl -X GET "http://systapi:1337/stouchrest/hasbutton?id=1"

Query Parameters:
id (byte): The ID of the button to search for. Responses:

200 OK: Returns a JSON object with the result.

touchbutton

POST /stouchrest/touchbutton
Simulates a touch event on a button with the specified ID.

curl -X POST "http://systapi:1337/stouchrest/touchbutton?id=1"

Query Parameters:
id (byte): The ID of the button to touch. Responses:

200 OK: Button pressed successfully.
404 Not Found: Button with the specified ID not found.
500 Internal Server Error: Error while pressing the button.

hastext

GET /stouchrest/hastext
Returns true if the display of the FakeSTouch has a DisplayText object with the given string in its objecttree.

curl -X GET "http://systapi:1337/stouchrest/hastext?text=Hello"

Query Parameters:
text (String): The text to search for. Responses:

200 OK: Returns a JSON object with the result.

touchtext

POST /stouchrest/touchtext
Simulates a touch event on the specified text.

curl -X POST "http://systapi:1337/stouchrest/touchtext?text=Hello"

Query Parameters:
text (String): The text to touch. Responses:

200 OK: Text touched successfully.
404 Not Found: Text not found on the display.
500 Internal Server Error: Error while touching the text.

automation

GET /stouchrest/automation
http://systapi:1337/STouchREST/automation
Executes a sequence of commands provided as query parameters. Between each command a delay of two seconds is added, because the reply sometimes need a while. To prevent communication problems, you should always start an automation with connect and finish it with disconnect.

Query Parameters:
Query parameters is a list of supported commands, seperated by &:
connect: Connect to the SystaComfort unit.
touch=x,y: Simulate a touch event on screen coordinates x and y as integers.
touchText=text: Simulate a touch event on the given text.
touchButton=id: Simulate a touch event on the button with the given ID.
whileText==text&doAction: While the given text is in the object tree, do the given action. text needs to be URL encoded, e.g. blank is %20. doAction is any supported command
whileText!=text&doAction: While the given text is not in the object tree, do the given action. text needs to be URL encoded, e.g. blank is %20. doAction is any supported command
whileButton==id&doAction: While the button with the given ID is in the object tree, do the given action. id is any integer,doAction is any supported command
whileButton!=id&doAction: While the button with the given ID is not in the object tree, do the given action. id is any integer,doAction is any supported command
checkText==text&thenDoThisAction&elseDoThisAction: If the given text is in the object tree, then excute the command given by thenDoThisAction, otherwise execute the command given in elseDoThisAction.
checkText!=text&thenDoThisAction&elseDoThisAction: If the given text is not in the object tree, then excute the command given by thenDoThisAction, otherwise execute the command given in elseDoThisAction.
checkButton==id&thenDoThisAction&elseDoThisAction: If the button with the given id is in the object tree, then execute the command given by thenDoThisAction, otherwise execute the command given in elseDoThisAction.
checkButton!=id&thenDoThisAction&elseDoThisAction: If the button with the given id is not in the object tree, then execute the command given by thenDoThisAction, otherwise execute the command given in elseDoThisAction.
disconnect: Disconnect from the SystaComfort unit.

# switch to Heating program 1
curl -X GET "http://systapi:1337/stouchrest/automation?connect&touch=155,141&touch=42,77&touch=157,182&whiletext!=Heating%20program%201&touchbutton=19&touchtext=Heating%20program%201&disconnect"
# switch to Off
curl -X GET "http://systapi:1337/stouchrest/automation?connect&touch=155,141&touch=42,77&touch=157,182&whiletext!=Off&touchbutton=20&touchtext=Off&disconnect"

Responses:

200 OK: Automation executed successfully.
500 Internal Server Error: Command failed.

Contribute

^{[Back to Contents]}

I highly appreciate contributions, especially information to help refine the understanding of the Paradigma communication protocols, as this project relies on reverse engineering. Information relevant for code contributions are given in DEVELOPMENT.md.

Before contributing, please read the CONTRIBUTING.md guide. It provides detailed instructions on how to report bugs, submit patches, ask questions, and propose new features.

Key ways to contribute:

Protocol Information (Most Needed!):
- The communication protocols used by the SystaComfort unit are not publicly available. Your help in identifying new data fields or understanding different system behaviors is invaluable.
- Tools to help you:
  - SystaREST API: Use the logging features, explore the dashboard, and utilize monitorrawdata to capture and analyze data from your system.
  - STouchREST API: The debugscreen can help you understand S-Touch interactions.
- Sharing your findings: If you discover new fields or protocol details, please start a new discussion to share your insights. This is the preferred way to report such information.
Bug Reports & Fixes: If you find a bug, please check existing Issues and then submit a new one if needed. Patches are welcome via Pull Requests (see CONTRIBUTING.md).
Feature Enhancements: If you have ideas for new features or improvements to existing ones, please discuss them first in Discussions.

Known Issues

^{[Back to Contents]}

There are some ENC28J60 modules sold with wrong jumper settings. Make sure you set the jumpers as in the picture on the left (vertically connecting the PINs).

correct	wrong

Links

^{[Back to Contents]}

SystaREST Javadoc
Paradigma Downloads
Heizungssteuerung: Daten auslesen
SystaComfortPrometheusExporter
ParadigmaHeatingReader also read protocols if you want to buils anything on top of that (S-touch App)

Name		Name	Last commit message	Last commit date
Latest commit History 244 Commits
.github/workflows		.github/workflows
SystaPi_files		SystaPi_files
SystaRESTServer		SystaRESTServer
docs		docs
helpers		helpers
resources		resources
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install_systapi.sh		install_systapi.sh

License

beep-projects/SystaPi

Folders and files

Latest commit

History

Repository files navigation

SystaPi, SystaREST and STouchREST

Contents

Project Status

Getting Started

Directory Structure of this Project

Parts List

Installation

SystaComfort

Linux

Windows / manual installation

Troubleshooting the installation

The SystaRESTServer

The SystaREST API

findsystacomfort

start

stop

servicestatus

rawdata

dashboard

monitorrawdata

waterheater

status

enablelogging

disablelogging

The STouchREST API

connect

disconnect

touch

screen

debugscreen

objecttree

hasbutton

touchbutton

hastext

touchtext

automation

Contribute

Known Issues

Links

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages