### Install and Run via Python

Source: https://context7.com/depau/meross2homie/llms.txt

Instructions for installing the bridge using pip and starting it with a configuration file.

```bash
# Clone and install
git clone https://github.com/Depau/meross2homie.git
cd meross2homie
pip install .

# Start the bridge with a config file
meross2homie ./config.yml
```

--------------------------------

### Install and Run Meross2Homie with Python

Source: https://github.com/depau/meross2homie/blob/main/README.md

Install the Meross2Homie bridge using pip and run it with a configuration file. Python 3.10 is required.

```bash
git clone https://github.com/Depau/meross2homie.git
cd meross2homie
pip install .

# To start the bridge
meross2homie ./config.yml
```

--------------------------------

### Meross2Homie Configuration Example

Source: https://github.com/depau/meross2homie/blob/main/README.md

Example configuration file (config.yml) for Meross2Homie. MQTT broker settings are mandatory. Other settings like log level, HTTP enablement, and topic prefixes are optional.

```yaml
# Logging level, one of: TRACE, DEBUG, INFO, WARNING, ERROR; default: INFO
log_level: INFO  # Optional

# MQTT broker settings
mqtt_host: ""
mqtt_port: 1883
mqtt_username: ""         # Optional
mqtt_password: ""         # Optional
mqtt_clean_session: true  # Optional


# Meross MQTT protocol settings

# Whether to enable connecting to the devices over HTTP. This is highly recommended, but it requires extra care to 
# ensure the broker has direct access to the devices. When this is off all requests will be sent over MQTT, except for
# reboot attempts if enabled.
enable_http: true  # Optional

# Key provided in the pairing app. It can be overridden on a per-device basis.
meross_key: ""                   # Optional

# Topic prefix that *this bridge* will see. Use a different value if you're
# mapping the devices to a different topic
meross_prefix: "/appliance"      # Optional

# Topic prefix that *the devices* will see. Defaults to the value of meross_prefix.
# Force this to "/appliance" if you're mapping the devices to a different topic.
meross_sent_prefix: "/appliance" # Optional

# Identifier used by this bridge. Change it if you're running multiple instances

```

--------------------------------

### Build and Run with Docker

Source: https://context7.com/depau/meross2homie/llms.txt

Commands to clone the repository, build the image using BuildKit, and start the container with a persistent configuration volume.

```bash
# Clone the repository
git clone https://github.com/Depau/meross2homie.git
cd meross2homie

# Build the Docker image with BuildKit
DOCKER_BUILDKIT=1 docker build -t meross2homie .

# Run the container with a configuration volume
docker run -v ./config:/config meross2homie
```

--------------------------------

### Bridge Configuration File

Source: https://context7.com/depau/meross2homie/llms.txt

A complete YAML configuration example defining MQTT broker settings, protocol options, and per-device overrides.

```yaml
# config.yml - Complete configuration example

# Logging level: TRACE, DEBUG, INFO, WARNING, ERROR
log_level: INFO

# MQTT broker connection settings (required)
mqtt_host: "192.168.1.100"
mqtt_port: 1883
mqtt_username: "homeassistant"
mqtt_password: "secret_password"
mqtt_clean_session: true

# Meross protocol settings
enable_http: true                      # Use HTTP for direct device communication (recommended)
meross_key: ""                         # Global device key (can be empty)
meross_prefix: "/appliance"            # MQTT topic prefix for this bridge
meross_sent_prefix: "/appliance"       # MQTT topic prefix devices see
meross_bridge_topic: "bridge"          # Bridge identifier

# Homie protocol settings
homie_prefix: "homie"                  # Homie MQTT topic prefix

# Bridge settings
persistence_file: "devices.json"       # File to store discovered devices
polling_interval: 10                   # Seconds between device polls
command_timeout: 2                     # Seconds to wait for command response
interview_command_timeout: 10          # Seconds for initial device interview
timed_out_commands_threshold: 5        # Failed commands before marking offline
interview_retry_times: 3               # Interview retry attempts
try_reboot_on_timeout: false           # Attempt device reboot on timeout

# Per-device configuration
devices:
  2102323a09d3381f813448f1c12345ab:    # Device UUID
    pretty_name: "Living Room Plug"
    pretty_topic: "living-room-plug"
    meross_key: "device_specific_key"

  abc123def456789012345678deadbeef:
    pretty_name: "Kitchen Appliance"
    pretty_topic: "kitchen-appliance"
```

