Discovery

UDP

For discovery, the thermostat uses UDP. With a regular interval of approximately 10 seconds it broadcasts an UDP message to the local network to port 11,000.

The contents of the message is the word "ONE" followed by a space and the Device ID. At UDP protocol level we know the receiver, so we can tell at what IP address to access the thermostat at.

Discovery Message Format

The total size of the message contents is exactly 37 bytes.

The message starts with the word ONE (3 bytes), a space (1 byte) and the device ID (33 bytes)

ONE	[space]	Device ID
3 bytes	1 byte	_______________ 33 bytes _______________
ONE		6808-1401-3109_15-30-001-123

Control

REST Interface

The thermostat runs a REST service at port 10,000.

To successfully communicate with the thermostat, the connecting device needs authorization first.

Request Authorization

The user has to grant authorization to a device that wants to connect. When the authorization request is send, the user has to physically push the "Yes" button at the thermostat when is asks for permission.

URL

http://<host>:10000/pair_message

Method

POST

Payload

Data model of REST JSON body payload.
All fields are required.

Name	Type	Description
/pair_message	-
.seqnr	Int	Set to 1
/pair_message/account_auth	-
.user_account	String	Email of Atag Portal account. May be empty
. mac_address	String	Unique id of connecting device
/pair_message/accounts	-
.entries[].user_account	String	Email of Atag Portal account. May be empty (same as above)
.entries[].mac_address	String	Unique id of connecting device (same as above)
.entries[].device_name	String	Name to show on thermostat display
.entries[].account_type	Int	Type of account. 0 = user, 1 = service

Example

{
	"pair_message": {
		"seqnr": 1,
		"account_auth": {
			"user_account": "",
			"mac_address": "A1:12:18:B6:E2:99"
		},
		"accounts": {
			"entries": [
				{
					"user_account": "",
					"mac_address": "A1:12:18:B6:E2:99",
					"device_name": "RaspberryPI",
					"account_type": 0
				}
			]
		}
	}
}

Success Response

Data model of JSON response.

Name	Type	Description
pair_reply.seqnr	Int	Set to 1 (copy of request seqnr value)
pair_reply.acc_status	Int	Result of auth request. 0=n/a, 1=pending, 2=granted, 3=denied

When access status is pending, the user has not yet granted or denied the authorization request.

Example

{
	"pair_reply": {
		"seqnr": 1,
		"acc_status": 1
	}
}

Retrieve Info

Retrieve schedules, configuration, reports, status and info about wifi networks.

URL

http://<host>:10000/retrieve

Method

POST

Payload

Data model of REST JSON body payload.
All fields are required.

Name	Type	Description
/retrieve_message	-
.seqnr	Int	Set to 1
.device_id	String	Unique identification of connecting device (See Authorization)
.info	Int	Type of information request

The types of information requests:

01 = Control
02 = Schedules
04 = Configuration
08 = Report
16 = Status
32 = Wifi scan
64 = Report details

Add up the message numbers to receive more than one type of message at the same time. To request e.g. both schedules and status, the type of information request is 02 + 16 = 18.

Example

{
	"retrieve_message": {
		"seqnr": 1,
		"device_id": "6808-1401-3109_15-30-001-123",
		"info": 18
	}
}

Success Response

Data model of full JSON response.
All temperatures are degrees celsius, round by one decimal.

