Comments
Description
Transcript
プログラミングガイド - アイオイ・システム
marblePORT ver.1.3
プログラミングガイド
第1版
改訂履歴
日付
2015/1/13
版
第1版
改訂内容
目次
1. 概要 ..................................................................................................................................................................... 1
2. 基本的な使用方法 ........................................................................................................................................ 3
2.1 marblePORT の呼び出し........................................................................................................................................................................................ 3
2.2 marblePORT 処理の完了を知る ......................................................................................................................................................................... 4
2.3 marblePORT からデータを受け取る ................................................................................................................................................................. 5
3. 機能別パラメータ ........................................................................................................................................... 6
3.1 ステータス表示 (機能番号=0) ........................................................................................................................................................................... 6
3.2 ステータス取得 (機能番号=1) ........................................................................................................................................................................... 6
3.3 ユーザーデータ読み取り (機能番号=2) ........................................................................................................................................................ 7
3.4 ユーザーデータ書き込み (機能番号=3) ....................................................................................................................................................... 8
3.5 画像表示 (機能番号=4) ....................................................................................................................................................................................... 9
3.6 表示画像登録 (機能番号=5) ............................................................................................................................................................................. 9
3.7 登録画像表示 (機能番号=6) ...........................................................................................................................................................................10
3.8 ディスプレイクリア (機能番号=7) ....................................................................................................................................................................10
3.9 テキスト表示 (機能番号=21) ............................................................................................................................................................................11
3.10 セキュリティコード変更 (機能番号=8) ........................................................................................................................................................12
3.11 複合処理..................................................................................................................................................................................................................12
4. オプションパラメータ....................................................................................................................................14
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
完了時の動作 ..........................................................................................................................................................................................................14
プログレスバー表示 ..............................................................................................................................................................................................14
タイトル/メッセージのカスタマイズ .................................................................................................................................................................14
通信に使用するタグのインスタンス指定 (NFC 対応端末のみ) .......................................................................................................15
完了時のバイブレータ動作................................................................................................................................................................................15
スマートタグの機種指定 .....................................................................................................................................................................................16
セキュリティコード指定 .........................................................................................................................................................................................16
おサイフケータイを明示的に使用する ..........................................................................................................................................................16
処理の最後にステータス確認を行う .............................................................................................................................................................17
5. 応用的な使用方法 ......................................................................................................................................18
5.1 複数の処理を連続実行する ...............................................................................................................................................................................18
5.2 独自にタグの検出を行う (NFC のみ) ...........................................................................................................................................................19
5.3 通信ログを使用する..............................................................................................................................................................................................19
6. エラー時の挙動 ............................................................................................................................................21
6.1 開始時のエラー .......................................................................................................................................................................................................21
6.2 通信処理中のエラー .............................................................................................................................................................................................21
6.3 電池残量が少ない時の挙動 .............................................................................................................................................................................22
7. 資料 ...................................................................................................................................................................24
7.1 パラメータ一覧 ..........................................................................................................................................................................................................24
7.2 marblePORT のバージョンコード ......................................................................................................................................................................27
1. 概要
本書について
本書は Android 端末向けアプリケーション”marblePORT”について、外部のアプリケーションから呼び出して使
用する方法について説明するものです。marblePORT を使ってスマートタグを使用するアプリケーションを開発
される方を対象としています。
marblePORT とは
marblePORT(マーブルポート)はスマートタグとの通信処理を代行して行う補助アプリケーションです。スマー
トタグとの通信を行いたいアプリケーションからインテントを利用して起動され、スマートタグとの通信処理を行
い、元のアプリケーションに結果を返します。このため、インテント呼び出しだけでスマートタグを利用するアプリ
ケーションを作成することができます。
主な特徴
marblePORT 自身はライブラリでは無く１つの Android アプリケーション。
スマートタグとの通信処理プログラムを書く必要は無く、簡単にスマートタグを利用するアプリケーション作
成が可能。
marblePORT を呼び出すには Android 組み込みの仕組みを利用するため、難しい知識は必要無い。
NFC とおサイフケータイ対応端末に対応。（自動判別）
動作環境
Android OS 2.3.3 以降
NFC 対応端末またはおサイフケータイ対応端末
対応スマートタグ
ST1020 (2 インチディスプレイスマートタグ)
ST1027 (2.7 インチディスプレイスマートタグ)
SC1029L (2.9 インチスマートカード)
1
バージョン履歴
バージョン 1.3
SC1029L(2.9 インチスマートカード)に対応しました。
バージョン 1.2
処理完了時にエラー判定を行うようにしました。
コマンド送信エラー時に再送信を行うようにしました。
通信ログの保存機能を追加しました。 (『5.3 通信ログを使用する』)
バージョン 1.1
ST1027(2.7 インチディスプレイスマートタグ)に対応。
『4.6 スマートタグの機種指定』参照
『3.10 セキュリティコード変更 (機能番号=8)』
「画像表示」の機能において、ディスプレイ書き換えを行わないオプションを追加。
オプションパラメータの追加。
『4.5 完了時のバイブレータ動作』
『4.8 おサイフケータイを明示的に使用する』
『4.9 処理の最後にステータス確認を行う』
「表示画像登録」の機能において、一緒に画像を指定するオプションを追加。
1 回の起動で複数種類の処理を実行する機能を追加。
『3.11 複合処理』
通信処理後、電池残量が少ない場合はその旨のメッセージを表示。
旧バージョンとの互換性について
バージョン 1.0 を使って作成したアプリケーションはバージョン 1.1～1.3 でもそのまま動作します。
使用上の注意
marblePORT は 1 つの処理毎にインテントで起動して使用する性質上、複数の処理（ユーザーデータ読込で読
み込んだ内容に応じてディスプレイ表示など）を行う場合、複数回起動する必要があり、パフォーマンスや見た
目が落ちるというデメリットがあります。
業務用システムへの導入において、実行速度やユーザーインターフェース等の要件を marblePORT で満たせ
ない場合は、marblePORT は使わずに通信処理を独自に実装することをご検討ください。前述のウェブサイトか
らサンプルプログラムをダウンロードできます。
marblePORT の仕様は画面のデザイン等を含め予告なく変更する場合があります。
2
2. 基本的な使用方法
この章では marblePORT を外部アプリケーションから使用する基本的な方法を説明します。
2.1 marblePORT の呼び出し
marblePORT 起動には明示的インテントを使用します。主な手順としては以下の通りです。
(1)
(2)
(3)
(4)
Intent クラスのインスタンス作成
Extra を使用して機能番号と機能番号に応じたパラメータを指定。
必要に応じてオプション設定のパラメータ設定。
作成した Intent オブジェクトを使ってアクティビティを起動。
Intent クラスのインスタンス作成時に、アクションとして marblePORT では以下の文字列を使用します。
com.aioisystems.marbleport.EXECUTE
機能番号の指定は必須です。この番号によって marblePORT を呼び出すアプリケーション(以下ホストアプリケ
ーションとします)が marblePORT に対して何をして欲しいのかを指定します。また、指定した機能番号によって
固有のパラメータがあり、指定が必須のパラメータと、省略可能なパラメータがあります。
機能番号一覧
機能番号 処理内容
0
ステータス表示
1
ステータス取得
2
データ読み込み
3
データ書き込み
4
画像表示
5
表示画像登録
6
登録画像表示
7
ディスプレイクリア
8
セキュリティコード設定
21
テキスト表示
コード例～画像をディスプレイに表示する際の呼び出し例です。(Java)
Intent intent = new Intent("com.aioisystems.marbleport.EXECUTE");
//Required
intent.putExtra("EXTRA_FUNCTION_NO", 4);
intent.putExtra("EXTRA_BITMAP", bitmap);
//Optional
intent.putExtra("EXTRA_DITHER", true);
startActivity(intent);
※この例では説明のために文字列や機能番号の値を直接指定しています。通常は定数を定義して使用することをお勧めします。また定
3
数を予め定義してある MpHelper クラスをウェブで配布しています。
marblePORT が起動するとスマートタグのスキャンを促す画面が表示され、スマートタグをかざすとホストアプリ
ケーションで指定したパラメータに従って通信処理が行われます。
スキャン待ち画面
2.2 marblePORT 処理の完了を知る
marblePORT でスマートタグの通信処理が正常終了すると、デフォルトの設定ではユーザーがスマートタグをリ
ーダー/ライターから離した時に marblePORT の画面が消え、ホストアプリケーションの画面(アクティビティ)に戻
ります。
ホストアプリケーションで marblePORT の処理完了を知るには marblePORT を起動するときに Activity クラス
(android.app.Activity)の startActivityForResult メソッドを使用します。
また、ホストアプリケーションのアクティビティの onActivityResult メソッドをオーバーライドして実装します。
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
この onActivityResult メソッドで渡される引数"reｓultCode"で完了時の状況を知ることができます。
marblePORT が返す resultCode は以下の通りです。
resultCode の値
RESULT_OK (=-1)
RESULT_CANCEL (=0)
RESULT_ERROR_CANCEL (=1)
(※marblePORT 独自の値)
要求した処理が正常終了した。
ユーザーがスマートタグをかざすこと無く、且つ"戻る"ボタンで
marblePORT を終了した。
スマートタグとの通信処理でエラーが発生し、ユーザーが"戻る"ボタンで
marblePORT を終了した。
4
2.3 marblePORT からデータを受け取る
marblePORT の機能の中にはデータをホストアプリケーションに渡すものがあります（データ読み込みなど）。デ
ータは前述の onActivityResult メソッドで渡される Intent オブジェクトに格納されており、marblePORT で定義さ
れたエクストラフィールド名を使って取り出すことができます。
コード例～データ読み込みからの完了かを確認し、スマートタグから読み込んだ byte 型配列データを取得
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if(resultCode == RESULT_OK){
if(requestCode == READ_DATA){
byte[] userData = data.getByteArrayExtra("EXTRA_USER_DATA");
※使用出来るエクストラフィールド名については後述します。
処理完了後、取得できるパラメータには機能番号に固有のパラメータ（その機能の実行後にしか取得できな
い）と、どの機能実行後でも必ず取得できるパラメータがあります。
5
3. 機能別パラメータ
この章では marblePORT の各機能やそのパラメータ仕様について説明します。
3.1 ステータス表示 (機能番号=0)
marblePORT の画面にスキャンしたスマートタグのステータスを表示します。表示されるステータスは以下の通り
です。単独で marblePORT を起動した場合もこの機能を実行します。
IDm
電池状態
バージョン番号
スマートタグの固有番号
スマートタグ内臓電池の状態
良好/普通/少なくなっています/使用できません
スマートタグのファームウェアバージョン(16 進数で表示)
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
int
必須
*
型
説明
0 を指定
説明
3.2 ステータス取得 (機能番号=1)
前述のステータスをホストアプリケーションで取得するために marblePORT を呼び出します。完了時のパラメー
タはこの機能番号に限らず、全機能番号の処理完了時に取得できます。
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
型
int
必須
*
説明
1 を指定
6
■完了時のパラメータ
エクストラフィールド名
EXTRA_IDM
EXTRA_BATTERY
型
byte[]
byte
EXTRA_TAG_STATUS
byte
EXTRA_FIRMWARE_VERSION
byte
説明
スマートタグの固有 ID (IDm)
スマートタグ内蔵電池の状態
0: 良好
1: 普通
2: 少なくなっています
3: 使用できません
最後に取得したスマートタグ本体の状態
00h：初期状態 （RESET）
F0h：処理完了
F1h：コマンド受信待ち（Fnum≠Fsum）
F2h：処理中
F3h：受信コマンドエラー（Address 異常）
F4h：受信コマンドエラー（Length 異常）
F6h：受信コマンドエラー（Size 異常）
F7h：受信コマンドエラー（未定義 Func.No.）
F8h：パラメータエラー
F9h:セキュリティコード不一致
FDh：Flash Rom 異常
FEh：電子ペーパーディスプレイ異常
FFh：FeliCa 受信データエラー
スマートタグのファームウェアバージョン
3.3 ユーザーデータ読み取り (機能番号=2)
スマートタグの内部メモリ（Free Information Area）からデータを読み出します。読み出すデータはバイト型の配
列です。marblePORT やスマートタグによるデータフォーマットの規定はありません。必要に応じてアプリケーシ
ョンでデータフォーマットを決定してください。
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
EXTRA_START_ADDRESS
型
int
int
必須
*
-
EXTRA_READ_SIZE
int
*
説明
2 を指定
読み出し開始アドレス
(ST1020: 0～3071, ST1027/SC1029L:0～16383,省略時=0)
読み出すデータのバイトサイズ
(ST1020:1～3072, ST1027/SC1029L:1～16384)
※開始アドレスやサイズ、また開始アドレス＋サイズの長さが範囲を超える場合は marblePORT 起動時にエラー表示され、通信処理は実
行できません。
■完了時の固有パラメータ
エクストラフィールド名
EXTRA_USER_DATA
型
byte[]
説明
読み出したデータ
7
3.4 ユーザーデータ書き込み (機能番号=3)
スマートタグの内部メモリ（Free Information Area）にデータを書き込みます。marblePORT やスマートタグによる
データフォーマットの規定はありません。必要に応じてアプリケーションでデータフォーマットを決定してくださ
い。
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
EXTRA_START_ADDRESS
型
int
int
EXTRA_USER_DATA
byte[]
必須
*
*
説明
3 を指定
書き込み開始アドレス
(ST1020: 0～3071, ST1027/SC1029L:0～16383,省略時=0)
書き込むデータ。配列内のデータ全てを書き込む。
配列サイズは
ST1020:1～3072, ST1027/SC1029L:1～16384
※開始アドレスやサイズ、また開始アドレス＋サイズの長さが範囲を超える場合は marblePORT 起動時にエラー表示され、通信処理は実
行できません。
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
説明
8
3.5 画像表示 (機能番号=4)
スマートタグのディスプレイに任意の画像を表示します。
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
EXTRA_BITMAP
型
int
Bitmap*1
必須
*
*
EXTRA_DITHER
boolean
-
EXTRA_LOCATION_X
int
-
EXTRA_LOCATION_Y
int
-
EXTRA_DRAW_MODE
int
-
EXTRA_LAYOUT_NUMBER
int
-
EXTRA_UPDATE_DISPLAY
boolean
説明
4 を指定
表示する画像データ
カラー画像の場合は白黒画像に変換される。機種別の
各ディスプレイサイズの範囲を超えた場合はエラー。
true: ディザリング（誤差拡散法）で白黒変換
false: しきい値で白黒変換 (既定値)
画像を配置する X 座標（左端が 0）
既定値=0
画像を配置する Y 座標(上端が 0)
既定値=0
背景(指定した画像の余白部分)の描画方法
0: 背景を白で塗りつぶす
1: 背景を黒で塗りつぶす
2: 既存の状態を維持 (既定値)
3: 指定した登録番号の画像
EXTRA_DRAW_MODE で 3 を指定した場合に登録番号を
指定。既定値=0（登録番号指定無し）
ディスプレイを書き換えるかどうかを指定します。複数の
部分画像を送る際に使用します。(ST1027/SC1029L)
true:ディスプレイを書き換える。(既定値)
false: ディスプレイを書き換えない。
*1: Bitmap = android.graphics.Bitmap
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
説明
3.6 表示画像登録 (機能番号=5)
スマートタグのディスプレイに表示されている画像をスマートタグ本体に登録します。登録した画像は「登録画
像表示」(機能番号=6)で表示できます。
9
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
EXTRA_LAYOUT_NUMBER
型
int
int
EXTRA_UPDATE_DISPLAY
boolean
EXTRA_BITMAP
Bitmap
■完了時の固有パラメータ
エクストラフィールド名
（無し）
必須
*
*
型
説明
5 を指定
登録する番号を指定。
（ST1020:1～12/ST1027:1～128/SC1029L:1）
登録時にディスプレイを書き換えるかどうかを指定しま
す。 (ST1027/SC1029L)
true:ディスプレイを書き換える。(既定値)
false: ディスプレイを書き換えない。
登録する画像を指定。省略した場合はスマートタグに表
示されている画像を登録します。
説明
3.7 登録画像表示 (機能番号=6)
「表示画像登録」で登録した画像をディスプレイに表示させます。何も登録されていない番号を指定した場合
は白で塗り潰します。
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
EXTRA_LAYOUT_NUMBER
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
int
int
必須
*
*
型
説明
6 を指定
表示する登録番号を指定。
（ST1020:1～12/ST1027:1～128/SC1029L:1）
説明
3.8 ディスプレイクリア (機能番号=7)
スマートタグのディスプレイをクリアします。（白で塗り潰します）
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
int
型
必須
*
説明
7 を指定
説明
10
3.9 テキスト表示 (機能番号=21)
スマートタグのディスプレイに簡易的にテキストを表示します。ディスプレイの端で自動的に折り返します。（英
単語のワードブレイク処理は行いません。） また、テキストに CR コード(0x0D)を指定すると改行します。
画面に収まらない場合は無視されます。
■起動時のパラメータ
エクストラフィールド名
EXTRA_FUNCTION_NO
EXTRA_DISPLAY_TEXT
EXTRA_TEXT_SIZE
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
int
String
int
型
必須
*
*
-
説明
21 を指定
表示するテキスト
文字の大きさ。1 以上を指定。既定値=16。
説明
11
3.10 セキュリティコード変更 (機能番号=8)
2.7 インチタイプで使用できます。ディスプレイ表示時、メモリ書き込み時、メモリ読み込み時それぞれで 3 バイト
のセキュリティコードをスマートタグ本体に設定します。
セキュリティコードを設定すると、各機能呼び出し時にセキュリティコードの指定が必要です。各機能呼び出し
時に指定したセキュリティコードと、本体に設定されたセキュリティコードが一致しないと処理は実行されません。
(エラーとしては表示されません)
セキュリティコードの変更が正常に実行されたかどうかを確認するには処理完了時にステータスを確認してくだ
さい。(『3.2 ステータス取得 (機能番号=1)』の『完了時のパラメータ』を参照。)
セキュリティコード１～３全て設定する必要はありません。必要な項目だけ設定が可能です。
セキュリティコードは工場出荷時は全て 0x30, 0x30, 0x30 です。
■起動時のパラメータ
エクストラフィールド名
型
EXTRA_FUNCTION_NO
EXTRA_SECURITY_CODE1
int
byte[]
必
須
*
(*)
EXTRA_NEW_SECURITY_CODE1
byte[]
(*)
EXTRA_SECURITY_CODE2
byte[]
(*)
EXTRA_NEW_SECURITY_CODE2
byte[]
(*)
EXTRA_SECURITY_CODE3
byte[]
(*)
EXTRA_NEW_SECURITY_CODE3
byte[]
(*)
■完了時の固有パラメータ
エクストラフィールド名
（無し）
型
説明
8 を指定
ディスプレイ表示用
変更前のセキュリティコード 3 バイト
ディスプレイ表示用
変更後のセキュリティコード 3 バイト
メモリ書き込み用
変更前のセキュリティコード 3 バイト
メモリ書き込み用
変更後のセキュリティコード 3 バイト
メモリ読み込み用
変更前のセキュリティコード 3 バイト
メモリ読み込み用
変更後のセキュリティコード 3 バイト
説明
3.11 複合処理
一回の marblePORT 起動で複数の処理を実行できます。ユーザーデータ読み取り／書き込み、画像表示、登
録画像表示、ディスプレイクリアの機能から以下で表す組み合わせが可能です。
組み合わせに対する機能番号を指定し、必要なパラメータを設定して marblePORT を起動します。必要なパラ
メータは個々の機能の説明を参照してください。
12
■使用可能な組み合わせ
組み合わせ(この順に実行)
ユーザーデータ読込→画像表示
ユーザーデータ読込→登録画像表示
ユーザーデータ読込→ディスプレイクリア
ユーザーデータ読込→ユーザーデータ書込
ユーザーデータ読込→ユーザーデータ書込→画像表示
ユーザーデータ読込→ユーザーデータ書込→登録画像表示
ユーザーデータ読込→ユーザーデータ書込→ディスプレイクリア
ユーザーデータ書込→画像表示
ユーザーデータ書込→登録画像表示
ユーザーデータ書込→ディスプレイクリア
機能番号
31
32
33
34
41
42
43
51
52
53
※処理中の通信エラー発生時について
途中で通信エラーになった場合は再度スマートタグをタッチすると処理を初めからやり直します。ただし、ユー
ザーデータ読込があるパターンの時では、ユーザーデータ読込が正常に完了している場合はデータがキャッ
シュされ、やり直した時に読込を飛ばして次の処理を実行します。
※ユーザーデータ読込と書込時の開始アドレスについて
読み込みと書き込みの組み合わせの時は、読み込みの開始アドレスのエクストラフィールド名は
"EXTRA_START_ADDRESS"、書き込みの開始アドレスのエクストラフィールド名は
"EXTRA_START_ADDRESS2"を使用してください。
13
4. オプションパラメータ
オプションとして設定可能なパラメータについて説明します。
4.1 完了時の動作
スマートタグをかざし、通信処理が終わった後の動作を指定します。
起動時に指定
エクストラフィールド名
EXTRA_AUTO_CLOSE
型
int
説明
0: 処理完了後画面は表示されたままにする（戻るときは
「戻る」ボタンを押す）
1: スマートタグを端末から離したときに閉じる （既定値）
2: 処理が完了次第直ちに閉じる
※"0"を指定して画面が表示されたままの状態で再度スマートタグをかざすと、同じ処理をもう一度実行しま
す。
4.2 プログレスバー表示
スマートタグとの通信中、プログレスバーを表示するかどうかを指定を行います。
起動時に指定
エクストラフィールド名
EXTRA_SHOW_PROGRESS
型
boolean
説明
true: 表示する
false: 表示しない (既定値)
4.3 タイトル/メッセージのカスタマイズ
marblePORT 画面のタイトルと各種メッセージを指定します。
タイトルは 1 行に収まるようにしてください。収まらない場合は省略されます。
メッセージは端で折り返しますが、2 行に収まるようにしてください。3 行になるとスマートタグの絵と重なって見
づらくなります。
14
タイトル
メッセージ
起動時に指定
エクストラフィールド名
EXTRA_TITLE
EXTRA_MSG_SCAN
EXTRA_MSG_PROCESSING
EXTRA_MSG_END
EXTRA_MSG_IO_ERROR
型
String
String
String
String
String
説明
タイトル欄のテキストを指定
スマートタグのスキャン待ちに表示するメッセージを指定
通信中に表示するメッセージを指定
通信完了時に表示するメッセージを指定
通信エラーが発生した時のメッセージを指定
(エラー内容を表す表示は画面下部に表示されます。)
4.4 通信に使用するタグのインスタンス指定 (NFC 対応端末のみ)
スマートタグとの通信で使用する Tag オブジェクト（android.nfc.Tag）を指定できます。NFC 対応端末のみで使
用します。
以下の３つのフィールド全てを指定します。
具体的な使用方法は後述します。
起動時に指定
エクストラフィールド名
EXTRA_RELAY_TAG
型
boolean
EXTRA_ACTIVE_TAG
Tag
EXTRA_IDM
byte[]
説明
タグインスタンスを渡す場合に true を指定。それ以外は
false を指定（既定値）。
渡す Tag オブジェクト。通信が可能な Tag の情報である必
要があります。
通信するスマートタグの IDm
4.5 完了時のバイブレータ動作
marblePORT がスマートタグとの通信を完了した直後にバイブレータの動作させるかどうかを指定します。
15
起動時に指定
エクストラフィールド名
EXTRA_VIBRATE
型
int
EXTRA_VIBRATE_DURATION
int
説明
0: 何もしない(既定値)
1: バイブレータを振動させる
振動させるミリ秒数を指定する。(0～10000)
4.6 スマートタグの機種指定
スマートタグの機種を指定します。指定しない場合は 2 インチタイプとして動作します。2.7 インチタイプを使用
する場合は marblePORT を呼び出す都度このオプションを使用してください。
起動時に指定
エクストラフィールド名
EXTRA_SMART_TAG_TYPE
型
int
説明
20: 2 インチタイプ(既定値)
27: 2.7 インチタイプ
29: 2.9 インチタイプ
4.7 セキュリティコード指定
ST1027(2.7 インチタイプのスマートタグ)の場合、ディスプレイの変更、メモリの書き込み、メモリの読み出しの時
に 3 バイトのセキュリティコードが必要です。あらかじめスマートタグ本体に設定されているセキュリティコードと
同じコードを指定する必要があります。工場出荷時のセキュリティコードは"000"(0x30, 0x30, 0x30)です。
指定を省略した場合は"000"と見なします。
起動時に指定
エクストラフィールド名
EXTRA_SECURITY_CODE1
型
byte[]
EXTRA_SECURITY_CODE2
EXTRA_SECURITY_CODE3
byte[]
byte[]
説明
ディスプレイ更新(画像表示/ディスプレイクリア/レイアウト
登録)用のセキュリティコード(3byte)
メモリ書き込み用のセキュリティコード(3byte)
メモリ読み込み用のセキュリティコード(3byte)
4.8 おサイフケータイを明示的に使用する
おサイフケータイと NFC を両方使用出来る端末の場合、marblePORT は NFC を優先して使用します。おサイ
フケータイでスマートタグと通信するよう指定することができます。
（おサイフケータイでは最大同時転送ブロック数は 8 です。必要に応じて marblePORT の設定画面で設定して
ください。）
16
起動時に指定
エクストラフィールド名
EXTRA_USE_FELICA
型
boolean
説明
false: NFC 優先 (既定値)
true: おサイフケータイ(モバイル Felica)を使用する
4.9 処理の最後にステータス確認を行う
スマートタグの処理が完全に完了するまで marblePORT の画面を「完了」にしたくない場合に使用します。
画面書換えを伴う処理の後にステータス確認を行うと、スマートタグの画面の描画の完了をもって通信完了とな
ります。
起動時に指定
エクストラフィールド名
EXTRA_CHECK_STATUS_AFTER_PROCESS
型
boolean
説明
false: 確認しない (既定値)
true: 確認する
※バージョン 1.2 からはこのオプションに関わらず、通信完了直後に 1 回だけステータス取得を行うようになりま
した。ステータスが 0xF0（正常終了）または 0xF2(処理中)の場合のみ正常終了とみなし、それ以外の場合はエ
ラーとして再度スマートタグをかざすよう要求する画面になります。
17
5. 応用的な使用方法
応用的な使用方法について説明します。
5.1 複数の処理を連続実行する
marblePORT では一回の起動で行えるスマートタグの通信処理のバリエーションは限られています。一回のス
マートタグスキャンでより複雑な通信を行いたい場合は、スマートタグをかざしている間に marblePORT の終了
と起動を繰り返して、複数の処理を行うことができます。
NFC 対応端末とおサイフケータイで若干処理が異なります。
5.1.1 NFC 対応端末の場合
基本的に連続して処理を起動させます。ただし NFC 対応端末では１回目の処理でスマートタグをかざした時の
タグの情報（Tag オブジェクトと IDm）を、2 回目以降の処理で使い回す必要があります。
1 回目の処理完了時にホストアプリケーションは返ってきたインテントの情報から Tag オブジェクトと IDm を取得
し、2 回目以降の処理呼び出し時にパラメータとして指定します。
処理完了時に受け取る情報
エクストラフィールド名
型
EXTRA_ACTIVE_TAG
Tag
EXTRA_IDM
byte[]
説明
処理中に使用した Tag オブジェクト。
スマートタグの IDm
次の処理起動時に指定するパラメータ
エクストラフィールド名
型
EXTRA_RELAY_TAG
boolean
EXTRA_ACTIVE_TAG
Tag
EXTRA_IDM
byte[]
説明
true を指定。
処理完了時に受け取った Tag オブジェクト。
スマートタグの IDm
また、最後の処理以外ではパラメータ"EXTRA_AUTO_CLOSE"（処理完了時の動作指定）で画面をすぐに閉
じるように設定(設定値=2)する必要があります。
18
5.1.2 おサイフケータイ対応端末の場合
おサイフケータイ対応端末の場合は単純に連続起動するだけで処理ができます。最後に実行される処理以外
は通信処理完了後にすぐ画面が閉じるようにオプション設定を行います。
※おサイフケータイ端末上で NFC 対応端末の手順で実行しても問題はありません。（処理は共通化できます）
5.2 独自にタグの検出を行う (NFC のみ)
通常の marblePORT の呼び出しではホストアプリケーションから起動後にスマートタグをスキャンという操作にな
りますが、ホストアプリケーション上でタグの検出を行い、通信処理だけ marblePORT に任せることができます。
ホストアプリケーションでタグの検出ができるのは NFC 環境のみです。また、Android SDK の NFC 関連のプロ
グラミングの知識が必要になります。
(1) ホストアプリケーションで NfcF クラス（android.nfc.tech.NfcF）に対応したタグを OS からインテントで受け取
れるように設定します。
(2) スマートタグが検出されたときに発生する onNewIntent メソッドで渡される Intent オブジェクトから Tag オブ
ジェクト(EXTRA_TAG)とスマートタグの ID(EXTRA_ID)を取得します。
(3) EXTRA_RELAY_TAG, EXTRA_ACTIVE_TAG, EXTRA_IDM のオプション設定とともに機能番号を設
定して marblePORT を起動します。
(4) marblePORT は渡された Tag オブジェクトと IDm を使用して処理を行います。
5.3 通信ログを使用する
marblePORT とスマートタグの間の通信内容の一部をログファイルに保存し、確認することができます。ログに記
録されるのはスマートタグの ID と通信コマンドのヘッダ部のみで、画像やユーザーデータは記録されることはあ
りません。ログファイルに必要な容量は約 2MByte です。それ以上ログが増えた場合は古いログから 1MByte 分
削除され、新しいログが記録されていきます。
ログの有効化
ログの有効無効は marblePORT の設定画面の操作によって行います。デフォルトは無効になっています。
設定画面は marblePORT の画面下部にあるスパナのアイコンをタッチして表示します。
[通信ログを有効にする]という項目にチェックを入れると有効になります。一度有効にすると次回 marblePORT
起動時も維持されます。
19
設定画面
ここをタッチ
ログの保存場所
ログは"/sdcard/aioisystems/marbleport/"の中に作成されます。保存場所の指定はできません。
ログファイル名
log.txt
log.bak.txt
最新のログが最大約 1MB 保存されます。1MB を超えると"log.bak.txt"にリネームされます。
log.txt より以前のログ 1MB 分が保存されています。
ログファイルの見方
スマートタグをかざした時の時刻
とその ID
W: スマートタグへの書き込み（送信）
R: スマートタグからの読み込み(受信)
スマートタグコマンドの先頭 1 ブロックのバイト値 (16 進数)
(セキュリティコードは**と表示)
ログに記録される内容
スマートタグコマンドのみ記録されます。(FeliCa のポーリングコマンド等は記録されません)
実際の通信は FeliCa コマンドで行われていますが、その中に含まれるスマートタグコマンドの部分のみを記
録しています。
送信時の再送が発生した場合は再送コマンドの直前に"retry sending."と 1 行記録されます。送信エラー判
定された場合は"sending error."と 1 行記録されます。
20
6. エラー時の挙動
marblePORT での処理時にエラーが発生した場合の挙動について説明します。
6.1 開始時のエラー
NFC またはおサイフケータイに対応してない場合
marblePORT は起動すると NFC の環境かおサイフケータイの環境かを判断するため、まずは NFC での開始を
試みます。
NfcAdapter クラス（android.nfc.NfcAdapter）の getDefaultAdapter メソッドを実行し、戻り値が null だった場合は
NFC 非対応と見なし、次におサイフケータイでの開始を試みます。
おサイフケータイでの開始でエラーが発生するとおサイフケータイ用 SDK（モバイル FeliCa クライアント）が出力
するエラー情報を表示します。
NFC、おサイフケータイの両方の開始処理でエラーになった場合は marblePORT の画面はエラー情報を表示
したままになり、スマートタグをかざしても反応しません。
Android の[戻る]ボタンを押すとホストアプリケーションに戻ります。この時 onActivityResult で取得できる
resultCode は RESULT_ERROR_CANCEL(=1)です。
NFC が OS の設定によって[無効]にされている場合
marblePORT 起動時に NFC が無効に設定されていると判断した場合、無効になっているという旨のメッセージ
を表示します。（スマートタグをかざしても反応しません。）
Android の[戻る]ボタンを押すとホストアプリケーションに戻ります。この時も onActivityResult で取得できる
resultCode は RESULT_ERROR_CANCEL(=1)です。
OS の設定画面で NFC を有効にすることで marblePORT が使用出来るようになります。
6.2 通信処理中のエラー
通信処理中にスマートタグを離してしまったなどの理由で通信が途切れた場合などに通信が失敗した旨のメッ
セージを表示し、画面下部にはエラーの種類を表示します。
21
表示されるエラーの種類
通信エラー
スマートタグエラー
不明なエラー
タグが NFC 搬送波から外れてしまい、通信が失敗。
「最大同時転送ブロック」と表示された場合は同時転送ブロックが大きすぎ
る。
スマートタグでのステータス異常。ステータスも画面に表示される。
F3～F8, FF: コマンドフォーマットに関するエラー。
FD, FE, F5: ハード的な異常
70: エラーコード無し
marblePORT で想定していないその他のエラー。
※ Android SDK ツールの LogCat でもエラーの詳細を確認できます。（タグ: marblePORT）
上記のエラー発生後はホストアプリケーションで指定したオプションに関係なく画面は表示されたままになりま
す。このときスマートタグを一度離して再度かざすと処理をやり直します。
Android の[戻る]ボタンを押すとホストアプリケーションに戻ります。この時 onActivityResult で取得できる
resultCode は RESULT_ERROR_CANCEL(=1)です。
6.3 電池残量が少ない時の挙動
電池残量のステータスが少ない時(2 または 3)に通信処理を行うと marblePORT 上の画面では通常通り通信処
理が完了したように見えます。スマートタグは電池残量が僅かな時はコマンドの通信応答処理は正常に行いま
すが、スマートタグ内部の処理を行わないためです。
marblePORT では通信完了後、電池残量が 2 または 3 の時は画面下に残量が少ない旨のメッセージを表示し
ます。
22
電池残量のステータスが 2 の時: 『少なくなっています』
電池残量のステータスが 3 の時: 『使用できません』
呼び出し元のアプリケーションでは、mablePORT の終了後 EXTRA_BATTERY で電池残量のステータス値を取
得できます。(『2.3 marblePORT からデータを受け取る』参照)
※上記のメッセージが表示された後でも環境や状態によって 0 や 1 に復帰する場合もあります。
23
7. 資料
7.1 パラメータ一覧
機能番号指定
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
説明
0: 状態表示
機能番号
1: 状態取得
2: データ読取
3: データ書込
4: ディスプレイ表示
5: 表示画像登録
6: 登録画像表示
7: ディスプレイクリア
8: セキュリティコード変更
21: テキスト表示
複合処理の機能番号
複合処理
機能番号
ユーザーデータ読込→画像表示
31
ユーザーデータ読込→登録画像表示
32
ユーザーデータ読込→ディスプレイクリア
33
ユーザーデータ読込→ユーザーデータ書込
34
ユーザーデータ読込→ユーザーデータ書込→画像表示
41
ユーザーデータ読込→ユーザーデータ書込→登録画像表示
42
ユーザーデータ読込→ユーザーデータ書込→ディスプレイクリア
43
ユーザーデータ書込→画像表示
51
ユーザーデータ書込→登録画像表示
52
ユーザーデータ書込→ディスプレイクリア
53
状態表示パラメータ
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
0
24
説明
ステータス取得
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
説明
EXTRA_IDM
byte[]
IDm
EXTRA_BATTERY
byte
電池状態
EXTRA_TAG_STATUS
byte
スマートタグのステータス
EXTRA_FIRMWARE_VERSION
byte
スマートタグのファームウェアバージョン
1
ユーザデータ読み取り
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
EXTRA_START_ADDRESS
int
0-3071(ST1020)
説明
2
開始アドレス
0-16383
(ST1027/SC1029L)
既定値:0
EXTRA_READ_SIZE
int
1-3072 (ST1020)
読み出すデータのバイトサイズ
1-16384
(ST1027/SC1029L)
EXTRA_USER_DATA
byte[]
読み出したデータ
ユーザデータ書き込み
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
EXTRA_START_ADDRESS
int
0-3071 (ST1020)
説明
3
書き込み開始アドレス
0-16383
(ST1027/SC1029L)
既定値:0
EXTRA_USER_DATA
byte[]
書き込むデータ
画像表示
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
EXTRA_BITMAP
Bitmap
EXTRA_DITHER
boolean
EXTRA_LOCATION_X
int
値
説明
4
表示する画像データ
true: ディザリング
false: しきい値(既定)
0(既定) – 199 (ST1020)
表示位置(左端が 0)
0-263 (ST1027)
0-299 (SC1029L)
EXTRA_LOCATION_Y
int
0(既定) – 95 (ST1020)
表示位置(上端が 0)
0-175 (ST1027)
0-199 (SC1029L)
EXTRA_DRAW_MODE
int
0: 背景を白で塗りつぶす
背景(指定画像の周辺の
1: 背景を黒で塗りつぶす
余白部分)の描画指定
2: 既存の状態を維持 (既定)
3: 指定した登録番号の画像
EXTRA_LAYOUT_NUMBER
int
0(既定):登録画像指定無し
1 以上: 登録画像番号
1-12(ST1020)/1-128(ST1027)/
1 (SC1029L)
25
EXTRA_UPDATE_DISPLAY
boolean
true:ディスプレイを書き換え
ST1027/SC1029L 専用
る。(既定値)
false: ディスプレイを書き換え
ない。
表示画像登録
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
EXTRA_LAYOUT_NUMBER
int
1-12(ST1020)
説明
5
登録番号
1-128(ST1027)
1(SC1029L)
EXTRA_UPDATE_DISPLAY
boolean
true:ディスプレイを書き換える。
ST1027/SC1029L 専用
(既定値)
false: ディスプレイを書き換えな
い。
EXTRA_BITMAP
Bitmap
登録する画像を指定。
登録画像表示
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
EXTRA_LAYOUT_NUMBER
int
1-12(ST1020)
説明
6
登録番号
1-128(ST1027)
1(SC1029L)
ディスプレイクリア
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
Extra フィールド名
EXTRA_FUNCTION_NO
型
int
値
EXTRA_DISPLAY_TEXT
String
EXTRA_TEXT_SIZE
int
既定値:16
型
int
値
説明
7
テキスト表示
説明
21
表示テキスト
文字の大きさ
オプション - 完了時の動作
Extra フィールド名
EXTRA_AUTO_CLOSE
説明
0:閉じない
1:離したら閉じる（既定）
2:直ちに閉じる
オプション – プログレスバー表示
Extra フィールド名
EXTRA_SHOW_PROGRESS
型
boolean
値
説明
true: 表示する
false: 表示しない (既定)
オプション – タイトル/メッセージのカスタマイズ
Extra フィールド名
EXTRA_TITLE
型
String
値
説明
EXTRA_MSG_SCAN
String
スキャン待ち
EXTRA_MSG_PROCESSING
String
通信中
タイトル欄
26
EXTRA_MSG_END
String
通信完了
EXTRA_MSG_IO_ERROR
String
通信失敗
オプション – タグのインスタンス指定
Extra フィールド名
EXTRA_RELAY_TAG
型
boolean
値
説明
EXTRA_ACTIVE_TAG
Tag
Tag オブジェクト
EXTRA_IDM
byte[]
IDm
true: 使用する
false: 使用しない(既定)
オプション – 完了時のバイブレータ動作
Extra フィールド名
EXTRA_VIBRATE
型
int
値
説明
0: 何もしない(既定値)
1: バイブレータを振動させる
オプション – スマートタグの機種指定
Extra フィールド名
EXTRA_SMART_TAG_TYPE
型
int
値
説明
20: 2 インチタイプ(既定値)
27: 2.7 インチタイプ
29: 2.9 インチタイプ
オプション – セキュリティコード指定 (ST1027, SC1029L 専用)
Extra フィールド名
EXTRA_SECURITY_CODE1
型
byte[]
値
説明
EXTRA_SECURITY_CODE2
byte[]
メモリ書き込み用のセキュリティコード(3byte)
EXTRA_SECURITY_CODE3
byte[]
メモリ読み込み用のセキュリティコード(3byte)
ディスプレイ更新用のセキュリティコード(3byte)
オプション – おサイフケータイを明示的に使用する
Extra フィールド名
EXTRA_USE_FELICA
型
boolean
値
説明
false: NFC 優先 (既定値)
true: おサイフケータイを使用する
オプション – 処理の最後にステータス確認を行う
Extra フィールド名
EXTRA_CHECK_STATUS_AFTER_PROCESS
型
boolean
値
false: 確認しない (既定値)
true: 確認する
7.2 marblePORT のバージョンコード
marblePORT のバージョン名とバージョンコードの対応は以下の通りです。
バージョン名
バージョンコード
1.0.0
100
1.1.0
110
1.2.0
120
1.3.0
130
1.3.1
131
27
説明
[ご注意]
株式会社アイオイシステムの書面による許可を得ることなく、マニュアルの一部または全部を複
写、複製することは、その形態にかかわらず禁じます。
このマニュアルに記載されている事項は、予告無しに変更することがあります。
このソフトウェアの仕様は予告無しに変更することがあります。
*
*
*
*
*
Android は Google Inc.の商標または登録商標です。
Eclipse は，Eclipse Foundation, Inc.の登録商標です。
Java は Oracle Corporation またはその関連会社の登録商標です。
『おサイフケータイ』は株式会社 NTT ドコモの登録商標です。
『FeliCa』は、ソニー株式会社の登録商標です。
marblePORT ver.1.3 プログラミングガイド
〒143-0016 東京都大田区大森北 1-6-8 ウィラ大森ビル 8 階
TEL 03（3764）0228（代表）
FAX 03（3764）7520
e-mail [email protected]
web http://www.hello-aioi.com/
Copyright(C)2015 AIOI・SYSTEMS CO., LTD.