--------------------------------

### Docker Compose Configuration

Source: https://context7.com/depau/meross2homie/llms.txt

Example docker-compose.yml file for deploying the bridge with a persistent volume for device data.

```yaml
# docker-compose.yml
version: '3'

services:
  meross2homie:
    build: ./meross2homie
    volumes:
      - ./config:/config   # Must be writable for device persistence
    restart: unless-stopped
```

--------------------------------

### Docker Compose Configuration

Source: https://github.com/depau/meross2homie/blob/main/README.md

Example docker-compose.yml to run the Meross2Homie service. Ensure the config volume is writable.

```yaml
version: '3' 

services:
  meross2homie:
    build: ./meross2homie
    volumes:
      - ./config:/config   # Do not mount as read-only
    restart: unless-stopped
```

--------------------------------

### Example Meross2Homie Persistence File Structure

Source: https://context7.com/depau/meross2homie/llms.txt

This JSON structure shows how discovered devices and their IP addresses are stored for persistence.

```json
// devices.json - Example persistence file structure
{
  "devices": {
    "2102323a09d3381f813448f1c12345ab": {
      "ip_address": "192.168.1.45"
    },
    "abc123def456789012345678deadbeef": {
      "ip_address": "192.168.1.46"
    }
  }
}
```

--------------------------------

### openHAB Thing Configuration for Meross Plug

Source: https://context7.com/depau/meross2homie/llms.txt

Example Thing configuration for an openHAB MQTT binding to control a Meross plug's power state.

```yaml
# openHAB Thing configuration example
Thing mqtt:topic:meross_plug "Living Room Plug" (mqtt:broker:local) {
    Channels:
        Type switch : power "Power" [
            stateTopic="homie/living-room-plug/switch/power",
            commandTopic="homie/living-room-plug/switch/power/set",
            on="true",
            off="false"
        ]
}
```

--------------------------------

### openHAB Items for Meross Energy Monitoring

Source: https://context7.com/depau/meross2homie/llms.txt

Example openHAB Items configuration to display daily and total energy consumption values.

```yaml
# openHAB Items example
Number:Energy  LivingRoomPlug_DailyConsumption  "Daily Consumption [%.3f kWh]"  {channel="mqtt:topic:meross_plug:daily"}
Number:Energy  LivingRoomPlug_TotalConsumption  "Total Consumption [%.3f kWh]"  {channel="mqtt:topic:meross_plug:total"}
```

--------------------------------

### Mosquitto Broker Configuration for Meross Devices

Source: https://context7.com/depau/meross2homie/llms.txt

Configuration for a dedicated Mosquitto MQTT broker, including TLS setup, YAML authentication, and bridging to a main broker. This setup is required for Meross devices.

```conf
# mosquitto.conf - Meross-dedicated broker configuration
listener 8883

# TLS certificates (required for Meross devices)
cafile /mosquitto/config/certs/ca.crt
certfile /mosquitto/config/certs/192.168.1.69.crt
keyfile /mosquitto/config/certs/192.168.1.69.key

# Authentication using YAML auth plugin
allow_anonymous true
auth_plugin /mosquitto/config/libmosquitto_yaml_auth.so
auth_opt_users_file /mosquitto/config/users.yml
auth_opt_allow_anonymous true

# Bridge to main MQTT broker
connection bridge_to_main
address main_mosquitto:1883

# Map /appliance/ topics to meross/ prefix on main broker
topic # both 2 /appliance/ meross/

bridge_attempt_unsubscribe false
remote_clientid broker.meross_bridge
try_private true
```

--------------------------------

### Mosquitto YAML Authentication User File

Source: https://context7.com/depau/meross2homie/llms.txt

Example user file for the Mosquitto YAML authentication plugin, defining usernames and passwords for device authentication.

```yaml
# users.yml - Mosquitto YAML auth plugin user file
users:
  - username: "00:11:22:33:44:55"
    password: "0_e8d95a51f3af4c15f5f66c9d8c12e4b3"
  - username: "aa:bb:cc:dd:ee:ff"
    password: "0_7a3b9c2d8e4f1a6b5c0d9e8f7a6b5c4d"
```

--------------------------------

### Control Meross Devices with BridgeManager API

Source: https://context7.com/depau/meross2homie/llms.txt

