[JS] Homebridge 전기매트 플러그인 제작, 플러그인 구현 - 2

[IoT 🏠/Homebridge] - Homebridge 전기매트 플러그인 제작, 블루투스 패킷 분석 - 1

[IoT 🏠/Homebridge] - [JS] Homebridge 전기매트 플러그인 제작, 플러그인 구현 - 2

 

저번 게시글에서, 전기매트의 블루투스 통신 패킷을 분석해 보았다.

이젠 그 패킷들을 토대로 Homebridge 플러그인에 적용시켜 보도록 하겠다.

 

플러그인 제작은 이미 한 번 해봤으므로

Homebridge API 설명은 생략하도록 하겠다.

 

 

플러그인 개발 (악세서리 구현)

 

먼저 node.js 프로젝트 생성 후,

linux 환경에서 돌아갈 node-ble 라이브러리를 설치해 주었다.

npm install node-ble

 

 

기본적인 홈브릿지 악세서리 부분을 구현해보자

온도조절 파트는 Thermostat 악세서리 타일을,

타이머는 마땅한 악세서리가 없기에 Lightburb 악세서리에 넣을 것이다.

https://developers.homebridge.io/#/service/Thermostat

Homebridge Plugin Developer Documentation

https://developers.homebridge.io/#/service/Lightbulb

Homebridge Plugin Developer Documentation

 

 

먼저, 온도 조절 서비스 타일 구현 부분이다.

Thermostat 서비스로 온도조절 형식의 타일을 선언하고,

TargetTemperature 로 온도의 15~50도 범위를 5도 단위로 각각 매트의 단계와 매핑했다.

그 외에 On/Off 현재 온도 상태 표시 부분도 구현했다.

initServices() {
    ...
    this.thermostatService = new this.Service.Thermostat(this.name + ' 온도');

    this.thermostatService.getCharacteristic(this.Characteristic.TargetTemperature)
        .setProps({ minValue: MIN_TEMP, maxValue: MAX_TEMP, minStep: 5 })
        .onSet(this.handleSetTargetTemperature.bind(this))
        .onGet(() => this.currentState.targetTemp);

    this.thermostatService.getCharacteristic(this.Characteristic.CurrentTemperature)
        .setProps({ minValue: MIN_TEMP, maxValue: MAX_TEMP, minStep: 1 })
        .onGet(() => this.currentState.currentTemp);

    const targetHeatingCoolingStateCharacteristic = this.thermostatService.getCharacteristic(this.Characteristic.TargetHeatingCoolingState);
    targetHeatingCoolingStateCharacteristic.setProps({
        validValues: [this.Characteristic.TargetHeatingCoolingState.OFF, this.Characteristic.TargetHeatingCoolingState.HEAT]
    });
    targetHeatingCoolingStateCharacteristic
        .onSet(this.handleSetTargetHeatingCoolingState.bind(this))
        .onGet(() => {
            return this.currentState.currentHeatingCoolingState === this.Characteristic.CurrentHeatingCoolingState.OFF
                ? this.Characteristic.TargetHeatingCoolingState.OFF
                : this.Characteristic.TargetHeatingCoolingState.HEAT;
        });

    this.thermostatService.getCharacteristic(this.Characteristic.CurrentHeatingCoolingState)
        .onGet(() => this.currentState.currentHeatingCoolingState);

    this.thermostatService.setCharacteristic(this.Characteristic.TemperatureDisplayUnits, this.Characteristic.TemperatureDisplayUnits.CELSIUS);
    ...
}

 

 

다음으로 온도 설정 로직 부분,

매트의 온도 단계와, 악세서리의 온도부분을 설정해주는 부분과,

통신 안정화를 위한 디바운싱, 중복 명령 방지 기능을 구현했다.

handleSetTargetTemperature(value) {
    let level = TEMP_LEVEL_MAP[Math.round(value / 5) * 5] || 0;
    if (value < MIN_TEMP) level = 0;
    if (value >= MAX_TEMP) level = 7;

    if (level === this.lastSentLevel && this.currentState.targetTemp === value) {
        // 이미 전송된 값 패스
        return;
    }

    if (this.setTempTimeout) {
        clearTimeout(this.setTempTimeout);
    }

    this.setTempTimeout = setTimeout(async () => {
        try {
            await this.sendTemperatureCommand(value, level);
        } catch (e) {
            // 온도 설정 중 ble 통신 오류
        }
    }, 350);
}

 

 

마지막으로 온도 제어 패킷의 BLE 통신 부분이다.

이 메서드에서는 패킷 생성, BLE 통신 전송/오류 처리

