[JS] Homebridge Smartthings 연동 플러그인 제작, 악세서리 매핑 - 2

[IoT 🏠/Homebridge] - [JS] Homebridge Smartthings 연동 플러그인 제작, OAuth 인증 - 1

[IoT 🏠/Homebridge] - [JS] Homebridge Smartthings 연동 플러그인 제작, 악세서리 매핑 - 2

 

저번 게시글에서, 프록시 서버와 OAuth 방식을 이용하여

영구적으로 토큰을 자동으로 발급/갱신하여 권한을 유지하는 로직을 구현했다.

 

이번에는 실제 발급된 토큰을 가지고 Smartthings API를 이용해,

디바이스를 조회하고, 해당 기기들을 Homebridge 악세서리에 매핑하여

실제로 Smartthings의 Device들을 연동해보도록 하자.

 

 

Smartthings API

 

역시 이번에도, API 문서를 확인해서

Device를 조회하는 명령과, 동작시키는 명령어를 찾아 보았다.

https://developer.smartthings.com/docs/api/public

API | Developer Documentation | SmartThings

 

먼저 Postman을 사용해, 헤더에 토큰을 넣어 디바이스 조회 요청을 넣어보았다.

https://api.smartthings.com/v1/devices

 

 

요청 결과 200, 정상적으로 디바이스 목록이 나왔다.

 

필자는 직접 TV와 Set-Top, 에어컨을 직접 Smartthings에 연결이 아닌

갤럭시 홈 미니의 IR 명령으로 사용중이기 때문에,

capabilites에 "stateless-" 로 시작하는 명령이 많이 나왔다.

 

API 문서에서 확인 결과, deprecated 된 명령들이어서

직접 github문서를 찾아, 해당 capablities id가 사용되는 command들을 하나하나 찾아야 했다.

https://github.com/hongtat/smartthings-capabilities/tree/master

GitHub - hongtat/smartthings-capabilities: SmartThings Capabilities

 

필요한 정보는 얼추 찾았으니 이제 플러그인을 만들어보자

 

 

플러그인 제작 (디바이스 제어)

 

저번에 만들던 플러그인에서 이제 디바이스 조회와,

각각의 디바이스들을 애플 홈 환경에 맞게 악세서리를 매핑해줄 것이다.

 

index.js 파일에 디바이스를 찾는 메서드를 추가하고,

postman에서 요청시 리턴받은 json 값에 맞게 원하는 디바이스만 매핑하도록 추출했다.

이때, Homekit 규격에 맞게 TV와 SetTop 악세서리는 브릿지 형태가 아닌 외부기기로 동작하게 구현했다.

async discoverDevices() {
    const url = 'https://api.smartthings.com/v1/devices';
    try {
        const response = await axios.get(url, {
            headers: { 'Authorization': `Bearer ${this.accessToken}` }
        });
        const devices = response.data.items;

        for (const device of devices) {
            const caps = device.components?.[0]?.capabilities?.map(c => c.id) || [];
            const cats = device.components?.[0]?.categories?.map(c => c.name) || [];
            let AccessoryClass = null;

            if (cats.includes('Television')) AccessoryClass = TVAccessory;
            else if (cats.includes('SetTop')) AccessoryClass = SetTopAccessory;
            else if (caps.includes('airConditionerMode')) AccessoryClass = AirConAccessory;
            else if (caps.includes('switch') && caps.includes('powerMeter')) AccessoryClass = PlugAccessory;

            if (!AccessoryClass) continue; // 사용 안할 기기 Skip

            const isExternal = ['TVAccessory', 'SetTopAccessory'].includes(AccessoryClass.name);

            if (isExternal) {
                new AccessoryClass(this, device);
            } else {
                const uuid = this.api.hap.uuid.generate(device.deviceId);
                let existingAccessory = this.accessories.find(acc => acc.UUID === uuid);

                if (existingAccessory) {
                    new AccessoryClass(this, existingAccessory, device);
                } else {
                    const accessory = new this.api.platformAccessory(device.label, uuid);
                    new AccessoryClass(this, accessory, device);
                    this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
                    this.accessories.push(accessory);
                }
            }
        }
    } catch (err) {
        this.log.error('기기 목록 로드 실패:', err.message);
    }
}

 

 

이제 BaseAccessory 클래스를 만들어

각각의 악세서리 제어 요청을 하나로 처리하게 만들어보자

 

구조체 안에, 각 기기에서 제어시 사용할 api 요청 로직을 만들고

this.client = axios.create({
    baseURL: `https://api.smartthings.com/v1/devices/${this.deviceId}`,
    headers: { 'Authorization': `Bearer ${this.platform.accessToken}` }
});

 

 

저번 게시글에서 만료된 토큰이 있을시, 토큰을 재발급 해주는 메서드를 만들었는데

401 에러 발생시(토큰만료), 해당 메서드를 동작시킬 인터셉터도 구조체에 구현하였다.