Use the BridgeManager class to load configuration, discover devices, send RPC commands (like GET system info or SET power state), and interact with Homie devices directly. Requires asyncio and meross2homie imports.

```python
import asyncio
from meross2homie.config import CONFIG
from meross2homie.manager import BridgeManager
from meross_iot.model.enums import Namespace

async def main():
    # Load configuration
    CONFIG.load("config.yml")

    # Create and run the bridge manager
    async with BridgeManager() as manager:
        # Wait for device discovery (devices auto-discovered on startup)
        await asyncio.sleep(5)

        # Send RPC command to a specific device
        device_uuid = "2102323a09d3381f813448f1c12345ab"

        # Get device system information
        response = await manager.rpc(
            uuid=device_uuid,
            method="GET",
            namespace=Namespace.SYSTEM_ALL,
            timeout=10.0
        )
        print(f"Device info: {response['payload']}")

        # Toggle device power via RPC
        await manager.rpc(
            uuid=device_uuid,
            method="SET",
            namespace=Namespace.CONTROL_TOGGLEX,
            payload={"togglex": {"onoff": 1, "channel": 0}}
        )

        # Access Homie device directly
        if device_uuid in manager.homie_devices:
            homie_device = manager.homie_devices[device_uuid]

            # Update switch state
            await homie_device["switch"]["power"].update_value(True)

            # Poll device for latest data
            await homie_device.poll()

        # Process events (blocks until interrupted)
        await manager.process_events()

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Monitor Meross Device Electricity Metrics

Source: https://context7.com/depau/meross2homie/llms.txt

Commands to get real-time voltage, current, and power consumption data from electricity-capable devices. Units are Volts, Amps, and Watts respectively.

```bash
# Get current voltage
mosquitto_sub -h localhost -t "homie/<device-topic>/electricity/voltage"
# Output: 120.5 (Volts)
```

```bash
# Get current amperage
mosquitto_sub -h localhost -t "homie/<device-topic>/electricity/current"
# Output: 0.85 (Amps)
```

```bash
# Get current power consumption
mosquitto_sub -h localhost -t "homie/<device-topic>/electricity/power"
# Output: 102.4 (Watts)
```

--------------------------------

### Mosquitto Configuration for Meross Bridge

Source: https://github.com/depau/meross2homie/blob/main/README.md

Configuration for a Mosquitto MQTT broker acting as a bridge for Meross devices. Includes TLS settings, authentication plugin setup, and bridging to a main MQTT broker with topic mapping.

```mosquitto
listener 8883

cafile /mosquitto/config/certs/ca.crt
certfile /mosquitto/config/certs/192.160.1.69.crt
keyfile /mosquitto/config/certs/192.160.1.69.key

allow_anonymous true
auth_plugin /mosquitto/config/libmosquitto_yaml_auth.so
auth_opt_users_file /mosquitto/config/users.yml
auth_opt_allow_anonymous true

connection bridge_to_main
address main_mosquitto:1883

# Maps /appliance/ to meross/
topic # both 2 /appliance/ meross/

# or if you don't want to do that
# topic /appliance/# both

bridge_attempt_unsubscribe false
remote_clientid broker.meross_bridge
try_private true
```

--------------------------------

### Subscribe to All Meross Device State Changes

Source: https://context7.com/depau/meross2homie/llms.txt

Use this command to subscribe to all state changes from a specific Meross device. Replace <device-topic> with the device's unique topic.

```bash
mosquitto_sub -h localhost -t "homie/2102323a09d3381f813448f1c12345ab/#" -v
```

--------------------------------

### Manage Device Persistence with Persistence Class

Source: https://context7.com/depau/meross2homie/llms.txt

Use the Persistence class to load, check, add, and save discovered devices and their IP addresses to a JSON file. Requires pathlib and meross2homie.persistence imports.

```python
from pathlib import Path
from meross2homie.persistence import Persistence, DeviceProps

# Load existing persistence file
persistence = Persistence.load(Path("devices.json"))

# Check discovered devices
for uuid, props in persistence.devices.items():
    print(f"Device {uuid}: IP={props.ip_address}")

# Add a device manually
persistence.devices["new_device_uuid"] = DeviceProps(
    ip_address="192.168.1.50"
)

