Marvelmind API

この章を読みやすいHTMLページで表示します。

この章（PDF）（127〜213ページ） ↗

「インターフェースとプロトコル」の「Marvelmind API」の章を、HTMLページとして再現したものです。不明な点がありましたら、次を開いてください：この章だけの元のPDF（127〜213ページ）（左上にも固定表示）。目次：全章。

APIとの接続を確認する

サンプルソフトウェアを実行したら、ターミナルで「スペース」キーを押し、コマンド「version」を入力してEnterキーを押します。サンプルソフトウェアがAPIのバージョンを表示すれば、APIライブラリと通信できています。

mm_api_version

Marvelmind APIライブラリの説明

APIは、MS Windows用のダイナミックリンクライブラリ（DLL）と、Linux（x86およびARMプラットフォーム）用の共有ライブラリとして提供されます。ライブラリには、コンピューターのUSBポートに接続したモデムを介してMarvelmindシステムを監視・制御するための関数一式が含まれています。このセクションでは、これらすべての関数について説明します。

さまざまなプログラミング言語との互換性を高めるため、複雑なデータ構造の大半は、型なしのメモリポインタを介して受け渡されます。関数の説明には、メモリプール内の各データフィールドのオフセットが記載されています。サンプルソフトウェアのファイル「marvelmind_api.c」で、メモリプールとC構造体のフィールドの間でデータを移す実装を確認できます。

説明中のパラメータの型はC言語の構文で示しています。各型の説明は次のとおりです：

型

サイズ（バイト）

説明

bool

1

ブール型。0はfalse、0以外はtrueを意味します

uint8_t

1

符号なし整数値、0…255

int8_t

1

2の補数形式の符号付き整数値、-128…127

uint16_t

2

符号なし整数値、0…65535

int16_t

2

2の補数形式の符号付き整数値、-32768…32767

uint32_t

4

符号なし整数値、0…4294967295

int32_t

4

2の補数形式の符号付き整数値、

-2147483648…2147483647

void *

4/8

メモリポインタ（メモリ上のアドレス）。

32ビットプラットフォームでは4バイト、64ビットプラットフォームでは8バイト。

各関数の説明には、その関数を使用できるAPIバージョンが記載されています。新しいAPIバージョンでは、Marvelmindシステムの新機能に対応する関数が追加されます。現時点では、Dashboardで使用できるすべての機能がAPIで使用できるわけではありません。さらにAPI関数が必要な場合は、次までお問い合わせください：info@marvelmind.com。

対応している関数の一覧：

関数

API

バージョン

必要なライセンス

Marvelmind APIライブラリのバージョンを取得

V1+

なし

最後のエラーを取得

V6+

なし

シリアルポートのオープンを試行

V1+

なし

指定した名前でシリアルポートのオープンを試行

V2+

なし

UDPポートのオープンを試行

V9+

なし

シリアルポートを閉じる

V1+

なし

MarvelmindデバイスのバージョンとCPU IDを取得

V1+

なし

デバイスリストを取得

V1+

なし

デバイスをウェイクアップ

V1+

なし

デバイスをスリープさせる

V1+

なし

ビーコンからテレメトリーデータを取得

V1+

なし

最新の位置データを取得

V1+

なし

最新の位置データを取得（角度付き）

V3+

なし

ビーコンの位置を設定

V3+

MMSW0005

ビーコン間の距離を設定

V4+

MMSW0005

最新の生の距離データを取得

V1+

なし

モバイルビーコンの高さを取得

V4+

なし

モバイルビーコンの高さを設定

V4+

MMSW0005

サブマップ内の固定ビーコンの高さを取得

V4+

なし

サブマップ内の固定ビーコンの高さを設定

V4+

MMSW0005

位置更新レートの設定を取得

V1+

なし

位置更新レートを設定

V1+

MMSW0005

サブマップを追加

V1+

MMSW0005

サブマップを削除

V1+

MMSW0005

サブマップを固定

V1+

MMSW0005

サブマップの固定を解除

V1+

MMSW0005

サブマップの設定を取得

V1+

なし

サブマップの設定を変更

V1+

MMSW0005

マップを固定

V4+

MMSW0005

マップの固定を解除

V4+

MMSW0005

ビーコンの超音波設定を取得

V1+

なし

ビーコンの超音波設定を変更

V1+

MMSW0005

Erase map

V1+

MMSW0005

デバイスをデフォルト設定にリセット

V1+

MMSW0005

ビーコンを座標軸に関連付け

V2+

MMSW0005

モデムの設定メモリダンプを読み出し

V3+

MMSW0005

モデムの設定メモリダンプを書き込み

V3+

MMSW0005

モデムから気温の設定を取得

V3+

なし

モデムに気温を設定

V3+

なし

デバイスのソフトウェアリセット

V3+

なし

ビーコンのReal-time Player設定を取得

V6+

なし

ビーコンのReal-time Player設定を変更

V6+

MMSW0005

ジオリファレンス設定を取得

V6+

なし

ジオリファレンス設定を変更

V6+

MMSW0005

位置の更新モードを取得

V6+

なし

位置の更新モードを設定

V6+

MMSW0005

位置を更新するコマンド

V6+

MMSW0005

ビーコンのジオフェンスアラーム状態を設定

V9+

MMSW0005

MMSW0006

汎用ユーザーペイロードデータを送信

V9+

MMSW0005

汎用ユーザーペイロードデータを取得

V9+

MMSW0005

手動距離測定のコマンドを送信

V9+

MMSW0011

モデムからストリーミングデータを取得

V9+

なし

デバイスタイプがモデムかどうかを確認

V1+

なし

デバイスタイプが固定ビーコンかどうかを確認

V1+

なし

デバイスタイプがモバイルビーコンかどうかを確認

V1+

なし

Marvelmind APIライブラリのバージョンを取得

APIライブラリのバージョンを読み出します。必要な関数がこのバージョンのライブラリで使用できるかを確認するために必要です。

関数名： mm_api_version