this.client.interceptors.response.use((response) => response,
    async (err) => {
        const originalRequest = error.config;

        if (error.response && error.response.status === 401 && !originalRequest._retry) {
            originalRequest._retry = true;
            try {
                const newToken = await this.platform.refreshAccessToken();
                originalRequest.headers['Authorization'] = `Bearer ${newToken}`;
                this.client.defaults.headers['Authorization'] = `Bearer ${newToken}`;

                return this.client(originalRequest);
            } catch (err) {
                this.log.error('토큰 갱신 실패. 수동 인증이 필요할 수 있습니다.');
            }
        }
        return Promise.reject(err);
    }
);

 

 

마지막으로 각각의 악세서리에서 명령을 보내는 동작도 구현

async executeCommand(capability, command, args = []) {
    try {
        await this.client.post('/commands', {
            commands: [{ component: 'main', capability, command, arguments: args }]
        });
    } catch (err) {
        this.log.error(`[${this.name}] 명령 실패: ${err.message}`);
    }
}

 

 

 

플러그인 제작 (악세서리 매핑)

 

이제 제어 동작을 완료했으니,

필요한 악세서리를 Homebridge에 맞게 매핑해보자

사용할 기기는 TV, Set-Top, 에어컨, 플러그 4개이므로 각각 클래스를 만들어 주었다.

 

먼저 TV 악세서리, 이전부터 TV 악세서리는 항상 만들때마다 오류가 났는데,

API 문서를 여러번 정독해본 결과, 얘는 무조건 개별 악세서리로 등록해야 된다는 것이었다.

까다롭게도 매핑도 틀림 없이 올바르게 해줘야 하므로, 차근차근 해보려고 한다.

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

Homebridge Plugin Developer Documentation

 

부모 클래스인 BaseAccessory 클래스를 상속받고,

악세서리 타입은 Television, 그리고 구조체에 동작들을 각각 매핑했다.

 

아까 Smartthings API에서 확인한 정보에 맞게

stateless 전원에는 "setButton", command에는 'powerToggle'이 들어가야 했다.

 

그리고 홈킷의 리모컨 악세서리를 사용하려면 악세서리가 켜짐상태이여야 하지만,

IR 명령은 상태가 없는 방식이므로 버튼이 눌려도 항시 켜짐상태를 유지하였다.

this.accessory = new this.platform.api.platformAccessory(this.name, uuid);
this.accessory.category = Categories.TELEVISION;

this.tvService.getCharacteristic(Characteristic.Active)
    .onGet(() => Characteristic.Active.ACTIVE)
    .onSet(async (value) => {
        await this.executeCommand('statelessPowerToggleButton', 'setButton', ['powerToggle']);

        if (value === Characteristic.Active.INACTIVE) {
            setTimeout(() => {
                this.tvService.updateCharacteristic(Characteristic.Active, Characteristic.Active.ACTIVE);
            }, 1000);
        }
    });

 

 

그리고 홈킷의 리모컨 악세서리의 십자 모형에 각각 채널 변경과, 볼륨 조절을 매핑했다.

this.tvService.getCharacteristic(Characteristic.RemoteKey)
    .onSet(async (value) => {
        const cmdMap = {
            [Characteristic.RemoteKey.ARROW_UP]: ['statelessAudioVolumeButton', 'volumeUp'],
            [Characteristic.RemoteKey.ARROW_DOWN]: ['statelessAudioVolumeButton', 'volumeDown'],
            [Characteristic.RemoteKey.ARROW_LEFT]: ['statelessChannelButton', 'channelDown'],
            [Characteristic.RemoteKey.ARROW_RIGHT]: ['statelessChannelButton', 'channelUp'],
        };

        if (cmdMap[value]) {
            await this.executeCommand(cmdMap[value][0], 'setButton', [cmdMap[value][1]]);
        }
    });

 

 

그리고 TV 악세서리에는 스피커 악세서리를 하위에 붙일 수 있으므로

역시 규격에 맞게 음소거 버튼도 만들어 주었다.

this.speakerService = this.accessory.getService(Service.TelevisionSpeaker);

this.speakerService.getCharacteristic(Characteristic.Mute)
    .onGet(() => false)
    .onSet(async () => {
        await this.executeCommand('statelessAudioMuteButton', 'setButton', ['muteToggle']);
    });

 

 

다음으로는 SetTopAccessory

셋톱박스는 사실 TV와 기능이 아예 같으므로, 설명은 생략하겠다.

이때 카테고리를 TV_SET_TOP_BOX로 지정해두면, TV와는 조금 다른 아이콘으로 매핑된다.

this.accessory.category = Categories.TV_SET_TOP_BOX;

 

 

이제 에어컨을 매핑해보자

기존에 쓰던 플러그인은 Fan 악세서리 형태로 켜고 끄고만 가능했지만,

HeaterCooler를 이용해서 온도를 직관적으로 확인하고, 모드조절도 할 수 있게 만들어 볼것이다.

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

Homebridge Plugin Developer Documentation

 

