Har tittet litt rundt og ser at protokollene for kommunikasjon gjennom RS485 finnes på en github, det vil si at vi kan tappe informasjon direkte fra vårt lokale Hyss system om vi vil. Samtidig ser jeg at de fortsatt leverer data til en server et sted, hvilket gjør at vi kan anta at våre data fortsatt lagres og vil være tilgjengelig om siden en dag kommer opp igjen.
Jeg kommer til å prøve meg på følgende vei for å få kontroll på datastrømmen:
Tappe RS485 signalet og konvertere det til USB. RS485 standarden tilsier at det skal gå fint å avlytte signalet uten at vi hindrer opplastning til den opprinnelige serveren.
Lese signalet med en Raspberry Pi ved hjelp av Geco protokollene jeg fant på Github
Dele data med Home Assistant slik at jeg når det med en mobil
Til det har jeg handlet utstyr for ca. 1500,-
Deler i denne tråden om jeg får det til, men andre får gjerne også prøve
Kjenner ikke utstyret, men å henge seg på kommunikasjonen på RS485 høres lurt ut å lagre så mye data som mulig vil også kunne hjelpe dere å skjønne protokollen i tilfelle utstyr slutter å sende data. Jeg gjorde noe slik med RS232 i studie tiden min der vi lagde logging på et system som bare viste data online.
Det går fint å lese data fra RS485 ved hjelp av Geco protokollene fra Github, ingen kryptering eller annet som hindrer lesing og skriving
Eksisterende leveranse av data til HYSS server virker ikke å bli forstyrret (grønt lys på overgang til Ethernet og ingen feilmelding i konsoll)
Det går fint å lese resultatene gjennom HomeAssistant sin app
Utfordringen er å matche data med sensorer; jeg finner rundt 70 registre men har så langt bare klart å identifisere rundt 10%. De er ikke i samme register posisjon som på andre Geco produkter hvilket gjør det til et detektivarbeid der jeg bare har det som kommer frem i konsollen å sammenligne med.
Fortsetter litt til å håper jeg klarer å identifisere flere dataelementer etterhvert. Innser at dette hadde vært litt lettere om jeg hadde gjort det mens Hyss appen var tilgjengelig...
Morn, vokna till ett kaldt hus, hadde ikke sett mailene om det HYSS før nå.
Regnet med dette ville komme så har forsøkt i noen år å reverse-engineere app.hyss, men jeg har bare klart å bytte ut frontenden, ut i fra tråden her høres det ut som dere har funnet ut av det jeg manglet, så...
Har en god del analyse data liggende av HYSS appen og de fleste, om ikke alle dens data elementer. Jeg samler det jeg har og får delt ila noen dager.
>**Purpose:** Collated technical data from reverse-engineering the HYSS web app. Intended to assist community efforts to build a replacement server/controller now that Hyss has ceased operations. > >**Source:** Reverse-engineered from the HYSS web application (ASP.NET WebForms). All endpoints, value IDs, and behaviors documented here have been confirmed working against the live system.
The HYSS system is a combined solar thermal + ground-source heat pump system. The web app runs on an ASP.NET WebForms stack at `https://app.hyss.com` (cloud) or a local IP for on-prem units.
**Communication model:** - Browser-style cookie-based sessions (no OAuth/Bearer required for handler endpoints) - All data exchange via HTTP GET/POST to `.ashx` handler endpoints and `.aspx` pages - Responses are JSON (from handlers) or HTML (from pages) - The system controller communicates upstream to the HYSS cloud server — this is the connection that needs replacing
**Key architectural components:** -**Heat pump** — compressor-based, ground-source (borehole) + solar collector -**Storage tank** — stratified, charged by solar loop (bottom) and heat pump (upper coil) -**Heating loop** — floor heating (and possibly radiators) fed from condenser output -**Brine/glycol loop** — connects solar collectors and/or borehole to HP evaporator
---
## 2. Authentication
### Login ``` POST <BASE>/login Content-Type: application/x-www-form-urlencoded
**Fields:** | Field | Value | Notes | |------------|----------------|-------| | `action` | `login` | Literal string | | `email` | User email | | | `pass` | User password | | | `remember` | `true`/`false` | Both values have been observed to work |
**Response:** HTTP 200 or 302. Sets `app_auth` cookie.
**Session validation:** After login, probe `GET <BASE>/handlers/system_status.ashx` — should return HTTP 200 with JSON.
**Session lifetime:** - Cookie `app_auth` has an expiration timestamp - If no expiration header: assume 30-minute session timeout - Re-authenticate 5 minutes before expiration as safety buffer - If any handler returns HTML (SPA shell) instead of JSON → session expired, re-login
### 3.1 System Status (Primary) ``` GET <BASE>/handlers/system_status.ashx ``` Returns JSON with nested structure: ```json { "temperatures": { "supply": 34.2, "return": 28.5 } } ```
**Alternative status paths observed** (fallbacks, may serve SPA shell without proper cookies): -`/ajax/getStatus` -`/ajax/status` -`/status.json` -`/ajax/telemetry` -`/data.json`
### 3.2 Specific Values (Primary data source) ``` POST <BASE>/handlers/get_values.ashx Content-Type: application/x-www-form-urlencoded
values_array=["t7","t8","t2","t9"] ```
**Payload:** Form field `values_array` containing a JSON-encoded array of string identifiers.
**Response:** JSON object mapping each requested ID to its current value: ```json { "t7": 34.2, "t8": 28.5, "t2": 45.1, "t9": 48.3 } ```
**Notes:** - Values may be returned as strings — coerce to numbers when possible - Only requested IDs are returned - Can batch all known IDs in a single request
---
## 4. Write Endpoints (Control)
### 4.1 Handler Set Values (Confirmed Working) ``` POST <BASE>/handlers/set_values.ashx Content-Type: application/x-www-form-urlencoded
values_array={"t7set": 34, "t2set": 52} ```
**Payload:** Form field `values_array` containing a JSON-encoded object of key→value pairs.
**Confirmed writable keys:** | Key | Description | Unit | Range | |---------|----------------------------------|------|-----------| | `t2set` | Max Tank Temp (Solar) | °C | 20–85 | | `t7set` | System Supply Temp Setpoint | °C | 10–60 | | `t9set` | Max Tank Temp (Heat Pump) | °C | 20–70 |
**Response:** JSON confirmation or plain text `ok`.
### 4.2 System Configuration Form (Full 10-field POST) ``` POST <BASE>/pages/system_configuration.aspx Content-Type: application/x-www-form-urlencoded; charset=UTF-8 X-Requested-With: XMLHttpRequest
**IMPORTANT:** The server expects ALL 10 fields in every POST. A partial submission returns: ```json {"error_msg": "Noen date er feil. Vennligst sjekk data og prøv igjen."} ``` (Norwegian: "Some data is incorrect. Please check data and try again.")
**Status note:** This endpoint has been observed to sometimes return HTTP 403 ("You do not have permission to view this directory or page.") — possibly restricted to certain account roles. The handler-based write path (4.1) remained accessible.
---
## 5. Complete Value ID Catalog
All 50+ identifiers confirmed readable via `POST /handlers/get_values.ashx`:
### Temperature Sensors | ID | Name | Unit | Physical Location | |----|------|------|-------------------| | `t1` | Collector/Brine Supply | °C | Glycol leaving solar collector toward tank heat exchanger | | `t2` | Tank Lower Water | °C | Bottom of storage tank (stratification/capacity indicator) | | `t3` | Collector/Brine Return | °C | Glycol returning after giving heat to tank HX | | `t4` | Borehole Return | °C | Glycol returning from borehole loop before HP evaporator | | `t5` | Evaporator In (brine in) | °C | Glycol entering heat pump evaporator (cold-side inlet) | | `t6` | Evaporator Out (brine out) | °C | Glycol leaving HP evaporator, back to borehole/collector | | `t7` | System Supply (condenser out) | °C | **Primary control point** — heating loop fluid leaving HP condenser | | `t8` | System Return (condenser in) | °C | Heating loop fluid returning to HP condenser | | `t9` | Tank Upper Coil Region | °C | Temp near HP coil in upper tank (HP charging control point) | | `t10` | Outdoor Air | °C | Outdoor sensor — input for heating curve and heating stop logic | | `t11` | (Unknown) | °C | Unidentified temperature sensor | | `t12` | (Unknown) | °C | Unidentified temperature sensor | | `t13` | (Unknown) | °C | Unidentified temperature sensor | | `t14` | (Unknown) | °C | Unidentified temperature sensor | | `t15` | (Unknown) | °C | Unidentified temperature sensor | | `t17` | (Unknown) | °C | Unidentified temperature sensor (note: t16 not observed) | | `comp_exh_t` | Compressor Discharge Gas | °C | Refrigerant temp after compressor (overheat diagnostic) | | `evaporating_t` | Refrigerant Evaporator Temp | °C | Cold-side refrigerant temp (source efficiency/icing risk) | | `t_in_port2` | T In Port2 | °C | Unknown port temperature |
### Flow Meters | ID | Name | Unit | |----|------|------| | `fm1` | Flow Meter 1 | L/min | | `fm2` | Flow Meter 2 | L/min | | `fm1_external` | Flow Meter 1 External | L/min | | `fm2_external` | Flow Meter 2 External | L/min |
### Compressor & Power | ID | Name | Unit | |----|------|------| | `compressor_frequency` | Compressor Frequency | Hz | | `compressor_rpm` | Compressor RPM | rpm | | `p1_power_consumption` | P1 Power Consumption | W |
### Pressures | ID | Name | Unit | |----|------|------| | `brine_circ_pressure` | Brine Circuit Pressure | bar | | `heating_circ_pressure` | Heating Circuit Pressure | bar |
### System States & Modes | ID | Name | Notes | |----|------|-------| | `heat_pump_mode` | Heat Pump Mode | Enumeration or numeric state | | `p4_state` | P4 State | Pump/valve state | | `hyss_active_state` | HYSS Active State | System running state | | `electric_heater_relay` | Electric Heater Relay | On/off state | | `pure_solar_status` | Pure Solar Status | Solar-only mode indicator | | `readout_options` | Readout Options | Display/readout configuration | | `ext_el_heater_connected` | External EL Heater Connected | Boolean — external heater present | | `p1p2v1` | P1P2V1 | Combined pump/valve state | | `el_heaters_states` | EL Heaters States | Electric heater bank states | | `p2_status` | P2 Status | Pump 2 state |
### Outputs & Manual Controls | ID | Name | Notes | |----|------|-------| | `out1` | Output 1 | Relay/digital output | | `out2` | Output 2 | Relay/digital output | | `out3` | Output 3 | Relay/digital output | | `relay1_manual_ctrl` | Relay 1 Manual Control | Manual override state | | `relay3_manual_ctrl` | Relay 3 Manual Control | Manual override state | | `relay5_manual_ctrl` | Relay 5 Manual Control | Manual override state | | `v2_manual_control` | V2 Manual Control | Valve manual override | | `v2_mixing_mode` | V2 Mixing Mode | Mixing valve mode | | `p3_manual_control` | P3 Manual Control | Pump 3 manual override | | `v_state` | V State | Valve state |
### Setpoint Echoes (readable via get_values) | ID | Name | Unit | |----|------|------| | `t2set` | Max Tank Temp (Solar) setpoint | °C | | `t7set` | System Supply Temp setpoint | °C | | `t9set` | Max Tank Temp (Heat Pump) setpoint | °C |
### Complete ID List (copy-paste ready) ``` t1,t2,t3,t4,t5,t6,t7,t8,t9,t10,t11,t12,t13,t14,t15,t17, fm1,fm2,fm1_external,fm2_external, p1p2v1,heat_pump_mode,p4_state, compressor_frequency,compressor_rpm,p1_power_consumption, hyss_active_state,electric_heater_relay,pure_solar_status, readout_options,comp_exh_t,evaporating_t,ext_el_heater_connected, out1,out2,out3, relay1_manual_ctrl,relay3_manual_ctrl,relay5_manual_ctrl, v2_manual_control,v2_mixing_mode,el_heaters_states, p2_status,p3_manual_control,v_state,t_in_port2, brine_circ_pressure,heating_circ_pressure, t2set,t7set,t9set ```
---
## 6. System Configuration Parameters (10 fields)
These are the system-level configuration parameters managed via the configuration page. All 10 must be submitted together.
| Key | Name | Unit | Range | Default | Description | |-----|------|------|-------|---------|-------------| | `Tmin` | Min Outdoor Temp | °C | -40 to 0 | -30 | Minimum outdoor temperature for system design | | `T0` | Base Temperature | °C | -10 to +10 | 0 | Base temperature for heating curve calculations | | `Theatingstop` | Heating Stop Threshold | °C | 10 to 25 | 15–18 | Outdoor temp at which space heating stops | | `T7min` | Min System Supply Temp | °C | 15 to 40 | 25 | Minimum supply temperature to the heating loop | | `DUT` | Design Outdoor Temp | °C | -30 to +10 | -15 | Design outdoor temperature for sizing calculations | | `T7max` | Max System Temp at DUT | °C | 30 to 80 | 55 | Maximum system supply temperature at design outdoor conditions | | `DELTA` | Heating Curve Offset | °C/K | -10 to +10 | 0 | Vertical offset applied to the heating curve | | `C` | Heating Curve Slope | — | 0.0 to 5.0 | 0.07–1.5 | Slope/curvature parameter of the heating curve | | `T9set` | Max Tank Temp (HP) | °C | 20 to 70 | 50 | Upper limit for tank charging from heat pump | | `T2set` | Max Tank Temp (Solar) | °C | 20 to 85 | 75 | Upper limit for tank charging from solar loop |
**Alias:** The UI sometimes uses `T_opvarming_stopp` for `Theatingstop` (Norwegian localization).
**Field order in POST (must match):** ``` Tmin, T0, Theatingstop, T7min, DUT, T7max, DELTA, C, T9set, T2set ```
---
## 7. Heating Curve Data
The system uses a 21-point piecewise-linear heating curve to calculate target supply temperature from outdoor temperature.
**Value IDs:**`hc_x0` through `hc_x20` (outdoor temp points) and `hc_y0` through `hc_y20` (supply temp curve values).
**Interpolation logic:** 1. Fetch all 42 values (21 x-y pairs) via `get_values.ashx` 2. Sort pairs by x (outdoor temperature), ascending 3. For a given outdoor temperature: - If below the lowest x → use the lowest y (max supply temp) - If above the highest x → use the highest y (min supply temp) - Otherwise → linear interpolation between the two bracketing points
**Heating curve parameters that modify the curve:** -`C` — slope/curvature factor -`DELTA` — vertical offset (shifts entire curve up/down) -`DUT` — design outdoor temperature (lowest expected outdoor temp) -`T7max` — supply temperature at DUT -`T7min` — minimum supply temperature -`Theatingstop` — outdoor temp above which heating is disabled
Failure (partial submission): ```json {"error_msg": "Noen date er feil. Vennligst sjekk data og prøv igjen."} ```
---
## 9. Number Formatting Rules
The server is sensitive to number formatting in POSTs:
| Rule | Example | Wrong | |------|---------|-------| | Integers: no trailing `.0` | `15` | `15.0` | | Decimals: trim trailing zeros | `0.07` | `0.0700` | | Slope `C`: full decimal precision | `0.07` | `0` | | Negative zero: normalize to `0` | `0` | `-0` | | Locale: may return comma decimals | Check response for `,` vs `.` | |
The web app uses European locale (comma as decimal separator) in some contexts. Implementations should auto-detect and adapt.
---
## 10. Error Handling & Session Management
| Scenario | Detection | Action | |----------|-----------|--------| | Session expired | Handler returns HTML instead of JSON | Re-authenticate and retry once | | Session expired | HTTP 401 or 403 | Re-authenticate and retry once | | Config page blocked | HTTP 403 on `system_configuration.aspx` | Fall back to handler-based reads/writes + local cache | | Partial config post | Server returns `error_msg` | Ensure all 10 fields are included | | Network error | Connection timeout/reset | Retry with exponential backoff | | Non-JSON 200 | Content starts with `<html` | Treat as expired session | | Missing value | Key absent from response | Return `None`, mark entity unavailable |
**Browser headers that improve reliability:** ``` User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ... Accept-Language: nb-NO,nb;q=0.9,en-US;q=0.8,en;q=0.7 Sec-Fetch-Dest: empty Sec-Fetch-Mode: cors Sec-Fetch-Site: same-origin ```
---
## 11. Physical Sensor Locations
Based on analysis of the HYSS system design and confirmed sensor readings:
T10 = Outdoor Air Temperature (mounted externally) ```
---
## 12. Geco / RS485 Connection Notes
The HYSS controller board is manufactured by **Geco** (a Polish industrial controller company). The controller uses RS485 for local communication.
**What the community has discovered:** - Reading data from RS485 using Geco protocols from GitHub works fine - No encryption or authentication barriers on the RS485 bus - Reading via RS485 does not disrupt the existing HYSS cloud data delivery - Around 70 registers found on the RS485 bus - Register positions differ from other Geco products — mapping is not 1:1 - ~10% of registers identified so far through manual correlation with console output
**Potential register-to-value mapping approach:** The value IDs documented above (t1–t17, fm1, fm2, compressor_frequency, etc.) map to physical measurements. Cross-referencing RS485 register values with the HTTP API values (when available) could accelerate identification. For example: - Read `t7` via HTTP → get system supply temperature - Scan RS485 registers simultaneously → find the register containing the same value - Repeat across operating conditions to confirm mappings
**Geco GitHub resources:** Search for "Geco" controller protocols — the communication protocol documentation for other Geco products (e.g., Geco G-422, G-427) provides the register map structure, even if the specific register assignments differ for HYSS.
---
## Appendix A: Discovered Endpoint Inventory
| Endpoint | Method | Purpose | Status | |----------|--------|---------|--------| | `/login` | POST | Authentication (form-based) | ✅ Working | | `/handlers/system_status.ashx` | GET | Primary status JSON | ✅ Working | | `/handlers/get_values.ashx` | POST | Read any values by ID | ✅ Working | | `/handlers/set_values.ashx` | POST | Write setpoints (t2set, t7set, t9set) | ✅ Working | | `/pages/system_configuration.aspx` | GET | Read config form (HTML scraping) | ⚠️ Sometimes 403 | | `/pages/system_configuration.aspx` | POST | Write all 10 config fields | ⚠️ Sometimes 403 | | `/ajax/getStatus` | GET | Alternative status endpoint | ❓ Observed | | `/ajax/status` | GET | Alternative status endpoint | ❓ Observed | | `/status.json` | GET | Alternative status endpoint | ❓ Observed | | `/data.json` | GET | Alternative data endpoint | ❓ Observed |
## Appendix B: Norwegian UI Strings
| Norwegian | English | Context | |-----------|---------|---------| | `Konfigurasjon lagret` | Configuration saved | Success response from config POST | | `Noen date er feil. Vennligst sjekk data og prøv igjen.` | Some data is incorrect. Please check data and try again. | Error response (partial POST) | | `T_opvarming_stopp` | Heating stop | Alias for `Theatingstop` field |
## Appendix C: Safety Recommendations
When building a replacement server or control interface:
1.**Safety window:** Enforce ±1°C change limits per operation by default for temperature setpoints 2.**Complete payloads:** Always send all 10 config fields together — partial POSTs are rejected 3.**Audit logging:** Log every write operation with timestamp, old value, new value 4.**Dry-run mode:** Implement a dry-run flag during development/testing 5.**Bounds checking:** Respect the min/max ranges documented per parameter 6.**Polling rate:** 300 seconds (5 min) appears to be the interval used by the original cloud app 7.**Compressor protection:** Avoid rapid setpoint changes that could cause compressor short-cycling
Jeg kommer til å prøve meg på følgende vei for å få kontroll på datastrømmen:
Til det har jeg handlet utstyr for ca. 1500,-
Deler i denne tråden om jeg får det til, men andre får gjerne også prøve
Fortsetter litt til å håper jeg klarer å identifisere flere dataelementer etterhvert. Innser at dette hadde vært litt lettere om jeg hadde gjort det mens Hyss appen var tilgjengelig...
hadde ikke sett mailene om det HYSS før nå.
Regnet med dette ville komme så har forsøkt i noen år å reverse-engineere app.hyss,
men jeg har bare klart å bytte ut frontenden, ut i fra tråden her høres det ut som dere har funnet ut av det jeg manglet, så...
Har en god del analyse data liggende av HYSS appen og de fleste, om ikke alle dens data elementer.
Jeg samler det jeg har og får delt ila noen dager.
# HYSS Heating System — Protocol & Data Reference
> **Purpose:** Collated technical data from reverse-engineering the HYSS web app. Intended to assist community efforts to build a replacement server/controller now that Hyss has ceased operations.
>
> **Source:** Reverse-engineered from the HYSS web application (ASP.NET WebForms). All endpoints, value IDs, and behaviors documented here have been confirmed working against the live system.
---
## Table of Contents
1. [System Overview](#1-system-overview)
2. [Authentication](#2-authentication)
3. [Read Endpoints (Telemetry)](#3-read-endpoints-telemetry)
4. [Write Endpoints (Control)](#4-write-endpoints-control)
5. [Complete Value ID Catalog](#5-complete-value-id-catalog)
6. [System Configuration Parameters (10 fields)](#6-system-configuration-parameters-10-fields)
7. [Heating Curve Data](#7-heating-curve-data)
8. [Request/Response Examples](#8-requestresponse-examples)
9. [Number Formatting Rules](#9-number-formatting-rules)
10. [Error Handling & Session Management](#10-error-handling--session-management)
11. [Physical Sensor Locations (Pipe/System Mapping)](#11-physical-sensor-locations)
12. [Geco / RS485 Connection Notes](#12-geco--rs485-connection-notes)
---
## 1. System Overview
The HYSS system is a combined solar thermal + ground-source heat pump system. The web app runs on an ASP.NET WebForms stack at `https://app.hyss.com` (cloud) or a local IP for on-prem units.
**Communication model:**
- Browser-style cookie-based sessions (no OAuth/Bearer required for handler endpoints)
- All data exchange via HTTP GET/POST to `.ashx` handler endpoints and `.aspx` pages
- Responses are JSON (from handlers) or HTML (from pages)
- The system controller communicates upstream to the HYSS cloud server — this is the connection that needs replacing
**Key architectural components:**
- **Heat pump** — compressor-based, ground-source (borehole) + solar collector
- **Storage tank** — stratified, charged by solar loop (bottom) and heat pump (upper coil)
- **Heating loop** — floor heating (and possibly radiators) fed from condenser output
- **Brine/glycol loop** — connects solar collectors and/or borehole to HP evaporator
---
## 2. Authentication
### Login
```
POST <BASE>/login
Content-Type: application/x-www-form-urlencoded
action=login&email=<USERNAME>&pass=<PASSWORD>&remember=true
```
**Fields:**
| Field | Value | Notes |
|------------|----------------|-------|
| `action` | `login` | Literal string |
| `email` | User email | |
| `pass` | User password | |
| `remember` | `true`/`false` | Both values have been observed to work |
**Response:** HTTP 200 or 302. Sets `app_auth` cookie.
**Session validation:** After login, probe `GET <BASE>/handlers/system_status.ashx` — should return HTTP 200 with JSON.
**Session lifetime:**
- Cookie `app_auth` has an expiration timestamp
- If no expiration header: assume 30-minute session timeout
- Re-authenticate 5 minutes before expiration as safety buffer
- If any handler returns HTML (SPA shell) instead of JSON → session expired, re-login
**Headers for AJAX calls (recommended):**
```
X-Requested-With: XMLHttpRequest
Accept: application/json, text/javascript, */*; q=0.01
```
---
## 3. Read Endpoints (Telemetry)
### 3.1 System Status (Primary)
```
GET <BASE>/handlers/system_status.ashx
```
Returns JSON with nested structure:
```json
{
"temperatures": {
"supply": 34.2,
"return": 28.5
}
}
```
**Alternative status paths observed** (fallbacks, may serve SPA shell without proper cookies):
- `/ajax/getStatus`
- `/ajax/status`
- `/status.json`
- `/ajax/telemetry`
- `/data.json`
### 3.2 Specific Values (Primary data source)
```
POST <BASE>/handlers/get_values.ashx
Content-Type: application/x-www-form-urlencoded
values_array=["t7","t8","t2","t9"]
```
**Payload:** Form field `values_array` containing a JSON-encoded array of string identifiers.
**Response:** JSON object mapping each requested ID to its current value:
```json
{
"t7": 34.2,
"t8": 28.5,
"t2": 45.1,
"t9": 48.3
}
```
**Notes:**
- Values may be returned as strings — coerce to numbers when possible
- Only requested IDs are returned
- Can batch all known IDs in a single request
---
## 4. Write Endpoints (Control)
### 4.1 Handler Set Values (Confirmed Working)
```
POST <BASE>/handlers/set_values.ashx
Content-Type: application/x-www-form-urlencoded
values_array={"t7set": 34, "t2set": 52}
```
**Payload:** Form field `values_array` containing a JSON-encoded object of key→value pairs.
**Confirmed writable keys:**
| Key | Description | Unit | Range |
|---------|----------------------------------|------|-----------|
| `t2set` | Max Tank Temp (Solar) | °C | 20–85 |
| `t7set` | System Supply Temp Setpoint | °C | 10–60 |
| `t9set` | Max Tank Temp (Heat Pump) | °C | 20–70 |
**Response:** JSON confirmation or plain text `ok`.
### 4.2 System Configuration Form (Full 10-field POST)
```
POST <BASE>/pages/system_configuration.aspx
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest
Tmin=-30&T0=0&Theatingstop=15&T7min=25&DUT=-15&T7max=55&DELTA=0&C=0.07&T9set=50&T2set=75
```
**IMPORTANT:** The server expects ALL 10 fields in every POST. A partial submission returns:
```json
{"error_msg": "Noen date er feil. Vennligst sjekk data og prøv igjen."}
```
(Norwegian: "Some data is incorrect. Please check data and try again.")
**Success response contains:** `Konfigurasjon lagret` (Norwegian: "Configuration saved")
**Status note:** This endpoint has been observed to sometimes return HTTP 403 ("You do not have permission to view this directory or page.") — possibly restricted to certain account roles. The handler-based write path (4.1) remained accessible.
---
## 5. Complete Value ID Catalog
All 50+ identifiers confirmed readable via `POST /handlers/get_values.ashx`:
### Temperature Sensors
| ID | Name | Unit | Physical Location |
|----|------|------|-------------------|
| `t1` | Collector/Brine Supply | °C | Glycol leaving solar collector toward tank heat exchanger |
| `t2` | Tank Lower Water | °C | Bottom of storage tank (stratification/capacity indicator) |
| `t3` | Collector/Brine Return | °C | Glycol returning after giving heat to tank HX |
| `t4` | Borehole Return | °C | Glycol returning from borehole loop before HP evaporator |
| `t5` | Evaporator In (brine in) | °C | Glycol entering heat pump evaporator (cold-side inlet) |
| `t6` | Evaporator Out (brine out) | °C | Glycol leaving HP evaporator, back to borehole/collector |
| `t7` | System Supply (condenser out) | °C | **Primary control point** — heating loop fluid leaving HP condenser |
| `t8` | System Return (condenser in) | °C | Heating loop fluid returning to HP condenser |
| `t9` | Tank Upper Coil Region | °C | Temp near HP coil in upper tank (HP charging control point) |
| `t10` | Outdoor Air | °C | Outdoor sensor — input for heating curve and heating stop logic |
| `t11` | (Unknown) | °C | Unidentified temperature sensor |
| `t12` | (Unknown) | °C | Unidentified temperature sensor |
| `t13` | (Unknown) | °C | Unidentified temperature sensor |
| `t14` | (Unknown) | °C | Unidentified temperature sensor |
| `t15` | (Unknown) | °C | Unidentified temperature sensor |
| `t17` | (Unknown) | °C | Unidentified temperature sensor (note: t16 not observed) |
| `comp_exh_t` | Compressor Discharge Gas | °C | Refrigerant temp after compressor (overheat diagnostic) |
| `evaporating_t` | Refrigerant Evaporator Temp | °C | Cold-side refrigerant temp (source efficiency/icing risk) |
| `t_in_port2` | T In Port2 | °C | Unknown port temperature |
### Flow Meters
| ID | Name | Unit |
|----|------|------|
| `fm1` | Flow Meter 1 | L/min |
| `fm2` | Flow Meter 2 | L/min |
| `fm1_external` | Flow Meter 1 External | L/min |
| `fm2_external` | Flow Meter 2 External | L/min |
### Compressor & Power
| ID | Name | Unit |
|----|------|------|
| `compressor_frequency` | Compressor Frequency | Hz |
| `compressor_rpm` | Compressor RPM | rpm |
| `p1_power_consumption` | P1 Power Consumption | W |
### Pressures
| ID | Name | Unit |
|----|------|------|
| `brine_circ_pressure` | Brine Circuit Pressure | bar |
| `heating_circ_pressure` | Heating Circuit Pressure | bar |
### System States & Modes
| ID | Name | Notes |
|----|------|-------|
| `heat_pump_mode` | Heat Pump Mode | Enumeration or numeric state |
| `p4_state` | P4 State | Pump/valve state |
| `hyss_active_state` | HYSS Active State | System running state |
| `electric_heater_relay` | Electric Heater Relay | On/off state |
| `pure_solar_status` | Pure Solar Status | Solar-only mode indicator |
| `readout_options` | Readout Options | Display/readout configuration |
| `ext_el_heater_connected` | External EL Heater Connected | Boolean — external heater present |
| `p1p2v1` | P1P2V1 | Combined pump/valve state |
| `el_heaters_states` | EL Heaters States | Electric heater bank states |
| `p2_status` | P2 Status | Pump 2 state |
### Outputs & Manual Controls
| ID | Name | Notes |
|----|------|-------|
| `out1` | Output 1 | Relay/digital output |
| `out2` | Output 2 | Relay/digital output |
| `out3` | Output 3 | Relay/digital output |
| `relay1_manual_ctrl` | Relay 1 Manual Control | Manual override state |
| `relay3_manual_ctrl` | Relay 3 Manual Control | Manual override state |
| `relay5_manual_ctrl` | Relay 5 Manual Control | Manual override state |
| `v2_manual_control` | V2 Manual Control | Valve manual override |
| `v2_mixing_mode` | V2 Mixing Mode | Mixing valve mode |
| `p3_manual_control` | P3 Manual Control | Pump 3 manual override |
| `v_state` | V State | Valve state |
### Setpoint Echoes (readable via get_values)
| ID | Name | Unit |
|----|------|------|
| `t2set` | Max Tank Temp (Solar) setpoint | °C |
| `t7set` | System Supply Temp setpoint | °C |
| `t9set` | Max Tank Temp (Heat Pump) setpoint | °C |
### Complete ID List (copy-paste ready)
```
t1,t2,t3,t4,t5,t6,t7,t8,t9,t10,t11,t12,t13,t14,t15,t17,
fm1,fm2,fm1_external,fm2_external,
p1p2v1,heat_pump_mode,p4_state,
compressor_frequency,compressor_rpm,p1_power_consumption,
hyss_active_state,electric_heater_relay,pure_solar_status,
readout_options,comp_exh_t,evaporating_t,ext_el_heater_connected,
out1,out2,out3,
relay1_manual_ctrl,relay3_manual_ctrl,relay5_manual_ctrl,
v2_manual_control,v2_mixing_mode,el_heaters_states,
p2_status,p3_manual_control,v_state,t_in_port2,
brine_circ_pressure,heating_circ_pressure,
t2set,t7set,t9set
```
---
## 6. System Configuration Parameters (10 fields)
These are the system-level configuration parameters managed via the configuration page. All 10 must be submitted together.
| Key | Name | Unit | Range | Default | Description |
|-----|------|------|-------|---------|-------------|
| `Tmin` | Min Outdoor Temp | °C | -40 to 0 | -30 | Minimum outdoor temperature for system design |
| `T0` | Base Temperature | °C | -10 to +10 | 0 | Base temperature for heating curve calculations |
| `Theatingstop` | Heating Stop Threshold | °C | 10 to 25 | 15–18 | Outdoor temp at which space heating stops |
| `T7min` | Min System Supply Temp | °C | 15 to 40 | 25 | Minimum supply temperature to the heating loop |
| `DUT` | Design Outdoor Temp | °C | -30 to +10 | -15 | Design outdoor temperature for sizing calculations |
| `T7max` | Max System Temp at DUT | °C | 30 to 80 | 55 | Maximum system supply temperature at design outdoor conditions |
| `DELTA` | Heating Curve Offset | °C/K | -10 to +10 | 0 | Vertical offset applied to the heating curve |
| `C` | Heating Curve Slope | — | 0.0 to 5.0 | 0.07–1.5 | Slope/curvature parameter of the heating curve |
| `T9set` | Max Tank Temp (HP) | °C | 20 to 70 | 50 | Upper limit for tank charging from heat pump |
| `T2set` | Max Tank Temp (Solar) | °C | 20 to 85 | 75 | Upper limit for tank charging from solar loop |
**Alias:** The UI sometimes uses `T_opvarming_stopp` for `Theatingstop` (Norwegian localization).
**Field order in POST (must match):**
```
Tmin, T0, Theatingstop, T7min, DUT, T7max, DELTA, C, T9set, T2set
```
---
## 7. Heating Curve Data
The system uses a 21-point piecewise-linear heating curve to calculate target supply temperature from outdoor temperature.
**Value IDs:** `hc_x0` through `hc_x20` (outdoor temp points) and `hc_y0` through `hc_y20` (supply temp curve values).
**Interpolation logic:**
1. Fetch all 42 values (21 x-y pairs) via `get_values.ashx`
2. Sort pairs by x (outdoor temperature), ascending
3. For a given outdoor temperature:
- If below the lowest x → use the lowest y (max supply temp)
- If above the highest x → use the highest y (min supply temp)
- Otherwise → linear interpolation between the two bracketing points
**Heating curve parameters that modify the curve:**
- `C` — slope/curvature factor
- `DELTA` — vertical offset (shifts entire curve up/down)
- `DUT` — design outdoor temperature (lowest expected outdoor temp)
- `T7max` — supply temperature at DUT
- `T7min` — minimum supply temperature
- `Theatingstop` — outdoor temp above which heating is disabled
---
## 8. Request/Response Examples
### Login
```http
POST /login HTTP/1.1
Host: app.hyss.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest
Accept: application/json, text/javascript, */*; q=0.01
action=login&email=user@example.com&pass=mypassword&remember=true
```
### Read Values
```http
POST /handlers/get_values.ashx HTTP/1.1
Host: app.hyss.com
Content-Type: application/x-www-form-urlencoded
X-Requested-With: XMLHttpRequest
Cookie: app_auth=<session_cookie>
values_array=["t7","t8","t2","t9","t10","compressor_frequency","brine_circ_pressure"]
```
Response:
```json
{
"t7": 34.2,
"t8": 28.5,
"t2": 45.1,
"t9": 48.3,
"t10": 3.5,
"compressor_frequency": 42,
"brine_circ_pressure": 1.8
}
```
### Write Setpoint
```http
POST /handlers/set_values.ashx HTTP/1.1
Host: app.hyss.com
Content-Type: application/x-www-form-urlencoded
X-Requested-With: XMLHttpRequest
Cookie: app_auth=<session_cookie>
values_array={"t7set":35}
```
### Write Full Configuration
```http
POST /pages/system_configuration.aspx HTTP/1.1
Host: app.hyss.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest
Cookie: app_auth=<session_cookie>
Tmin=-30&T0=0&Theatingstop=15&T7min=25&DUT=-15&T7max=55&DELTA=0&C=0.07&T9set=50&T2set=75
```
Success:
```json
{"server_msg": "Konfigurasjon lagret"}
```
Failure (partial submission):
```json
{"error_msg": "Noen date er feil. Vennligst sjekk data og prøv igjen."}
```
---
## 9. Number Formatting Rules
The server is sensitive to number formatting in POSTs:
| Rule | Example | Wrong |
|------|---------|-------|
| Integers: no trailing `.0` | `15` | `15.0` |
| Decimals: trim trailing zeros | `0.07` | `0.0700` |
| Slope `C`: full decimal precision | `0.07` | `0` |
| Negative zero: normalize to `0` | `0` | `-0` |
| Locale: may return comma decimals | Check response for `,` vs `.` | |
The web app uses European locale (comma as decimal separator) in some contexts. Implementations should auto-detect and adapt.
---
## 10. Error Handling & Session Management
| Scenario | Detection | Action |
|----------|-----------|--------|
| Session expired | Handler returns HTML instead of JSON | Re-authenticate and retry once |
| Session expired | HTTP 401 or 403 | Re-authenticate and retry once |
| Config page blocked | HTTP 403 on `system_configuration.aspx` | Fall back to handler-based reads/writes + local cache |
| Partial config post | Server returns `error_msg` | Ensure all 10 fields are included |
| Network error | Connection timeout/reset | Retry with exponential backoff |
| Non-JSON 200 | Content starts with `<html` | Treat as expired session |
| Missing value | Key absent from response | Return `None`, mark entity unavailable |
**Browser headers that improve reliability:**
```
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ...
Accept-Language: nb-NO,nb;q=0.9,en-US;q=0.8,en;q=0.7
Sec-Fetch-Dest: empty
Sec-Fetch-Mode: cors
Sec-Fetch-Site: same-origin
```
---
## 11. Physical Sensor Locations
Based on analysis of the HYSS system design and confirmed sensor readings:
```
┌─────────────────────────┐
│ SOLAR COLLECTOR │
│ (Roof) │
└──┬──────────────────┬────┘
T1 │ (supply, hot) │ T3 (return, cooled)
▼ ▲
┌──────────────────────────┐
│ STORAGE TANK │
│ T9 (upper, HP coil) │
│ │
│ T2 (lower, solar HX) │
└──┬──────────────────┬─────┘
│ │
┌──────────────────┴──────────────────┴──────────────────┐
│ HEAT PUMP │
│ │
│ CONDENSER SIDE │ EVAPORATOR SIDE │
│ T7 (supply out) ────► │ T5 (brine in) ◄──── │
│ T8 (return in) ◄──── │ T6 (brine out) ────► │
│ │ │
│ comp_exh_t (discharge) │ evaporating_t │
│ compressor_frequency │ │
│ compressor_rpm │ │
│ p1_power_consumption │ │
└───────────────────────────┴────────────────────────────┘
│ ▲ │ ▲
│ │ │ │
▼ │ ▼ │
┌────────────────────┐ ┌─────────────────────┐
│ FLOOR HEATING │ │ BOREHOLE / WELL │
│ (System Loop) │ │ T4 (return from │
│ │ │ borehole) │
└────────────────────┘ └─────────────────────┘
heating_circ_pressure brine_circ_pressure
fm1, fm2 (flow rates) fm1_external, fm2_external
T10 = Outdoor Air Temperature (mounted externally)
```
---
## 12. Geco / RS485 Connection Notes
The HYSS controller board is manufactured by **Geco** (a Polish industrial controller company). The controller uses RS485 for local communication.
**What the community has discovered:**
- Reading data from RS485 using Geco protocols from GitHub works fine
- No encryption or authentication barriers on the RS485 bus
- Reading via RS485 does not disrupt the existing HYSS cloud data delivery
- Around 70 registers found on the RS485 bus
- Register positions differ from other Geco products — mapping is not 1:1
- ~10% of registers identified so far through manual correlation with console output
**Potential register-to-value mapping approach:**
The value IDs documented above (t1–t17, fm1, fm2, compressor_frequency, etc.) map to physical measurements. Cross-referencing RS485 register values with the HTTP API values (when available) could accelerate identification. For example:
- Read `t7` via HTTP → get system supply temperature
- Scan RS485 registers simultaneously → find the register containing the same value
- Repeat across operating conditions to confirm mappings
**Geco GitHub resources:** Search for "Geco" controller protocols — the communication protocol documentation for other Geco products (e.g., Geco G-422, G-427) provides the register map structure, even if the specific register assignments differ for HYSS.
---
## Appendix A: Discovered Endpoint Inventory
| Endpoint | Method | Purpose | Status |
|----------|--------|---------|--------|
| `/login` | POST | Authentication (form-based) | ✅ Working |
| `/handlers/system_status.ashx` | GET | Primary status JSON | ✅ Working |
| `/handlers/get_values.ashx` | POST | Read any values by ID | ✅ Working |
| `/handlers/set_values.ashx` | POST | Write setpoints (t2set, t7set, t9set) | ✅ Working |
| `/pages/system_configuration.aspx` | GET | Read config form (HTML scraping) | ⚠️ Sometimes 403 |
| `/pages/system_configuration.aspx` | POST | Write all 10 config fields | ⚠️ Sometimes 403 |
| `/ajax/getStatus` | GET | Alternative status endpoint | ❓ Observed |
| `/ajax/status` | GET | Alternative status endpoint | ❓ Observed |
| `/status.json` | GET | Alternative status endpoint | ❓ Observed |
| `/data.json` | GET | Alternative data endpoint | ❓ Observed |
## Appendix B: Norwegian UI Strings
| Norwegian | English | Context |
|-----------|---------|---------|
| `Konfigurasjon lagret` | Configuration saved | Success response from config POST |
| `Noen date er feil. Vennligst sjekk data og prøv igjen.` | Some data is incorrect. Please check data and try again. | Error response (partial POST) |
| `T_opvarming_stopp` | Heating stop | Alias for `Theatingstop` field |
## Appendix C: Safety Recommendations
When building a replacement server or control interface:
1. **Safety window:** Enforce ±1°C change limits per operation by default for temperature setpoints
2. **Complete payloads:** Always send all 10 config fields together — partial POSTs are rejected
3. **Audit logging:** Log every write operation with timestamp, old value, new value
4. **Dry-run mode:** Implement a dry-run flag during development/testing
5. **Bounds checking:** Respect the min/max ranges documented per parameter
6. **Polling rate:** 300 seconds (5 min) appears to be the interval used by the original cloud app
7. **Compressor protection:** Avoid rapid setpoint changes that could cause compressor short-cycling