Homekit 악세서리와의 상태 동기화 부분을 구현했다.

async sendTemperatureCommand(value, level) {
    this.setTempTimeout = null;
    const packet = this.createControlPacket(level);

    if (this.tempCharacteristic && this.isConnected) {
        try {
            await this.safeWriteValue(this.tempCharacteristic, packet);
            this.lastSentLevel = level;

            this.currentState.targetTemp = value;
            this.currentState.currentTemp = LEVEL_TEMP_MAP[level];
            this.currentState.currentHeatingCoolingState =
                level > 0 ? this.Characteristic.CurrentHeatingCoolingState.HEAT : this.Characteristic.CurrentHeatingCoolingState.OFF;

            if (level > 0) {
                this.currentState.lastHeatTemp = value;
            }

            this.thermostatService.updateCharacteristic(this.Characteristic.CurrentTemperature, this.currentState.currentTemp);
            this.thermostatService.updateCharacteristic(this.Characteristic.CurrentHeatingCoolingState, this.currentState.currentHeatingCoolingState);
            this.thermostatService.updateCharacteristic(this.Characteristic.TargetHeatingCoolingState, this.currentState.currentHeatingCoolingState === this.Characteristic.CurrentHeatingCoolingState.OFF
                ? this.Characteristic.TargetHeatingCoolingState.OFF
                : this.Characteristic.TargetHeatingCoolingState.HEAT);
        } catch (error) {
            // BLE 쓰기 오류
            throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
        }
    } else {
        if (level === 0) {
            return;
        } else {
            // BLE 연결 없음, 명령 전송 불가 
            throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
        }
    }
}

 

 

타이머 부분도 동일하다.

서비스 초기화 메서드에 Lightbulb 서비스 타입으로 선언한 후,

타이머(1~15시간)을 100/15 == 약 6.67%에 한 시간으로 설정했다.

initServices() {
    ...
    this.timerService = new this.Service.Lightbulb(this.name + ' 타이머 설정');

    this.timerService.getCharacteristic(this.Characteristic.On)
        .onSet(this.handleTimerSwitch.bind(this))
        .onGet(() => this.currentState.timerOn);

    this.timerService.getCharacteristic(this.Characteristic.Brightness)
        .setProps({ minValue: 0, maxValue: 100, minStep: BRIGHTNESS_PER_HOUR })
        .onSet(this.handleSetTimerHours.bind(this))
        .onGet(() => this.currentState.timerHours * BRIGHTNESS_PER_HOUR);

    this.timerService.setCharacteristic(this.Characteristic.Brightness, this.currentState.timerHours * BRIGHTNESS_PER_HOUR);
    this.timerService.setCharacteristic(this.Characteristic.On, this.currentState.timerOn);
    ...
}

 

 

마찬가지로 타이머 로직 부분,

위에 말했듯 악세서리의 6.67%를 한 시간으로 계산해주는 로직과,

BLE 전송 및 업데이트 기능을 구현했다.

async handleSetTimerHours(value) {
    let hours = Math.round(value / BRIGHTNESS_PER_HOUR);

    if (value > 0 && hours === 0) {
        hours = 1;
    }

    if (hours > MAX_TIMER_HOURS) {
        hours = MAX_TIMER_HOURS;
    }

    if (hours === 0) {
        // 0시간 > OFF
        this.handleSetTargetTemperature(MIN_TEMP);
    }

    await this.sendTimerCommand(hours);

    this.currentState.timerHours = hours;
    this.currentState.timerOn = hours > 0;

    const brightnessToSet = hours * BRIGHTNESS_PER_HOUR;

    this.timerService.updateCharacteristic(this.Characteristic.On, this.currentState.timerOn);
    this.timerService.updateCharacteristic(this.Characteristic.Brightness, brightnessToSet);
}

 

 

여기도 BLE 통신과, Homekit과 상태 동기화,

타이머 제어 패킷 생성 부분을 구현해 주었다.

async sendTimerCommand(hours) {
    const packet = this.createControlPacket(hours); // 패킷 전송

    if (this.timeCharacteristic && this.isConnected) {
        try {
            await this.safeWriteValue(this.timeCharacteristic, packet);
        } catch (error) {
            // BLE 오류
            throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
        }
    } else {
        if (hours === 0) {
            return;
        } else {
            // BLE 연결 없음, 명령 전송 불가
            throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
        }
    }
}

 

 

 

플러그인 개발 (BLE 연결 구현)

 

이제 실제 매트와 서버가 블루투스로 통신 할 부분을 구현해 주어야 한다.

 

node-ble 라이브러리를 사용해 ble 서비스를 초기화 하고,