역시 악세서리는 HeaterCooler로 매핑 후,

Smartthings 명령 틀에 맞게 on/off 를 구현

this.service = this.accessory.getService(Service.HeaterCooler)

this.service.getCharacteristic(Characteristic.Active)
    .onGet(() => this.state.active)
    .onSet(async (value) => {
        this.state.active = value;
        const command = (value === Characteristic.Active.ACTIVE) ? 'on' : 'off';
        await this.executeCommand('switch', command);
     });

 

 

그리고, 사용중인 에어컨엔 난방 모드가 없으므로,

여름에 자주 사용하는 제습 운전 동작을 매핑하여 냉방/제습/자동을 구현하였다.

this.service.getCharacteristic(Characteristic.TargetHeaterCoolerState)
    .setProps({
        validValues: [
            Characteristic.TargetHeaterCoolerState.AUTO,
            Characteristic.TargetHeaterCoolerState.HEAT,
            Characteristic.TargetHeaterCoolerState.COOL
        ]
    })
    .onGet(() => this.state.mode)
    .onSet(async (value) => {
        this.state.mode = value;
        let mode = 'cool';
        if (value === Characteristic.TargetHeaterCoolerState.HEAT) mode = 'dry';
        else if (value === Characteristic.TargetHeaterCoolerState.AUTO) mode = 'auto';
        
        await this.executeCommand('airConditionerMode', 'setAirConditionerMode', [mode]);
    });

 

 

마지막으로, 약/중/강 바람세기 조절 동작을

악세서리 하위에 Fan 형태로 매핑하여 사용할 수 있게 하였다.

( 약: 15, 중: 50, 강: 85 )

this.service.getCharacteristic(Characteristic.RotationSpeed)
    .setProps({ minStep: 35, minValue: 15, maxValue: 85 })
    .onGet(() => this.state.fanSpeed)
    .onSet(async (value) => {
        this.state.fanSpeed = value;
        let fanMode = 'low';
        if (value > 75) fanMode = 'high';
        else if (value > 40) fanMode = 'medium';

        await this.executeCommand('airConditionerFanMode', 'setFanMode', [fanMode]);
    });

 

 

이제 마지막 악세서리인 헤이홈 스마트 플러그

생일때 선물 받았던건데, Smartthings에만 붙어서

이번에야말로 연동해서 제대로 써보려고 한다.

 

악세서리 매핑은 Outlet

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

Homebridge Plugin Developer Documentation

 

Outlet 악세서리는 복잡한 작업은 없었고,

얘는 가진것중 유일하게, 현재 상태를 조회할 수 있으므로

기본동작과, 악세서리 타일과 동기화 하여 실시간 상태를 반영하게 구현했다.

this.service = this.accessory.getService(Service.Outlet);

this.service.getCharacteristic(Characteristic.On)
    .onGet(async () => {
        try {
            const response = await this.client.get('/status');
            const state = response.data.components.main.switch.switch.value;
            return state === 'on';
        } catch (e) return false;
    })
    .onSet(async (value) => {
        const command = value ? 'on' : 'off';
        await this.executeCommand('switch', command);
        this.service.updateCharacteristic(Characteristic.On, value);
    });

this.service.getCharacteristic(Characteristic.OutletInUse)
    .onGet(async () => {
        try {
            const response = await this.client.get('/status');
            return response.data.components.main.switch.switch.value === 'on';
        } catch (e) return false;
    });

 

 

코드 작업 완료.

꽤 코드가 길어져, 게시글에는 코드를 많이 생략했는데,

이 외에 생략된 메서드들은 아래 github 코드를 보면 되겠다.

https://github.com/101Sean/homebridge-smartthings-device

GitHub - 101Sean/homebridge-smartthings-device: Smartthings Device 연동 (Home mini IR 대응)

 

 

테스트

 

저번 게시글에서 정상적으로 토큰이 발급되는 걸 확인했으니,

이젠 디바이스가 정상적으로 불러와지는지 봐야한다.

 

플러그인 적용 후, 정상적으로 디바이스들이 요청되는 것을 볼 수 있다.

 

이제 직접 홈 앱에 브릿지와, 외부 악세서리를 등록 하고,

보통, TV와 Set-Top을 동시에 키는 동작을 자주 쓰므로

해당 Scene을 만들어줘서 원터치 버튼으로 쓰게 만들었다.

 

주로 쓰는 기기는 Set-Top이므로, Set-Top을 테스트 해보자

매핑한 리모컨에 알맞게 모든 동작이 되는것을 볼 수 있다.

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

 

 

이로써 Smartthings 생태계와 애플 홈의 완전한 통합을 이뤘다.

아직 애플 홈앱에서 제공하는 악세서리 타입이 다양하지 않지만,

차차 새로운 악세서리 타입도 지원해줄거라 믿는다.

 

 

원본 게시글

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

Homebridge Smartthings 연동 플러그인 제작, 악세서리 매핑 - 2