ZeroKeyざっくりAPI解説

第1章：はじめに
第2章：ZeroKey ECDへの接続方法：Edge vs Cloud
第3章：ZeroKey APIの基本：SignalRベースのEvent Hub system
第4章：位置情報の理解：リアルタイムアップデート、位置情報、位置情報フラグ
まとめ
- 関連リソース

第1章：はじめに

ZeroKey屋内位置測位システムとは

近年、工場や倉庫、オフィスといった様々な屋内環境において、人やモノ、ロボットなどの正確な位置情報を把握することの重要性が増しています。これは、作業効率の向上、安全性の確保、資産管理の最適化など、多くのメリットをもたらすためです。

屋外であればGPSが広く利用されていますが、GPSの信号は屋内の奥深くまで届きにくいため、屋内での精密な位置測位には別の技術が必要となります。ここで登場するのが、ZeroKeyが提供する高精度屋内位置測位システムです。

ZeroKeyのシステムは、独自の超音波技術を利用して、ミリメートルレベルという非常に高い精度で3次元（X, Y, Z）の位置情報をリアルタイムに提供することを特徴としています。従来の屋内位置測位技術（Wi-Fi、Bluetooth、UWB、RFIDなど）と比較しても、その精度と3Dでの測位能力において大きな優位性を持っています。この高い精度により、これまでは難しかった緻密な位置ベースのアプリケーションや、自動化システムの高度な制御が可能になります。

なぜAPI連携が必要なのか

ZeroKeyシステム自体は、屋内の正確な位置情報を提供する優れた基盤ですが、その真価を発揮するためには、他のシステムやアプリケーションとの連携が不可欠です。取得した高精度な位置情報を単に見るだけでなく、それを活用して何かを実行に移すことで、初めてビジネスやオペレーションの課題解決につながります。

例えば、

製造実行システム（MES）と連携し、作業者の位置に基づいたタスクの自動割り当てや進捗管理を行う。
AGV（無人搬送車）やAMR（自律移動ロボット）のナビゲーションシステムに正確な自己位置情報を提供する。
従業員や来訪者の位置情報を基にした安全エリアの監視や、危険エリアへの立ち入りの警告システムを構築する。
倉庫内の在庫品の位置をリアルタイムに追跡し、ピッキング作業の効率化を図る。

このように、ZeroKeyシステムから得られる位置情報を様々な外部システムと連携させることで、単なる「位置の見える化」を超えた、より高度な自動化、最適化、安全管理などが実現可能になります。そして、このシステム連携の鍵となるのが、ZeroKeyが提供するAPI（Application Programming Interface）なのです。

本ブログで解説すること

本ブログでは、ZeroKeyシステムを活用したシステム開発や連携を検討されている方を対象に、ZeroKeyのAPIを利用する上で特に重要となる以下の3つの要素に焦点を当てて解説を進めます。

ZeroKey ECDへの接続方法：Edge vs Cloud
ZeroKey APIの基本：SignalRベースのEvent Hub systemの利用
位置情報の理解：リアルタイムアップデート、位置情報のアップデート、位置情報フラグ

これらの情報は、ZeroKeyのシステムと外部システムを連携させる上で基礎となる部分ですが、**私自身がZeroKeyについて色々と調べ始めた際に、これらの核心的な情報になかなか手軽にアクセスできず、体系的に理解するのに苦労した経験があります。私と同じように、「ZeroKeyのAPIを使ってみたいけれど、どこから手をつければいいのか」「どうやって位置情報を取得・解釈すればいいのか」と困っている方、手っ取り早く全体像を把握したいと思っている方のために、**私の調査と理解を基に、要点をまとめて分かりやすく解説することを目指します。

本ブログが、ZeroKeyシステムを活用した素晴らしいアプリケーションやソリューション開発の一助となれば幸いです。次章からは、早速ZeroKey ECDへの接続方法について詳しく見ていきましょう。

第2章：ZeroKey ECDへの接続方法：Edge vs Cloud

ZeroKeyシステムから高精度な位置情報を取得し、外部システムと連携するためには、まずZeroKeyシステムの中心的なコンポーネントであるZeroKey ECD（Edge Computing Device）に接続する必要があります。このECDは、ZeroKeyのアンカー（超音波を発信する基準局）やタグ（位置を測位したい対象に取り付けるデバイス）といったハードウェアと連携し、生データから位置情報を計算、集約する役割を担います。

ZeroKey ECDへの接続方法には、主に「Edge接続」と「Cloud接続」の二種類があります。それぞれに特徴があり、実現したいシステム構成や運用要件によって適切な方法を選択する必要があります。

