우리집제어

개요

앱에서 세대 내 기기를 켜고 끄는 기능임. 제어 대상은 월패드에 연결된 기기임. 에어컨·세탁기·건조기·로봇청소기 같은 가전은 LG ThinQ 연동으로 체험단이 있는 2개 단지에서만 제공함. 세탁기·건조기는 조회와 완료 알림만 되고 제어는 안전상 이유로 제공하지 않음(2026-09-16 기준). 2026-09 기준 그 2개 단지에는 기능을 추가하고, 나머지 단지에서도 쓸 수 있게 하는 작업이 진행 중임. 기기별 범위와 개발 현황은 공개노트/개발/LG 가전기기 제어 추가 개발.

로그에서 확인된 기기 종류(type)는 이러함.

type	이름 예	제어 항목
`light`	거실_조명1, 디밍 전등01	`power` (on/off), `dimming` (1~5)
`thermostat`	보일러01, 거실_난방	`power`, `setTemperature`(설정), `temperature`(현재값)
`ventilator`	환기01, 베란다_환기	`power`, `speed`(“1”약 “2”중 “3”강 “4”바이패스), `filter`, `auto`
`gas`	가스 락01	`lock` (on 열림 / off 잠김)
`prevention`	방범, 방범1	`set` (on/off)
`outing`	외출	`set`
`safety`	안전	-
`noise`	층간소음	-

앱이 제어하는 홈넷 기기는 위 6종(조명·난방·가스·환기·외출·방범)뿐임. 대기전력·커튼·콘센트 제어는 앱에 없음. 기기별 지원 여부는 기기 목록에 그 타입이 있는지와 서버가 내려준 options에 해당 키가 있는지로 갈림. 예를 들어 조명에 dimming 옵션이 없으면 밝기 조절 UI 자체가 안 뜨고, 환기 speed에 "4"가 있어야 바이패스 버튼이 뜸.

가스 제어 키는 서버 기준으로 lock 하나뿐임(2026-09-18 코드 확인). 요청·응답·제어 내역 저장이 전부 lock을 읽고, 서버에 gas + power 조합을 읽는 코드는 없음. 외출(outing)의 속성 키도 set 하나뿐이고 서버가 외출 카드에 가스 상태를 합쳐 주지 않음. 따라서 외출모드 카드의 가스 표시가 실제 밸브 상태와 다른 것은 앱 쪽 문제임.

동작 흐름

앱이 POST /maw/v1/iot/devicesControl을 호출함.
WAS가 먼저 디바이스 동기화를 함. 홈넷사에서 디바이스 목록을 조회하고 DB 목록과 맞춤. 로그에 [디바이스 동기화 시작] → [디바이스 동기화 종료]로 찍힘.
동기화 후 실제 제어 명령을 보냄. MAW 코드 기준으로는 MAW가 홈넷서버 POST /api/um/devices/command를 직접 호출함(응답 타임아웃 3초). 호출용 토큰만 APW에서 매번 받아 씀. 공개노트/기능/홈넷 서버 연동
성공하면 디바이스 제어 성공, 실패하면 기기 제어 실패 - resultCode: FAIL이 찍힘.

입주민 앱의 기기 제어는 APW 홈넷 프록시를 거치지 않음(2026-09-18 확정). MAW 코드 1~3편 전 범위에 APW 홈넷 프록시를 부르는 곳이 한 군데도 없고 홈넷서버를 직접 부름. MAW가 APW에 맡기는 것은 홈넷 토큰·푸시·SMS·이벤트 네 가지뿐임. APW 홈넷 프록시를 쓰는 것은 가전사 앱 쪽(PIW) 임 → 공개노트/개발/모듈/PIW 연계 서버. 그래서 “제어가 오래 걸린다”의 기준은 10분이 아니라 3초임. 3초 안에 홈넷 응답이 없으면 앱에는 바로 실패로 뜸. 방범 OFF·외출 OFF·가스 열기 차단(4102)도 가전사 앱 경로의 규칙이고 입주민 앱은 그 차단을 타지 않음. 공개노트/개발/모듈/APW 연계 서버

동기화와 제어는 별개임. 동기화(조회)는 성공했는데 제어만 실패하는 경우가 흔함. 기기 목록은 잘 보이는데 눌러도 안 되는 증상이 이것임.

