[Feature Request] Setup Guide

I love this project. I used it to successfully onboard several Meross mfc100 fan/dimmer switches to my local MQTT broker without ever connecting them to the cloud.

While the process worked great, I found getting started to be daunting as a less technical user. The main hurdles were:
- Understanding the build/install process
- Discovering that newer firmware (encrypt: 1) requires TLS on port 8883
- Interpreting the WiFi scan output for encryption/cipher values

I traced my steps and created a step-by-step guide with the help of Claude. I'm adding it here in case it might help others and encourage more people to use this excellent project.

# Meross Device Setup Guide

This guide walks you through configuring Meross smart devices to use your own MQTT broker instead of the Meross cloud.

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Installation](#installation)
3. [Device Preparation](#device-preparation)
4. [Configuration Steps](#configuration-steps)
5. [Verifying the Setup](#verifying-the-setup)
6. [Troubleshooting](#troubleshooting)
7. [Home Assistant Integration](#home-assistant-integration)

---

## Prerequisites

Before you begin, ensure you have:

- **Node.js** version 18 or higher installed
- **Git** installed
- An **MQTT broker** running on your network (e.g., Mosquitto)
- Your **WiFi network name (SSID)** and **password**
- A computer that can connect to WiFi networks

### MQTT Broker Requirements

**Important:** Newer Meross devices (firmware with `encrypt: 1`) require TLS/SSL connections. Your MQTT broker must:

- Listen on port **8883** with TLS enabled
- Have a valid certificate (self-signed is fine)

If your broker only supports plain MQTT on port 1883, older devices may still work, but newer firmware will fail with "protocol error".

---

## Installation

### Step 1: Clone the Repository

```bash
git clone https://github.com/bytespider/Meross.git
cd Meross
```

### Step 2: Install Dependencies

```bash
npm install
```

### Step 3: Build the Project

```bash
npm run build
```

### Step 4: Link the CLI (Optional)

To use `meross` as a global command:

```bash
npm link --workspace=meross
```

After linking, you can run commands as `meross info` instead of `node packages/cli/dist/meross.js info`.

---

## Device Preparation

### Step 1: Put Device in Pairing Mode

1. Locate the button on your Meross device
2. Press and hold the button for **5-7 seconds**
3. The LED should start **alternating amber/green** (pairing mode)

If the LED shows a different pattern, consult your device manual or try holding the button longer (up to 10 seconds) for a factory reset.

### Step 2: Connect to the Device's WiFi

1. On your computer, open WiFi settings
2. Look for a network named **`Meross_XXXXXX`** (where XXXXXX varies)
3. Connect to this network (no password required)
4. Your computer should now be connected to the device directly

**Note:** You will lose internet access while connected to the device's WiFi.

---

## Configuration Steps

### Step 1: Scan for WiFi Networks

Run the following command to see available WiFi networks and get your network's encryption settings:

```bash
meross info -a 10.10.10.1 --with-wifi
```

Or if you didn't link the CLI:

```bash
node packages/cli/dist/meross.js info -a 10.10.10.1 --with-wifi
```

Look for your WiFi network in the output and note the **encryption** and **cipher** values.

Example output:
```
┌───────────────────┬──────────────────────────────────────────────────────────┐
│Device │mfc100 un rtl8710cm (hardware:7.0.0 firmware:7.3.17) │
├───────────────────┼──────────────────────────────────────────────────────────┤
│UUID │25070266958584680801c4e7ae1a168b │
├───────────────────┼──────────────────────────────────────────────────────────┤
│Mac address │c4:e7:ae:1a:16:8b │
│... │... │
└───────────────────┴──────────────────────────────────────────────────────────┘
✓Getting WIFI list…
┌──────────────────────────────────────────────────────┬───────────────────────┐
│WIFI │Signal strength │
├──────────────────────────────────────────────────────┼───────────────────────┤
│MyNetwork │▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▎ │
│60:22:32:8a:71:ce Ch: 6 Encryption: 6 Cipher: 3 │ │
├──────────────────────────────────────────────────────┼───────────────────────┤
│AnotherNetwork │▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▊ │
│62:22:32:aa:71:ce Ch: 6 Encryption: 13 Cipher: 6 │ │
└──────────────────────────────────────────────────────┴───────────────────────┘
```

Find your network in the list and note the **Encryption** and **Cipher** values shown below the SSID. In the first example above, encryption is `6` and cipher is `3`.

### Step 2: Configure the Device

Run the setup command with your network details:

```bash
meross setup -a 10.10.10.1 \
--wifi-ssid 'YourNetworkName' \
--wifi-pass 'YourWiFiPassword' \
--wifi-encryption \
--wifi-cipher \
--mqtt 'mqtts://YOUR_BROKER_IP:8883' \
-t
```

**Replace:**
- `YourNetworkName` - Your WiFi network name
- `YourWiFiPassword` - Your WiFi password
- `` - The encryption value from Step 1
- `` - The cipher value from Step 1
- `YOUR_BROKER_IP` - Your MQTT broker's IP address

**Examples:**

For a broker with TLS on port 8883:
```bash
meross setup -a 10.10.10.1 \
--wifi-ssid 'HomeNetwork' \
--wifi-pass 'secretpassword123' \
--wifi-encryption 6 \
--wifi-cipher 3 \
--mqtt 'mqtts://192.168.1.100:8883' \
-t
```

### Step 3: Reconnect to Your Home Network

After running the setup command:

1. The device will reboot automatically
2. Disconnect from the `Meross_XXXXXX` network
3. Reconnect your computer to your home WiFi network

---

## Verifying the Setup

### Step 1: Find the Device's New IP Address

Check your router's DHCP leases or use a network scanner to find the device. Look for a device with a MAC address starting with the Meross prefix or matching the one shown during setup.

### Step 2: Query the Device

```bash
meross info -a
```

Replace `` with the device's new IP address on your network.

You should see output showing:
- Device model and firmware version
- **Current MQTT broker** pointing to your broker
- MQTT credentials and topics

### Step 3: Check the LED

| LED Color | Meaning |
|-----------|---------|
| Solid Green | Connected and working |
| Flashing Green | Connecting to WiFi/MQTT |
| Solid Red | Cannot connect to MQTT broker |
| Amber/Green Alternating | Pairing mode |

### Step 4: Check MQTT Broker Logs

On your MQTT broker, you should see a new client connection:
```
New client connected from X.X.X.X as fmware:DEVICE_UUID...
```

---

## Troubleshooting

### Device Shows Solid Red LED

**Cause:** Device cannot connect to MQTT broker.

**Solutions:**

1. **Check TLS requirement:** Newer devices require TLS. Use `mqtts://` and port 8883.

2. **Verify network connectivity:** Ensure the device can reach your broker's IP address.

3. **Check broker logs:** Look for connection attempts or errors:
- "Protocol error" = TLS mismatch (device expects TLS, broker doesn't have it)
- No connection attempts = Network/firewall issue

4. **Verify broker is listening:**
```bash
nc -zv YOUR_BROKER_IP 8883
```

### "Protocol Error" in Broker Logs

**Cause:** Device firmware requires TLS but broker is configured for plain MQTT.

**Solution:** Enable TLS on your MQTT broker:

```bash
# Generate self-signed certificate
openssl req -new -x509 -days 365 -nodes \
-out /etc/mosquitto/certs/server.crt \
-keyout /etc/mosquitto/certs/server.key \
-subj "/CN=mqtt-broker"

# Add to mosquitto.conf
listener 8883
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
```

Then reconfigure the device with `mqtts://` URL.

### Device Not Responding at 10.10.10.1

**Cause:** Not connected to device's WiFi or device not in pairing mode.

**Solutions:**
1. Verify you're connected to the `Meross_XXXXXX` network
2. Ensure the device LED shows alternating amber/green
3. Try factory reset: hold button for 10+ seconds

### Cannot Find Device After Setup

**Cause:** Device connected to wrong network or DHCP issue.

**Solutions:**
1. Double-check SSID spelling in setup command
2. Check router DHCP leases
3. Try setup again, ensuring correct WiFi credentials

---

## Home Assistant Integration

Once your device is connected to your MQTT broker, you can integrate it with Home Assistant using the [Meross LAN integration](https://github.com/krahabb/meross_lan) or by manually configuring MQTT entities.

### Device Information Needed

From the `meross info` output, note:
- **UUID** - Used in MQTT topics
- **MQTT topics:**
- Subscribe to: `/appliance//publish`
- Publish to: `/appliance//subscribe`

### MQTT Topic Structure

The device:
- **Publishes** state changes to: `/appliance//publish`
- **Listens** for commands on: `/appliance//subscribe`

---

## Quick Reference

### Commands

| Command | Description |
|---------|-------------|
| `meross info -a ` | Get device information |
| `meross info -a --with-wifi` | Include nearby WiFi networks |
| `meross info -a --with-ability` | Include device capabilities |
| `meross setup -a [options]` | Configure device |