ZeroKey ECD (Edge Computing Device) の役割

ZeroKey ECDは、ZeroKeyシステムの核となる部分です。多数設置されたアンカーからの信号や、タグから送られてくる情報を受け取り、これらのデータをもとにタグの正確な3次元位置を計算します。計算された位置情報はECD内部で集約・処理され、APIを通じて外部に提供可能な状態になります。つまり、ECDはZeroKeyシステムが生み出す「位置情報」というデータを管理・配信するゲートウェイとしての役割を果たします。

Edge接続の概要、メリット・デメリット

Edge接続とは、文字通りネットワークの「エッジ」、つまり位置情報が発生する現場に近い場所で、外部システムがZeroKey ECDに直接、あるいはローカルネットワーク経由で接続する方法です。

概要:

外部システム（アプリケーションサーバー、ローカルPCなど）が、同一ネットワーク内にあるZeroKey ECDに直接IPアドレスやホスト名指定で接続します。
データのやり取りは基本的にローカルネットワーク内で完結します。

メリット:

低遅延: 位置情報がECDで計算され次第、直接外部システムに配信されるため、データの伝送経路が短く、遅延を最小限に抑えることができます。リアルタイム性が非常に重視されるアプリケーション（ロボット制御、衝突防止システムなど）には大きな利点です。
安定性: インターネット回線の状態に依存しないため、外部のネットワーク障害の影響を受けにくく、安定した通信が可能です。
セキュリティ: 位置情報データがローカルネットワークから外に出ないため、情報漏洩のリスクを低減できます。機密性の高い情報を扱うシステムに適しています。
帯域幅の節約: 大量の位置情報データを常にクラウドに送信する必要がないため、インターネット回線の帯域幅を節約できます。

デメリット:

リモートアクセスへの制約: 外部から直接ECDの状態監視やデータ取得を行うのが難しくなる場合があります。リモートでのシステム管理や複数拠点の一元管理には工夫が必要です。
ネットワーク設定の複雑さ: 外部システムとECD間のローカルネットワーク設定やファイアウォールの構成が必要になる場合があります。
インフラの管理: 接続する外部システムやECDが動作するローカルインフラ（サーバー、ネットワーク機器など）の管理が必要になります。

Cloud接続の概要、メリット・デメリット

Cloud接続とは、ZeroKey ECDが計算した位置情報を一度クラウド上のZeroKeyが提供するサービス（Spatial Intelligence Platform: SIPなど）に送信し、外部システムはそのクラウドサービスに接続して位置情報を取得する方法です。

概要:

ZeroKey ECDはインターネット経由でZeroKeyのクラウドサービスに接続し、位置情報データをアップロードします。
外部システムはインターネット経由でZeroKeyのクラウドサービスに接続し、APIを利用して位置情報データを取得します。

メリット:

容易なリモートアクセス: インターネットに接続されていれば、どこからでもZeroKeyシステムの状態監視やデータアクセスが可能です。複数拠点に設置されたシステムのデータを一元管理するのに適しています。
スケーラビリティ: クラウドサービスがデータ処理や負荷分散を担うため、システム規模の拡張が比較的容易です。
管理の簡素化: ECDや外部システムが直接インターネットに公開されるわけではないため、個別のネットワークセキュリティ設定の複雑さを軽減できる場合があります。ZeroKey側で提供される管理機能を利用できる可能性があります。
クラウド連携の容易さ: 他のクラウドサービス（データ分析プラットフォーム、ストレージサービスなど）との連携がスムーズに行えます。

デメリット:

遅延の増加: 位置情報がECDからクラウドを経由して外部システムに配信されるため、Edge接続と比較するとデータ伝送に時間がかかり、遅延が増加する可能性があります。リアルタイム性が非常に要求される用途には注意が必要です。
インターネット依存: ECDとクラウドサービス、および外部システムとクラウドサービスの間のインターネット接続が必須となります。インターネット回線の状態や障害がシステム運用に影響を与えます。
セキュリティに関する考慮: 位置情報データがインターネット上を通過するため、適切な暗号化や認証などのセキュリティ対策がより重要になります。
帯域幅の消費: 常に位置情報データをクラウドにアップロードする必要があるため、インターネット回線の帯域幅を継続的に消費します。

どちらの接続方法を選ぶべきか（ユースケースに応じた考察）

Edge接続とCloud接続のどちらを選択するかは、ZeroKeyシステムを導入する具体的なユースケースと要件によって判断する必要があります。