장치가 오프라인 일 경우, 재연결 루프를 진행하는 부분을 구현했다.

async initializeBleAdapter() {
    try {
        // ble 초기화
        const { bluetooth } = NodeBle.createBluetooth();
        this.startScanningLoop(); // 스캔 루프 시작
    } catch (error) {
        // 초기화 실패 
    }
}

async startScanningLoop() {
    if (!this.adapter || this.isScanningLoopActive) {
        // 실행 중 혹은 어댑터 없음
        return;
    }
    this.isScanningLoopActive = true; // 연결 루프 시작

    while (this.isScanningLoopActive) {
        if (!this.isConnected) {
            // 스캔 시작
            try {
                await this.adapter.startDiscovery();
                const targetAddress = this.macAddress.toUpperCase();

                await this.adapter.stopDiscovery();
                const deviceAddresses = await this.adapter.devices();

                let targetDevice = null;
                let foundAddress = null;

                for (const address of deviceAddresses) {
                    const normalizedAddress = address.toUpperCase().replace(/:/g, '');

                    if (normalizedAddress === targetAddress) {
                        targetDevice = await this.adapter.getDevice(address);
                        foundAddress = address;
                        break;
                    }
                }

                if (targetDevice) {
                    this.device = targetDevice;  // 장치 발견
                    await this.connectDevice();
                } else {
                    if (deviceAddresses.length > 0) {
                        // 장치 발견 실패
                    } else {
                        // 장치 발견 실패(all)
                    }
                }
            } catch (error) {
                // BLE 스캔 오류
            }
        } else {
            // 연결 유지
        }
        await sleep(this.scanInterval);
    }
}

 

 

connectDevice 메서드에서는, 스캔 루프에서 발견된 장치와 연결을 진행한다.

discoverCharacteristics 메서드는 제어 UUID를 적용하여,

온도 및 타이머의 실제 제어를 담당한다.

마지막으로 연결이 끊어졌을때 초기화 하는 부분도 구현했다.

async connectDevice() {
    if (!this.device || this.isConnected) {
        return;
    }

    try {
        await this.device.connect();  // 연결 시도
        this.isConnected = true;  // 연결 성공

        this.device.on('disconnect', () => {
            this.disconnectDevice(); // 해제됨, 재연결 루프 실행
        });

        // GATT 탐색 전 le-connection-abort-by-local 방지
        await sleep(500);
        await this.discoverCharacteristics();
    } catch (error) {
        this.disconnectDevice(true);
    }
}

async discoverCharacteristics() {
    if (!this.device) return;

    try {
        // 특성 탐색 대상
        const gatt = await this.device.gatt();
        const service = await gatt.getPrimaryService(this.serviceUuid);
        // 발견 성공 
        if (this.charSetUuid) {
            this.setCharacteristic = await service.getCharacteristic(this.charSetUuid);
        }
        this.tempCharacteristic = await service.getCharacteristic(this.charTempUuid);
        this.timeCharacteristic = await service.getCharacteristic(this.charTimeUuid);

        if (this.tempCharacteristic && this.timeCharacteristic) {
            // 제어준비 완료
            if (this.setCharacteristic) {
                // 연결 후 초기화 패킷 전송
                await this.sendInitializationPacket();
            }
            // Keep-Alive 패킷
            this.startKeepAlive();

        } else {
            // 온도 or 타이머 탐색 실패
            this.disconnectDevice(true);
        }
    } catch (error) {
        // 탐색 오류 UUID 확인
        this.disconnectDevice(true);
    }
}

disconnectDevice(resetDevice = false) {
    this.stopKeepAlive();

    const deviceToDisconnect = this.device;

    this.isConnected = false;
    this.tempCharacteristic = null;
    this.timeCharacteristic = null;
    this.setCharacteristic = null;

    if (resetDevice) {
        this.device = null;
    }

    if (deviceToDisconnect) {
        deviceToDisconnect.disconnect().catch(e => {
            if (!e.message.includes('not connected') && !e.message.includes('does not exist')) {
                // 안전 연결 해제 실패
            }
        });
    }
}

 

 

다음으로는 연결 안정화 부분이다.

 

여기서는, 연결 안정성을 위해 keep-alive 메커니즘을 적용했다.

Linux BLE 스택(BlueZ)의 110초 타임아웃을 회피하고,

초기 지연 및, 주기적인 keep-alive 패킷 전송으로 안정성을 확보했다.

async sendInitialKeepAlivePacket() {
    try {
        await this.sendInitializationPacket(true);
        // Keep-Alive 패킷 전송
    } catch (e) {
        // 전송 실패
    }
}