서버에는 감사 대비 방어코드가 들어 있음. 조명 여러 개를 한 번에 켤 때는 power 외 속성(밝기 등)을 버리고, 환기에 power=on과 speed=off가 같이 오면 speed=off만 제거함. 잘못된 속성 조합으로 제어가 통째로 실패하는 것을 막는 장치임.

기기 동기화 (기기가 사라지는 이유)

기기 목록 조회와 기기 제어 앞에서 매번 동기화가 돎.

홈넷서버 GET /api/um/devices 호출
응답 코드가 2102(미전입)면 홈넷사에 자동 전입 이벤트를 보냄. “우리집제어를 켰더니 홈넷 쪽에 전입 이벤트가 들어왔다”는 이 동작임
DB에 있는데 응답에 없는 기기는 삭제 표시됨
응답에 있는데 DB에 없는 기기는 새로 등록되고, 삭제 표시였던 기기는 되살아남

“기기가 갑자기 사라졌다”는 3단계임. 홈넷서버가 일시적으로 빈 목록을 주면 세대 기기가 전부 삭제 표시됨. 다음 조회에서 응답이 정상으로 돌아오면 자동으로 되살아나지만, 그 사이 공간(방) 배치와 예약은 끊어짐. 기본매뉴얼/입주민/검색된 IoT 기기가 없다고 떠요

동기화는 트랜잭션으로 묶여 있지 않아 중간에 실패하면 일부만 반영됨. 로그 키워드는 [디바이스 동기화 시작], 홈넷사 디바이스 목록 조회 완료, 디바이스 수:, 삭제된 디바이스 수:, 신규 디바이스 수:임.

제어 내역이 남는 곳

홈넷 기기와 가전이 서로 다른 테이블에 쌓이고, 홈넷 쪽은 앱에서 볼 수 있는 조회 API가 없음.

대상	통합 테이블	조회 방법
홈넷 기기(조명·난방·가스·환기·외출·방범·안전·층간소음)	`smah.tb_mrg_cont_l` + 타입별 상세	DB 직접 조회만 가능
가전(에어컨·세탁기·건조기·로봇청소기)	`smah.tb_smah_hmapp_cont_l` + 타입별 상세	앱 `파트너 가전 제어 이력` 화면

제어에 실패해도 내역은 저장됨. 실패 시 응답코드 자리에 홈넷 결과 코드 또는 FAIL이 들어감
앱이 받은 traceId로 smah.tb_mrg_cont_l을 조회하면 요청·응답 시각과 응답코드를 바로 볼 수 있음. 문의 대응의 1순위 경로임
성공 여부는 응답코드가 2000인지로 판단함. 상세 테이블의 “응답 상태” 컬럼이 비어 있어도 실패가 아님 — 층간소음을 뺀 나머지 타입은 응답 자리에 요청 값을 그대로 넘기는 구조라 대부분 null로 저장됨
여러 기기를 한 번에 제어해도 상세 테이블의 요청값은 첫 기기 것만 채워짐
가전 제어 내역의 “응답값”도 요청값 복사본임(에어컨 현재 온도만 null). 제어 후 실제 상태는 상세 조회를 따로 해야 알 수 있음

앱 상태가 자동으로 안 바뀜 (문의 많음)

앱에는 주기 폴링도 푸시 수신 갱신도 없음. 상태를 다시 읽는 경우는 둘뿐임.

화면에 처음 들어갈 때 1회 조회
제어·저장·삭제가 성공한 직후 1회 재조회

게다가 기기 목록에 30초 캐시가 걸려 있어 화면을 빠르게 들락거리면 옛 상태가 그대로 보임.

“월패드에서 조명을 껐는데 앱에는 켜짐으로 보인다”는 정상 동작임. 화면을 나갔다 30초 뒤 다시 들어가거나 앱에서 한 번 제어하면 맞춰짐. 당겨서 새로고침은 파트너 가전 제어이력 화면에만 있음.

홈넷사별 차이

앱 코드에 코맥스·코콤·현대통신 같은 브랜드 분기가 없음. 서버가 내려주는 homenetServerYn(Y/N) 하나로만 갈림.

