Mysa Smart Thermostat

Cloud driver for Mysa thermostats — radiant baseboard, in-floor, and in-ceiling lines. GEM signs in to the user's Mysa account through AWS Cognito and drives setpoint and mode through the app-prod.mysa.cloud user API.

Prerequisites

• A Mysa account (the same email + password used in the iOS / Android Mysa app).
• Each thermostat to be controlled must already be claimed in the Mysa app — this driver does not provision new devices.
• Outbound HTTPS from GEM to:
  • cognito-idp.us-east-1.amazonaws.com (Cognito sign-in)
  • app-prod.mysa.cloud (device state and command API)
• The Mysa account must not have multi-factor auth enabled. MFA is on the roadmap but not yet handled by this driver.

Setup

1. Add a device in GEM with driver mysa.
2. Fill in:
   • email — Mysa account email.
   • password — Mysa account password (stored encrypted).
   • status_interval (optional) — poll cadence in ms, default 30000.
3. Save and reload the device. Watch the server log for mysa connected: … and mysa devices: <count>.
4. Run the get_devices command to print every thermostat with its Mysa device ID and model.
5. Create one zone per thermostat under your climate subsystem and set zone.address to the Mysa device ID. The driver will populate zone.model automatically on the next status poll.

Auth flow

1. POST cognito-idp.us-east-1.amazonaws.com/ with AuthFlow: USER_PASSWORD_AUTH returns IdToken, AccessToken, and RefreshToken.
2. IdToken is sent as the Authorization header on every Mysa API call.
3. When the IdToken nears expiry the driver issues REFRESH_TOKEN_AUTH to mint a fresh one. If the refresh fails (token revoked, password changed) the driver falls back to a full sign-in.

Attributes

Device

Name	Required	Description
email	yes	Mysa account email.
password	yes	Mysa account password. Encrypted via GEM's secure-attribute system.
status_interval	no	Poll cadence in ms, default 30000.

Zone

Name	Required	Description
address	yes	Mysa device ID (run get_devices to enumerate).
model	no	Auto-populated.

The driver also writes the following live state attributes per zone on each poll: temperature, setpoint, humidity, mode.

Zone address format

A Mysa device ID is a GUID-like string returned in the Devices map of getDevicesV2. Use it verbatim as zone.address.

Commands

Command	Args	Notes
setpoint	address, setpoint	Target temperature in °C. The driver hard-codes scheduleHold: "forever".
system_mode	address, mode (heat / cool / auto / off)	Sets HVAC mode. Not every Mysa hardware supports every mode (the baseboard line is heat-only).
on / off	address	Convenience: equivalent to system_mode heat and system_mode off.
get_state	address	Returns parsed temperature / setpoint / humidity / mode for one device.
get_devices	—	Lists every thermostat on the account with its device ID and model.

Known limitations

• Setpoints are Celsius. UIs that work in Fahrenheit must convert before invoking setpoint. A future revision may auto-convert using the device's LockedUnits field.
• Schedule-hold is forever. The driver does not yet expose timed hold-until.
• Cognito MFA is not handled. Accounts with MFA enabled cannot sign in until the auth flow is extended to support MFA_SETUP / SMS_MFA challenges.
• Cloud-only. Mysa does not publish a LAN API. If the upstream cloud is unreachable the driver will surface a disconnected state.

Troubleshooting

• cognito did not return AuthenticationResult — almost always a credential issue. Confirm you can sign in with the same email and password in the Mysa mobile app.
• NotAuthorizedException — wrong password or the account was rate-limited after repeated failures. Wait a few minutes.
• UserNotConfirmedException — the Mysa account hasn't been verified via the welcome email yet.
• 401 / 403 after a long-running connection — the IdToken expired and the silent refresh failed; the driver retries a fresh sign-in automatically. Sustained 401s usually mean the password changed in the Mysa app.
• http request error: ETIMEDOUT — Mysa or AWS Cognito is unreachable from the GEM server. Check outbound HTTPS / DNS.
• Setpoint sent but the thermostat doesn't change — confirm the device's mode is heat or cool (not off); a setpoint while off is accepted by the API but won't actuate the relay.