> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ones1ght.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 트러블슈팅

> 측위가 정상적으로 동작하지 않을 때 증상별로 원인을 확인하고 해결하는 방법을 안내합니다.

증상에 해당하는 항목을 찾아 확인 순서를 위에서부터 진행합니다.
각 항목은 가장 흔한 원인부터 배치되어 있습니다.

## 빠른 진단

| 증상 | 바로가기 |
| - | - |
| 앱에 도면 자체가 안 나옴 | [앱에 도면이 표시되지 않음](#앱에-도면이-표시되지-않음) |
| 도면은 나오는데 위치 점이 없음 | [앱에 위치 점이 표시되지 않음](#앱에-위치-점이-표시되지-않음) |
| 앱에 '로케이터 신호를 찾을 수 없습니다'가 뜸 | [로케이터 신호를 찾을 수 없다고 표시됨](#로케이터-신호를-찾을-수-없다고-표시됨) |
| 점은 나오는데 엉뚱한 자리에 있음 | [위치가 실제와 다른 곳에 표시됨](#위치가-실제와-다른-곳에-표시됨) |
| 점이 가만히 있어도 계속 움직임 | [위치가 심하게 흔들리거나 튐](#위치가-심하게-흔들리거나-튐) |
| 10 m 이동했는데 화면에서는 5 m | [이동 거리가 실제와 맞지 않음](#이동-거리가-실제와-맞지-않음) |
| 구역에 들어가도 이벤트가 없음 | [구역(존) 이벤트가 발생하지 않음](#구역-존-이벤트가-발생하지-않음) |
| 로케이터 LED가 빨강 | [로케이터 LED가 빨강](#로케이터-led가-빨강) |
| 로케이터 하단 LED가 자주색·하늘색으로 깜빡임 | [로케이터 하단 LED가 자주색과 하늘색으로 깜빡임](#로케이터-하단-led가-자주색과-하늘색으로-깜빡임) |
| Wi-Fi를 다시 설정해도 접속되지 않음 | [Wi-Fi를 다시 설정해도 로케이터가 접속되지 않음](#wi-fi를-다시-설정해도-로케이터가-접속되지-않음) |
| 하드웨어 선택 목록에 로케이터가 없음 | [하드웨어 선택 목록에 로케이터가 없음](#하드웨어-선택-목록에-로케이터가-없음) |
| 장치 적용이 안 됨 / 로케이터가 미접속 | [장치 적용이 안 되거나 로케이터가 미접속으로 보임](#장치-적용이-안-되거나-로케이터가-미접속으로-보임) |
| 로케이터를 옮기거나 교체했는데 측위가 그대로임 | [로케이터를 옮기거나 교체했는데 측위에 반영되지 않음](#로케이터를-옮기거나-교체했는데-측위에-반영되지-않음) |
| OneS1ght 연동이 미연결로 표시됨 / 도면이 안 보임 | [OneS1ght 연동이 미연결로 표시됨](#ones1ght-연동이-미연결로-표시됨) |

***

## 앱에 도면이 표시되지 않음

앱을 열었을 때 도면이 비어 있거나 로딩만 계속되는 경우입니다.

> [!NOTE]
>
> 도면을 등록하지 않은 층은 앱에 도면 없이 위치 점만 표시됩니다. 이 경우는 정상이며,
> 아래 항목은 도면을 등록한 층에만 해당합니다.

> [!NOTE]
>
> 검증 앱(담당자 전달)을 사용하는 경우 키는 앱에 내장되어 있습니다.
> 아래 1번(SDK 키 확인)은 건너뛰고 2번(측위 키 연동)부터 확인합니다.
> 키 확인은 자체 앱을 개발하는 경우에만 해당합니다.

1. **SDK 키 확인**
   * 앱에 입력한 키가 `ock_sdk_` 로 시작하는지, 앞뒤에 공백이 포함되지 않았는지 확인합니다.
     복사·붙여넣기 과정에서 공백이나 줄바꿈이 함께 들어가는 경우가 많습니다.
   * [모바일 SDK 키 관리](/console/sdk-keys)를 참고합니다.

2. **측위 키 연동 확인**
   * 도면·로케이터 정보는 콘솔에 연동해 둔 측위 키로 SDK 가 초기화할 때 자동으로 받아옵니다. 앱에 따로 넣는 값은 없습니다.
     연동이 안 되어 있거나 키를 받지 못하면 도면이 로딩되지 않고 SDK 로그에 `E1007` 이 남습니다.
   * [OneS1ght 연동이 미연결로 표시됨](#ones1ght-연동이-미연결로-표시됨)과 [주요 에러 코드](/developers/sdk/troubleshooting/error-codes)를 참고합니다.

3. **네트워크 확인**
   * 도면은 서버에서 내려받습니다. 현장 Wi-Fi가 외부 접속을 차단하는 경우 로딩되지 않으므로,
     휴대폰 데이터로 전환하여 다시 시도합니다.

4. **해당 층 도면 저장 여부 확인**
   * GeoSpace 층 목록에서 해당 층이 '미완료'로 표시되어 있으면 도면이 저장되지 않은 상태입니다.
     도면 배치 화면에서 \[층정보 저장]까지 눌렀는지 확인합니다. 저장되면 '도면 완료'로 바뀝니다.
   * [공간 등록](/locator/spaces)을 참고합니다.

***

## 앱에 위치 점이 표시되지 않음

도면은 정상적으로 표시되는데 위치 점만 나타나지 않는 경우입니다.
측위 자체가 시작되지 않은 상태로, 대부분 아래 다섯 가지 중 하나가 원인입니다.

> [!NOTE]
>
> 검증 앱(키 내장)을 사용하는 경우 3번(초기화 코드)은 해당하지 않습니다.
> 1·2번 확인 후 4·5번으로 진행합니다.

1. **UWB 지원 기기 확인**
   * iPhone 11 은 UWB(U1) 칩이 있지만 SDK 의 측위를 지원하지 않습니다.
     iPhone 12 이상, iOS 27.0 이상인지 확인합니다.
   * UWB를 지원하지 않는 기기에서도 앱은 정상 동작하며 측위 기능만 비활성화되므로,
     오류 메시지 없이 위치 점만 표시되지 않을 수 있습니다.

2. **앱 권한 확인**
   * iOS 설정 → 해당 앱에서 위치와 블루투스 권한이 허용되어 있는지 확인합니다.
     하나라도 거부 상태이면 UWB 측위가 시작되지 않습니다.

3. **초기화 코드 확인**
   * SDK 는 SDK 키 하나로 초기화합니다. 측위 키는 콘솔에 연동해 두면 초기화할 때 자동으로 받아옵니다.

     ```swift theme={null}
     try await OneS1ght.initialize(sdkKey: "ock_sdk_...")
     ```

   * 측위 키를 받지 못하면 초기화는 성공한 것처럼 보여도 건물·층·구역 목록이 비고 위치 점이 표시되지 않습니다.
     SDK 로그(`onDebugLog`)나 콘솔 로그 분석기에서 `E1007` 이 있는지 확인합니다.

   * 0.1.17 이하에서 쓰던 `geospaceKey` 인자는 0.1.18 에서 없어졌습니다. 예전 코드라면 SDK 를 최신 버전으로 올립니다.
     [주요 에러 코드](/developers/sdk/troubleshooting/error-codes)를 참고합니다.

4. **클러스터 적용 상태 확인**
   * GeoSpace Intelligence Hub \[도면 배치 · 무선 설계]에서 해당 층을 선택해 상태가 '구축 완료'로
     표시되는지 확인합니다. '미적용'이나 '설정확인필요'이면 등록이 끝나지 않은 것이므로
     \[구성 편집] → 클러스터 탭에서 \[장치 적용] → \[완료]를 다시 진행합니다.
   * [3) 클러스터](/locator/placement#3-클러스터)와
     [장치 적용이 안 되거나 로케이터가 미접속으로 보임](#장치-적용이-안-되거나-로케이터가-미접속으로-보임)을 참고합니다.

> [!CAUTION]
>
> 마스터 로케이터와 세션 ID 값은 서비스 도입 시 OneS1ght에서 안내됩니다.
> 임의로 지정하지 말고 안내받은 값을 입력하십시오.
> 안내받지 못한 경우 [support@ones1ght.com](mailto:support@ones1ght.com) 로 문의하십시오.

5. **로케이터 전원·위치 확인**
   * 모든 로케이터의 LED가 켜져 있는지 확인합니다. 하단 LED가 파랑이 아니라 자주색과 하늘색으로
     깜빡여도 클러스터가 '구축 완료'된 상태라면 측위에는 영향이 없습니다.
   * 현재 위치가 로케이터가 이루는 사각형 안쪽인지 확인합니다. 영역 밖에서는 위치가 잡히지 않습니다.

***

## 로케이터 신호를 찾을 수 없다고 표시됨

측위 중 로케이터 신호가 일정 시간 끊기면 '로케이터 신호를 찾을 수 없습니다' 화면이 표시됩니다.
감지 영역 밖으로 이동했거나, 로케이터 신호에 문제가 생긴 경우입니다.

1. **감지 영역 확인 후 \[대기] 클릭**
   * 감지 영역 밖에 있었다면 영역 안으로 이동합니다. \[대기]를 클릭하면 신호가 돌아올 때까지
     자동으로 재탐색하며, 신호가 잡히면 측위가 그대로 이어집니다.
   * 여러 번 재시도해도 신호가 잡히지 않으면 자동으로 종료되고 '로케이터 찾는 중' 화면으로 돌아갑니다.

2. **로케이터 전원·클러스터 상태 확인**
   * 감지 영역 안인데도 반복되면 로케이터의 LED가 켜져 있는지(전원) 확인합니다.
     하단 LED가 파랑이 아니라 자주색과 하늘색으로 깜빡여도 클러스터가 '구축 완료'된 상태라면
     Wi-Fi 없이 측위 신호를 계속 보내므로 정상입니다.
   * \[도면 배치 · 무선 설계]에서 해당 층의 상태가 '구축 완료'인지 확인합니다. 아니면
     [장치 적용이 안 되거나 로케이터가 미접속으로 보임](#장치-적용이-안-되거나-로케이터가-미접속으로-보임)을 참고합니다.
   * LED 위치와 색상별 의미는 [로케이터 현장 설치](/locator/install)의 LED 표 참고

3. **\[측위 종료] 후 재탐색**
   * \[측위 종료]를 클릭하면 현재 측위를 종료하고 처음부터 다시 로케이터를 찾습니다.

***

## 위치가 실제와 다른 곳에 표시됨

점은 표시되지만 실제 서 있는 곳과 다른 자리에 표시되는 경우입니다.

1. **도면상 배치 위치 확인 (도면을 등록한 경우)**
   * 도면 배치 화면에서 각 로케이터가 실제 설치 위치에 배치되어 있는지 확인합니다.
     점 전체가 일정한 방향으로 밀려 있다면 로케이터 전체가 같은 방향으로 어긋나게 배치된\

     경우가 대부분입니다.
   * [2) 위치 배치](/locator/placement#2-위치-배치)를 참고합니다.

2. **로케이터 사이 거리 확인**
   * '배치됨' 목록에서 로케이터 사이의 좌표 차이가
     [설치 전 준비에서 측정한 실측 거리](/locator/site-survey#3-현장-실측)와 일치하는지 확인합니다.\

   * 차이가 있으면 좌표를 실측값으로 수정합니다. '구축 완료' 뒤라면 \[도면 배치 · 무선 설계] → \[위치 조정]에서 수정합니다.
     값을 바꾸면 바로 저장되며, Wi-Fi가 연결된 상태면 \[변경된 장치에 위치 설정 푸시]도 누릅니다 ([4) 구축 완료 뒤 좌표만 수정할 때](/locator/placement#4-구축-완료-뒤-좌표만-수정할-때)).
   * 도면을 등록한 경우, 좌표를 실측값으로 맞춰도 위치가 계속 어긋나면 도면 스케일이 맞지 않는 것입니다.
     [이동 거리가 실제와 맞지 않음](#이동-거리가-실제와-맞지-않음)대로 스케일을 다시 설정합니다.

3. **X·Y 입력 확인**
   * 가로로 걸었는데 점은 세로로 움직이면(또는 그 반대) 좌표를 입력할 때 X와 Y를 서로 바꿔 넣은 것입니다.
     '배치됨' 목록에서 각 로케이터의 X(기준점에서 가로 거리)와 Y(세로 거리)가 바뀌지 않았는지 확인합니다.

4. **로케이터별 좌표 대조**
   * 각 로케이터 바로 아래에 서서 점의 위치를 확인합니다.
     특정 모서리에서만 어긋나는 경우 해당 로케이터의 좌표만 잘못 입력된 것입니다.

5. **도면 없이 진행한 경우**
   * 도면이 없으면 좌표가 유일한 기준입니다. 기준 로케이터를 (0, 0)으로 두고 각 로케이터까지의
     가로(X)·세로(Y) 거리와 설치 높이(Z)를 다시 실측해 '배치됨' 목록의 값을 보정합니다.

***

## 위치가 심하게 흔들리거나 튐

가만히 서 있어도 점이 계속 떨리거나 갑자기 먼 곳으로 튀는 경우입니다.
설치 환경 문제일 가능성이 높습니다.

1. **주변 금속 확인**
   * 금속 재질의 물체(예: 금속 선반, 철제 기둥, 냉장 설비)는 측위 신호에 영향을 줍니다.
     로케이터와 금속 재질의 물체 사이에 최소 0.5 m 이상의 거리가 확보되어 있는지 확인하고,\

     가까운 경우 로케이터를 이동합니다.

2. **설치 높이 확인**
   * 권장 설치 높이는 3 m이며, 최소 2 m 이상이어야 합니다.
     낮은 높이에서는 사람의 몸이나 집기가 신호를 가려 측위가 불안정해집니다.

3. **배치 형태 확인**
   * 로케이터가 한쪽에 몰려 있거나 일직선에 가까우면 오차가 크게 늘어납니다.
     감지 영역을 감싸는 사각형 형태로 네 모서리에 배치되어 있는지 확인합니다.

4. **로케이터 대수 확인**
   * 4대 미만으로는 안정적인 측위가 어렵습니다.
     일부 로케이터의 전원이 빠진 채 동작 중인 것은 아닌지 확인합니다.

5. **측정 영역 가장자리 확인**
   * 사각형 바깥쪽으로 갈수록 정확도가 떨어집니다.
     가장자리에서만 흔들리는 경우 정상 범위일 수 있으므로 중앙에서 다시 확인합니다.

> [!NOTE]
>
> 정지해 있어도 위치 점은 조금씩 움직입니다. 서 있는 자리를 크게 벗어나지 않으면 정상입니다.

***

## 이동 거리가 실제와 맞지 않음

10 m를 이동했는데 화면에서는 5 m만 이동한 것처럼 보이는 경우입니다.
도면을 등록한 층이면 도면 스케일이, 도면 없이 진행한 층이면 좌표의 거리 기준이 실제와 다른 것입니다.

1. **줄자(거리 측정)로 스케일 확인 (도면을 등록한 경우)**
   * 공간 등록 → 해당 층의 \[도면 배치 →]로 들어가, 실제 거리를 알고 있는 구간(벽에서 맞은편 벽까지 등)을
     줄자로 측정하여 실측값과 일치하는지 확인합니다. 가로와 세로를 각각 한 번씩, 가능한 한 긴 구간으로 확인합니다.
   * [3) 도면 등록 및 설정(선택)](/locator/spaces#3-도면-등록-및-설정-선택)을 참고합니다.

2. **스케일 다시 맞추기 (도면을 등록한 경우)**
   * '도면 실측 크기'는 공간 안쪽 치수가 아니라 도면 이미지 전체의 가로·세로에 적용됩니다.
     이미지에 공간 바깥 여백이나 벽 두께가 포함되어 있으면 공간 치수를 그대로 입력해도 어긋납니다.
   * \[두 점으로 스케일 설정]으로 실제 거리를 아는 두 점을 도면에서 찍고 그 실측 거리를 입력합니다.
     여백이 있는 도면은 이쪽이 쉽습니다.
   * '도면 실측 크기'를 다시 입력하는 경우에는 이미지 전체가 담고 있는 범위의 실제 가로 길이를 입력합니다.
   * 조정한 뒤 1번대로 가로와 세로를 다시 측정해 확인하고 \[층정보 저장]을 누릅니다.

3. **단위 확인**
   * 실제 거리 입력값의 단위는 미터(m)입니다. cm로 입력하면 100배 어긋납니다.

4. **도면 없이 진행한 경우**
   * '배치됨' 목록에서 로케이터 간 좌표 차이가 실측 거리(m)와 같은지 확인하고 보정합니다.
     '구축 완료' 뒤라면 \[위치 조정]에서 고칩니다 (바로 저장됨).

> [!NOTE]
>
> 스케일을 변경하면 도면 좌표계 전체가 변경됩니다.
> 스케일을 다시 설정한 후에는 로케이터 좌표를 다시 확인합니다.

***

## 구역(존) 이벤트가 발생하지 않음

위치는 정상적으로 잡히는데 구역에 들어가도 진입 이벤트가 발생하지 않는 경우입니다.

1. **구역 저장 여부 확인**
   * OneS1ght 공간 관리에서 해당 층에 존이 저장되어 있는지 확인합니다.
   * [공간 관리](/console/areas)를 참고합니다.

2. **측위 영역 확인**
   * 로케이터가 이루는 사각형 바깥에 그린 구역은 위치가 잡히지 않아 이벤트도 발생하지 않습니다.

3. **구역 크기 확인**
   * 측위에는 오차가 있으므로 구역이 지나치게 좁으면 점이 안팎을 오가며
     진입·이탈이 반복되거나 감지되지 않을 수 있습니다.

***

## 로케이터 LED가 빨강

로케이터 전면 LED가 빨강으로 켜져 있는 경우입니다.
제조사 정의상 하단 LED의 빨강 켜짐은 '장치 오류' 상태입니다.

> [!NOTE]
>
> 빨강이어도 측위 자체는 될 수 있습니다. 이 네트워크는 GeoSpace에서 설정을 내려받는
> 관리 채널로, 로케이터가 측위 신호를 송출하는 것과는 별개입니다.
> 검증 앱에 위치 점이 표시되면 측위는 정상입니다.

LED 위치와 색상별 의미는 [로케이터 현장 설치](/locator/install#1-로케이터-현장-설치)의 LED 표를 참고하십시오.

1. **현장 Wi-Fi 확인**
   * 로케이터는 현장 Wi-Fi(2.4 GHz)로 서버에 접속합니다. 공유기 전원, 인터넷 연결,
     Wi-Fi 비밀번호 변경 여부를 확인합니다.

2. **전원 재연결**
   * USB-C 케이블을 분리했다가 다시 연결하여 재부팅합니다.
     1\~2분 후 빨강이 사라지는지 확인합니다.

3. **어댑터 사양 확인**
   * 5V/3A 어댑터인지 확인합니다. 용량이 부족한 어댑터(예: 1A)는 부팅·통신 불안정의 원인이 됩니다.

4. **Wi-Fi 재설정 (프로비저닝 다시 실행)**
   * [하드웨어 등록](/locator/hardware)의 \[기기 프로비저닝]을 다시 진행하여
     로케이터의 Wi-Fi 정보를 재설정합니다.

5. **해결되지 않는 경우**
   * [support@ones1ght.com](mailto:support@ones1ght.com) 로 로케이터 S/N과 LED 상태를 알려 문의하십시오.

***

## 로케이터 하단 LED가 자주색과 하늘색으로 깜빡임

하단 LED가 자주색과 하늘색으로 번갈아 깜빡이는 것은 저장된 Wi-Fi로 접속을 시도하며 IP 할당을 기다리는 상태입니다.
로케이터는 2.4 GHz Wi-Fi만 지원합니다. 어느 시점에 보이는지에 따라 정상인지, 조치가 필요한지가 다릅니다.

**하드웨어 등록 전: 정상**

* 재설치하거나 다른 현장에서 쓰던 장비에 이전 Wi-Fi가 남아 있는 것입니다.
  [하드웨어 등록](/locator/hardware)에서 현장 Wi-Fi를 설정하면 파랑으로 바뀝니다.

**하드웨어 등록 뒤, 클러스터 적용 전: 조치**

입력한 Wi-Fi에 접속하지 못한 것입니다. 접속된 로케이터만 클러스터에 등록되므로,
파랑으로 만든 뒤 [측위 기능 활성화](/locator/placement)를 진행해야 합니다.

1. **접속할 네트워크 확인**
   * SSID와 비밀번호가 맞는지, 2.4 GHz 네트워크인지 확인합니다.
     공유기에 2.4 GHz와 5 GHz 이름이 따로 있으면 2.4 GHz 쪽(예: 이름 끝에 2.4G, 2G가 붙은 것)을 씁니다.

2. **Wi-Fi 다시 설정**
   * GeoSpace Mobile → \[기기 프로비저닝]에서 해당 로케이터를 다시 선택해
     [(1) 검색 → (2) 연결 → (3) Wi-Fi 정보 입력](/locator/hardware#2-기기-프로비저닝)에 확인한 SSID와 비밀번호를
     입력하고 \[설정 전송]을 누릅니다.
   * 로케이터가 재부팅(약 30초)된 뒤 하단 LED가 파랑으로 바뀌면 완료입니다. 그래도 깜빡이면
     [Wi-Fi를 다시 설정해도 로케이터가 접속되지 않음](#wi-fi를-다시-설정해도-로케이터가-접속되지-않음)을 참고합니다.

3. **현장에 2.4 GHz Wi-Fi가 없어 iPhone 개인용 핫스팟(테더링)을 쓰는 경우**
   * iPhone 설정 → 개인용 핫스팟을 켜고, 같은 화면의 **\[호환성 최대화]**를 켭니다. 이걸 켜야 핫스팟이 2.4 GHz로 동작합니다.
   * 2번의 Wi-Fi 정보 입력에 네트워크(SSID)는 iPhone 이름, 비밀번호는 핫스팟 화면의 'Wi-Fi 암호'를 입력합니다.
   * 핫스팟을 켠 iPhone은 하드웨어 등록과 클러스터 적용이 끝날 때까지 로케이터 근처에 둡니다.

**클러스터 '구축 완료' 뒤: 정상**

* 측위는 계속 동작합니다. Wi-Fi는 클러스터 등록 때만 쓰이므로,
  한 번 '구축 완료'된 뒤에는 접속이 끊겨도 됩니다.
* 로케이터를 옮기거나 교체해 클러스터를 다시 적용할 때, 또는 \[위치 조정]으로 좌표를 고쳐 푸시할 때만 위 조치대로 Wi-Fi를 다시 연결합니다.

***

## Wi-Fi를 다시 설정해도 로케이터가 접속되지 않음

프로비저닝을 다시 진행해도 하단 LED가 계속 자주색과 하늘색으로 깜빡이는 경우입니다.
이전 설정이 남아 덮어쓰기가 되지 않는 상태로, 이 경우에만 \[공장 초기화]를 사용합니다.

> [!CAUTION]
>
> \[공장 초기화]는 평소에는 사용하지 않습니다. 재사용 장비도 보통은 Wi-Fi를 다시 설정하는 것으로 충분합니다.

1. **공장 초기화 실행**
   * GeoSpace Mobile → \[기기 프로비저닝] → (3) Wi-Fi 정보 입력 화면 하단의 **\[공장 초기화]**를 실행합니다.
   * 초기화 중에는 하단 LED가 자주색으로만 깜빡이고(하늘색과 번갈아 깜빡이는 것과 다름), 완료되면 상단 초록, 하단 노랑(설정 전 상태)으로 돌아갑니다.

2. **기존 등록 삭제**
   * GeoSpace Intelligence Hub \[하드웨어 관리]에서 해당 로케이터의 기존 등록을 수동으로 삭제합니다.

3. **다시 프로비저닝**
   * [하드웨어 등록](/locator/hardware#2-기기-프로비저닝)의 (1)부터 다시 진행합니다.

***

## 하드웨어 선택 목록에 로케이터가 없음

6단계 \[구성 편집] → 하드웨어 선택 목록에 배치할 로케이터가 보이지 않는 경우입니다. 아래 네 가지 중 하나입니다.

1. **하드웨어 등록 확인**
   * [하드웨어 등록](/locator/hardware)이 끝나지 않은 로케이터는 표시되지 않습니다.
     GeoSpace \[하드웨어 관리] 목록에 있는지 확인합니다.

2. **다른 층 배치 여부 확인**
   * 이미 다른 층에 배치된 로케이터는 표시되지 않습니다.
     어느 층에 배치되어 있는지는 GeoSpace \[하드웨어 관리] 목록에서 확인합니다.

3. **'온라인' 스위치 확인**
   * 하드웨어 선택 목록의 검색창 오른쪽에 있는 '온라인' 스위치가 꺼져 있으면 로케이터가 표시되지 않습니다.
     배치 단계에서는 켜 둡니다.

4. **구성 초기화 뒤 다시 추가했는지 확인**
   * 단계 표시줄 오른쪽 끝의 빨간 휴지통으로 구성을 초기화하면 '이 층 등록' 목록이 비워집니다.
     로케이터의 하드웨어 등록은 유지되므로(\[하드웨어 관리] 목록에서 어느 층에 배치되어 있는지 확인 가능) 다시 프로비저닝하지 말고, 하드웨어 선택 목록에서 로케이터를 다시 클릭해 추가합니다.

***

## 장치 적용이 안 되거나 로케이터가 미접속으로 보임

6단계 \[구성 편집] → 클러스터 탭의 등록된 기기 목록에서 로케이터가 미접속(회색)으로 표시되거나, \[장치 적용] 때 미접속 경고가 뜨거나,
\[장치 적용] 뒤 상태가 '미적용' 또는 '설정확인필요'로 남는 경우입니다.

> [!NOTE]
>
> 클러스터 적용은 접속된 로케이터를 이 공간의 측위 구역으로 서버에 등록하는 과정입니다. 미접속(회색) 로케이터는 등록에서 빠지므로
> 접속 상태로 만든 뒤 적용해야 하며, 최초 1회는 상태가 '구축 완료'가 되어야 합니다.

1. **전원 확인**
   * LED가 점등되어 있으면 전원은 정상입니다.
     꺼져 있는 로케이터만 케이블·멀티탭을 확인합니다.

2. **Wi-Fi 접속 확인**
   * 하단 LED가 파랑(서버 연결 성공)인지 확인합니다. 자주색과 하늘색으로 깜빡이면 Wi-Fi에 접속하지 못한 것이므로
     [로케이터 하단 LED가 자주색과 하늘색으로 깜빡임](#로케이터-하단-led가-자주색과-하늘색으로-깜빡임)대로 조치합니다.
   * 접속되면 등록 기기 목록에 접속 상태로 다시 표시됩니다 (최근 1분 이내 접속 기준).

3. **다시 적용**
   * 클러스터 탭에서 (1) 접속 상태를 확인하고 (3) \[장치 적용] → \[완료]까지 진행합니다.
   * 상태가 '미적용'이면 \[장치 적용]이 실행되지 않은 것이므로 다시 실행합니다.
     '설정 실패'(층 상태 '설정확인필요')이면 일부 로케이터에 반영되지 않은 것이므로 전원과 접속 상태를 확인하고 다시 적용합니다.
   * 반복되면 그대로 두고 [동작 검증](/locator/verify)에서 실제 측위 동작으로 판단합니다.

4. **검증에서도 실패하는 경우 문의**
   * [support@ones1ght.com](mailto:support@ones1ght.com) 로 로케이터 S/N, LED 상태, 등록 기기 목록 화면 캡처를
     보내 문의하십시오.

***

## 로케이터를 옮기거나 교체했는데 측위에 반영되지 않음

클러스터 적용은 "이 로케이터들을 이 공간의 측위 구역으로 쓴다"고 서버에 등록하는 과정입니다.
로케이터 구성이 바뀐 뒤 다시 등록하지 않으면 측위는 이전 구성대로 동작합니다. 다음 경우에 다시 적용해야 합니다.

* 이 층의 로케이터를 다른 층에 옮겨 등록한 경우
* 이 층에 로케이터를 추가하거나 교체한 경우

1. **전원과 Wi-Fi 연결**
   * 이 층에 배치된 로케이터의 전원과 Wi-Fi를 모두 연결합니다 (하단 LED 파랑).

2. **클러스터 탭 진입**
   * \[도면 배치 · 무선 설계] → 층 선택 → \[구성 편집] → 클러스터 탭으로 들어갑니다.

3. **구성 확인**
   * (1) 접속 상태를 확인하고 (2) 클러스터 구성을 확인합니다.
     그룹이 달라졌으면 \[자동 클러스터 구성]부터 다시 실행하고 세션 ID와 마스터 로케이터를 다시 지정합니다.

4. **적용**
   * (3) \[장치 적용] → \[완료]까지 진행하고 상태가 '구축 완료'인지 확인합니다.

> [!NOTE]
>
> 좌표만 고치는 경우에는 다시 적용하지 않습니다. \[위치 조정]에서 수정하면 바로 저장됩니다 (Wi-Fi가 연결된 상태면 푸시까지)
> ([4) 구축 완료 뒤 좌표만 수정할 때](/locator/placement#4-구축-완료-뒤-좌표만-수정할-때)).

***

## OneS1ght 연동이 미연결로 표시됨

\[조직 설정] → API 연동의 Geospace 연동에서 Intelligence Hub (모바일)가 미연결로 표시되거나,
공간 관리에서 건물이 '도면 미연동 건물'로 표시되는 경우입니다.

> [!NOTE]
>
> 도면을 등록하지 않은 층은 넘어올 도면이 없으므로 '도면 미연동 건물'로 표시되는 것이 정상이며, 측위에는 영향이 없습니다.
> 연동 상태가 '연결됨'인데 도면을 등록한 층이 미연동으로 보이면 GeoSpace 층 목록에서 해당 층이 '도면 완료'인지 확인합니다.

1. **파트너 키 등록 확인**
   * GeoSpace에서 키를 발급하는 것과 OneS1ght에 등록하는 것은 서로 다른 작업입니다.
     발급만 하고 등록하지 않은 경우가 가장 많습니다.
   * [측위 정보 연동](/locator/connect#3-ones1ght에-등록)을 참고합니다.

2. **키 형식 확인**
   * 파트너 키는 `gpk_` 로 시작합니다. SDK 키(`ock_sdk_`)와는 서로 다른 키입니다.

3. **\[저장] 확인**
   * 키를 입력한 후 \[저장]을 클릭해야 반영됩니다.
     저장 전에 \[연결 테스트]로 키가 유효한지 확인할 수 있습니다.

4. **권한 확인**
   * 이 화면은 관리자(Manager) 이상만 접근·수정할 수 있습니다.
     viewer 계정으로는 등록할 수 없습니다.

5. **네트워크 확인**
   * OneS1ght 서버가 GeoSpace 서버로 나가는 아웃바운드 통신이 가능해야 합니다.
     사내망에서 차단된 경우 허용 호스트 설정을 확인합니다.

***

## 그래도 해결되지 않는다면

[support@ones1ght.com](mailto:support@ones1ght.com) 로 문의하십시오.
아래 정보를 함께 보내면 원인 확인이 빨라집니다.

| 항목 | 예시 |
| - | - |
| 증상 | "점은 보이는데 항상 오른쪽으로 2 m 밀려 있음" |
| 현장 | 건물·층 이름, 공간 실측 크기 |
| 로케이터 좌표 | '배치됨' 목록 화면 캡처 |
| OneS1ght 연결 상태 | 설정 → Geospace 연동 카드의 배지 캡처 |
| 테스트 기기 | iPhone 15 Pro / iOS 27.1 |
| 앱 화면 | 위치 점이 보이는(또는 안 보이는) 화면 캡처 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.