homenetServerYn == "Y" 일 때만 대시보드에 외출·방범·조명·난방·가스·환기·방문 카드 7종이 붙음
홈넷사별 프로토콜 차이는 MAW·홈넷서버가 흡수하고, 앱은 서버가 준 옵션만 그림
“이 단지는 밝기 조절이 안 된다” 같은 문의는 앱이 아니라 홈넷사가 내려주는 options 구성 문제임. 공개노트/기능/홈넷 서버 연동

기기별 제어 규칙

제어는 종류와 상관없이 전부 POST /maw/v1/iot/devicesControl 하나로 나감.

기기	앱에서 되는 것	제약
조명	개별 on/off, 전체 on/off 일괄, 밝기 1~5	`dimming` 옵션이 있는 기기만 밝기 노출
난방	개별·전체 on/off, 설정 온도 변경	켜짐일 때만 온도 전송. 상세 조회가 실패하면 토스트 후 화면이 그냥 닫힘
가스	잠그기만 됨	앱에서 가스를 열 수 없음. 여는 것은 월패드에서만 가능. 문구 `안전을 위해 해제할 수 없습니다`
환기	on/off, 풍량(약·중·강·바이패스)	켜짐일 때만 풍량 전송. `filter` 값이 정상이 아니면 `필터 교체가 필요한 장치가 있습니다.`
외출·방범	켤 수만 있음	해제는 월패드에서만. 둘을 동시에 켤 수 없음. 공개노트/기능/방범

자주 나오는 문구

성공 IoT 제어 요청을 완료하였습니다. / 실패 IoT 제어 요청중 오류가 발생하였습니다.
기기 0개 검색된 기기가 없습니다.\n\n월패드 상태를 확인하여 주십시오.
미인증 세대 위 화면은 예시이며 입주민 인증 후 모든 기능을 사용하실 수 있습니다.
미지원 단지 위 화면은 예시이며 해당 기능을 지원하지 않는 단지입니다.

예약 (조명·난방·환기)

요일 + 시각(24시간) + 켜짐/꺼짐을 저장함. 요일을 안 고르면 예약할 요일을 선택해주세요. 로 저장이 막힘.
저장할 수 있는 제어 속성은 한 예약당 최대 3개임. 시각을 2400으로 보내면 서버가 0000으로 바꿔 저장함.
등록·수정 때 내 단말기에 붙은 살아 있는 기기인지 먼저 확인함. 동기화에서 기기가 삭제 처리되면(위 “기기 동기화”) 예약 행은 남아 있어도 수정이 막힘.
삭제한 예약은 이력 테이블로 옮긴 뒤 지움.
화면에 한달이상 HOMEZ 앱에 접속하지 않으면, 등록된 스케줄은 삭제될 수 있습니다. 가 항상 표시됨. 예약이 사라졌다는 문의의 근거임.
홈넷 기기 예약과 파트너 가전 예약은 저장 방식이 완전히 다름. 파트너 가전 쪽은 공개노트/개발/에어컨 꺼짐 예약.

예약 실행은 SCW가 함

저장된 예약을 시간 맞춰 실행하는 것은 앱·MAW가 아니라 SCW 스케줄러(SCW_SCHEDULER_CONTROL_USER_IOT_DEVICE)임. 공개노트/개발/모듈/SCW 스케줄러 서버

지금 ~ 지금 + pod_hr분 사이 예약을 가져옴
예약할 때 저장해 둔 사용자 토큰이 만료되지 않았는지 먼저 검증함
홈넷서버 POST /api/um/devices/command로 제어함
실행된 예약은 예약 테이블에서 지우고 이력으로 옮김. 실패는 실패 테이블(smah.tb_cont_schdl_fil_l)에 남김

“예약 제어가 안 됐다”의 가장 흔한 원인은 토큰 만료임. 위 안내 문구대로 입주민이 오래 앱에 로그인하지 않으면 예약이 실행되지 않음. smah.tb_cont_schdl_fil_l을 확인할 것. 재로그인 후 예약을 다시 등록하도록 안내함.

공간(방) 관리

우리집제어 > 공간 관리에서 방을 만들고 기기를 담음. 공간을 고르면 그 공간의 기기만 대시보드에 남음.