C言語での宣言：bool mm_api_version(void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造。

型

説明

uint32_t

APIライブラリのバージョン

最後のエラーを取得

エラーの原因を区別するため、APIライブラリで最後に行った操作のステータスを読み出します。

関数名： mm_get_last_error

C言語での宣言：bool mm_get_last_error(void *pdata);

対応APIバージョン：V6+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造。

型

説明

uint32_t

最後の操作のステータス：

0：操作が正常に実行されました

1：通信エラー

2：シリアルポートを開く際のエラー

3：ライセンスが必要です

シリアルポートを開く

Marvelmindデバイス（モデムまたはビーコン）がUSB（仮想シリアルポート）で接続されているポートを開きます。APIがすべてのシリアルポートを検索し、Marvelmindデバイスに対応するかどうかを確認するため、シリアルポート名を指定する必要はありません。

関数名： mm_open_port

C言語での宣言：bool mm_open_port ();

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、ポートが開かれました

false – 実行中にエラーが発生しました

パラメータ：なし

指定した名前のシリアルポートを開く

Marvelmindデバイス（モデムまたはビーコン）がUSB（仮想シリアルポート）で接続されているポートを開きます。この関数は、指定した名前のポートを開こうとします。

関数名： mm_open_port_by_name

C言語での宣言：bool mm_open_port_by_name(void *pdata);

対応APIバージョン：V2+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、ポートが開かれました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

シリアルポート名へのポインタ – ゼロ終端のASCII文字列（ASCIIZ）

UDPポートを開く

USBの代わりにUDPでSuper-Modemとの通信を確立できます。

関数名： mm_open_port_udp

C言語での宣言：bool mm_open_port_udp(void *pdata);

対応APIバージョン：V9+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、UDPポートが開かれました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

UDP設定の構造体へのポインタ（下記参照）

ポインタが指すデータの構造：

型

説明

uint16_t

接続先のUDPポート

uint16_t

通信のタイムアウト、ms

uint16_t

予約済み

最大255バイト

IPアドレス – ゼロ終端のASCII文字列（ASCIIZ）

IPアドレスとUDPポートは、Super-Modemの設定と一致させる必要があります（下のスクリーンショットを参照）。

インターフェースとプロトコル、Marvelmind API：図1

シリアルポートを閉じる

ポートを閉じます（以前に mm_open_port 関数で開かれていた場合）。

関数名： mm_close_port

C言語での宣言：bool mm_close_port ();

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、ポートが閉じられました

false – 実行中にエラーが発生しました

パラメータ：なし

MarvelmindデバイスのバージョンとCPU IDを取得

バージョンとCPU IDを読み出します。バージョンには、ファームウェアのバージョンとデバイスのハードウェアの種類に関する情報が含まれます。CPU IDは、デバイス個体ごとの固有IDです。

関数名： mm_get_device_version_and_id

C言語での宣言：bool mm_get_device_version_and_id (uint8_t address, void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、バージョンとCPU IDのデータが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

Marvelmindデバイスのアドレス（1…254）

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint8_t

ファームウェアのメジャーバージョン（例：バージョンV6.07aの場合は「6」）

uint8_t

ファームウェアのマイナーバージョン（例：バージョンV6.07aの場合は「7」）

uint8_t

ファームウェアの第2マイナーバージョン（例：バージョンV6.07aの場合は「1」）

uint8_t

デバイスタイプID (詳細は付録).

uint8_t

ファームウェアオプション（未定）。

uint32_t

CPU ID。この値を16進数で表示すると、Dashboardやデバイスのステッカーに記載されている形式のCPU IDになります。

デバイスリストを取得

モデムが認識しているMarvelmindデバイスのリストを読み出します。このリストには、スリープ中のデバイスを含め、モデムのネットワークに無線で接続されているすべてのデバイスが含まれます。

関数名： mm_get_devices_list

C言語での宣言：bool mm_get_devices_list (void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、デバイスリストが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint8_t

リスト内で後に続くデバイスの数（N）

N*9バイト

N個のデバイス構造体の並び（次の表で説明）

リスト内の各デバイスの構造：

型

説明

uint8_t

デバイスのアドレス

bool

true = アドレス重複 – 同じアドレスのデバイスが2台以上見つかりました

false = アドレス重複なし

bool

true = デバイスはスリープ中

false = デバイスはスリープしていない

uint8_t

ファームウェアのメジャーバージョン（例：バージョンV6.07aの場合は「6」）

uint8_t

ファームウェアのマイナーバージョン（例：バージョンV6.07aの場合は「7」）

uint8_t

ファームウェアの第2マイナーバージョン（例：バージョンV6.07aの場合は「1」）

uint8_t

デバイスタイプID (詳細は付録).

uint8_t

ファームウェアオプション（未定）。

uint8_t

フラグ：

ビット0：1 – デバイスの接続完了 – デバイスが接続を確認済み

0 – デバイスからの確認待ち（Dashboardの「Connecting…」に相当）。

ビット1…7 – 未定

デバイスをウェイクアップ

指定したデバイスにウェイクアップコマンドを送信します。ウェイクアップコマンドが送信され、該当するデバイスが存在する場合、そのデバイスは数秒でモデムに接続し、次に表示されるようになります：デバイスリスト。

関数名： mm_wake_device

C言語での宣言：bool mm_wake_device (uint8_t address);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、ウェイクアップコマンドが送信されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

1…254 – ウェイクアップするMarvelmindデバイスのアドレス

0 – すべてのデバイスをウェイクアップ

デバイスをスリープさせる

既存のデバイスをスリープさせます。

関数名： mm_send_to_sleep_device

C言語での宣言：bool mm_send_to_sleep_device (uint8_t address);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、スリープコマンドが送信されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

1…254 – スリープさせるMarvelmindデバイスのアドレス

0 – すべてのデバイスをスリープさせる

ビーコンからテレメトリーデータを取得

Marvelmindビーコンのテレメトリーデータを読み出します。

関数名： mm_get_beacon_telemetry

C言語での宣言：bool mm_get_beacon_telemetry (uint8_t address, void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、テレメトリーが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

Marvelmindビーコンのアドレス（1…254）

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint32_t

ビーコンの稼働時間、秒（リセットまたはウェイクアップからの時間）。

int8_t

RSSI、dBm – 無線信号強度

int8_t

測定温度、°C

uint16_t

電源電圧、mV

16バイト

予約済み（0）

最新の位置データを取得

モデムから最新の座標パックを読み出します。ユーザーペイロードデータがある場合は、それも読み出します。

関数名： mm_get_last_locations

C言語での宣言：bool mm_get_last_locations(void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、位置データが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

18*6バイト

最後に更新された座標を表す18バイトのデータ構造6個（下表を参照）

bool

true – 新しい生の距離データを読み出せます

5バイト

未定

uint8_t

ユーザーペイロードデータのサイズ（M）

Mバイト

ユーザーペイロードデータ

各位置データ項目の構造：

型

説明

uint8_t

デバイスのアドレス（1…254）

0 – このデータ項目は未設定

uint8_t

ヘッドインデックス（未定）

int32_t

X座標、mm

int32_t

Y座標、mm

int32_t

Z座標、mm

uint8_t

ステータスフラグ（未定）

uint8_t

測位品質、0…100%

uint8_t

未定

uint8_t

未定

最新の位置データを取得（角度付き）

モデムから最新の座標パックを読み出します（ペアードビーコンの場合は角度付き）。ユーザーペイロードデータがある場合は、それも読み出します。

関数名： mm_get_last_locations2

C言語での宣言：bool mm_get_last_locations2(void *pdata);

対応APIバージョン：V3+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、位置データが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

20*6バイト

最後に更新された座標を表す20バイトのデータ構造6個（下表を参照）

bool

true – 新しい生の距離データを読み出せます

5バイト

未定

uint8_t

ユーザーペイロードデータのサイズ（M）

Mバイト

ユーザーペイロードデータ

各位置データ項目の構造：

型

説明

uint8_t

デバイスのアドレス（1…254）

0 – このデータ項目は未設定

uint8_t

ヘッドインデックス（未定）

int32_t

X座標、mm

int32_t

Y座標、mm

int32_t

Z座標、mm

uint8_t

ステータスフラグ（未定）

uint8_t

測位品質、0…100%

uint8_t

未定

uint8_t

未定

uint16_t

ビット0…11 – 回転角、0.1度単位（ペアードビーコン機能が有効な場合）

ビット12 – 1 = 角度は利用できません

ビット13…15 – 予約

ビーコンの位置を設定

指定したビーコンの位置を手動で設定します。

関数名： mm_set_beacon_location

C言語での宣言：bool mm_set_beacon_location (uint8_t address, void *pdata);

対応APIバージョン：V3+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、位置が更新されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

ビーコンのアドレス

void *

位置データを格納したバッファへのポインタ

ポインタが指すデータの構造（関数呼び出し前に設定しておく必要があります）：

型

説明

int32_t

ビーコンの新しいX座標、mm

int32_t

ビーコンの新しいY座標、mm

int32_t

ビーコンの新しいZ座標、mm

ビーコン間の距離を設定

ビーコン間の距離を手動で設定します。

関数名： mm_set_beacons_distance

C言語での宣言：bool mm_set_beacons_distance (void *pdata);

対応APIバージョン：V4+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、距離が書き込まれました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

距離データを格納したバッファへのポインタ

ポインタが指すデータの構造（関数呼び出し前に設定しておく必要があります）：

型

説明

uint8_t

1番目のビーコンのアドレス

uint8_t

2番目のビーコンのアドレス

int32_t

ビーコン間の距離、mm

最新の生の距離データを取得

モデムから最新の生の距離データパックを読み出します。

関数名： mm_get_last_distances

C言語での宣言：bool mm_get_last_distances(void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、生の距離データが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint8_t

生の距離データ項目の数（N）。

1回のリクエストで取得できる生の距離の最大数は16です：N<=16

9*Nバイト

最新の生の距離を表す9バイトのデータ構造N個（下表を参照）

各生の距離データ項目の構造：

型

説明

uint8_t

超音波受信（RX）デバイスのアドレス（1…254）

0 – このデータ項目は未設定

uint8_t

RXヘッドインデックス（未定）

uint8_t

超音波送信（TX）デバイスのアドレス（1…254）

0 – このデータ項目は未設定

uint8_t

TXヘッドインデックス（未定）

uint32_t

TXデバイスからRXデバイスまでの距離、mm

uint8_t

未定

モバイルビーコンの高さを取得

モバイルビーコン（hedgehog）の高さを返します。

関数名： mm_get_hedge_height

C言語での宣言：bool mm_get_hedge_height (uint8_t address, void *pdata);

対応APIバージョン：V4+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、高さが返されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

モバイルビーコンのアドレス

void *

高さデータを格納するバッファへのポインタ

ポインタが指すデータの構造：

型

説明

int32_t

モバイルビーコンの高さ、mm

モバイルビーコンの高さを設定

モバイルビーコン（hedgehog）の高さを設定します。

関数名： mm_set_hedge_height

C言語での宣言：bool mm_set_hedge_height (uint8_t address, void *pdata);

対応APIバージョン：V4+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、高さが変更されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

モバイルビーコンのアドレス

void *

高さデータを格納するバッファへのポインタ

ポインタが指すデータの構造（関数呼び出し前に設定しておく必要があります）：

型

説明

int32_t

モバイルビーコンの高さ、mm

サブマップ内の固定ビーコンの高さを取得

サブマップ内の固定ビーコンの高さを返します。

関数名： mm_get_beacon_height

C言語での宣言：bool mm_get_beacon_height (uint8_t address, void *pdata);

対応APIバージョン：V4+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、高さが返されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

ビーコンのアドレス

void *

高さデータを格納するバッファへのポインタ

ポインタが指すデータの構造：

型

説明

uint8_t

サブマップID（関数呼び出し前に設定しておく必要があります）

int32_t

ビーコンの高さ、mm

サブマップ内の固定ビーコンの高さを設定

サブマップ内の固定ビーコンの高さを設定します。

関数名： mm_set_beacon_height

C言語での宣言：bool mm_set_beacon_height (uint8_t address, void *pdata);

対応APIバージョン：V4+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、高さが変更されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

ビーコンのアドレス

void *

高さデータを格納するバッファへのポインタ

ポインタが指すデータの構造（関数呼び出し前に設定しておく必要があります）：

型

説明

uint8_t

サブマップID

int32_t

ビーコンの高さ、mm

位置更新レートの設定を取得

モデムから位置更新レートの設定を読み出します。

関数名： mm_get_update_rate_setting

C言語での宣言：bool mm_get_update_rate_setting (void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、更新レートが取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint32_t

位置更新レートの設定値（mHz単位）。つまり、1 Hzでは1000、16 Hzでは16000、0.05 Hzモードでは50が返されます。

位置更新レートを設定

位置更新レートの設定をモデムに書き込みます。

関数名： mm_set_update_rate_setting

C言語での宣言：bool mm_set_update_rate_setting (void *pdata);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、更新レートが変更されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

データへのポインタ

ポインタが指すデータの構造（関数呼び出し前に設定しておく必要があります）：

型

説明

uint32_t

位置更新レートの設定値（mHz単位）。つまり、1 Hzは1000、16 Hzは16000、0.05 Hzモードは50です。システムは、次の系列のうち指定値に最も近い更新レートを使用します：0.05 Hz、0.1 Hz、0.2 Hz、0.5 Hz、1 Hz、2 Hz、4 Hz、8 Hz、12 Hz、16 Hz、16+Hz。

サブマップを追加

新しいサブマップを追加します。

関数名： mm_add_submap

C言語での宣言：bool mm_add_submap (uint8_t submapId);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、サブマップが追加されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

追加するサブマップのID（0…254）

サブマップを削除

既存のサブマップを削除します。

関数名： mm_delete_submap

C言語での宣言：bool mm_delete_submap (uint8_t submapId);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、サブマップが削除されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

削除するサブマップのID（0…254）

サブマップを固定

サブマップを固定します。

関数名： mm_freeze_submap

C言語での宣言：bool mm_freeze_submap (uint8_t submapId);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、サブマップが固定されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

固定するサブマップのID（0…254）

サブマップの固定を解除

サブマップの固定を解除します。

関数名： mm_unfreeze_submap

C言語での宣言：bool mm_unfreeze_submap (uint8_t submapId);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、サブマップの固定が解除されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

固定を解除するサブマップのID（0…254）

サブマップの設定を取得

モデムからサブマップの設定を読み出します。

関数名： mm_get_submap_settings

C言語での宣言：bool mm_get_submap_settings (uint8_t submapId, void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、サブマップの設定が取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

サブマップID（0…254）

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint8_t

三辺測量の起点ビーコン

uint8_t

起点となるビーコンセット、ビーコン1

uint8_t

起点となるビーコンセット、ビーコン2

uint8_t

起点となるビーコンセット、ビーコン3

uint8_t

起点となるビーコンセット、ビーコン4

bool

true = 3Dナビゲーション有効

bool

true = サブマップをZ座標のみに使用

bool

true = 距離制限を手動で設定

false = 距離制限を自動で設定

uint8_t

最大距離、m（距離制限を手動で設定する場合）

int16_t

サブマップのXシフト、cm

int16_t

サブマップのYシフト、cm

int16_t

サブマップのZシフト、cm

uint16_t

サブマップの回転、0.01度単位

int16_t

平面回転クォータニオン、W（クォータニオンは10000に正規化）

int16_t

平面回転クォータニオン、X

int16_t

平面回転クォータニオン、Y

int16_t

平面回転クォータニオン、Z

int16_t

サービスゾーンの厚さ、cm

int16_t

2Dモードでのモバイルビーコンの高さ

bool

true = サブマップは固定済み

bool

true = サブマップはロック済み

bool

true = 固定ビーコンがモバイルビーコンより高い位置にある

bool

true = サブマップはミラー反転

4バイト

サブマップ内のビーコンのアドレスリスト（0 = なし）

8バイト

近隣サブマップのIDリスト（255 = なし）

uint8_t

サービスゾーンのポリゴン頂点数（P）

P*4バイト

サービスゾーンのポリゴン頂点構造体のリスト（下記参照）

サービスゾーンのポリゴン頂点の構造：

型

説明

int16_t

X、cm

int16_t

Y、cm

サブマップの設定を変更

サブマップの設定をモデムに書き込みます。

関数名： mm_set_submap_settings

C言語での宣言：bool mm_set_submap_settings (uint8_t submapId, void *pdata);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、サブマップの設定が変更されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

サブマップID（0…254）

void *

書き込むデータへのポインタ（「サブマップの設定を取得」関数を参照）。

マップを固定

サブマップを固定します。

関数名： mm_freeze_map

C言語での宣言：bool mm_freeze_map ();

対応APIバージョン：V4+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、マップが固定されました

false – 実行中にエラーが発生しました

マップの固定を解除

サブマップを固定します。

関数名： mm_unfreeze_map

C言語での宣言：bool mm_freeze_map ();

対応APIバージョン：V4+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、マップの固定が解除されました

false – 実行中にエラーが発生しました

ビーコンの超音波設定を取得

指定したビーコンから超音波設定を読み出します。

関数名： mm_get_ultrasound_settings

C言語での宣言：bool mm_get_ultrasound_settings (uint8_t address, void *pdata);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、超音波設定が取得されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

ビーコンのアドレス（1…254）

void *

結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint16_t

超音波送信（TX）の周波数（受信専用のDSP RXビーコンには無関係）

uint8_t

TX周期の数（受信専用のDSP RXビーコンには無関係）

bool

true = RXにAGCを使用

false = RXのゲインを手動で設定

uint16_t

手動ゲイン値（0…4000）

bool

true = 通常モードでセンサーRX1が有効

bool

true = 通常モードでセンサーRX2が有効

bool

true = 通常モードでセンサーRX3が有効

bool

true = 通常モードでセンサーRX4が有効

bool

true = 通常モードでセンサーRX5が有効

bool

true = 固定モードでセンサーRX1が有効

bool

true = 固定モードでセンサーRX2が有効

bool

true = 固定モードでセンサーRX3が有効

bool

true = 固定モードでセンサーRX4が有効

bool

true = 固定モードでセンサーRX5が有効

uint8_t

DSP RXフィルターのインデックス（DSPビーコンのみ該当）

0 = 19 kHz

1 = 25 kHz

2 = 31 kHz

3 = 37 kHz

4 = 45 kHz

ビーコンの超音波設定を変更

指定したビーコンに超音波設定を書き込みます。

関数名： mm_set_ultrasound_settings

C言語での宣言：bool mm_set_ultrasound_settings (uint8_t address, void *pdata);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、超音波設定が変更されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

ビーコンのアドレス（1…254）

void *

書き込むデータへのポインタ（「超音波設定を取得」関数を参照）。

Erase map

モデム内のマップを消去します。サブマップ0を除くすべてのサブマップを削除し、サブマップ0を初期状態にリセットし、接続されているすべてのビーコンをネットワークから削除します。

関数名： mm_erase_map

C言語での宣言：bool mm_erase_map ();

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、マップが消去されました

false – 実行中にエラーが発生しました

パラメータ：なし

デバイスをデフォルト設定にリセット

デバイスをデフォルト設定（無線、超音波など）にリセットします。

関数名： mm_set_default_settings

C言語での宣言：bool mm_set_default_settings (uint8_t address);

対応APIバージョン：V1+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、デバイスがデフォルト設定にリセットされました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

デバイスのアドレス（1…254）

255 – USBで接続されたデバイスをデフォルト設定にリセット

ビーコンを座標軸に関連付け

選択したビーコンが座標軸上に来るように、マップをシフトします。

関数名： mm_beacons_to_axes

C言語での宣言：bool mm_beacons_to_axes (uint8_t address_0, uint8_t address_x, uint8_t address_y);

対応APIバージョン：V2+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、マップがシフトされました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

address_0 – 原点（X=0、Y=0）に置くビーコンのアドレス

uint8_t

address_x – X軸上（Y=0）に置くビーコンのアドレス

uint8_t

address_y – Yの正方向（Y>0）に置くビーコンのアドレス

モデムの設定メモリダンプの読み出し

モデムの設定メモリのダンプを読み出します。モデムの設定と、格納されているマップを保存できます。

関数名： mm_read_flash_dump

C言語での宣言：bool mm_read_flash_dump(uint32_t offset, uint32_t size, void *pdata);

対応APIバージョン：V3+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、ダンプが読み出されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint32_t

offset – 設定メモリの先頭からのオフセット、バイト

uint32_t

size – 読み出すデータのサイズ、バイト

void *

pdata – データを受け取るユーザーバッファへのポインタ

モデムの設定メモリダンプの書き込み

モデムの設定メモリにデータダンプを書き込みます。モデムの設定とマップを復元できます。

関数名： mm_write_flash_dump

C言語での宣言：bool mm_write_flash_dump(uint32_t offset, uint32_t size, void *pdata);

対応APIバージョン：V3+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行され、ダンプが書き込まれました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint32_t

offset – 設定メモリの先頭からのオフセット、バイト

正しく動作させるには、offsetを4096バイトのページ境界に合わせる必要があります（0、4096、8192などの値）。

uint32_t

size – 書き込むデータのサイズ、バイト

void *

pdata – 書き込むデータを格納したユーザーバッファへのポインタ

注：設定を書き込んだ後は、新しい設定を適用し、上書きされるのを防ぐため、モデムのソフトウェアリセット（mm_reset_device(255)）を実行することをおすすめします。

デバイスの再起動（ソフトリセット）

指定したデバイスのソフトウェアリセットを実行します。

関数名： mm_reset_device

C言語での宣言：bool mm_reset_device (uint8_t address);

対応APIバージョン：V3+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、デバイスがリセット中です

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

デバイスのアドレス（1…254）

255 – USBで接続されたデバイスのソフトウェアリセット

モデムからの気温設定の読み出し

モデムから気温の設定（摂氏）を読み出します。

関数名： mm_get_air_temperature

C言語での宣言：bool mm_get_air_temperature (void *pdata);

対応APIバージョン：V3+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、気温が返されました

false – 実行中にエラーが発生しました

pdataポインタ経由で返されるデータの構造：

型

説明

int8_t

気温、°C

モデムへの気温設定の書き込み

モデムに気温の設定（摂氏）を書き込みます。

関数名： mm_set_air_temperature

C言語での宣言：bool mm_set_air_temperature (void *pdata);

対応APIバージョン：V3+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行され、気温が書き込まれました

false – 実行中にエラーが発生しました

ユーザーがpdataポインタ経由で渡すデータの構造：

型

説明

int8_t

気温、°C

ビーコンのReal-time Player設定を取得

ビーコンのReal-time Player設定を読み出します。

関数名： mm_get_realtime_player_settings

C言語での宣言：bool mm_get_realtime_player_settings (uint8_t address, void *pdata);

対応APIバージョン：V6+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

address – ビーコンのアドレス（1…254）

void *

pdata – 結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

bool

true = Real-time Playerが有効

uint8_t

Real-time Playerで処理する前方サンプル数

uint8_t

Real-time Playerで処理する後方サンプル数

uint8_t

予約済み（0）

uint8_t

予約済み（0）

ビーコンのReal-time Player設定を変更

ビーコンのReal-time Player設定を変更します。

関数名： mm_set_realtime_player_settings

C言語での宣言：bool mm_set_realtime_player_settings (uint8_t address, void *pdata);

対応APIバージョン：V6+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

address – ビーコンのアドレス（1…254）

void *

pdata – 書き込むデータへのポインタ（「ビーコンのReal-time Player設定を取得」関数を参照）

ジオリファレンス設定を取得

ジオリファレンス設定（Marvelmindマップの点（X=0、Y=0）の地理的位置）を読み出します。

関数名： mm_get_georeferencing_settings

C言語での宣言：bool mm_get_georeferencing_settings (void *pdata);

対応APIバージョン：V6+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

int32_t

緯度、x10-7 度

int32_t

経度、x10-7 度

ジオリファレンス設定を変更

ジオリファレンス設定（Marvelmindマップの点（X=0、Y=0）の地理的位置）を変更します。

関数名： mm_set_georeferencing_settings

C言語での宣言：bool mm_set_georeferencing_settings (void *pdata);

対応APIバージョン：V6+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 書き込むデータへのポインタ（「ジオリファレンス設定を取得」関数を参照）

位置の更新モードを取得

モバイルビーコンの位置の現在の更新モードを読み出します。

関数名： mm_get_update_position_mode

C言語での宣言：bool mm_get_update_position_mode (void *pdata);

対応APIバージョン：V6+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 結果を格納するデータへのポインタ

ポインタ経由で返されるデータの構造：

型

説明

uint8_t

モバイルビーコンの位置の更新モード：

0 – 位置を自動で更新（デフォルトモード）

1 – ユーザーの要求に応じて、次の更新サイクルで位置を更新

2 – ユーザーの要求に応じて、直ちに位置を更新

7バイト

予約済み（0）

位置の更新モードを設定

モバイルビーコンの位置の更新モードを設定します。

関数名： mm_set_update_position_mode

C言語での宣言：bool mm_set_update_position_mode (void *pdata);

対応APIバージョン：V6+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 書き込むデータへのポインタ（関数‘位置の更新モードを取得’)

位置を更新するコマンド

モバイルビーコンの位置を更新するコマンドを送信します（更新モードが自動ではない場合）。

関数名： mm_set_update_position_command

C言語での宣言：bool mm_set_update_position_command (void *pdata);

対応APIバージョン：V6+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 書き込むデータへのポインタ

ポインタが指すデータの構造：

型

説明

8バイト

予約済み（0）

ビーコンのジオフェンスアラーム状態を設定

ビーコンのアラームピンにアラーム状態を設定するコマンドを送信します（Super-Beacon用）。

ピンのアラーム状態は、Dashboardの設定の「Interfaces」セクションにある「Alarm pin mode」で指定できます（MMSW0006 ライセンスが有効な場合）。

関数名： mm_set_alarm_state

C言語での宣言：bool mm_set_alarm_state (uint8_t address, void *pdata);

対応APIバージョン：V9+

必要なライセンス：MMSW0005、MMSW0006

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

address – ビーコンのアドレス（1…254）

void *

pdata – 書き込むデータへのポインタ

ポインタが指すデータの構造：

型

説明

uint8_t

アラームピンのモード：

0 – ジオフェンスの状態に応じてピンを自動制御

1 – ピンを手動制御 – アラームなしの状態

2 – ピンを手動制御 – アラーム状態

uint8_t

ジオフェンスゾーンのインデックス – アラーム状態のときにビーコンがストリーミングで出力するジオフェンスゾーンの番号

6バイト

予約済み（0）

汎用ユーザーペイロードデータを送信

汎用ユーザーペイロードデータを送信します。APIがモデムに接続されている場合、データは指定したモバイルビーコンのUART/USBポートから出力されます。APIがモバイルビーコンに接続されている場合、データはモデムのUART/USBポートから出力されます。受信したデータは、相手側で受信用のAPI関数、Arduinoのサンプル、ROSなどのソフトウェアで取得できます。

関数名： mm_send_user_payload_data

C言語での宣言：bool mm_send_user_payload_data (uint8_t address, void *pdata);

対応APIバージョン：V9+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

uint8_t

address – APIがモデムに接続されている場合は、ビーコンのアドレス（1…254）

APIがビーコンに接続されている場合は該当なし

void *

pdata – 書き込むデータへのポインタ

ポインタが指すデータの構造：

型

説明

uint8_t

送信するデータのサイズ

256バイト

送信する汎用データのバッファ

汎用ユーザーペイロードデータを取得

汎用ユーザーペイロードデータを受信します。送信元は、送信用のAPI関数、Arduino、ROS、またはその他のユーザーソフトウェアです。APIがモデムに接続されている場合、この関数は、モバイルビーコンのUART/USBポートに入力されたデータを受信できます。APIがモバイルビーコンに接続されている場合、この関数は、モデム経由で送信されたデータを受信できます。

関数名： mm_get_user_payload_data

C言語での宣言：bool mm_get_user_payload_data (void *pdata);

対応APIバージョン：V9+

必要なライセンス：MMSW0005

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 受信するデータへのポインタ

ポインタが指す受信データの構造：

型

説明

uint8_t

address – ビーコンのアドレス

int64_t

データ送信のタイムスタンプ – 01.01.1970からのミリ秒数（UNIX時間）

uint8_t

送信するデータのサイズ

256バイト

受信データのバッファ

手動距離測定のコマンドを送信

指定したビーコンからシステム内の他のビーコンまでの距離を測定するコマンドを送信します。現在のバージョンのソフトウェアで対応しているのはIAアーキテクチャ（Inverse Architecture）です。

関数名： mm_send_distances_measurement_command

C言語での宣言：bool mm_send_distances_measurement_command (void *pdata);

対応APIバージョン：V9+

必要なライセンス：MMSW0011

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 送信するデータへのポインタ

ポインタが指すデータの構造：

型

説明

uint8_t

モード：

0 – 自動

1 – 手動（このコマンドで測定）

uint8_t

ビーコンのアドレス

uint32_t

測定する最大距離、mm

8バイト

予約済み

モデムからストリーミングデータを取得

モデムのストリーミングデータを読み出します。形式は前述のとおりです。

関数名： mm_get_stream_data

C言語での宣言：bool mm_get_stream_data (void *pdata);

対応APIバージョン：V9+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 関数が正常に実行されました

false – 実行中にエラーが発生しました

パラメータ：

型

説明

void *

pdata – 送信するデータへのポインタ

ポインタが指すデータの構造：

型

説明

uint8_t

この応答に含まれるストリームレコードの数（0…16）

138*16バイト

138バイトのストリーミングレコード16個（下記参照）

8バイト

予約済み

ストリームレコードの構造：

型

説明

uint8_t

レコードのサイズ、バイト

uint8_t

レコードの種類。「line type」と同じ値です。参照：Dashboardのログファイル。

例えば、41はMarvelmindプロトコルのデータを意味します

8バイト

予約済み

128バイト

ストリームレコードのデータ

デバイスタイプがモデムかどうかを確認

指定したデバイスタイプがモデムに該当するかどうかを確認します。

関数名： mm_device_is_modem

C言語での宣言：bool mm_device_is_modem (uint8_t deviceType);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 指定したデバイスタイプはモデムに該当します

パラメータ：

型

説明

uint8_t

デバイスタイプ（確認対象）

デバイスタイプが固定ビーコンかどうかを確認

指定したデバイスタイプが固定ビーコンに該当するかどうかを確認します。

関数名： mm_device_is_beacon

C言語での宣言：bool mm_device_is_beacon (uint8_t deviceType);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 指定したデバイスタイプは固定ビーコンに該当します

パラメータ：

型

説明

uint8_t

デバイスタイプ（確認対象）

デバイスタイプがモバイルビーコンかどうかを確認

指定したデバイスタイプがモバイルビーコン（hedgehog）に該当するかどうかを確認します。

関数名： mm_device_is_hedgehog

C言語での宣言：bool mm_device_is_hedgehog (uint8_t deviceType);

対応APIバージョン：V1+

必要なライセンス：なし

戻り値：

型

説明

bool

true – 指定したデバイスタイプはモバイルビーコンに該当します

パラメータ：

型

説明

uint8_t

デバイスタイプ（確認対象）

Marvelmind API用Cサンプルの説明

Cサンプルは、Marvelmind APIのテストに使用するもので、ユーザーアプリケーションを構築する際のベースとしても使用できます。

Cサンプルはコンソールアプリケーションです。次のプラットフォームでテスト済みです：

  • CPU：Intel Core 2 Duo、OS：MS Windows XP
  • CPU：Intel Core i5、OS：Linux Ubuntu 16.04
  • Raspberry Pi 3 Model B+、OS：Raspbian（2018-11-13-raspbian-stretch-full）

Windowsプラットフォームでは、サンプルはCodeBlocks IDEでビルドしたため、CodeBlocksのプロジェクトファイルが含まれています。

Linuxプラットフォームでは、サンプルはmakeユーティリティでビルドしたため、そのためのmakefileが含まれています。

サンプルには次のモジュールが含まれます：

ファイル名

説明

main.c

main()関数を含むモジュール。サンプルの関数を呼び出し、簡単なコマンドラインインターフェースを実装しています。

marvelmind_example.c

marvelmind_example.h

marvelmindStart() – サンプルの初期化

marvelmindFinish() – APIでの作業終了後に呼び出し

marvelmindCycle() – メインループから頻繁に呼び出し

また、このモジュールには、ユーザーが入力したコマンドを処理する関数がいくつか含まれています。

marvelmind_api.c

marvelmind_api.h

marvelmindAPILoad() – APIライブラリを読み込み

marvelmindAPIFree() – APIライブラリが使用したメモリを解放

APIライブラリとの通信用のすべての関数。

marvelmind_devices.c

marvelmind_devices.h

モデムから取得したビーコンのリストを管理します。取得には「デバイスリストを取得」コマンドを呼び出します。各ビーコンには、自身の位置と他のビーコンまでの距離のデータが含まれます。

marvelmind_pos.c

marvelmind_pos.h

次を読み出します：最新の位置データと最新の生の距離。これらのデータでデバイスリストを更新します。

marvelmind_utils.c

marvelmind_utils.h

他のモジュールで使用する補助関数。

サンプルの動作：

  1. 成功するまで、シリアルポートを開く操作を試みます
  2. ポートが開かれると、プログラムはUSBで接続されたデバイスのバージョンを読み出します。それがモデムであれば、プログラムは次の手順に進みます
  3. モデムに接続されると、プログラムは次を読み出します：デバイスリスト（1 Hzの頻度）。デバイスリストは、marvelmind_devices.cモジュールに現在格納されているものと比較され、変更が検出されるとmarvelmind_devices.c内のリストが更新されます。すべての変更はコンソールに表示されます
  4. モデムに接続されると、プログラムは次を読み出します：最新の位置データ（20 Hzの頻度）。新しい生の距離データのフラグがセットされていれば、プログラムは次も読み出します：最新の生の距離。プログラムは、位置と距離をmarvelmind_devices.c内のデバイスリストのデータと比較し、変更があればデータを更新します。変更されたデータはすべてコンソールに表示されます
  5. 最新の位置データを10回取得できない場合、プログラムはポートを閉じ、手順1に戻ってポートを開き直します。ポートの開き直しは、モデムがUSBから切断され、再接続された場合に必要です
  6. ユーザーが「スペース」キーを押すと、プログラムは「Enter command:」というメッセージを表示し、ユーザーのコマンドを待ちます。ほとんどのAPI関数はユーザーコマンドで呼び出されます。詳細は以下を参照してください

ユーザーコマンド：

ユーザーが「スペース」キーを押すと（プログラムの実行中）、次のメッセージが表示されます：「Enter command:」。キーボードでコマンドを入力し、Enterキーを押します。

すべてのユーザーコマンドの形式を次の表に示します：

コマンドグループ

説明

APIバージョン

コマンドの形式：

version

動作：

APIライブラリのバージョンを表示

プログラムの終了

コマンドの形式：

quit

動作：

プログラムの実行を終了

スリープ/ウェイクアップ

コマンドの形式：

wake <address>

動作：

次のコマンドを実行します：ウェイクアップ。

例：

wake 5 – デバイス5にウェイクアップコマンドを送信

wake 0 – すべてのデバイスにウェイクアップコマンドを送信

コマンドの形式：

sleep <address>

動作：

次のコマンドを実行します：スリープ。

例：

sleep 5 – デバイス5をスリープさせる

sleep 0 – すべてのデバイスをスリープさせる

Default

コマンドの形式：

default <address>

動作：

次のコマンドを実行します：デフォルト設定へのリセット。

例：

default 5 – デバイス5をデフォルト設定にする

テレメトリーの読み出し

コマンドの形式：

tele <address>

動作：

ビーコンのテレメトリーデータを読み出して表示します。

例：

tele 5 – ビーコン5のテレメトリーを読み出して表示

サブマップのコマンド

コマンドの形式：

submap add <submapId>

動作：

次のコマンドを実行します：サブマップを追加（指定したサブマップID）。

例：

submap add 1 – サブマップ1を追加

コマンドの形式：

submap delete <submapId>

動作：

次のコマンドを実行します：サブマップを削除（指定したサブマップID）。

例：

submap delete 1 – サブマップ1を削除

コマンドの形式：

submap freeze <submapId>

動作：

次のコマンドを実行します：サブマップを固定（指定したサブマップID）。

例：

submap freeze 0 – サブマップ0を固定

コマンドの形式：

submap unfreeze <submapId>

動作：

次のコマンドを実行します：サブマップの固定を解除（指定したサブマップID）。

例：

submap unfreeze 0 – サブマップ0の固定を解除

コマンドの形式：

submap get <submapId>

動作：

次のコマンドを実行します：サブマップの設定を取得（指定したサブマップID）。

例：

submap get 0 – サブマップ0の設定を取得して表示

コマンドの形式：

submap testset <submapId>

動作：

次のコマンドを実行します：サブマップの設定を変更（指定したサブマップID）。プログラムは、コマンドのテスト用にあらかじめ定義した設定を書き込みます。詳細はサンプルコードを参照してください。

例：

submap testset 0 – サブマップ0の設定を変更

マップのコマンド

コマンドの形式：

map erase

動作：

次のコマンドを実行します：マップを消去。

例：

map erase – モデム内のマップを消去

コマンドの形式：

map freeze

動作：

次のコマンドを実行します：マップを固定。

例：

map freeze – マップを固定

コマンドの形式：

map unfreeze

動作：

次のコマンドを実行します：マップの固定を解除。

例：

map unfreeze – マップの固定を解除

更新レートのコマンド

コマンドの形式：

rate get

動作：

次のコマンドを実行します：更新レート設定の読み出し。

例：

rate get – 更新レートの設定を読み出して表示

コマンドの形式：

rate set <value>

動作：

次のコマンドを実行します：更新レート設定の変更。値はHz単位で指定します

例：

rate set 0.5 – 更新レートを0.5 Hzに設定

超音波のコマンド

コマンドの形式：

usound get <address>

動作：

次のコマンドを実行します：超音波設定の読み出し（指定したビーコン）。

例：

usound get 5 – ビーコン5の超音波設定を読み出して表示

コマンドの形式：

usound testset <address>

動作：

次のコマンドを実行します：超音波設定の書き込み（指定したビーコン）。プログラムは、コマンドのテスト用にあらかじめ定義した設定を書き込みます。詳細はサンプルコードを参照してください。

例：

usound testset 5 – ビーコン5の超音波設定を変更

座標軸への関連付けのコマンド

コマンドの形式：

axes <address_0> <address_x> <address_y>

動作：

次のコマンドを実行します：ビーコンを座標軸に関連付け。

例：

axes 3 4 5 – ビーコン3をX=0、Y=0に、ビーコン4をX軸上（Y=0）に、ビーコン5をX軸より上（Y>0）に配置

モデムからの設定メモリダンプの読み出し

コマンドの形式：

read_dump <offset> <size>

動作：

次のコマンドを実行します：モデムの設定メモリダンプの読み出し。

例：

read_dump 0 1000 – 設定メモリの先頭から最初の1000バイトを読み出し

モデムへの設定メモリのテストダンプの書き込み

コマンドの形式：

write_dump_test <offset> <size>

動作：

次のコマンドを実行します：モデムの設定メモリダンプの書き込み。

例：

write_dump_test 0 1000 – 設定メモリの先頭から最初の1000バイトをテストパターンで埋める

デバイスのソフトウェアリセット

コマンドの形式：

reset <address>

動作：

次のコマンドを実行します：ソフトウェアリセット。

例：

reset 255 – USBで接続されたデバイスのソフトウェアリセットを実行

気温のコマンド

コマンドの形式：

temperature get

動作：

読み出しを実行します：気温の設定（モデムから）

例：

temperature get 超音波用の気温の設定を読み出して表示

コマンドの形式：

temperature set <value>

動作：

書き込みを実行します：気温の設定（モデムへ）

例：

temperature set 30 気温の設定を30 °Cに設定

ビーコンの位置の設定

コマンドの形式：

setloc <address> <X > <Y > <Z>

動作：

次のコマンドを実行します：ビーコンの位置を設定。X、Y、Zはメートル単位の座標です。

例：

setloc 12 1.51 3.45 2.0 – ビーコン12の位置をX= 1.51 m、Y= 3.45 m、Z= 2.0 mに設定

ビーコン間の距離を設定

コマンドの形式：

setdist <address1> <address2 > <distance>

動作：

次のコマンドを実行します：ビーコン間の距離を設定。address1とaddress2はビーコンのアドレス、distanceはメートル単位の距離です。

例：

setdist 12 13 16.5 – ビーコン12と13の間の距離を16.5 mに設定

高さのコマンド

コマンドの形式：

height_h get <address>

動作：

次のコマンドを実行します：モバイルビーコンの高さを取得。addressはモバイルビーコンのアドレスです。

例：

height_h get 15 – モバイルビーコン15の高さを読み出して表示

コマンドの形式：

height_h set <address> <height>

動作：

次のコマンドを実行します：モバイルビーコンの高さを設定。addressはモバイルビーコンのアドレス、高さはメートル単位です

例：

height_h set 15 2.5 – モバイルビーコン15の高さを2.5 mに設定

コマンドの形式：

height_b get <address> <submap_id>

動作：

次のコマンドを実行します：固定ビーコンの高さを取得。addressはビーコンのアドレス、submap_idはビーコンが属するサブマップのIDです。

例：

height_b get 12 0 – サブマップ0内の固定ビーコン12の高さを読み出して表示します。

コマンドの形式：

height_b set <address> <submap_id> <height>

動作：

次のコマンドを実行します：固定ビーコンの高さを設定。addressは固定ビーコンのアドレス、submap_idはビーコンが属するサブマップのID、高さはメートル単位です

例：

height_b set 12 0 5.1 – サブマップ0内のビーコン12の高さを5.1 mに設定

Real-time Playerのコマンド

コマンドの形式：

rtp get <address>

動作：

次のコマンドを実行します：Real-time Player設定を取得。addressはビーコンのアドレスです。

例：

rtp get 15 – ビーコン15のReal-time Player設定を読み出して表示

コマンドの形式：

rtp testset <address>

動作：

次のコマンドを実行します：Real-time Player設定を変更。addressはビーコンのアドレスです。プログラムは、コマンドのテスト用にあらかじめ定義した設定を書き込みます。詳細はサンプルコードを参照してください。

例：

rtp testset 15 – ビーコン15にテスト用のReal-time Player設定を書き込み

ジオリファレンスのコマンド

コマンドの形式：

georef get

動作：

次のコマンドを実行します：ジオリファレンス設定の取得。

例：

georef get – ジオリファレンス設定を読み出して表示

コマンドの形式：

georef set <latitude> <longitude>

動作：

次のコマンドを実行します：ジオリファレンス設定の変更。

例：

georef set 10 20 – ジオリファレンスとして緯度10度、経度20度を書き込み

更新モードのコマンド

コマンドの形式：

update_mode get

動作：

次のコマンドを実行します：位置の更新モードを取得。

例：

update_mode get – 位置の更新モードを読み出して表示

コマンドの形式：

update_mode set <mode>

動作：

次のコマンドを実行します：位置の更新モードを設定。

例：

update_mode set 0 – 位置の更新を自動モードに設定

コマンドの形式：

update

動作：

次のコマンドを実行します：位置を更新。

例：

update – 次に従ってモバイルビーコンの位置を更新：現在のモード

ジオフェンスアラーム状態の設定

コマンドの形式：

alarm <address> <mode> <zone>

動作：

次のコマンドを実行します：ジオフェンスアラーム状態を設定。

例：

alarm 10 2 5 – ビーコンn10で、ジオフェンスゾーン番号5のジオフェンスアラーム信号を設定

ユーザーペイロードのコマンド

コマンドの形式：

payload read <address>

動作：

次のコマンドを実行します：ユーザーペイロードデータを取得。

例：

payload read – 任意のビーコン/モデムからユーザーペイロードを読み出し

例：

payload read 10 – ビーコンn10からユーザーペイロードを読み出し

コマンドの形式：

payload write <address>

動作：

次のコマンドを実行します：ユーザーペイロードデータを送信。

例：

payload write 10 – ビーコンn10にテスト用のペイロードデータを書き込み

テストパターンは100から始まる40バイトです：100、101、…、139

手動距離測定のコマンド

コマンドの形式：

distance <manual/auto> <address> <max distance>

動作：

次のコマンドを実行します：手動距離測定。

例：

distance manual 10 5 – ビーコン10から他のビーコンまでの距離を測定、最大距離5 m

例：

distance manual 10 – ビーコン10から他のビーコンまでの距離を測定、最大距離30 m（デフォルト）

例：

distance auto – 自動距離測定モードに戻る

デバイスタイプ

各デバイスの「Device type ID」の値を次に示します：

デバイスタイプID

デバイスの説明

22

Beacon HW V4.5

23

Beacon HW V4.5（モバイルビーコンモード）

24

Modem HW V4.9

30

Beacon HW V4.9

31

Beacon HW V4.9（モバイルビーコンモード）

32

Beacon Mini-RX

36

Beacon Mini-TX

37

Beacon-TX-IP67

41

Beacon industrial-RX

42

Super-Beacon

43

Super-Beacon（モバイルビーコンモード）

44

Industrial Super-Beacon

45

Industrial Super-Beacon（モバイルビーコンモード）

46

Super-Modem

48

Modem HW V5.1

デバイスタイプIDは、デバイスリストとデバイスバージョンの読み出しのコマンドで取得できます。

ユーザーデバイスとのユーザーデータの送受信

Marvelmindは、Marvelmindシステムを介してユーザーデータを伝送するさまざまな方法に対応しています：

  • モデムのUARTまたはUSBからデータを送信し、モバイルビーコンのUARTまたはUSBから受信
  • モバイルビーコンのUARTまたはUSBからデータを送信し、モデムのUARTまたはUSBで受信。

Super-Modemは、UDPによるユーザーデータの送受信にも対応しています。

データ伝送のプロトコルは、このドキュメントの前のセクションで説明しています：

Marvelmindは、通信用のさまざまなサンプルソフトウェアを提供しています：

例

Arduino

（UART）

PC / Raspberry Pi（USB）

PC / raspberry Pi

（UDP、Super-Modem）

API

C

Python

ROS/ROS2

Cのサンプル

ユーザーデバイス ← ビーコン

+

+

+

+

+

n/a

モデム → ユーザーデバイス

+

+

+

+

+

+

ユーザーデバイス → ビーコン

+

+

–

–

+

n/a

モデム ← ユーザーデバイス

+

+

–

–

+

+

サンプルの一覧：

  • ユーザーデータを送受信するArduinoのサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 06_Examples/ arduino」にあります。「hedgehog_sample_uart_user_data_receive_v2」はユーザーデータの受信用、「hedgehog_sample_uart_user_data_send_v2」はユーザーデータの送信用です
  • API通信のサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 05_API/example_source」（ソースコード）と「01_Common_Indoor_positioning_SW/ 05_API/example_bin_win32」（Windows用バイナリ）にあります。データの送信や受信は、このドキュメントで説明しているとおりに呼び出せます。
  • ストリーミングデータを受信するCのサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 06_Examples/ c」にあります。このサンプルは次でも入手できます：GitHubのリポジトリ。このサンプルは、モバイルビーコンまたはモデムから受信したすべてのデータ（ユーザーデータを含む）を表示するだけのものです。
  • ストリーミングデータを受信するPythonのサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 06_Examples/ python」にあります。このサンプルは次でも入手できます：GitHubのリポジトリ。このサンプルは、モバイルビーコンまたはモデムから受信したすべてのデータ（ユーザーデータを含む）を表示するだけのものです。
  • ストリーミングデータを受信するROSパッケージのサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 06_Examples/ ROS」にあります。このパッケージは次でも入手できます：リポジトリ。ROSパッケージでは、API経由でユーザーデータの受信と送信ができます。詳細はドキュメントを参照してください。
  • ストリーミングデータを受信するROS-2パッケージのサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 06_Examples/ ROS2」にあります。このパッケージは次でも入手できます：リポジトリ。ROSパッケージでは、API経由でユーザーデータの受信と送信ができます。詳細はドキュメントを参照してください。
  • UDPでデータを受信するCのサンプルは、Marvelmindソフトウェアパッケージのフォルダー「01_Common_Indoor_positioning_SW/ 06_Examples/ c」にあります。このサンプルは、Super-ModemまたはDashboardからUDPで受信したすべてのデータ（ユーザーデータを含む）を表示するだけのものです。APIをUSBの代わりに UDPでのSuper-Modemとの接続に使用している場合は、API経由でUDPによるユーザーデータの送信ができます。

お問い合わせ

その他のサポートについては、次のアドレスまでご質問をお送りください：info@marvelmind.com

付録1. CRC-16の計算

チェックサムにはCRC-16を使用します。Nバイトのフレームの最後の2バイトには、フレームの最初の(N-2)バイトに対するCRC-16が格納されます。データを検査するには、Nバイトのフレーム全体にCRC-16を適用します。結果の値は0になるはずです。

C言語によるアルゴリズムの実装を次に示します：

typedef uint16_t ModbusCrc;

typedef union { uint16_t w; struct{ uint8_t lo; uint8_t hi; } b; uint8_t bs[2]; } Bytes;

static ModbusCrc modbusCalcCrc(const void *buf, uint16_t length)

{

uint8_t *arr = (uint8_t *)buf;

Bytes crc; crc.w = 0xffff; while(length--){ char i; bool odd; crc.b.lo ^= *arr++;

for(i = 0; i< 8; i++){

odd = crc.w& 0x01; crc.w>>= 1; if (odd) crc.w ^= 0xa001; } }

return (ModbusCrc) crc.w;

}

付録2. モデムからのエラー応答の形式

エラーフレームの形式（モデムからホストへ）

オフセット

サイズ（バイト）

型

説明

値

0

1

uint8_t

モデムのアドレス

0xff

1

1

uint8_t

パケットの種類

2

1

uint8_t

エラーコード

3

2

uint16_t

CRC-16（付録1を参照）

エラーパケットの種類は、要求フレームのパケットの種類に最上位ビットを加えたものです。例えば、要求のパケットの種類が0x03の場合、エラーパケットの種類は0x83になります。

エラーコードは次のいずれかです：

1 – 要求のパケットの種類が不明

2 – 要求のデータコードが不明

3 – 要求のデータフィールドにエラー

6 – デバイスがビジー状態

10 – リモートデバイスからのエラーメッセージ

11 – リモートデバイスからの応答タイムアウト

← DashboardのCSVログ形式すべての章 →
トップへ戻る