A JavaScript SDK for accessing Mysa smart thermostats.
This SDK provides a simple and intuitive way to interact with Mysa smart thermostats, allowing developers to easily query and update data from their Mysa smart thermostats, including real-time updates.
This SDK was developed without the consent of the Mysa Smart Thermostats company, and makes use of undocumented and unsupported APIs. Use at your own risk, and be aware that Mysa may change the APIs at any time and break this repository permanently.
# Using npm
npm install mysa-js-sdk
# Using yarn
yarn add mysa-js-sdk
# Using pnpm
pnpm add mysa-js-sdk
To run the example application, you'll need to provide your Mysa credentials. Create a .env file in
the project root:
MYSA_USERNAME=your-email@example.com
MYSA_PASSWORD=your-password
Then, run the example:
npm run example
If you prefer to see the raw data published by your Mysa smart thermostats, run:
npm run example:raw
The Mysa SDK provides a simple interface to interact with Mysa smart thermostats.
import { MysaApiClient } from 'mysa-js-sdk';
// The client holds your credentials and authenticates on demand
const client = new MysaApiClient({
username: 'your-email@example.com',
password: 'your-password'
});
// Optional: log in eagerly to fail fast on invalid credentials
await client.login();
The client manages its session on its own: it refreshes the session when it needs to, and logs back in automatically when the refresh token has itself expired or been revoked. There is nothing to persist, and no need to re-create the client after a long run.
Once authenticated, you can access your thermostat data:
// Get all devices
const devices = await client.getDevices();
// Access individual devices
for (const [deviceId, device] of Object.entries(devices.DevicesObj)) {
console.log(`Device: ${device.Name}`);
console.log(`Model: ${device.Model}`);
console.log(`Location: ${device.Location}`);
console.log(`Voltage: ${device.Voltage}V`);
}
// Set device temperature and mode
await client.setDeviceState('device-id', 22, 'heat'); // Set to 22°C in heat mode
await client.setDeviceState('device-id', undefined, 'off'); // Turn off
Commands are sent over MQTT. If a device's MQTT topic rejects them — as now happens on some accounts, where AWS IoT drops the connection on every publish — set point and mode changes are sent through Mysa's REST API instead, the same way the Mysa app does, and later ones for that device go straight there. Fan speed and tracked sensor changes have no REST equivalent and are always sent over MQTT.
The REST API also exposes each device's structured state, which separates the values last requested from those the device has applied:
const state = await client.getDeviceShadowState('device-id');
console.log(`Requested: ${state.targetHeat?.desired?.setpoint}°C, applied: ${state.targetHeat?.reported?.setpoint}°C`);
The SDK also supports real-time updates:
// Listen for temperature and status changes
client.emitter.on('statusChanged', (status) => {
console.log(`Device ${status.deviceId}:`);
console.log(` Temperature: ${status.temperature}°C`);
console.log(` Humidity: ${status.humidity}%`);
console.log(` Set Point: ${status.setPoint}°C`);
if (status.current !== undefined) {
console.log(` Current: ${status.current}A`);
}
});
// Listen for setpoint changes
client.emitter.on('setPointChanged', (change) => {
console.log(`Setpoint changed from ${change.previousSetPoint}°C to ${change.newSetPoint}°C`);
});
// Listen for device state changes
client.emitter.on('stateChanged', (change) => {
console.log(`Device mode changed to: ${change.mode}`);
console.log(`New setpoint: ${change.setPoint}°C`);
});
// Start real-time updates for all devices
const devices = await client.getDevices();
for (const deviceId of Object.keys(devices.DevicesObj)) {
await client.startRealtimeUpdates(deviceId);
}
The SDK provides specific error types to handle API errors:
import { MysaApiClient, MysaApiError, UnauthenticatedError } from 'mysa-js-sdk';
const client = new MysaApiClient({ username: 'user@example.com', password: 'password' });
try {
const devices = await client.getDevices();
} catch (error) {
if (error instanceof UnauthenticatedError) {
console.error('Authentication failed:', error.message);
} else if (error instanceof MysaApiError) {
console.error(`API Error ${error.status}: ${error.statusText}`);
} else {
console.error('Unexpected error:', error);
}
}
You can customize the client with various options:
import { MysaApiClient } from 'mysa-js-sdk';
import { pino } from 'pino';
// Create a custom logger
const logger = pino({
name: 'mysa-client',
level: 'debug'
});
// Configure client with options
const client = new MysaApiClient(
{ username: 'user@example.com', password: 'password' },
{
logger: logger,
fetcher: fetch // Custom fetch implementation if needed
}
);
The complete reference documentation for the mysa-js-sdk library can be found at
https://bourquep.github.io/mysa2mqtt/mysa-js-sdk/.
If you want to contribute to this project, please read the CONTRIBUTING.md file for guidelines.
mysa-js-sdk is licensed under the MIT License. This is a permissive license that allows you to use, modify, and
redistribute this software in both private and commercial projects. You can change the code and distribute your changes
without being required to release your source code. The MIT License only requires that you include the original
copyright notice and license text in any copy of the software or substantial portion of it.
© 2025 Pascal Bourque
For bug reports and feature requests, please use the GitHub Issues page.
For general questions and discussions, join our Discussion Forum.
This library would not be possible without the amazing work by @dlenski in his mysotherm repository. He's the one who reversed-engineered the Mysa MQTT protocol which is being used by this library.
The REST fallback used to control thermostats whose MQTT topic rejects commands is based on the Mysa cloud API
reverse-engineered by @SokolskyNikita and documented in their
mysa-homeassistant
repository. Thanks also to @laurentlgm for diagnosing the rejected MQTT commands and
validating the REST state endpoints on a BB-V1 thermostat.
This project follows the all-contributors specification. See the contributor list in the repository README. Contributions of any kind welcome!