リアルタイム性が最重要、かつシステムがローカルで完結する場合
ロボットの精密制御、人と機械の衝突防止、高速な追跡が求められる製造ラインなど、ミリ秒単位の遅延も許されないようなアプリケーションでは、Edge接続が有利です。データがローカルネットワーク内で完結するため、外部への情報漏洩リスクを最小限にしたい場合にも適しています。
複数拠点の一元管理、リモートアクセス、スケーラビリティが重要な場合
広範囲にわたる施設や複数の拠点のZeroKeyシステムをまとめて管理したい場合、あるいはオフィスなどから現場の状況を遠隔で監視・分析したい場合には、Cloud接続が適しています。大量のデータをクラウド上で処理・分析したい場合にも拡張性のメリットがあります。
インターネット接続の安定性
導入環境のインターネット接続が不安定な場合は、Edge接続の方がシステムの安定稼働には有利と言えます。

多くの場合、両方の接続方法を組み合わせたハイブリッドな構成も考えられます。例えば、リアルタイム性が求められる制御系システムはEdge接続を利用しつつ、データの長期保存や分析、リモート監視のためにはCloud接続も併用するといった構成です。

ZeroKeyのAPIは、これらの接続方法に対応した形で提供されています。次章では、このAPIの基本的な仕組み、特にSignalRベースのEvent Hub systemの利用について詳しく見ていきます。

第3章：ZeroKey APIの基本：SignalRベースのEvent Hub system

ZeroKeyシステムから位置情報を取得し、外部システムと連携するための主要な手段がZeroKey APIです。このAPIは、リアルタイムなデータ配信に特化した技術であるSignalRを基盤としたEvent Hub systemを利用しています。

ZeroKey APIのアーキテクチャ概要

ZeroKey APIは、ZeroKey ECDまたはクラウド上のSIP（Spatial Intelligence Platform）から、クライアント（外部連携システムやアプリケーション）に対して効率的にデータを配信するために設計されています。

項目	概要
基盤技術	SignalR
データ配信モデル	Event Hub System (イベント駆動型)
主な接続先	ZeroKey ECD (Edge接続) または ZeroKey SIP (Cloud接続)
取得可能な情報	位置情報のリアルタイムアップデート、位置情報（3D座標）、位置情報フラグなど

SignalRとは？なぜZeroKeyで使われるのか

SignalRは、Microsoftが開発した、Webアプリケーションにリアルタイムな双方向通信機能を追加するためのオープンソースライブラリです。サーバーとクライアント間でのプッシュ通信（サーバーからクライアントへ能動的にデータを送信する仕組み）を容易に実現します。

特徴	ZeroKey APIでのメリット
リアルタイム通信	ZeroKeyシステムで測位された最新の位置情報を、発生次第すぐに外部システムへプッシュ通知できる。
双方向通信	クライアントからAPIに対してリクエストを送信することも可能。（例：アンカー座標の取得など）
接続管理	クライアントとの接続維持や管理を効率的に行う機能が提供されている。
多様なトランスポート	WebSocket, Server-Sent Events, Long Pollingなど、環境に応じた最適な通信方式を自動選択する。

ZeroKeyシステムのように、常に変化する位置情報をリアルタイムかつ効率的に多数のクライアントに配信する必要がある用途において、SignalRは非常に適した技術と言えます。

Event Hub systemによるデータ配信の仕組み

ZeroKey APIは、SignalRの上に構築されたEvent Hub systemとして機能します。これは、特定のできごと（イベント）、例えば新しい位置情報が測位されたこと、が発生した際に、そのイベントに関連するデータを購読しているクライアントにまとめて通知する仕組みです。

コンポーネント	役割
イベントソース	ZeroKeyシステム（アンカー、タグ、ECD/SIP） – 位置情報などのイベントを発生させる源。
Event Hub	イベントを集約し、購読者（クライアント）に分配する中心的なハブ。SignalRの機能を活用していると考えられます。
購読者（クライアント）	ZeroKey APIに接続し、特定種類のイベント（例：特定のタグの位置情報アップデート）を購読登録した外部システムやアプリケーション。
イベントデータ	イベント発生時に配信される情報本体。（例：タグID、X/Y/Z座標、タイムスタンプ、位置情報フラグなど）

このEvent Hub systemにより、クライアントはポーリング（定期的な問い合わせ）を行うことなく、必要な位置情報データが発生したタイミングでリアルタイムに受け取ることができます。これにより、システム全体の効率が向上し、より即応性の高いアプリケーションを構築することが可能になります。

