> ## 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가-빨강) | | 장치 적용이 안 됨 / 로케이터가 미접속 | [장치 적용이 안 되거나 로케이터가 미접속으로 보임](#장치-적용이-안-되거나-로케이터가-미접속으로-보임) | | OneS1ght에 샘플 도면만 보임 | [OneS1ght가 계속 시뮬레이션 모드](#ones1ght가-계속-시뮬레이션-모드) | *** ## 앱에 도면이 표시되지 않음 앱을 열었을 때 도면이 비어 있거나 로딩만 계속되는 경우입니다. 검증 앱(담당자 전달)을 사용하는 경우 키는 앱에 내장되어 있습니다. 아래 1·2번(키 확인)은 건너뛰고 3번(네트워크)부터 확인합니다. 키 확인은 자체 앱을 개발하는 경우에만 해당합니다. 1. **SDK 키 확인** * 앱에 입력한 키가 `ock_sdk_` 로 시작하는지, 앞뒤에 공백이 포함되지 않았는지 확인합니다. 복사·붙여넣기 과정에서 공백이나 줄바꿈이 함께 들어가는 경우가 많습니다. * [모바일 SDK 키 관리](/locator/sdk-keys)를 참고합니다. 2. **geospaceKey 값 확인** * 앱의 도면·로케이터 정보는 이 값으로 받아옵니다. 담당자에게 전달받은 값이 누락되었거나 잘못된 경우 도면이 로딩되지 않습니다. 값과 앞뒤 공백을 확인합니다. * [SDK 키 발급](/locator/sdk-keys#키-발급)을 참고합니다. 3. **네트워크 확인** * 도면은 서버에서 내려받습니다. 현장 Wi-Fi가 외부 접속을 차단하는 경우 로딩되지 않으므로, 휴대폰 데이터로 전환하여 다시 시도합니다. 4. **해당 층 도면 저장 여부 확인** * GeoSpace 층 목록에서 해당 층이 미완료로 표시되어 있으면 도면이 저장되지 않은 상태입니다. * [3. 공간 등록](/geospace/spaces)을 참고합니다. *** ## 앱에 위치 점이 표시되지 않음 도면은 정상적으로 표시되는데 위치 점만 나타나지 않는 경우입니다. 측위 자체가 시작되지 않은 상태로, 대부분 아래 다섯 가지 중 하나가 원인입니다. 검증 앱(키 내장)을 사용하는 경우 3번(초기화 코드)은 해당하지 않습니다. 1·2번 확인 후 4·5번으로 진행합니다. 1. **UWB 지원 기기 확인** * iPhone 11 이하에는 UWB 칩이 없어 측위가 동작하지 않습니다. iPhone 12 이상, iOS 27.0 이상인지 확인합니다. * UWB를 지원하지 않는 기기에서도 앱은 정상 동작하며 측위 기능만 비활성화되므로, 오류 메시지 없이 위치 점만 표시되지 않을 수 있습니다. 2. **앱 권한 확인** * iOS 설정 → 해당 앱에서 위치와 근처 기기(Nearby Interaction) 권한이 허용되어 있는지 확인합니다. 하나라도 거부 상태이면 UWB 측위가 시작되지 않습니다. 3. **geospaceKey 초기화 확인** * SDK를 `geospaceKey` 없이 초기화하면 오류 없이 측위만 비활성화됩니다. 도면·존은 정상인데 위치 점만 표시되지 않는 전형적인 원인입니다. ```swift
theme={null} try await OneS1ghtSDK.initialize(sdkKey: "ock_sdk_...",
geospaceKey: "<담당자 전달값>") // ← 이 인자가 있는지
``` * 이 값은 발급받는 키가 아니라 담당자가 데모 킷과 함께 전달합니다. [SDK 키 발급](/locator/sdk-keys#키-발급)을 참고합니다. 4. **클러스터 적용 확인** * GeoSpace 도면 배치 · 무선 설계에서 클러스터 설정 후 \[저장] → \[장치 적용] → \[완료]까지 진행했는지 확인합니다. [3) 클러스터](/geospace/placement#3-클러스터)을 참고합니다. 데모 킷은 클러스터 설정이 미리 적용된 상태로 전달되기도 합니다. 장치 적용이 완료되지 않아도 측위가 되는 경우가 있으므로, 최종 판단은 앱에 위치 점이 표시되는지로 합니다. [장치 적용이 안 되거나 로케이터가 미접속으로 보임](#장치-적용이-안-되거나-로케이터가-미접속으로-보임)을 참고합니다. 마스터 로케이터와 세션 ID 값은 서비스 도입 시 OneS1ght에서 안내됩니다. 임의로 지정하지 말고 안내받은 값을 입력하십시오. 안내받지 못한 경우 [onesight-support@onecheck.co.kr](mailto:onesight-support@onecheck.co.kr) 로 문의하십시오. 5. **로케이터 전원·위치 확인** * 모든 로케이터에 전원이 들어와 있는지, 현재 위치가 로케이터가 이루는 사각형 안쪽인지 확인합니다. 영역 밖에서는 위치가 잡히지 않습니다. *** ## 위치가 실제와 다른 곳에 표시됨 점은 표시되지만 실제 서 있는 곳과 다른 자리에 표시되는 경우입니다. 1. **도면상 배치 위치 확인** * 도면 배치 화면에서 각 로케이터가 실제 설치 위치에 배치되어 있는지 확인합니다. 점 전체가 일정한 방향으로 밀려 있다면 로케이터 전체가 같은 방향으로 어긋나게 배치된
경우가 대부분입니다. * [2) 위치 배치](/geospace/placement#2-위치-배치)를 참고합니다. 2. **로케이터 사이 거리 확인** * '배치됨' 목록에서 로케이터 사이의 좌표 차이가 [1. 설치 전 준비에서 측정한 실측 거리](/geospace/site-survey#3-현장-실측)와 일치하는지 확인합니다.
* 차이가 있으면 좌표를 실측값으로 수정합니다. * 좌표를 실측값으로 맞춰도 위치가 계속 어긋나면 도면 스케일이 맞지 않는 것입니다. [3. 공간 등록](/geospace/spaces)에서 두 점 스케일 설정을 다시 진행합니다. 3. **X·Y 입력 확인** * 점이 대각선으로 뒤집혀 보이는 경우 X·Y가 서로 바뀐 것입니다. 가로 방향이 X, 세로 방향이 Y입니다. 4. **로케이터별 좌표 대조** * 각 로케이터 바로 아래에 서서 점의 위치를 확인합니다. 특정 모서리에서만 어긋나는 경우 해당 로케이터의 좌표만 잘못 입력된 것입니다. *** ## 위치가 심하게 흔들리거나 튐 가만히 서 있어도 점이 계속 떨리거나 갑자기 먼 곳으로 튀는 경우입니다. 설치 환경 문제일 가능성이 높습니다. 1. **주변 금속 확인** * 금속 재질의 물체(예: 금속 선반, 철제 기둥, 냉장 설비)는 측위 신호에 영향을 줍니다. 로케이터와 금속 재질의 물체 사이에 최소 0.5 m 이상의 거리가 확보되어 있는지 확인하고,
가까운 경우 로케이터를 이동합니다. 2. **설치 높이 확인** * 권장 설치 높이는 2.4 \~ 3 m이며, 최소 2 m 이상이어야 합니다. 낮은 높이에서는 사람의 몸이 신호를 가려 측위가 불안정해집니다. 3. **배치 형태 확인** * 로케이터가 한쪽에 몰려 있거나 일직선에 가까우면 오차가 크게 늘어납니다. 감지 영역을 감싸는 사각형 형태로 네 모서리에 배치되어 있는지 확인합니다. 4. **로케이터 대수 확인** * 4대 미만으로는 안정적인 측위가 어렵습니다. 일부 로케이터의 전원이 빠진 채 동작 중인 것은 아닌지 확인합니다. 5. **측정 영역 가장자리 확인** * 사각형 바깥쪽으로 갈수록 정확도가 떨어집니다. 가장자리에서만 흔들리는 경우 정상 범위일 수 있으므로 중앙에서 다시 확인합니다. *** ## 이동 거리가 실제와 맞지 않음 10 m를 이동했는데 화면에서는 5 m만 이동한 것처럼 보이는 경우입니다. 도면 스케일이 잘못 설정된 것입니다. 1. **스케일 재설정** * GeoSpace 도면 설정에서 \[두 점으로 스케일 설정]을 다시 실행합니다. 두 점을 지정한 구간과 입력한 실제 거리가 정확히 같은 구간이어야 합니다. * [3) 도면 등록 및 설정](/geospace/spaces#3-도면-등록-및-설정)을 참고합니다. 2. **측정 구간 길이 확인** * 스케일은 입력한 실제 거리 ÷ 도면에서 지정한 두 점 사이의 거리로 계산됩니다. 화면에서 정확한 지점을 클릭하기 어려워 매번 몇 픽셀씩 어긋나는데, 이 어긋남은 구간
길이와 관계없이 비슷하므로 짧은 구간일수록 비율로 환산한 오차가 커집니다. | 지정한 구간 | 클릭 3픽셀 오차 시 오차 비율 | 12 m 공간 전체로 환산 | | ----------------- | ----------------- | -------------- | | 1 m (화면 약 30픽셀) | 10 % | 1.2 m 어긋남 | | 12 m (화면 약 360픽셀) | 0.8 % | 0.1 m 어긋남 | * 가능한 한 긴 구간(벽에서 벽까지)으로 다시 설정합니다. 3. **단위 확인** * 실제 거리 입력값의 단위는 미터(m)입니다. cm로 입력하면 100배 어긋납니다. 스케일을 변경하면 도면 좌표계 전체가 변경됩니다. 스케일 재설정 후에는 로케이터 좌표를 다시 확인합니다. *** ## 구역(존) 이벤트가 발생하지 않음 위치는 정상적으로 잡히는데 구역에 들어가도 진입 이벤트가 발생하지 않는 경우입니다. 1. **구역 저장 여부 확인** * OneS1ght 공간 관리에서 해당 층에 존이 저장되어 있는지 확인합니다. * [공간 관리](/locator/areas)를 참고합니다. 2. **측위 영역 확인** * 로케이터가 이루는 사각형 바깥에 그린 구역은 위치가 잡히지 않아 이벤트도 발생하지 않습니다. 3. **구역 크기 확인** * 측위에는 오차가 있으므로 구역이 지나치게 좁으면 점이 안팎을 오가며 진입·이탈이 반복되거나 감지되지 않을 수 있습니다. *** ## 로케이터 LED가 빨강 로케이터 전면 LED가 빨강으로 켜져 있는 경우입니다. 로케이터가 GeoSpace 관리 채널(Wi-Fi)에 접속하지 못한 상태입니다. 빨강이어도 측위 자체는 될 수 있습니다. 이 네트워크는 GeoSpace에서 설정을 내려받는 관리 채널로, 로케이터가 측위 신호를 송출하는 것과는 별개입니다. 검증 앱에 위치 점이 표시되면 측위는 정상입니다. **참고 — 제조사 LED 정의** (지원팀에 상태를 알릴 때 사용) | LED | 제조사 정의 | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | | 노랑 켜짐 | ·전원 정상 | | 초록 켜짐 | ·무선 네트워크 연결 정상 | | 초록 깜빡 + 파랑 켜짐 / 빨강 깜빡 + 초록 켜짐 | ·UWB 신호 수신 중 | | 빨강 켜짐 | ·무선 네트워크 오류 | 출처: Geoplan AN-500 제품 사양서 (2025) 1. **현장 Wi-Fi 확인** * 로케이터는 현장 Wi-Fi(2.4 GHz)로 서버에 접속합니다. 공유기 전원, 인터넷 연결, Wi-Fi 비밀번호 변경 여부를 확인합니다. 2. **전원 재연결** * USB-C 케이블을 분리했다가 다시 연결하여 재부팅합니다. 1\~2분 후 빨강이 사라지는지 확인합니다. 3. **어댑터 사양 확인** * 5V/3A 어댑터인지 확인합니다. 용량이 부족한 어댑터(예: 1A)는 부팅·통신 불안정의 원인이 됩니다. 4. **해결되지 않는 경우** * 로케이터의 Wi-Fi 설정을 다시 잡아야 할 수 있습니다. [onesight-support@onecheck.co.kr](mailto:onesight-support@onecheck.co.kr) 로 로케이터 S/N과 LED 상태를 알려 문의하십시오. *** ## 장치 적용이 안 되거나 로케이터가 미접속으로 보임 5단계 클러스터의 등록 기기 목록에 로케이터가 미접속(회색)으로 표시되거나, \[장치 적용]이 완료되지 않는 경우입니다. 대부분 그대로 진행할 수 있습니다. 로케이터는 측위 신호를 송출하는 장비로 서버에 상시 접속해 있을 필요가 없으며, 데모 킷은 클러스터 설정이 미리 적용된 상태로 전달되기도 합니다. 목록 표시와 관계없이 \[무시하고 장치 적용] → \[완료]로 진행한 뒤, [7. 동작 검증](/geospace/verify)에서 앱에 위치 점이 표시되는지로 판단합니다. 1. **전원 확인** * LED가 점등되어 있으면 전원은 정상입니다. 꺼져 있는 로케이터만 케이블·멀티탭을 확인합니다. 2. **\[완료]까지 진행** * 경고가 표시되어도 \[무시하고 장치 적용] → \[완료]를 클릭한 뒤 7단계로 진행합니다. 3. **검증에서도 실패하는 경우 문의** * [onesight-support@onecheck.co.kr](mailto:onesight-support@onecheck.co.kr) 로 로케이터 S/N, LED 상태, 등록 기기 목록 화면 캡처를 보내 문의하십시오. *** ## OneS1ght가 계속 시뮬레이션 모드 설정 → Geospace 연동 카드에서 미연결 — 시뮬레이션 모드 배지가 사라지지 않는 경우입니다. 1. **파트너 키 등록 확인** * GeoSpace에서 키를 발급하는 것과 OneS1ght에 등록하는 것은 서로 다른 작업입니다. 발급만 하고 등록하지 않은 경우가 가장 많습니다. * [6. 측위 정보 연동](/geospace/connect#2-ones1ght에-등록)을 참고합니다. 2. **키 형식 확인** * 파트너 키는 `gpk_` 로 시작합니다. SDK 키(`ock_sdk_`)와는 서로 다른 키입니다. 3. **\[저장] 확인** * 키를 입력한 후 \[저장]을 클릭해야 반영됩니다. 저장 전에 \[연결 테스트]로 키가 유효한지 확인할 수 있습니다. 4. **권한 확인** * 이 화면은 관리자(Manager) 이상만 접근·수정할 수 있습니다. viewer 계정으로는 등록할 수 없습니다. 5. **네트워크 확인** * OneS1ght 서버가 GeoSpace 서버로 나가는 아웃바운드 통신이 가능해야 합니다. 사내망에서 차단된 경우 허용 호스트 설정을 확인합니다. *** ## 그래도 해결되지 않는다면 [onesight-support@onecheck.co.kr](mailto:onesight-support@onecheck.co.kr) 로 문의하십시오. 아래 정보를 함께 보내면 원인 확인이 빨라집니다. | 항목 | 예시 | | -------------- | ---------------------------- | | 증상 | "점은 보이는데 항상 오른쪽으로 2 m 밀려 있음" | | 현장 | 건물·층 이름, 공간 실측 크기 | | 로케이터 좌표 | '배치됨' 목록 화면 캡처 | | OneS1ght 연결 상태 | 설정 → Geospace 연동 카드의 배지 캡처 | | 테스트 기기 | iPhone 15 Pro / iOS 27.1 | | 앱 화면 | 위치 점이 보이는(또는 안 보이는) 화면 캡처 |