Name	Type	Description
/retrieve_reply	-
.seqnr	Int	Set to 1 (copy of request seqnr value)
.acc_status	Int	Result of auth request. 0=n/a, 1=pending, 2=granted, 3=denied
.status.device_id	String	Unique id of connecting device
.status.device_status	Int	todo
.status.connection_status	Int	todo
.status.date_time	Long	Current time in seconds sinds 2000
.report.report_time	Long	Report time in seconds sinds 2000
.report.burning_hours	Int	Total operating hours
.report.device_errors	String	Device error message
.report.boiler_errors	String	Boiler error message
.report.room_temp	Int	Current room temperature
.report.outside_temp	Int	Current outside temperature
.report.dbg_outside_temp	Int	Current box temperature?
.report.pcb_temp	Int	Current Internal circuit board temperature
.report.ch_setpoint	Int	Central Heating setpoint temperature
.report.dhw_water_temp	Int	Domestic Hot Water temperature
.report.ch_water_temp	Int	Central Heating Water temperature
.report.dhw_water_pres	Int	Domestic Hot Water pressure
.report.ch_water_pres	Int	Central Heating water pressure
.report.ch_return_temp	Int	Central Heating return temperature
.report.boiler_status	Int	&512 = dhw_schema, &256 = ch_schema, &8 = boilerHeating, &4 = dhwHeating, &2 = chHeating. Meaning of dhw_schema/ch_schema, keep up the temperature using the predefined schedule.
.report.boiler_config	Int	todo
.report.ch_time_to_temp	Int	Central Heating time to temperature?
.report.shown_set_temp	Int	Central Heating Target temperature
.report.power_cons	Int	Current gas flow. Probably deciliter/h. Divide by 10.000 to get m³/h, which makes most sense for gas consumption.
.report.tout_avg	Int	Average outside temperature
.report.rssi	Int	Received signal strength indication?
.report.current	Int	Some ATAG One types have a battery, this is the current in and out of battery
.report.voltage	Int	Some ATAG One types have a battery, this is the battery voltage
.report.charge_status	Int	todo
.report.lmuc_burner_starts	Int	todo
.report.dhw_flow_rate	Int	todo
.report.resets	Int	todo
.report.memory_allocation	Int	todo
.report.details.boiler_temp	Int	Current boiler temperature
.report.details.boiler_return_temp	Int	Current boiler return temperature
.report.details.min_mod_level	Int	Minimal modulation level
.report.details.rel_mod_level	Int	Relative modulation level. A value between 0 and 100.
.report.details.boiler_capacity	Int	Boiler capacity
.report.details.target_temp	Int	Target temperature
.report.details.overshoot	Int	todo
.report.details.max_boiler_temp	Int	Maximal boiler temperature
.report.details.alpha_used	Int	todo
.report.details.regulation_state	Int	todo
.report.details.ch_m_dot_c	Int	todo
.report.details.c_house	Int	todo
.report.details.r_rad	Int	todo
.report.details.r_env	Int	todo
.report.details.alpha	Int	todo
.report.details.alpha_max	Int	todo
.report.details.delay	Int	todo
.report.details.mu	Int	todo
.report.details.threshold_offs	Int	todo
.report.details.wd_k_factor	Int	todo
.report.details.wd_exponent	Int	todo
.report.details.lmuc_burner_hours	Int	todo
.report.details.lmuc_dhw_hours	Int	todo
.report.details.KP	Int	todo
.report.details.KI	Int	todo
.control.ch_status	Int	&4 = heating ch active
.control.ch_control_mode	Int	todo
.control.ch_mode	Int	"Standby" : 0, "Manual" : 1, "Automatic" : 2, "Vacation" : 3, "Extend" : 4, "Fireplace" : 5
.control.ch_mode_duration	Int	todo
.control.ch_mode_temp	Int	Central Heating target temperature
.control.dhw_temp_setp	Int	DHW temperature setpoint
.control.dhw_status	Int	todo
.control.dhw_mode	Int	todo
.control.dhw_mode_temp	Int	DHW taregt temperature
.control.weather_temp	Int	Current outside temperature
.control.weather_status	Int	1 = clear night, 2 = rain, 3 = snow, 4 = todo, 5 = strong wind, 6 = misty, 7 = cloudy, 8 = partly cloudy day, 9 = partly cloudy night, 0 = sunny
.control.vacation_duration	Int	todo
.control.extend_duration	Int	todo
.control.fireplace_duration	Int	todo
/schedules	-
.ch_schedule.base_temp	Int	Central Heating schedule base temperature
.ch_schedule.entries	Int[]	todo
.dhw_schedule.base_temp	Int	DHW schedule base temperature
.dhw_schedule.entries	Int[]	todo
.configuration.report_url	String	URL of location the thermostat reports to (SSL/https)
.configuration.download_url	String	URL for firmware updates (http)
.configuration.boiler_id	String	Boiler ID
.configuration.boiler_det_type	Int	todo
.configuration.language	Int	Thermostat language; 0=Dutch, 1=English, 2=French, 3=Italian, 4=German
.configuration.pressure_unit	Int	todo
.configuration.temp_unit	Int	todo
.configuration.time_format	Int	todo
.configuration.time_zone	Int	todo
.configuration.summer_eco_mode	Int	todo
.configuration.summer_eco_temp	Int	todo
.configuration.shower_time_mode	Int	todo
.configuration.comfort_settings	Int	todo
.configuration.room_temp_offs	Int	todo
.configuration.outs_temp_offs	Int	todo
.configuration.ch_temp_max	Int	Max CH flow temperature (maximum CV aanvoertemperatuur)
.configuration.ch_vacation_temp	Int	todo
.configuration.start_vacation	Int	todo
.configuration.wd_k_factor	Int	todo
.configuration.wd_exponent	Int	todo
.configuration.wd_control_temp	Int	todo
.configuration.climate_zone	Int	todo
.configuration.wd_temp_offs	Int	todo
.configuration.dhw_legion_day	Int	todo
.configuration.dhw_legion_time	Int	todo
.configuration.dhw_boiler_cap	Int	todo
.configuration.ch_building_size	Int	todo
.configuration.ch_heating_type	Int	todo
.configuration.ch_isolation	Int	todo
.configuration.installer_id	Int	todo
.configuration.disp_brightness	Int	todo
.configuration.ch_mode_vacation	Int	todo
.configuration.ch_mode_extend	Int	todo
.configuration.support_contact	Int	todo
.configuration.privacy_mode	Int	todo
.configuration.ch_max_set	Int	Real max flow temperature (absolute max aanvoertemperatuur, ch_temp_max de relatieve)
.configuration.ch_min_set	Int	Real min flow temperature (absolute minimum aanvoertemperatuur)
.configuration.dhw_max_set	Int	todo
.configuration.dhw_min_set	Int	todo
.configuration.mu	Int	todo
.configuration.dhw_legion_enabled	Int	todo
.configuration.frost_prot_enabled	Int	todo
.configuration.frost_prot_temp_outs	Int	todo
.configuration.frost_prot_temp_room	Int	todo
.configuration.wdr_temps_influence	Int	todo
.configuration.max_preheat	Int	todo
.wifi_scan.ssid_list[]	[]	List of Wifi network SSID's found
.wifi_scan.ssid_list[].SSID	String	Wifi SSID
.wifi_scan.ssid_list[].RSSI	Int	Wifi signal strength
.wifi_scan.ssid_list[].SECURITY	Int	Type of security (2=WPA)