# Save changes
persistence.persist(Path("devices.json"))
```

--------------------------------

### Build Meross2Homie Docker Image

Source: https://github.com/depau/meross2homie/blob/main/README.md

Build the Docker image for the Meross2Homie bridge. Requires Docker 18.09+ with BuildKit support. Mount the configuration directory as a writable volume to /config.

```bash
git clone https://github.com/Depau/meross2homie.git
cd meross2homie
DOCKER_BUILDKIT=1 docker build -t meross2homie .
```

--------------------------------

### Generate MQTT Credentials

Source: https://context7.com/depau/meross2homie/llms.txt

Methods for generating device MQTT passwords using the command-line tool or the Python library.

```bash
# Generate password for a device
# Usage: meross_mqtt_password <user_id> <key> <MAC_address>
$ meross_mqtt_password 0 "" 00:11:22:33:44:55
Username: 00:11:22:33:44:55
Password: 0_e8d95a51f3af4c15f5f66c9d8c12e4b3

# With a custom user ID and device key
$ meross_mqtt_password 12345 "mysecretkey" AA:BB:CC:DD:EE:FF
Username: aa:bb:cc:dd:ee:ff
Password: 12345_7a3b9c2d8e4f1a6b5c0d9e8f7a6b5c4d
```

```python
# Programmatic password calculation
from meross2homie.main import calc_mqtt_password

# Calculate MQTT password for device authentication
password = calc_mqtt_password(
    user_id="0",
    key="",  # Empty key is fine
    mac_address="00:11:22:33:44:55"
)
print(f"Password: {password}")
# Output: Password: 0_e8d95a51f3af4c15f5f66c9d8c12e4b3

# Password formula: user_id + "_" + md5(mac_address.lower() + key).hexdigest()
```

--------------------------------

### Meross Bridge and Homie MQTT Configuration

Source: https://github.com/depau/meross2homie/blob/main/README.md

Configure Meross bridge topic, Homie MQTT topic prefix, and persistence file location. Device-specific configurations for vanity names and Meross keys can also be set.

```yaml
meross_bridge_topic: "bridge"    # Optional
homie_prefix: "homie"
persistence_file: "devices.json" # Optional
devices:
  device_uuid:
    pretty_name: "Pretty name"
    pretty_topic: "pretty-topic"
    meross_key: "key"
  other_device_uuid:
  # ...
```

--------------------------------

### Generate Meross MQTT Password

Source: https://github.com/depau/meross2homie/blob/main/README.md

Use this command-line tool to generate the MQTT password for Meross devices. The username is the lowercase MAC address. Requires USER_ID, MQTT_DEVICE_KEY, and the device's MAC address.

```bash
$ meross_mqtt_password USER_ID MQTT_DEVICE_KEY 00:11:22:33:44:55
```

--------------------------------

### System Reboot Command

Source: https://context7.com/depau/meross2homie/llms.txt

Trigger a device reboot.

```APIDOC
## MQTT homie/<device-topic>/system/reboot/set

### Description
Send a command to reboot the device.

### Endpoint
homie/<device-topic>/system/reboot/set

### Request Body
- **payload** (string) - Required - Must be "REQUEST".
```

--------------------------------

### Generate CA and Broker Certificates

Source: https://github.com/depau/meross2homie/blob/main/README.md

Shell script commands to generate Certificate Authority (CA) and broker certificates for TLS encryption. First, generate the CA, then generate specific certificates for the broker IP address.

```bash
./generate-CA.sh               # First generate the CA
./generate-CA.sh 192.168.1.69  # Generate certificates for broker IP address
```

--------------------------------

### Meross MQTT Password Generation Logic

Source: https://github.com/depau/meross2homie/blob/main/README.md

Python code snippet illustrating the logic for generating the Meross MQTT password using MD5 hashing. It concatenates the user ID with the hexdigest of the MD5 hash of the MAC address and device key.

```python
from hashlib import md5

password = str(user_id) + "_" + md5(mac_address + device_key).hexdigest().lower()
```

--------------------------------

### Energy Monitoring Node

Source: https://context7.com/depau/meross2homie/llms.txt

Access historical and real-time power consumption data.

```APIDOC
## MQTT homie/<device-topic>/energy/daily
## MQTT homie/<device-topic>/energy/total
## MQTT homie/<device-topic>/energy/history

### Description
Retrieve energy consumption metrics.

### Endpoint
homie/<device-topic>/energy/daily
homie/<device-topic>/energy/total
homie/<device-topic>/energy/history