목록 맨 앞의 “전체 기기”는 서버 데이터가 아니라 앱이 끼워 넣는 가상 항목임. 그래서 “기기 추가/편집” 메뉴가 안 보임(정상).
안전·층간소음 타입은 공간 목록에서 제외되고, 같은 타입은 대표 1개만 표시됨.
서버에는 공간에 기기를 넣고 빼는 API가 없음. 공간-기기 매핑 테이블을 읽어서 목록에 붙이기만 함. “공간은 만들어지는데 기기를 담을 수 없다”는 문의가 여기서 나옴. 공개노트/개발/모듈/MAW 앱 API 서버 “확인 필요”
공간 추가 응답에 새로 만들어진 공간 번호가 들어가지 않음. 수정·삭제는 공간 번호만으로 동작하고 소유자 검증이 없음.

방문 확인

우리집제어 안에 있지만 IoT API가 아니라 아파트 관리 API(household/findVisitsList) 를 씀. 당일 방문 건수를 보여줌. 문구는 금일 총 방문 건 수는 {n}건 입니다.

파트너 가전 (LG 씽큐 / 삼성 스마트싱스)

앱이 아는 파트너는 LG 씽큐와 삼성 스마트싱스 둘임. 나머지는 서버가 준 이름·로고로 일반 표시함.

연동 순서

파트너 목록에서 미연동 파트너를 누름
앱 내 웹뷰로 파트너 로그인(OAuth) 진행
성공하면 파트너사와 연결 중입니다. 후 기기 추가 화면. 실패하면 연동 인증에 실패하였습니다. 다시 시도해주세요.
인증이 만료되면(SQI2010) 인증이 만료되었습니다.다시 인증해주세요. 를 띄우고 같은 웹뷰를 다시 염

“연동됨”으로 보이는 판정 기준이 파트너마다 다름.

파트너	연동됨으로 보는 조건
LG	Redis에 리프레시 토큰이 있음. 개발 프로필은 시뮬레이터 모드라 항상 연동됨으로 보임(운영은 꺼져 있음)
삼성	삼성 커넥터가 심어 준 Redis 키가 있음. 서버가 이 키를 쓰지 않고 읽기만 함. 키가 사라지면 연동 해제 상태로 보임

파트너 계정에는 있는데 목록에 안 뜨는 기기는 지원하지 않는 기기 타입임. 지원 타입은 에어컨·세탁기·건조기·로봇청소기 4종뿐이고, 로그에 Unknown LG device type: 또는 지원하지 않는 Samsung 디바이스 타입입니다:로 원인 타입 문자열이 그대로 찍힘.

기기 등록·삭제 때 세탁기·건조기만 LG 푸시 구독·해제를 호출함. “세탁 완료 알림이 안 온다”는 등록 시 구독 로그(LG 푸시 구독 요청 성공/실패)부터 봄. 같은 기기를 여러 사람이 각각 등록할 수 있고, 삭제는 소프트 삭제라 같은 기기를 다시 등록하면 되살아남.

삼성 연동 해제

내 삼성 기기를 전부 삭제 표시함
삼성 커넥터로 스마트앱 삭제 알림을 보냄
알림이 성공하면 10초 기다린 뒤 스마트앱 제거를 호출함(삼성 가이드 요구사항)

1단계는 알림·제거 실패와 무관하게 이미 반영됨. 알림이 실패하면 우리 쪽에서는 기기가 사라졌는데 SmartThings에는 스마트앱이 남는 불일치가 생김. 이때는 SmartThings 앱에서 직접 삭제하도록 안내함
10초 대기가 요청 스레드를 붙잡아 앱에서는 10초 이상 로딩으로 보임. 정상 동작임
삼성은 선택 옵션(프로파일) 전용 API가 없어 상태 조회를 한 번도 하지 않은 기기는 옵션이 비어 있음. 상세 화면을 먼저 열어야 옵션이 채워짐

기기 상태 표시

상태 코드는 파트너사마다 체계가 다름. 앱이 파트너별 표를 두고 한글로 바꿔 보여주고, 모르는 코드는 LG 표로 폴백함.
예: 세탁기 running 세탁 중 / rinsing 헹굼 중 / spinning 탈수 중 / end 세탁완료, 로봇청소기 homing 충전대로 이동 중 / working 청소중.
모르는 코드가 오면 화면에 그대로 뜨거나 비어 보일 수 있음. 가전사가 새 상태를 추가하면 앱 수정이 필요함.

