> ## 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-が赤)                    |
| 装置適用ができない / アンカーが未接続 | [装置適用ができない・アンカーが未接続に見える](#装置適用ができないアンカーが未接続に見える) |
| コンソールにサンプル図面しか表示されない | [コンソールがシミュレーションモードのまま](#コンソールがシミュレーションモードのまま)    |

***

## アプリに図面が表示されない

アプリを開いても図面が空のまま、あるいは読み込みが終わらない場合です。

<Note>
  **検証アプリ（担当者よりお渡しするもの）をお使いの場合**、キーはアプリに組み込まれています — 下の 1・2 番（キーの確認）は
  飛ばして 3 番（ネットワーク）から確認してください。キーの確認は、自社アプリを開発中の場合のみ該当します。
</Note>

<Steps>
  <Step title="SDK キーが正しいか確認">
    アプリに設定したキーが `ock_sdk_` で始まっているか、前後に空白が混ざっていないかを確認してください。
    コピー＆ペーストの際に空白や改行が紛れ込むことがよくあります。

    → [モバイル SDK キー管理](/ja/locator/sdk-keys)
  </Step>

  <Step title="geospaceKey の暫定値が正しいか確認">
    アプリの図面・アンカー情報は、現在この暫定値で取得しています。担当者よりお渡しした値が抜けていたり誤っていたりすると
    図面が読み込まれません — 値と前後の空白を確認してください。

    → [インストール・キーの準備](/ja/sdk/quick-start)
  </Step>

  <Step title="ネットワークの確認">
    図面はサーバーから取得します。現場の Wi-Fi が外部接続を遮断していると読み込まれません。
    携帯データ通信に切り替えて、もう一度お試しください。
  </Step>

  <Step title="該当フロアに図面が保存されているか確認">
    GeoSpace のフロア一覧でそのフロアが **未完了** と表示されている場合、図面が保存されていません。

    → [建物・図面の登録](/ja/geospace/spaces)
  </Step>
</Steps>

***

## アプリに位置の点が表示されない

図面は正常に表示されるのに、自分の位置の点だけが現れない場合です。
**測位そのものが開始されていない状態**で、原因はほとんど次の 5 つのいずれかです。

<Note>
  検証アプリ（キー組み込み済み）をお使いの場合、3 番（初期化コード）は該当しません — 1・2 番を確認したら 4・5 番へ進んでください。
</Note>

<Steps>
  <Step title="UWB 対応端末か確認">
    **iPhone 11 以前には UWB チップがないため、測位は動作しません。**
    iPhone 12 以降 · iOS 27.0 以降かを確認してください。

    <Note>
      UWB に対応しない端末でもアプリは正常に動作し、測位機能だけが無効になります。
      そのためエラーメッセージも出ないまま、点だけが表示されないことがあります。
    </Note>
  </Step>

  <Step title="アプリの権限確認">
    iOS の設定 → 該当アプリで、**位置情報**と**近くのデバイス**（Nearby Interaction）の権限が
    許可されているか確認してください。どちらか一方でも拒否になっていると UWB 測位は開始されません。
  </Step>

  <Step title="geospaceKey の暫定値を渡して初期化したか確認">
    SDK を `geospaceKey` なしで初期化すると、**エラーは出ず測位だけが無効**になります —
    図面・ゾーンは正常なのに点だけ出ない、典型的な原因です。

    ```swift theme={null}
    try await OneS1ghtSDK.initialize(sdkKey: "ock_sdk_...",
                                     geospaceKey: "<担当者よりお渡しする値>")  // ← この引数があるか
    ```

    → この値は発行するキーではなく、**担当者がデモキットとあわせてお渡しします** — [インストール・キーの準備](/ja/sdk/quick-start) をご参照ください。
  </Step>

  <Step title="クラスターが適用されているか確認">
    GeoSpace の **図面配置・無線設計** で 3 ステップ目のクラスターまで終え、
    **［保存］→［装置適用］→［完了］** を押したか確認してください。

    <Note>
      デモキットはクラスター設定が**あらかじめ入った状態でお渡しする**こともあります — 装置適用が完了していなくても
      測位できる場合がありますので、最終的な判断は**アプリに点が表示されるか**で行ってください。
      → [装置適用ができない・アンカーが未接続に見える](#装置適用ができないアンカーが未接続に見える)
    </Note>

    <Warning>
      マスターアンカーとセッション ID は**任意に指定してはいけません。**
      OneS1ght よりご案内した値をそのまま入力してください。
      ご案内を受けていない場合は `onesight-support@onecheck.co.kr` までお問い合わせください。
    </Warning>
  </Step>

  <Step title="アンカーの電源と位置の確認">
    アンカー 4 台すべてに電源が入っているか、そして今立っている場所が
    **アンカー 4 台がつくる四角形の内側**かを確認してください。範囲の外では位置が取得できません。
  </Step>
</Steps>

***

## 位置が実際と違う場所に表示される

点は出るものの、実際に立っている場所と違うところに表示される場合です。
**全体が一定の方向へずれている場合**は、座標の原点の問題である可能性が最も高いです。

<Steps>
  <Step title="図面画像のオフセットを反映したか確認">
    最もよくある原因です。図面配置画面の座標の原点は
    **部屋の隅ではなく、アップロードした図面画像全体の (0, 0)** です。

    画像に余白や外壁が含まれている場合は、その分を足して入力する必要があります。
    たとえば部屋の左下が画像の原点から (0.6, 1.5) 離れているなら、
    現場で (0, 0) として測定したアンカーは `(0.6, 1.5)` と入力します。

    <Tip>
      **ずれた距離と方向を測っておくと補正が簡単です。** アンカー 4 台を同じように誤入力していれば、点も同じ方向へ
      同じ距離だけずれるので、**すべてのアンカー座標をその逆方向へ同じ距離だけ**動かせば合います。
      オフセットを入れ忘れた場合、点は**図面の原点側（左下）へ**ずれます。
      （アプリでは図面が回転して見えることがあるため、方向は画面ではなく**図面基準**で判断してください。）
    </Tip>
  </Step>

  <Step title="X と Y を入れ替えて入力していないか確認">
    点が対角線方向に反転して見える場合は、X と Y が入れ替わっています。
    横方向が X、縦方向が Y です。
  </Step>

  <Step title="アンカーごとの座標を 1 つずつ照合">
    各アンカーの真下に立って点の位置を確認してください。
    **特定の隅でだけ**ずれる場合は、そのアンカー 1 台の座標だけが誤入力されています。
  </Step>

  <Step title="ドラッグだけで配置していないか確認">
    図面上にドラッグして置いただけでは、目測の誤差がそのまま残ります。
    「配置済み」リストで**現場で測定した値を数値で直接入力**してください。

    → [図面配置](/ja/geospace/placement#1-図面配置)
  </Step>
</Steps>

***

## 位置が大きくぶれる・飛ぶ

じっと立っているのに点が震え続けたり、突然遠くへ飛んだりする場合です。
**設置環境の問題**である可能性が高いです。

<Steps>
  <Step title="アンカー周辺の金属を確認">
    鉄・スチール・アルミなどの金属は電波を干渉します。
    金属棚、鉄製の柱、冷蔵設備、金属パーティションの近くにアンカーがある場合は移設してください。
  </Step>

  <Step title="設置高さの確認">
    推奨の高さは **2.4 ～ 3 m** で、**3 m に近いほど有利**です。最低でも 2 m 以上必要です。
    机の上に置いた程度の低い高さでは、人の体が信号を遮って測位が不安定になります。
  </Step>

  <Step title="アンカーの配置形状を確認">
    アンカーが一方に偏っていたり、ほぼ一直線に並んでいたりすると誤差が大きく増えます。
    **検知範囲を囲む長方形**になるよう、四隅に配置されているか確認してください。
  </Step>

  <Step title="アンカーの台数を確認">
    4 台未満では安定した測位は困難です。
    1 台の電源が抜けて 3 台で動作していないか確認してください。
  </Step>

  <Step title="測定範囲の端ではないか確認">
    四角形の外側へ出るほど精度が落ちます。
    端でだけぶれる場合は正常な範囲のこともありますので、中央で再度確認してみてください。
  </Step>
</Steps>

***

## 移動距離が実際と合わない

10 m 歩いたのに、画面では 5 m しか移動していないように見える場合です。
**図面のスケール**が正しく設定されていません。

<Steps>
  <Step title="スケール設定を確認し直す">
    GeoSpace の **図面配置** で **［2点でスケール設定］** をもう一度実行してください。
    2 点を指定した区間と入力した実際の距離が、**まったく同じ区間**である必要があります。

    → [図面の設定（スケール）](/ja/geospace/spaces#3-図面の設定スケール)
  </Step>

  <Step title="測定区間が十分に長いか確認">
    スケールは **入力した実際の距離 ÷ 図面上で指定した 2 点間の距離** で計算されます。
    ところがマウスで正確な位置を指定するのは難しく、毎回数ピクセルずつずれますが、
    **このずれは区間が短くても長くてもほぼ同じです。** そのため区間が短いほど、割合で見た誤差は大きくなります。

    クリックが 3 ピクセルずれたとすると —

    | 指定した区間               | 誤差の割合 | 12 m の店舗全体に換算すると |
    | -------------------- | ----- | ---------------- |
    | 1 m（画面上で約 30 ピクセル）   | 10 %  | **1.2 m のずれ**    |
    | 12 m（画面上で約 360 ピクセル） | 0.8 % | 10 cm のずれ        |

    同じミスをしても、長い区間で取れば誤差は埋もれます —
    **図面上で最も長い区間（壁から壁まで）** で取り直してください。
  </Step>

  <Step title="単位がメートルか確認">
    実際の距離の入力値の単位は\*\*メートル（m）\*\*です。cm で入力すると 100 倍ずれます。
  </Step>
</Steps>

<Note>
  スケールを変更すると図面の座標系全体が変わります。
  **スケールを再設定したあとは、アンカー座標を必ず確認し直して**ください。
</Note>

***

## ゾーンイベントが発生しない

位置は正常に取得できているのに、ゾーンに入っても進入イベントが届かない場合です。

<Steps>
  <Step title="ゾーンが実際に描かれているか確認">
    OneS1ght コンソールの **空間管理** で、該当フロアにゾーンが保存されているか確認してください。

    → [空間管理](/ja/locator/areas)
  </Step>

  <Step title="ゾーンが測位範囲の内側にあるか確認">
    アンカー 4 台がつくる四角形の**外側**に描いたゾーンは位置が取得できないため、イベントも発生しません。
  </Step>

  <Step title="ゾーンが小さすぎないか確認">
    測位には誤差があります。ゾーンが狭すぎると点が内外を行き来し、
    進入・退出が繰り返されたり、まったく検知されなかったりすることがあります。
  </Step>
</Steps>

***

## アンカーの LED が赤

アンカー前面の LED が**赤く点灯**している場合です。アンカーが GeoSpace の管理チャネル（Wi-Fi）に接続できていない状態です。

<Note>
  赤でも**測位自体はできることがあります** — このネットワークは GeoSpace から設定を受け取る管理チャネルであり、
  アンカーが信号を発信する測位とは別ものです。検証アプリに点が表示されていれば測位は正常です。
</Note>

**参考 — メーカーの LED 定義**（サポートチームに状態を伝えるときに使用）

| LED                       | メーカー定義       |
| ------------------------- | ------------ |
| 黄 点灯                      | 電源正常         |
| 緑 点灯                      | 無線ネットワーク接続正常 |
| 緑 点滅 + 青 点灯 / 赤 点滅 + 緑 点灯 | UWB 信号を受信中   |
| 赤 点灯                      | 無線ネットワークエラー  |

<small>出典: Geoplan AN-500 製品仕様書 (2025)</small>

<Steps>
  <Step title="現場の Wi-Fi を確認">
    アンカーは\*\*現場の Wi-Fi（2.4GHz）\*\*でサーバーに接続します。ルーターの電源が入っているか、インターネットに接続できるか、
    Wi-Fi のパスワードが変更されていないかを確認してください。
  </Step>

  <Step title="電源を入れ直す">
    USB-C を抜き差しして再起動します。1～2 分ほど様子を見て、赤が消えるか確認します。
  </Step>

  <Step title="アダプターの仕様を確認">
    **5V/3A** のアダプターか確認してください。容量の足りないアダプター（例: 1A）は起動・通信が不安定になる原因です。
  </Step>

  <Step title="それでも赤のままなら">
    アンカーの Wi-Fi 設定自体をやり直す必要があるかもしれません — `onesight-support@onecheck.co.kr` へ
    アンカーの S/N と LED の状態をお知らせください。
  </Step>
</Steps>

***

## 装置適用ができない・アンカーが未接続に見える

ステップ5 のクラスターで、**接続リストにアンカーが未接続（グレー）** と表示されたり、**［装置適用］** が完了しない場合です。

<Note>
  **ほとんどの場合、そのまま進めて問題ありません。** アンカーは測位信号を**発信するだけ**なので、サーバーに接続し続ける必要はなく、
  デモキットはクラスター設定があらかじめ入った状態でお渡しすることもあります。
  接続リストの表示にかかわらず **［無視して装置適用］→［完了］** で先に進み、
  [ステップ7 動作検証](/ja/geospace/verify) で**アプリに点が表示されるか**で判断してください。
</Note>

<Steps>
  <Step title="アンカー 4 台に電源が入っているか確認">
    LED が点灯していれば電源は正常です。消えているアンカーだけ、ケーブル・電源タップを確認してください。
  </Step>

  <Step title="［完了］まで進めて動作検証へ">
    警告が出ても **［無視して装置適用］→［完了］** を押したうえで、ステップ7 へ進みます。
    ここで留まっていても、確認できることはありません。
  </Step>

  <Step title="動作検証でも点が出なければお問い合わせ">
    `onesight-support@onecheck.co.kr` へ **アンカーの S/N · LED の状態 · 接続リスト画面のキャプチャ** をお送りください。
  </Step>
</Steps>

***

## コンソールがシミュレーションモードのまま

**設定 → Geospace 連携** カードで **未接続 — シミュレーションモード** バッジが消えない場合です。

<Steps>
  <Step title="パートナーキーを登録したか確認">
    GeoSpace でキーを**発行**することと、OneS1ght コンソールに**登録**することは別の作業です。
    発行しただけで登録していないケースが最も多くあります。

    → [6. 測位連携・キー発行](/ja/geospace/connect#2-ones1ght-コンソールへの登録)
  </Step>

  <Step title="キーの形式を確認">
    パートナーキーは `gpk_` で始まります。SDK キー（`ock_sdk_`）と混同しないでください。両者は別のキーです。
  </Step>

  <Step title="［保存］を押したか確認">
    キーを入力しただけで **［保存］** を押さないと反映されません。保存の前に **［接続テスト］** で、キーが有効かを先に確認できます。
  </Step>

  <Step title="権限の確認">
    この画面は**管理者（Manager）以上**のみアクセス・編集できます。
    viewer アカウントでは登録できません。
  </Step>

  <Step title="ネットワークの確認">
    コンソールサーバーから GeoSpace サーバーへのアウトバウンド通信ができる必要があります。
    社内ネットワークで遮断されている場合は、許可ホストの設定を確認してください。
  </Step>
</Steps>

***

## それでも解決しない場合

`onesight-support@onecheck.co.kr` までお問い合わせください。
**下記の情報を添えていただくと、はるかに早く確認できます。**

| 項目         | 例                             |
| ---------- | ----------------------------- |
| 症状         | 「点は見えるが、常に右へ 2 m ずれている」       |
| 現場         | 建物・フロア名、空間の実測サイズ              |
| アンカー座標     | 「配置済み」リストの画面キャプチャ             |
| コンソールの接続状態 | 設定 → Geospace 連携カードのバッジのキャプチャ |
| テスト端末      | iPhone 15 Pro / iOS 27.1      |
| アプリ画面      | 位置の点が見える（または見えない）画面のキャプチャ     |