### Response
- **daily** (float) - Daily consumption in kWh.
- **total** (float) - Total consumption in kWh.
- **history** (json) - Array of objects containing timestamp and total_consumption_kwh.
```

--------------------------------

### Access Meross Device Energy Consumption Data

Source: https://context7.com/depau/meross2homie/llms.txt

Commands to retrieve daily, total, and historical energy consumption data in kWh. The history output is a JSON array of consumption records.

```bash
# Get daily consumption in kWh
mosquitto_sub -h localhost -t "homie/<device-topic>/energy/daily"
# Output: 0.245
```

```bash
# Get total consumption (sum of historical data) in kWh
mosquitto_sub -h localhost -t "homie/<device-topic>/energy/total"
# Output: 15.782
```

```bash
# Get consumption history as JSON
mosquitto_sub -h localhost -t "homie/<device-topic>/energy/history"
# Output: [{"timestamp": "2024-01-15T00:00:00", "total_consumption_kwh": 0.245}, ...]
```

--------------------------------

### Electricity Metrics Node

Source: https://context7.com/depau/meross2homie/llms.txt

Monitor real-time electrical measurements.

```APIDOC
## MQTT homie/<device-topic>/electricity/voltage
## MQTT homie/<device-topic>/electricity/current
## MQTT homie/<device-topic>/electricity/power

### Description
Retrieve real-time electrical measurements.

### Endpoint
homie/<device-topic>/electricity/voltage
homie/<device-topic>/electricity/current
homie/<device-topic>/electricity/power

### Response
- **voltage** (float) - Volts.
- **current** (float) - Amps.
- **power** (float) - Watts.
```

--------------------------------

### Control Meross Smart Plug Power State

Source: https://context7.com/depau/meross2homie/llms.txt

Commands to read the current power state and to turn a smart plug on or off. For multi-channel devices, append the channel number (e.g., switch-1).

```bash
# Read current power state
mosquitto_sub -h localhost -t "homie/<device-topic>/switch/power"
# Output: true or false
```

```bash
# Turn device on
mosquitto_pub -h localhost -t "homie/<device-topic>/switch/power/set" -m "true"
```

```bash
# Turn device off
mosquitto_pub -h localhost -t "homie/<device-topic>/switch/power/set" -m "false"
```

```bash
# For multi-channel devices, channels are numbered (switch-0, switch-1, etc.)
mosquitto_pub -h localhost -t "homie/<device-topic>/switch-1/power/set" -m "true"
```

--------------------------------

### Control Meross Device LED (Do Not Disturb)

Source: https://context7.com/depau/meross2homie/llms.txt

Commands to check the Do Not Disturb (DND) status and to enable or disable the device LED indicator.

```bash
# Check DND status
mosquitto_sub -h localhost -t "homie/<device-topic>/dnd/dnd"
# Output: true or false
```

```bash
# Enable DND (turn off LED)
mosquitto_pub -h localhost -t "homie/<device-topic>/dnd/dnd/set" -m "true"
```

```bash
# Disable DND (turn on LED)
mosquitto_pub -h localhost -t "homie/<device-topic>/dnd/dnd/set" -m "false"
```

--------------------------------

### Switch Control Node

Source: https://context7.com/depau/meross2homie/llms.txt

Control the power state of toggle-capable devices like smart plugs and switches.

```APIDOC
## MQTT homie/<device-topic>/switch/power

### Description
Read or set the power state of a switch or plug.

### Endpoint
homie/<device-topic>/switch/power
homie/<device-topic>/switch/power/set

### Request Body
- **payload** (string) - Required - "true" to turn on, "false" to turn off.

### Response
- **state** (string) - "true" or "false"
```

--------------------------------

### Trigger Meross Device Reboot

Source: https://context7.com/depau/meross2homie/llms.txt

Command to send a reboot request to the Meross device via the system node.

```bash
# Send reboot command
mosquitto_pub -h localhost -t "homie/<device-topic>/system/reboot/set" -m "REQUEST"
```

--------------------------------

### Do Not Disturb Node

Source: https://context7.com/depau/meross2homie/llms.txt

Control the device LED indicator.

```APIDOC
## MQTT homie/<device-topic>/dnd/dnd

### Description
Check or set the DND (LED) status.

### Endpoint
homie/<device-topic>/dnd/dnd
homie/<device-topic>/dnd/dnd/set

### Request Body
- **payload** (string) - Required - "true" to disable LED, "false" to enable LED.

### Response
- **status** (string) - "true" or "false"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.