제어 이력

우리집제어 > 파트너 가전 제어 이력에서 봄. 대상은 에어컨·세탁기·건조기·로봇청소기임. 커서 방식 무한스크롤이고 한 번에 15건씩 내려감.
결과 코드가 6200 또는 SQI0000이면 “성공” 배지, 그 외는 “실패”임.
조회 필터가 기기 ID가 아니라 기기 이름임(2026-09-18 서버 코드 확인). 이름 목록으로 걸러 내고, 응답에 기기 ID가 같이 내려가더라도 조회 키는 어디까지나 이름임.
- 기기 이름을 바꾸면 예전 이름으로 남은 과거 이력은 조회되지 않음. 이력이 비어 보인다는 문의의 원인임
- 같은 이름의 기기가 둘이면 두 기기 이력이 섞여 나옴
제어 1건은 항목별로 펼쳐져 보임. 에어컨을 한 번 제어해도 전원·운전모드·설정온도가 각각 한 줄이 됨.
상세 테이블에 행이 없는 제어건은 목록에서 통째로 빠짐. 제어 내역이 DB에는 있는데 앱에 안 보이는 경우가 여기임.
한 기기를 두 사람이 등록한 세대에서 이력이 중복되던 문제는 조회 조건 보강으로 해결됨(2026-09-16).

LG ThinQ 토큰 갱신 (서버 쪽)

LG 가전 제어용 API 토큰은 SCW 스케줄러(SCW_SCHEDULER_REFRESH_LG_TOKEN)가 주기적으로 재발급받음. 공개노트/개발/모듈/SCW 스케줄러 서버

파트너(LG) 기본 정보로 전역 토큰을 갱신함(cmn.tb_ptnr_m)
운영에서는 이어서 cmn.tb_ptnr_sbd_d의 단지별 키를 순회하며 각각 토큰을 발급함. 단지에 시크릿이 없으면 전역 시크릿을 씀
단지별 실패는 건별로 넘기고 계속 진행함(전체 롤백 없음)

“특정 단지만 LG 가전 제어가 안 된다” → 그 단지의 키가 잘못된 것임. 로그 키워드 단지별 토큰 갱신 실패 - sbdId:
“전체가 안 된다” → 전역 토큰 발급 실패임. 로그 키워드 LG 전역 토큰 갱신
단지별 키 사용은 운영 프로필만 켜져 있음. 개발에서는 전역 토큰만 씀
로그에 찍히는 키·토큰은 앞 4자리만 남음

기기별 지원 범위와 개발 현황은 공개노트/개발/LG 가전기기 제어 추가 개발.

알려진 문제

