mysa2mqtt/README.md

mysa2mqtt

A Node.js application that bridges Mysa smart thermostats to MQTT, enabling integration with Home Assistant and other home automation platforms.

Features

• MQTT Integration: Exposes Mysa thermostats as MQTT devices compatible with Home Assistant's auto-discovery
• Real-time Updates: Live temperature, humidity, and power consumption monitoring
• Full Control: Set temperature, change modes (heat/off), and monitor thermostat status
• Session Management: Persistent authentication sessions to minimize API calls
• Configurable Logging: Support for JSON and pretty-printed log formats with adjustable levels

Supported hardware

Model Number	Description	Supported
BB-V1-X	Mysa Smart Thermostat for Electric Baseboard Heaters V1	✅ Tested and working
BB-V2-X	Mysa Smart Thermostat for Electric Baseboard Heaters V2	⚠️ Partially working, in progress
BB-V2-X-L	Mysa Smart Thermostat LITE for Electric Baseboard Heaters	⚠️ Partially working, in progress; does not report power consumption
unknown	Mysa Smart Thermostat for Electric In-Floor Heating	⚠️ Should work but not tested
AC-V1-X	Mysa Smart Thermostat for Mini-Split Heat Pumps & AC	🚫 Not supported (yet)

Disclaimer

This tool 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 tool permanently.

Prerequisites

• Node.js 22+
• A Mysa account with configured thermostats
• An MQTT broker (like Mosquitto)
• Optional: Home Assistant for auto-discovery

Installation

Option 1: Global Installation (Recommended)

Install globally via npm to use the mysa2mqtt command anywhere:

npm install -g mysa2mqtt

Option 2: Run with npx (No Installation Required)

Run directly without installing:

npx mysa2mqtt --help

Option 3: Development Setup

For development or custom modifications:

1. Clone the repository:

   git clone https://github.com/bourquep/mysa2mqtt.git
   cd mysa2mqtt
   

2. Install dependencies:

   npm install
   

3. Run the tool:

   npm run dev
   

Quick Start

1. Install the CLI tool:

   npm install -g mysa2mqtt
   

2. Run with basic configuration:

   mysa2mqtt --mqtt-host your-mqtt-broker.local --mysa-username your-email@example.com --mysa-password your-password
   

3. For persistent configuration, create a .env file:

   M2M_MQTT_HOST=your-mqtt-broker.local
   M2M_MYSA_USERNAME=your-mysa-email@example.com
   M2M_MYSA_PASSWORD=your-mysa-password
   

   Then simply run:

   mysa2mqtt
   

4. Check Home Assistant (if using auto-discovery):

   • Go to Settings → Devices & Services
   • Look for automatically discovered Mysa devices
   • Configure and add to your dashboard

Configuration

The application can be configured using either command-line arguments or environment variables. Environment variables take precedence over command-line defaults.

Required Configuration

CLI Option	Environment Variable	Description
-H, --mqtt-host	M2M_MQTT_HOST	Hostname of the MQTT broker
-u, --mysa-username	M2M_MYSA_USERNAME	Your Mysa account username/email
-p, --mysa-password	M2M_MYSA_PASSWORD	Your Mysa account password

Optional Configuration

MQTT Settings

CLI Option	Environment Variable	Default	Description
-P, --mqtt-port	M2M_MQTT_PORT	1883	Port of the MQTT broker
-U, --mqtt-username	M2M_MQTT_USERNAME	-	Username for MQTT broker authentication
-B, --mqtt-password	M2M_MQTT_PASSWORD	-	Password for MQTT broker authentication
-N, --mqtt-client-name	M2M_MQTT_CLIENT_NAME	mysa2mqtt	Name of the MQTT client
-T, --mqtt-topic-prefix	M2M_MQTT_TOPIC_PREFIX	mysa2mqtt	Prefix for MQTT topics

Application Settings

CLI Option	Environment Variable	Default	Description
-l, --log-level	M2M_LOG_LEVEL	info	Log level: silent, fatal, error, warn, info, debug, trace
-f, --log-format	M2M_LOG_FORMAT	pretty	Log format: pretty, json
-s, --mysa-session-file	M2M_MYSA_SESSION_FILE	session.json	Path to Mysa session file

Usage Examples

Using Environment Variables (.env file)

Create a .env file:

# Required
M2M_MQTT_HOST=mosquitto.local
M2M_MYSA_USERNAME=user@example.com
M2M_MYSA_PASSWORD=your-password

# Optional
M2M_MQTT_PORT=1883
M2M_MQTT_USERNAME=mqtt-user
M2M_MQTT_PASSWORD=mqtt-password
M2M_LOG_LEVEL=info
M2M_LOG_FORMAT=pretty

