Venstar ColorTouch Thermostat

Local-LAN driver for the Venstar ColorTouch family of thermostats (T5800, T6800, T7800, T7850, T8850 and Explorer Mini). The thermostat runs an on-device HTTP server with a documented JSON REST API — no cloud account, no broker, no vendor dependency.

Prerequisites

• A Venstar ColorTouch thermostat on the same LAN as the GEM controller.
• Firmware 3.x or newer. The Local API was added in 2014 and ships enabled by default on every modern firmware.
• The Local API enabled on the thermostat: Menu → Wi-Fi → Local API, toggle Read and Control on.
• A static IP or DHCP reservation for the thermostat. The thermostat's current IP is shown on the same Local API screen.

Setup

1. On the thermostat: Menu → Wi-Fi → Local API → Read + Control.
2. In GEM admin, go to System → Devices → Add Device (Open Devices) and choose the Venstar ColorTouch Thermostat driver.
3. Fill in ip (required) — the address shown on the thermostat screen.
4. Leave username and password blank unless you set a Local API password on the thermostat itself. If you did, fill in username (default admin) and password — the driver will use HTTP Basic auth on every request.
5. Save. On connect the driver hits GET / to read the model and firmware, then begins polling /query/info every status_interval ms (default 30 s).
6. Create one zone bound to this device. File it under the Climate subsystem — the zone editor pre-selects Climate for you, because this driver reports a climate subsystem hint that matches the built-in Climate subsystem. A zone.address is not required — Venstar exposes a single thermostat per unit.

This driver does not create zones for you. It only writes thermostat state onto a zone you have already created and bound to the device. Until that zone exists, the device connects and polls but has nowhere to publish temperature, mode, or setpoints.

Attributes

Device

Attribute	Type	Required	Description
ip	string	yes	LAN IP of the thermostat.
port	int	no	Default 80. Set if the firmware exposes a non-standard port.
username	string	no	Local API username. Default admin. Only used if a password is set.
password	string (secure)	no	Local API password. Encrypted at rest.
status_interval	int	no	Poll interval in ms. Default 30000, min 2000.
api_version	string	auto	Reported by GET /.
model	string	auto	Reported by GET /.
firmware	string	auto	Reported by GET /.

Zone

The driver publishes the following zone attributes from each /query/info poll:

Attribute	Description
temperature	Current indoor temperature, in the thermostat's units.
humidity	Current relative humidity %, on humidity-equipped models.
setpoint	Active setpoint — follows mode (heat / cool / auto midpoint).
heat_setpoint	Heat setpoint.
cool_setpoint	Cool setpoint.
mode	off / heat / cool / auto.
fan_mode	auto / on.
running	idle / heating / cooling / lockout / error.
away	home / away.
schedule	off / on.
units	F / C — read-only, configured on the thermostat.
state	off if mode is off, otherwise on.

Commands

• set_mode (off | heat | cool | auto)
• set_fan_mode (auto | on)
• set_setpoint — sets the active leg (heat in heat mode, cool in cool mode, both shifted around the value in auto mode while preserving the configured spread).
• set_heat_setpoint, set_cool_setpoint — directly set one leg.
• set_setpoints (heat, cool) — atomic write of both.
• set_away (home | away)
• set_schedule (off | on)
• on / off — convenience aliases for set_mode auto / set_mode off.
• get_info, get_status, get_sensors, get_runtimes, get_alerts — read-only diagnostics.

Zone address format

Optional. ColorTouch is a single-thermostat device, so the typical install is one zone per device with zone.address blank. Multi-zone bindings work (the driver polls each), but they all reflect the same thermostat state.

Known limitations

• The thermostat's control endpoint (POST /control) requires all four of mode, fan, heattemp, and cooltemp in every write. The driver handles this for you — it reads the current state first and merges in only the field your command changes — so you always issue a single named command (set_mode, set_setpoint, set_fan_mode, …) and never have to supply the other fields yourself.
• In auto mode, the cool setpoint must remain at least setpointdelta above the heat setpoint (factory default 2 °F). The thermostat rejects violations with {"error": true, "reason": "..."} — the driver surfaces the reason as the command result.
• Temperature units (F/C) are read-only from GEM. Change them on the thermostat's local UI; setpoint commands are interpreted in whatever units the device is currently configured for.
• Schedule / event editing (the on-device weekly program) is not exposed — only enable / disable. Editing the schedule itself is a separate /schedule endpoint that is not part of this driver's command surface.
• Humidify / dehumidify control is not part of this driver's command surface. On humidifier-equipped models the thermostat exposes humidity setpoints, but the driver has no command to write them — it only reads the current relative humidity (the humidity zone attribute). There is no humidity-control command to call from a macro, trigger, or the command tester.
• The driver assumes a single thermostat per device. ColorTouch units are stand-alone — there is no controller / multi-thermostat hub variant in the product line.

Troubleshooting

Symptom	Check
connect probe error: connect ECONNREFUSED	The Local API is disabled on the thermostat. Enable Read and Control under Menu → Wi-Fi → Local API.
Commands return {"error": true, "reason": "..."}	The thermostat rejected the merged body. Common cause: trying to write a cool setpoint below heat + setpointdelta in auto mode.
Setpoint changes silently revert	The on-device schedule is still active. Either disable the schedule (set_schedule off) or set away to keep your override.
401 Unauthorized on POSTs	A Local API password is set on the thermostat but the driver username/password attributes are blank or wrong. Default username is admin.
GET requests work but mode never changes	Confirm Control (not just Read) is enabled on the thermostat's Local API screen.
Device shows Connected but the zone has no temperature, mode, or setpoint	No zone is bound to this device yet (the driver does not create one for you), or the bound zone isn't where your UI is looking. Create a zone with this device as its driver, under the Climate subsystem, and add it to the UI or site space that should show it.

Related documentation

• Devices — adding the thermostat, secure attributes, and Reload.
• Zones — creating the zone this driver publishes thermostat state onto.
• Subsystems — the Climate subsystem these zones live under.
• Commands — running set_mode, set_setpoint, and the read-only diagnostics from the command tester, macros, and triggers.