증상	원인	조치	관련
`resultCode: FAIL` + `ReadTimeoutException`	단지 로컬망 통신 불안정으로 게이트웨이 응답 지연	홈넷사에 로그 전달	기본매뉴얼/입주민/IoT 제어가 안 돼요
`resultCode: FAIL` + `error: null` + 서버에서 `NullPointerException`	홈넷사 쪽 밸리데이션 오류 (2026-06-01 확인)	홈넷사가 수정. 조회는 원래 되던 상태라 우리가 재현 테스트할 수 없어 사용자 제어를 기다려야 함	기본매뉴얼/입주민/IoT 제어가 안 돼요
`실패(2102)`	미전입 세대 제어 요청	전입 승인 상태 확인	기본매뉴얼/관리사무소/입주민 승인 처리는 어떻게 하나요
`실패(4803)`	SCW 구간 오류. 2026-06 고양장항에서 SCW 동작이 전부 실패	홈넷사에 별건으로 제기	기본매뉴얼/운영/WAS 로그 확인
앱에서만 안 되고 월패드는 정상, 서버 기록은 전부 성공	짧은 시간 연속 클릭 → 앱 단에서 네트워크 오류로 차단, 요청이 WAS까지 오지 않음	한 번만 누르고 기다리도록 안내. 앱 개발 담당에 전달	기본매뉴얼/입주민/월패드에서는 되는데 앱에서 난방 제어가 안 돼요
`요청/응답 설정 온도가 Double 형식이 아님`	난방 온도 값 형식 경고. 제어 성공 건에도 찍히므로 실패 원인이 아님	무시. 앱 수정 완료(2026-09-17 확인)	기본매뉴얼/입주민/월패드에서는 되는데 앱에서 난방 제어가 안 돼요
월패드에서도 제어 안 됨	월패드 자체 고장	관리사무소에 월패드 A/S 신청	기본매뉴얼/입주민/IoT 제어가 안 돼요
월패드에서 바꾼 상태가 앱에 안 보임	앱에 폴링이 없고 기기 목록 30초 캐시가 있음	정상 동작. 화면을 나갔다 다시 들어오게 안내	위 “앱 상태가 자동으로 안 바뀜”
난방 상세를 누르면 화면이 닫힘	기기 상태 조회(`devicesInfo`) 실패	로그에서 해당 구간 확인 후 홈넷사 전달	기본매뉴얼/입주민/월패드에서는 되는데 앱에서 난방 제어가 안 돼요
파트너 가전 제어이력이 비어 있음	기기 이름으로 조회하는데 이름을 바꿈	이름 변경 여부 확인	위 “제어 이력”
기기가 갑자기 전부 사라짐	홈넷서버가 빈 목록을 돌려줘 동기화가 전부 삭제 처리함	다시 조회하면 되살아남. 공간 배치·예약은 다시 잡아야 함	위 “기기 동기화”
가전은 뜨는데 회색(오프라인)으로 보임	목록 조회 중 그 기기만 파트너 상태 조회에 실패함	로그에서 `디바이스 상태/프로파일 조회 실패`와 해당 기기 ID를 봄	기본매뉴얼/입주민/에어컨 등 가전 제어가 안 돼요
우리집제어 전체가 로딩만 돎	홈넷 토큰 조회(APW)가 3초 안에 응답하지 못함	APW 쪽을 먼저 봄. MAW 로그에는 원인이 안 남음	공개노트/기능/홈넷 서버 연동
로봇청소기 배터리가 항상 80%	서버 기본값 하드코딩	실제 값 아님을 안내	공개노트/개발/모듈/MAW 앱 API 서버
제휴사 로고가 깨져 보임	로고 URL이 코드 상수로 하드코딩됨	표시 문제일 뿐 연동과 무관함을 안내	공개노트/개발/모듈/MAW 앱 API 서버
기기 상태에 `UNKNOWN`이 보임	가전사가 변환표에 없는 새 상태값을 줌	서버 변환표 수정 필요. 개발 담당에 전달	공개노트/개발/LG 가전기기 제어 추가 개발

실패 현황

2026-06 조사(30일 기준) 시 실패율 100%인 세대가 존재한 단지: 부천원종휴튼3단지, 고양장항, 청주지북A5, 목포상락, 파주운정3 물향기7단지, 인천검단37단지, 세종조치원역, 김제지평선, 시흥정왕, 인천검단38단지.

2026-06-01~~09 고양장항 단지에서만 오류 210건(1~~4일 171건, 5~9일 39건). 세대별 실패율은 31/61, 17/29, 15/29, 2/2 등으로 편차가 큼. 대부분 로컬망 타임아웃으로 판단함.

2026-09-01 기준: 시흥정왕 10,680건 중 2,085건 실패. 과천S11은 거의 전건 실패(간간이 4803). 평택고덕도 거의 전건 실패였고 8/26 오후부터는 2102로 바뀜.

2026-09-01 건은 해결 완료(2026-09-17 확인).

책임 구간 판단 기준: 앱에서 제어했을 때 우리 서버(MAW)가 홈넷 서버로 정상 호출했다면 우리 문제가 아님. 세부 원인은 추적하지 않고 홈넷사에 로그를 전달하면 됨.

tags	iot, 우리집제어, 홈넷
aliases	기기 제어, IoT 제어, 디바이스 제어, 홈 제어, devicesControl, 기기 동기화, 조명 제어, 난방 제어, 가스 잠금, 환기 제어, 공간 관리, 파트너 가전, 씽큐 연동, 스마트싱스, 기기 예약, 월패드와 앱 상태 다름, 제어 내역, 기기가 사라짐, 삼성 연동 해제

스마트홈 위키

탐색기