Glossary:

Abbreviation	Description
CH	Central Heating (CH)
DHW	Water heated for uses other than space heating is also called domestic hot water (DHW)

Example of full JSON response.

{
  "retrieve_reply": {
    "seqnr": 0,
    "status": {
      "device_id": "6808-1401-3109_15-30-001-123",
      "device_status": 16385,
      "connection_status": 23,
      "date_time": 504130530
    },
    "report": {
      "report_time": 634653661,
      "burning_hours": 6273.64,
      "device_errors": "",
      "boiler_errors": "",
      "room_temp": 19.3,
      "outside_temp": 6.1,
      "dbg_outside_temp": 21.3,
      "pcb_temp": 24.4,
      "ch_setpoint": 35.9,
      "dhw_water_temp": 35.8,
      "ch_water_temp": 38.8,
      "dhw_water_pres": 0.0,
      "ch_water_pres": 2.0,
      "ch_return_temp": 31.6,
      "boiler_status": 266,
      "boiler_config": 772,
      "ch_time_to_temp": 0,
      "shown_set_temp": 19.5,
      "power_cons": 11251,
      "tout_avg": 7.9,
      "rssi": 35,
      "current": 46,
      "voltage": 3901,
      "charge_status": 1,
      "lmuc_burner_starts": 0,
      "dhw_flow_rate": 0.0,
      "resets": 3,
      "memory_allocation": 7640,
      "details": {
        "boiler_temp": 38.8,
        "boiler_return_temp": 31.6,
        "min_mod_level": 22,
        "rel_mod_level": 11,
        "boiler_capacity": 0,
        "target_temp": 19.5,
        "overshoot": 0.000,
        "max_boiler_temp": 83.0,
        "alpha_used": 0.00200,
        "regulation_state": 2,
        "ch_m_dot_c": 1245.934,
        "c_house": 29082124,
        "r_rad": 0.0014,
        "r_env": 0.0043,
        "alpha": 0.00012,
        "alpha_max": 0.00200,
        "delay": 1368,
        "mu": 0.30,
        "threshold_offs": 15.0,
        "wd_k_factor": 1.6,
        "wd_exponent": 1.2,
        "lmuc_burner_hours": 0,
        "lmuc_dhw_hours": 0,
        "KP": 36.100,
        "KI": 0.00568
      }
    },
    "control": {
      "ch_status": 9,
      "ch_control_mode": 0,
      "ch_mode": 1,
      "ch_mode_duration": 0,
      "ch_mode_temp": 20.0,
      "dhw_temp_setp": 60.0,
      "dhw_status": 5,
      "dhw_mode": 1,
      "dhw_mode_temp": 60.0,
      "weather_temp": 12.3,
      "weather_status": 5,
      "vacation_duration": 0,
      "extend_duration": 0,
      "fireplace_duration": 10800
    },
    "schedules": {
      "ch_schedule": {
        "base_temp": 15.0,
        "entries": [
          [
            [
              420,
              540,
              20.0
            ],
            [
              1020,
              1380,
              20.0
            ]
          ],
          [
            [
              420,
              540,
              20.0
            ],
            [
              1020,
              1380,
              20.0
            ]
          ],
          [
            [
              420,
              540,
              20.0
            ],
            [
              1020,
              1380,
              20.0
            ]
          ],
          [
            [
              420,
              540,
              20.0
            ],
            [
              1020,
              1380,
              20.0
            ]
          ],
          [
            [
              420,
              540,
              20.0
            ],
            [
              1020,
              1380,
              20.0
            ]
          ],
          [
            [
              420,
              1380,
              20.0
            ]
          ],
          [
            [
              420,
              1380,
              20.0
            ]
          ]
        ]
      },
      "dhw_schedule": {
        "base_temp": 60.0,
        "entries": [
          [],
          [],
          [],
          [],
          [],
          [],
          []
        ]
      }
    },
    "configuration": {
      "report_url": "https://reportprd.atag-one.com:443/api/message",
      "download_url": "http://firmware.atag-one.com:80/R42",
      "boiler_id": "P154230065",
      "boiler_det_type": 1,
      "language": 0,
      "pressure_unit": 0,
      "temp_unit": 0,
      "time_format": 1,
      "time_zone": 0,
      "summer_eco_mode": 0,
      "summer_eco_temp": 10.0,
      "shower_time_mode": 0,
      "comfort_settings": 0,
      "room_temp_offs": 0.0,
      "outs_temp_offs": 0.0,
      "ch_temp_max": 55.0,
      "ch_vacation_temp": 12.0,
      "start_vacation": 0,
      "wd_k_factor": 2.0,
      "wd_exponent": 1.4,
      "wd_control_temp": 0.0,
      "climate_zone": -12.0,
      "wd_temp_offs": 0.0,
      "dhw_legion_day": 3,
      "dhw_legion_time": 3,
      "dhw_boiler_cap": 0,
      "ch_building_size": 2,
      "ch_heating_type": 3,
      "ch_isolation": 1,
      "installer_id": "102749",
      "disp_brightness": 75,
      "ch_mode_vacation": 604800,
      "ch_mode_extend": 3600,
      "support_contact": "Installatiebedrijf\r\nTijhaar-Vilsteren BV\r\n\r\n0529458288",
      "privacy_mode": 0,
      "ch_max_set": 85.0,
      "ch_min_set": 20.0,
      "dhw_max_set": 10.0,
      "dhw_min_set": 10.0,
      "mu": 0.00,
      "dhw_legion_enabled": 1,
      "frost_prot_enabled": 0,
      "frost_prot_temp_outs": 0.0,
      "frost_prot_temp_room": 4.0,
      "wdr_temps_influence": 0,
      "max_preheat": 1440
    },
    "acc_status": 2,
    "wifi_scan": {
      "ssid_list": [
        {
          "SSID": "Ziggo06432",
          "RSSI": 7,
          "SECURITY": 2
        },
        {
          "SSID": "Ziggo",
          "RSSI": 6,
          "SECURITY": 2
        },
        {
          "SSID": "devolo-bcf2af9f1c0d",
          "RSSI": 2,
          "SECURITY": 2
        }
      ]
    }
  }
}

JSON documentation is loosely based on template https://bocoup.com/weblog/documenting-your-api

Thermostat Protocol - kozmoz/atag-one-api GitHub Wiki

Discovery

UDP

Discovery Message Format

Control

REST Interface

Request Authorization

Retrieve Info

⚠️ GitHub.com Fallback ⚠️

Thermostat Protocol - kozmoz/atag-one-api GitHub Wiki

Discovery

UDP

Discovery Message Format

Control

REST Interface

Request Authorization

Retrieve Info

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️