次章では、このAPIから実際に取得できる位置情報データ、具体的にはリアルタイムアップデートされる「位置情報」とその状態を示す「位置情報フラグ」について、その内容と活用方法を詳しく解説します。

第4章：位置情報の理解：リアルタイムアップデート、位置情報、位置情報フラグ

ZeroKey APIのEvent Hub systemを通じて配信される最も重要なデータは、言うまでもなく「位置情報」です。しかし、この位置情報データを効果的に活用するためには、「リアルタイムアップデート」の意味するところ、そしてデータに含まれる「位置情報」そのものの内容、「位置情報フラグ」が示す状態を正しく理解することが不可欠です。

リアルタイム位置情報アップデートとは

ZeroKeyシステムにおける「リアルタイム位置情報アップデート」とは、ZeroKeyタグの最新の位置が測位されるたびに、その情報がAPIクライアントに対してほぼ即座にプッシュ配信されることを指します。これは、クライアント側から定期的に「今の位置は？」と問い合わせるポーリング方式とは異なり、データが発生したイベントをトリガーとして能動的に情報が送られてくるイベント駆動型の仕組みです。

このリアルタイム性により、以下のような高度なアプリケーションが可能になります。

即時的な追跡
移動するオブジェクト（ロボット、AGV、作業者など）の軌跡を滑らかに、遅延なく描画する。
リアルタイムなトリガー
特定のエリアへの出入りや、他のオブジェクトとの接近といったイベント発生時に、遅延なく後続処理（警告、制御コマンドの発行など）を実行する。
高頻度なデータ取得
設定によっては高い頻度で位置情報のアップデートを受け取れるため、ロボット制御のような高速なフィードバックループが必要な用途にも対応できます。

リアルタイムアップデートは、特にダイナミックに変化する現場の状況を把握し、それに基づいて即応的なアクションを求められる場合にZeroKeyシステムの強みを最大限に引き出します。

「位置情報」が含むデータ要素

ZeroKey APIから配信される位置情報データは、単なる座標値だけでなく、その情報が付帯する様々な要素を含んでいます。正確なデータ構造はAPIのバージョンや設定によって異なる場合がありますが、一般的には以下のような情報が含まれます。

データ要素	説明	例	補足
Tag ID	位置情報がどのタグ（対象物）のものかを示す一意な識別子。	`tag_001`, `AGV_A`	システム設定によって任意のIDが付与されます。
Timestamp	その位置情報がいつ測位されたかを示すタイムスタンプ。正確な時刻管理に重要。	`2023-10-27T10:30:00.123Z`	通常は高精度なタイムスタンプが含まれます。
Position (X, Y, Z)	タグの3次元空間における座標値。ZeroKeyの最大の強みの一つです。	`{"x": 1.234, "y": 5.678, "z": 0.901}`	システム原点からの相対座標や、グローバル座標として定義されます。単位はメートルなど。
Orientation	タグの姿勢や向きを示す情報。（システム設定による）	`{"pitch": 10.5, "roll": 2.1, "yaw": 90.0}`	傾きや回転の情報が含まれる場合があります。
Velocity	タグの移動速度や方向を示す情報。（システム設定による）	`{"vx": 0.1, "vy": -0.5, "vz": 0.0}`	一部のシステムや設定で利用可能。
Position Flags	その位置情報データの状態や品質、種類などを示すフラグ。（後述）	`["Valid", "3D"]`	重要な要素であり、別途詳細を理解する必要があります。
Accuracy	測位された位置情報の推定精度。（システム設定による）	`{"position": 0.005}`	ミリメートル単位の精度情報が含まれることがあります。
System ID	複数のZeroKeyシステムを運用している場合に、どのシステムからの情報かを示すID。	`site_A`, `factory_02`	大規模な導入で役立ちます。

これらの要素を組み合わせることで、単に「どこにいるか」だけでなく、「いつ、どこで、どのような状態（精度、姿勢など）でその位置にいたか」という、よりリッチな情報を取得・活用できます。

「位置情報フラグ」の役割と種類

位置情報フラグは、配信された位置情報データがどのような状態であるかを示す非常に重要なメタ情報です。このフラグを確認することで、その位置情報データが信頼できるものか、どのような種類のデータなのかを判断し、アプリケーション側で適切な処理を行うことができます。

