├── .gitignore ├── pics ├── schema.png └── adapter.png ├── .eslintrc.json ├── package.json ├── LICENSE ├── README.md ├── ADAPTER.md └── sniffer.js /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules 3 | -------------------------------------------------------------------------------- /pics/schema.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/reneklootwijk/midea-uartsniffer/HEAD/pics/schema.png -------------------------------------------------------------------------------- /pics/adapter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/reneklootwijk/midea-uartsniffer/HEAD/pics/adapter.png -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "env": { 3 | "commonjs": true, 4 | "es6": true, 5 | "mocha": true, 6 | "node": true 7 | }, 8 | "extends": [ 9 | "standard", 10 | "plugin:mocha/recommended" 11 | ], 12 | "globals": { 13 | "Atomics": "readonly", 14 | "SharedArrayBuffer": "readonly" 15 | }, 16 | "parserOptions": { 17 | "ecmaVersion": 2018 18 | }, 19 | "plugins": [ 20 | "mocha" 21 | ], 22 | "rules": { 23 | } 24 | } -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "midea-uartsniffer", 3 | "version": "0.1.0", 4 | "author": "Rene Klootwijk ", 5 | "description": "Sniffer for the 'Midea' UART protocol ", 6 | "repository": { 7 | "type": "git", 8 | "url": "https://github.com/reneklootwijk/midea-uartsniffer.git" 9 | }, 10 | "dependencies": { 11 | "serialport": "^9.0.1", 12 | "winston": "^3.3.3" 13 | }, 14 | "license": "MIT", 15 | "main": "./index.js", 16 | "devDependencies": { 17 | "eslint": "^6.6.0", 18 | "eslint-config-standard": "^14.1.0", 19 | "eslint-plugin-import": "^2.18.2", 20 | "eslint-plugin-mocha": "^6.2.1", 21 | "eslint-plugin-node": "^10.0.0", 22 | "eslint-plugin-promise": "^4.2.1", 23 | "eslint-plugin-standard": "^4.0.1" 24 | } 25 | } 26 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Rene Klootwijk 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Sniffer for 'Midea'-UART protocol 2 | 3 | This script implements a sniffer for the 'Midea'-UART protocol to support examining and reverse engineering of the protocol. Various vendors of air conditioners, (de-)humidifiers and fans, use a dongle, called the SmartKey, to provide a WiFi interface to control the appliance using a mobile app. 4 | 5 | Examples of vendors using this interface for their appliances: 6 | 7 | * Midea 8 | * Qlima 9 | * Artel 10 | * Carrier 11 | * Pioneer 12 | 13 | This dongle wraps the UART protocol used to communicate with the appliance with a layer for authentication and encryption for communication with a mobile app via the Midea cloud or directly via a local LAN connection. It turns out the dongle is just connected to a serial interface (TTL level) of the appliance. To examine and reverse engineer the protocol we can snif the communication between dongle and appliance by replacing the dongle with a TCP-Serial bridge, based on an ESP8266, and connecting the WiFi SmartKey to a computer using a USB-TTL interface. More information on how to create the TCP-Serial bridge and how to connected everything can be found in [ADAPTER.md](./ADAPTER.md). 14 | 15 | ## Installation of the script 16 | To install the script clone it to your computer: 17 | 18 | ```bash 19 | $ git clone https://github.com/reneklootwijk/midea-uartsniffer.git 20 | ``` 21 | 22 | Install the dependencies: 23 | 24 | ```bash 25 | $ cd midea-uartsniffer 26 | $ npm install 27 | ``` 28 | 29 | Modify the script by adding the address of the TCP-Serial bridge and the serial port to which the WiFi SmartKey is connected: 30 | 31 | ```javascript 32 | const applianceHost = '' 33 | const smartKeyPort = '' 34 | ``` 35 | 36 | When the TCP-Serial bridge has been installed and the WiFi SmartKey has been connected to your computer, run the script: 37 | 38 | ```bash 39 | $ node sniffer.js 40 | ``` 41 | 42 | ## Output 43 | When everything is connected correctly and the TCP-Serial bridge has been configured correctly, the output of the script will look as follows: 44 | 45 | ```bash 46 | 2020-09-27T10:14:21.435Z: SK: aa1eacb200000000030d0101044a05a8c0ff000001010000000000000000b6 47 | 2020-09-27T10:14:21.609Z: SK: aa20ac00000000000003418100ff03ff000200000000000000000000000003cd9c 48 | 2020-09-27T10:14:21.967Z: AP: aa1eac0000000000030d0101044a05a8c0ff00000101000000000000000068 49 | 2020-09-27T10:14:22.617Z: SK: aa0fac00000000000203b1011500a6d3 50 | 2020-09-27T10:15:29.702Z: SK: aa1eacb200000000030d0101044a05a8c0ff000001010000000000000000b6 51 | 2020-09-27T10:15:30.239Z: AP: aa1eac0000000000030d0101044a05a8c0ff00000101000000000000000068 52 | ``` 53 | 54 | Where: 55 | 56 | * SK prefixes the messages send by the WiFi SmartKey 57 | * AP prefixes the messages send by the appliance 58 | -------------------------------------------------------------------------------- /ADAPTER.md: -------------------------------------------------------------------------------- 1 | # Creating 2 | 3 | Prerequisites: 4 | 5 | * ESP-01 + Level Shifter adapter () 6 | * USB-TTL adapter 5V (( 7 | * USB Type-A Female cable (4 wires) ()) 8 | * 4 Female Dupont connectors (or solder the wires of the cable to the USB-TTL adapter) 9 | * esp-link firmware () 10 | * Soldering iron or Dupont connectors 11 | 12 | ## Creating the TCP-Serial Bridge 13 | 14 | ### The Hardware 15 | Because the TTL levels of the appliance are 5V and the ESP8266 microcontrollers require 3.3V, level shifters are required for the Rx and Tx lines and a voltage regulator is required to feed the ESP from the 5V provided by the appliance. 16 | 17 | The ESP-01 in combination with the level shifter adapter listed in the prerequisites provides exactly what we need. 18 | 19 | ### The Software 20 | 21 | Jeelabs created the `esp-link` firmware for the ESP8266 family of microcontrollers, which perfectly fits our need. 22 | 23 | To program the ESP-01 you need the USB-TTL adapter, note that it must support 5V levels. You connect the ESP-01 via the level shifter adapter to the USB-TTL adapter which is connected to your computer. How to flash the `esp-link` firmware onto the ESP-01 is described here . Note: You have to connect the GPIO 0 pin of the ESP-01 to ground when powering it to have it boot into flash mode (I solder a switch between the GPIO-0 and GND pins to make this easy). You can also use a programmer board () which has the switch already on-board. 24 | 25 | ## Connecting everything 26 | ![](./pics/schema.png) 27 | 28 | The ESP-01 and adapter board can be powered using the 5V from the appliance. There are two types of connectors used to connect the WiFi SmartKey to the appliance: 29 | 30 | * an USB connector 31 | * a JST-XH connector 32 | 33 | The drawing and table show which pins need to be connected. 34 | 35 | ![](./pics/adapter.png) 36 | 37 | | ESP-01 adapter | USB | JST-XH | 38 | |-|-|-| 39 | | Gnd | 4 | 4 | 40 | | Vcc | 1 | 1 | 41 | | Rx | 2 | 2 | 42 | | Tx | 3 | 3 | 43 | 44 | The WiFi SmartKey must be connected to the USB-TTL adapter and the USB-TTL adapter must be connected to your computer. 45 | 46 | ### Configure the ESP-Link firmware 47 | When the adapter is flashed with the firmware and connected to the appliance it will start an access point that you can connect to configure the WiFi settings. See [WIFI-CONFIG.md](https://github.com/jeelabs/esp-link/blob/master/WIFI-CONFIG.md) for a description how to configure the network settings of the adapter. 48 | 49 | When the network is configured, the connection to the appliance need to be set to 9600bps, 8 databits and no parity. You can do this by selecting the uC Console menu option. Set `Baud` to 9600 and `Fmt` to 8N1. 50 | 51 | To configure the GPIO ports select the esp-01 preset on the home page. 52 | -------------------------------------------------------------------------------- /sniffer.js: -------------------------------------------------------------------------------- 1 | // WiFi SmartKey -> TTL-USB adapter -> PC -> WiFi -> TCP-Serial bridge -> Appliance 2 | // Receive on serial -> Copy on network connection 3 | // Receive on network connection -> Copy on serial 4 | 5 | 'use strict' 6 | 7 | const EventEmitter = require('events').EventEmitter 8 | const logger = require('winston') 9 | const net = require('net') 10 | const SerialPort = require('serialport') 11 | 12 | const applianceHost = '192.168.5.122' 13 | const smartKeyPort = '/dev/cu.usbserial-A600dVFD' 14 | 15 | logger.remove(logger.transports.Console) 16 | logger.add(new logger.transports.Console({ 17 | format: logger.format.combine( 18 | logger.format.timestamp(), 19 | logger.format.colorize(), 20 | logger.format.printf(event => { 21 | return `${event.timestamp}: ${event.message}` 22 | }) 23 | ), 24 | level: 'info' 25 | })) 26 | 27 | class Appliance extends EventEmitter { 28 | constructor (options = {}) { 29 | super() 30 | 31 | if (!options.host) { 32 | throw new Error('Cannot create Appliance connection, no host specified') 33 | } 34 | 35 | this.host = options.host 36 | this.port = options.port || 23 37 | 38 | this._connection = null 39 | this.connected = false 40 | 41 | this._rcvBuf = [] 42 | 43 | this._cmdTimer = null 44 | this._cmdInProgress = false 45 | this._cmdQueue = [] 46 | } 47 | 48 | connect () { 49 | var self = this 50 | 51 | logger.debug('Appliance: Connecting') 52 | 53 | return new Promise((resolve, reject) => { 54 | self._connection = net.createConnection(self.port, self.host) 55 | 56 | self._connection.on('connect', () => { 57 | // Set connection flag 58 | self.connected = true 59 | 60 | logger.debug(`Appliance.connect: Connected to ${applianceHost}`) 61 | 62 | // Emit connected event 63 | self.emit('connected') 64 | 65 | resolve() 66 | }) 67 | 68 | // Process received data 69 | self._connection.on('data', function (data) { 70 | logger.debug(`Appliance.connect: Received data: ${data.toString('hex')}`) 71 | 72 | self.emit('data', data) 73 | }) 74 | 75 | // Handler for connection end 76 | self._connection.on('close', function () { 77 | // Reset connection flag 78 | self.connected = false 79 | 80 | // Emit disconnected event 81 | self.emit('disconnected') 82 | 83 | logger.error('Appliance: Closed') 84 | 85 | // Reconnect logic 86 | setTimeout(function () { 87 | logger.debug('Appliance: Reconnecting') 88 | 89 | self.connect() 90 | }, 1000) 91 | }) 92 | 93 | // Handler for errors 94 | self._connection.on('error', function (err) { 95 | logger.error(`Appliance.connect: ${err.message}`) 96 | }) 97 | }) 98 | } 99 | 100 | write (data) { 101 | var self = this 102 | 103 | return new Promise((resolve, reject) => { 104 | logger.debug(`Appliance.write: Write ${data.toString('hex')}`) 105 | 106 | self._connection.write(data, (err) => { 107 | if (err) { 108 | return reject(err) 109 | } 110 | resolve() 111 | }) 112 | }) 113 | } 114 | } 115 | 116 | class SmartKey extends EventEmitter { 117 | constructor (options = {}) { 118 | super() 119 | 120 | if (!options.port) { 121 | throw new Error('Cannot create connection to SmartKey, no port specified') 122 | } 123 | 124 | this._port = options.port 125 | this._baudrate = 9600 126 | this._parity = 'none' 127 | this._databits = 8 128 | this._serialParser = options.serialParser 129 | 130 | this._connection = null 131 | this.connected = false 132 | 133 | this._rcvBuf = [] 134 | } 135 | 136 | connect () { 137 | var self = this 138 | 139 | logger.debug('SmartKey.connect: Entering') 140 | 141 | if (!self._connection) { 142 | self._connection = new SerialPort(self._port, { 143 | baudRate: self._baudrate, 144 | dataBits: self._databits, 145 | parity: self._parity, 146 | autoOpen: false 147 | }) 148 | } 149 | 150 | // Handler for open event serial port 151 | self._connection.on('open', function () { 152 | logger.debug(`SmartKey.connect: Connected to ${smartKeyPort}`) 153 | 154 | // Set connection flag 155 | self.connected = true 156 | 157 | // Emit connected event 158 | self.emit('connected') 159 | }) 160 | 161 | self._connection.on('data', data => { 162 | // logger.debug(`SmartKey: Received ${data.toString('hex')}`) 163 | 164 | for (let i = 0; i < data.length; i++) { 165 | if (!self._rcvBuf.length) { 166 | if (data[i] === 0xAA) { 167 | self._bytesToRcv = 0 168 | self._rcvBuf.push(data[i]) 169 | } 170 | } else { 171 | if (self._bytesToRcv === 0) { 172 | self._bytesToRcv = data[i] 173 | } 174 | 175 | self._bytesToRcv-- 176 | 177 | // Add byte to buffer 178 | self._rcvBuf.push(data[i]) 179 | 180 | // When all bytes are received, emit the data 181 | if (self._bytesToRcv === 0) { 182 | self.emit('data', Buffer.from(self._rcvBuf)) 183 | self._rcvBuf = [] 184 | } 185 | } 186 | } 187 | }) 188 | 189 | self._connection.on('error', function (err) { 190 | logger.error(`Connection.connect: ${err.message}`) 191 | }) 192 | 193 | // Handler for connection end 194 | self._connection.on('close', function () { 195 | self.connected = false 196 | 197 | // Emit disconnected event 198 | self.emit('disconnected') 199 | 200 | logger.error('Connection: Closed') 201 | 202 | // Reconnect logic 203 | setTimeout(function () { 204 | logger.debug('Connection: Reconnecting') 205 | 206 | self._connection.open() 207 | }, 1000) 208 | }) 209 | 210 | self._connection.open() 211 | } 212 | 213 | write (data) { 214 | var self = this 215 | 216 | return new Promise((resolve, reject) => { 217 | // logger.debug(`SmartKey.write: Write ${data.toString('hex')}`) 218 | 219 | self._connection.write(data, (err) => { 220 | if (err) { 221 | return reject(err) 222 | } 223 | resolve() 224 | }) 225 | }) 226 | } 227 | } 228 | 229 | const appliance = new Appliance({ 230 | host: applianceHost 231 | }) 232 | 233 | const smartKey = new SmartKey({ 234 | port: smartKeyPort 235 | }) 236 | 237 | appliance.on('data', data => { 238 | if (smartKey.connected) { 239 | logger.info(`AP: ${data.toString('hex')}`) 240 | 241 | smartKey.write(data) 242 | .catch(error => { 243 | logger.error(`Failed to write to SmartKey (${error.message})`) 244 | }) 245 | } 246 | }) 247 | 248 | smartKey.on('data', data => { 249 | if (appliance.connected) { 250 | logger.info(`SK: ${data.toString('hex')}`) 251 | 252 | appliance.write(data) 253 | .catch(error => { 254 | logger.error(`Failed to write to Appliance ${error.message})`) 255 | }) 256 | } 257 | }) 258 | 259 | appliance.connect() 260 | smartKey.connect() 261 | --------------------------------------------------------------------------------