Then run:

mysa2mqtt

Using Command Line Arguments

mysa2mqtt \
  --mqtt-host mosquitto.local \
  --mqtt-port 1883 \
  --mqtt-username mqtt-user \
  --mqtt-password mqtt-password \
  --mysa-username user@example.com \
  --mysa-password your-password \
  --log-level debug \
  --log-format json

Mixed Configuration

You can combine both approaches. Environment variables will override command-line defaults:

# .env file
M2M_MQTT_HOST=mosquitto.local
M2M_MYSA_USERNAME=user@example.com
M2M_MYSA_PASSWORD=your-password

# Command line (will override .env if present)
mysa2mqtt --log-level debug --mqtt-port 8883

Home Assistant Integration

When using Home Assistant, devices will be automatically discovered and appear in:

• Settings → Devices & Services → MQTT
• Climate entities for temperature control
• Sensor entities for power monitoring

Troubleshooting

Common Issues

1. Authentication Failures

   • Verify your Mysa username and password
   • Check if session.json exists and is valid
   • Try deleting session.json to force re-authentication

2. MQTT Connection Issues

   • Verify MQTT broker hostname and port
   • Check MQTT credentials if authentication is required
   • Ensure the MQTT broker is accessible from your network

3. No Devices Found

   • Ensure your Mysa thermostats are properly configured in the Mysa app
   • Check logs for API errors
   • Verify your Mysa account has active devices

Debug Mode

Enable debug logging to get more detailed information:

mysa2mqtt --log-level debug

Or set in environment:

M2M_LOG_LEVEL=debug

Log Formats

• Pretty format (default): Human-readable colored output
• JSON format: Structured logging suitable for log aggregation

Docker Usage

Option 1: Pre-built Image (Recommended)

Use the official pre-built Docker image:

docker run -d --name mysa2mqtt \
  -e M2M_MQTT_HOST=your-mqtt-broker \
  -e M2M_MYSA_USERNAME=your-email \
  -e M2M_MYSA_PASSWORD=your-password \
  bourquep/mysa2mqtt:latest

With additional configuration:

docker run -d --name mysa2mqtt \
  -e M2M_MQTT_HOST=your-mqtt-broker \
  -e M2M_MQTT_PORT=1883 \
  -e M2M_MQTT_USERNAME=mqtt-user \
  -e M2M_MQTT_PASSWORD=mqtt-password \
  -e M2M_MYSA_USERNAME=your-email \
  -e M2M_MYSA_PASSWORD=your-password \
  -e M2M_LOG_LEVEL=info \
  -v $(pwd)/session.json:/app/session.json \
  bourquep/mysa2mqtt:latest

Option 2: Build Your Own Image

If you prefer to build your own image, create a Dockerfile:

FROM node:22-alpine

WORKDIR /app

# Install mysa2mqtt globally
RUN npm install -g mysa2mqtt

CMD ["mysa2mqtt"]

Build and run:

docker build -t mysa2mqtt .
docker run -d --name mysa2mqtt \
  -e M2M_MQTT_HOST=your-mqtt-broker \
  -e M2M_MYSA_USERNAME=your-email \
  -e M2M_MYSA_PASSWORD=your-password \
  mysa2mqtt

Option 3: Use Official Node.js Image

Run directly with the official Node.js image:

docker run -d --name mysa2mqtt \
  -e M2M_MQTT_HOST=your-mqtt-broker \
  -e M2M_MYSA_USERNAME=your-email \
  -e M2M_MYSA_PASSWORD=your-password \
  node:22-alpine \
  sh -c "npm install -g mysa2mqtt && mysa2mqtt"

Docker Compose

For easier management, create a docker-compose.yml file:

services:
  mysa2mqtt:
    image: bourquep/mysa2mqtt:latest
    container_name: mysa2mqtt
    restart: unless-stopped
    environment:
      - M2M_MQTT_HOST=your-mqtt-broker
      - M2M_MYSA_USERNAME=your-email
      - M2M_MYSA_PASSWORD=your-password
      - M2M_LOG_LEVEL=info
    volumes:
      - ./session.json:/app/session.json

Then run:

docker-compose up -d

Contributing

If you want to contribute to this project, please read the CONTRIBUTING.md file for guidelines.

License

mysa2mqtt 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.

Copyright

© 2025 Pascal Bourque

Support

• Issues: Report bugs and feature requests on GitHub Issues
• Discussions: Join the conversation on GitHub Discussions

Acknowledgments

• mysa-js-sdk - Mysa API client library

  • 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.

• mqtt2ha - MQTT to Home Assistant bridge library

• Commander.js - Command-line argument parsing

• Pino - Fast JSON logger