フラグの例	説明	活用例
`Valid`	位置情報が正常に測位され、有効なデータであることを示します。	このフラグがないデータは処理対象から外す、または低精度なデータとして扱う。
`Invalid`	位置情報が正常に測位できなかったことを示します。	対象オブジェクトが測位エリア外に出た、障害物で信号が遮られたなどの状態を検知する。
`2D`	2次元（X, Y）の位置情報のみが測位されたことを示します。（限定的な場合）	高さを考慮しないアプリケーションでのみ利用する、または高さ情報が必要な場合は警告を出す。
`3D`	3次元（X, Y, Z）の位置情報が測位されたことを示します。	3D空間での正確な追跡やナビゲーションが必要なアプリケーションで、このフラグを確認してデータを利用する。
`Initialized`	システムが初期化された直後など、位置情報が確定した状態であることを示します。	システム起動時や復旧時に、位置情報の利用開始の合図として使用する。
`Calibrating`	システムがキャリブレーション中であるため、位置情報が不安定または利用不可であることを示します。	このフラグがある間は位置情報データの利用を一時停止する、またはユーザーインターフェース上でキャリブレーション中であることを表示する。
`Kinematic`	タグが動いている状態での位置情報であることを示します。	静止時と移動時で異なる処理を行う場合に利用する。
`Static`	タグが静止している状態での位置情報であることを示します。（推定）	静止しているオブジェクトの最終位置を確定させる、または長期間静止している状態を検知する。
`LowAccuracy`	測位精度が通常よりも低いことを示します。（システム設定による）	このフラグがあるデータは、より緩やかな制御にのみ利用する、またはユーザーに注意喚起を行う。

位置情報フラグは、単に位置座標を見るだけでは分からないデータの「質」や「状態」を判断するための重要な情報源です。これらのフラグを適切に処理することで、アプリケーションの堅牢性や信頼性を向上させることができます。

これらの情報を活用する方法

取得したリアルタイムの位置情報、そのデータ要素、そして位置情報フラグを組み合わせることで、ZeroKeyシステムの能力を最大限に引き出す様々なアプリケーションを構築できます。

リアルタイムモニタリング
地図上や3D空間にタグの位置をリアルタイムに表示し、現在の状況を正確に把握する。位置情報フラグ（例: Valid, 3D）を確認しながら表示を更新する。

自動化と制御
タグの位置情報（X, Y, Z座標）と姿勢情報（Orientation）を基に、ロボットやAGVを精密に制御する。位置情報フラグ（例: Valid, Kinematic）を確認して、制御コマンドを発行するかの判断材料とする。

エリア管理とジオフェンシング
事前に定義したエリアに対するタグの出入りを、位置情報とリアルタイムアップデートを利用して検知する。特定のエリアへの立ち入りを検知した場合に、セキュリティシステムと連携して警告を発する。

データの分析と最適化
取得した位置情報データ（Position, Timestamp）を蓄積し、タグの移動履歴、滞留時間、非効率な経路などを分析する。位置情報フラグ（例: Valid, Invalid）を用いて、分析対象とするデータのフィルタリングを行う。

安全管理
人と機械の位置情報をリアルタイムに監視し、危険な距離に接近した場合に警告を発したり、機械を停止させたりする。位置情報フラグ（例: Valid）を確認して、正確な位置情報に基づいた判断を行う。

ZeroKey APIから提供されるこれらの情報を、構築したいシステムの要件に合わせて適切に取捨選択し、活用することで、高精度な屋内位置測位システムがもたらす恩恵を最大限に享受することができます。

まとめ

本ブログでは、ZeroKeyの高精度屋内位置測位システムと外部システムを連携させるための鍵となるAPIに焦点を当て、以下の3つの重要なポイントについて解説しました。

ZeroKey ECDへの接続方法：Edge vs Cloud: リアルタイム性やセキュリティを重視するEdge接続と、リモート管理やスケーラビリティに優れるCloud接続、それぞれの特徴とユースケースについて理解しました。
ZeroKey APIの基本：SignalRベースのEvent Hub system: ZeroKey APIがSignalRを活用したイベント駆動型のシステムであり、リアルタイムな位置情報アップデートが効率的に配信される仕組みを確認しました。
位置情報の理解：リアルタイムアップデート、位置情報、位置情報フラグ: APIから取得できる位置情報データが単なる座標だけでなく、タイムスタンプや様々な状態を示すフラグを含んでいること、そしてそれらを活用することの重要性を学びました。

これらの知識は、ZeroKeyシステムが生み出す高精度な位置情報を、皆様が開発される独自のシステムやアプリケーションに組み込み、活用するための土台となります。ZeroKey APIを介した連携により、製造現場の自動化、倉庫の最適化、作業者の安全管理、ロボットの精密制御など、これまで屋内の位置情報活用における精度やリアルタイム性の壁によって実現が難しかった多くのことが可能になります。