startKeepAlive() {
    this.stopKeepAlive();
    
    this.keepAliveTimer = setTimeout(() => {
        if (!this.isConnected) return;
        this.sendInitialKeepAlivePacket();

        this.keepAliveInterval = setInterval(async () => {
            if (this.isConnected) {
                try {
                    await this.sendInitializationPacket(true);
                    // keep-alive 패킷 재전송
                } catch (e) {
                    // keep-alive 패킷 전송 실패 
                }
            }
        }, KEEP_ALIVE_INTERVAL_MS);
    }, KEEP_ALIVE_INITIAL_DELAY_MS);
}

stopKeepAlive() {
    if (this.keepAliveTimer) {
        clearTimeout(this.keepAliveTimer);
        this.keepAliveTimer = null;
    }
    if (this.keepAliveInterval) {
        clearInterval(this.keepAliveInterval);
        this.keepAliveInterval = null;
    }
}

async sendInitializationPacket(isKeepAlive = false) {
    if (!this.setCharacteristic || !this.isConnected || !this.initPacketHex) {
        return;
    }

    try {
        const initPacket = Buffer.from(this.initPacketHex, 'hex');
        if (!isKeepAlive) {
            // keep-alive 패킷 전송 시도
        }
        await this.setCharacteristic.writeValue(initPacket, { type: 'command' });

        if (!isKeepAlive) {
            // 패킷 전송 성공
            await sleep(500); 
        }
    } catch (error) {
        if (!isKeepAlive) {
            // 패킷 전송 오류
            this.disconnectDevice(true); 
            throw new this.api.hap.HapStatusError(this.api.hap.HAPStatus.SERVICE_COMMUNICATION_FAILURE);
        }
        throw error; 
    }
}

 

 

 

플러그인 개발 (유틸리티)

 

마지막으로 플러그인에 사용할 유틸 부분이다.

 

여기서는 지난 게시글에서 분석한 제어 패킷인,

[date, cheksum, data, checksum] 구조의 패킷을 만드는 메서드와

 

온도 타이머 제어 UUID에 패킷 전송시, 재시도 및 오류 처리를 담당하는 메서드이다.

명령 충돌방지를 위한 지연 처리와, 재시도 횟수를 3회로 두어 안정성을 높였다.

createControlPacket(value) {
    const dataByte = value;
    const checkSum = (0xFF - dataByte) & 0xFF;

    const buffer = Buffer.alloc(4);

    buffer.writeUInt8(dataByte, 0);
    buffer.writeUInt8(checkSum, 1);
    buffer.writeUInt8(dataByte, 2);
    buffer.writeUInt8(checkSum, 3);

    return buffer;
}

async safeWriteValue(characteristic, packet, maxRetries = 3, delayMs = WRITE_DELAY_MS) {
    if (!this.isConnected) {
        throw new Error("Device not connected.");
    }
    const writeOptions = { type: 'command' };
    
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            await characteristic.writeValue(packet, writeOptions); // 쓰기 시도
            await sleep(delayMs);
            return true;
        } catch (error) {
            // 쓰기 오류 발생
        }
    }
}

 

 

이렇게 플러그인 제작이 끝났다.

이제 실제 Homebridge 서버에 등록 후 설정을 진행해보자

 

 

플러그인 등록

 

저번 데스크탑 제어 플러그인 설치 때와 같은 방법을 진행할 것이므로

설명은 생략 하고 바로 설치를 진행해 주었다.

 

설치 후, 플러그인 목록에 정상적으로 뜨는 것을 볼 수 있다.

 

이제 config파일에 저번 게시글의 패킷 분석에서 찾은 UUID값과

매트의 MAC 주소, 그 외 설정들을 작성해 주었다.

 

저장 후, Home 앱에 등록시, 브릿지가 정상으로 뜨는 것을 볼 수 있다.

악세서리 타일은 온도조절 타일로 잘 뜨는 모습

 

이제 정상적으로 작동되는지 테스트를 해 보았다.

온도 조절과 타이머 조절 모두 정상적으로 동작하는 것을 볼 수 있었다.

https://youtube.com/shorts/CuSvevZmTho?feature=share

 

 

이로써 구형 전기매트도 애플 홈 생태계에 등록하게 되었다.

덕분에 블루투스 통신 구조에 대한 이해와 통신 매커니즘도 이해하는 계기가 되었다.

이번 겨울에는 Siri를 이용해 전기 매트도 제어 할 수 있어서 만족스럽다

 

원본 게시글

https://blog.naver.com/101artspace/224061230387

Homebridge 전기매트 플러그인 제작, 플러그인 구현 - 2