Canarium RPC Server

Canarium RPCはFlashAirを使ってFPGAリソースへのアクセスを提供するリモートプロシージャコール(RPC)ライブラリです。
インターフェースはJSON-RPCをベースにFlashAirのHTTPサーバーの制約にあわせて変更しています。
canarium_rpc.lua および crs.lua はFlashAir側にRPCサーバー機能を提供します。クライアント側はCanarium RPC Clientを参照してください。

ライセンス

The MIT License (MIT)
Copyright (c) 2017-2019 J-7SYSTEM WORKS LIMITED.

対象環境

FlashAir W-04 ファーム W4.00.03 以降
Canarium Air I/O v0.3.0726 以降

使い方

FlashAir準備

FlashAirのGPIOモードを使用します。/SD_WLAN/CONFIG ファイルに IFMODE=1 を追加します。
canarium_rpc.lua と canarium_air.lua をFlashAirの任意のフォルダに格納します。
CanariumRPC over HTTPを使う場合は crs.lua をFlashAirのルートに格納します。
環境にあわせて crs.lua の先頭部分を修正します。

-- 格納したフォルダに修正
require "/foo/bar/canarium_air"
require "/foo/bar/canarium_rpc"

-- カレントフォルダをルート以外にする場合に追加
cr.setpath("/foo/bar")

設定が終わったFlashAirを再起動します。

RPC呼び出し

クライアント側からFlashAirが認識できるようになった後は

http://flashair/crs.lua?<クエリ>

を呼び出します。クエリはRPCへのパラメータをBase64urlでエンコードした文字列です。
レスポンスはJSON-RPC形式で返します。

呼び出し例

FPGAがコンフィグされてるかどうかのチェックをする

> GET http://flashair/crs.lua?MDkBAQE

HTTPレスポンス

> HTTP/1.1 200 OK
> Access-Control-Allow-Origin: *
> Connection: close
> Content-Type: application/json; charset=utf-8
> Content-Length: 38
>
> {"jsonrpc":"2.0","result":1,"id":12345}
>

クエリの詳細についてはクエリリファレンスを参照してください。

関数リファレンス

cr.version

Canarium RPCのバージョンを取得します。

書式
string cr.version()
記述例

ver = cr.version()

引数
なし
返値
- ver
  バージョンを string で返します。

cr.setpath

RPCサーバーのカレントパスを指定します。パスの初期値は実行したLuaファイルのカレントフォルダが設定されます。
またクエリのファイルパスは、デフォルトでは相対パスのみ許可されていますが、この関数の第2引数で絶対パス指定の許可・禁止を操作することができます。省略時は false です。

書式
string cr.setpath( [string path, [boolean ena_abs] ] )
記述例

-- カレントパスの設定
cr.setpath("/lua/rpc")

-- カレントパスの取得
cur_path = cr.setpath()

引数
- path
  カレントパスを string 指定します。"/"から始まるパスは絶対パス、それ以外はカレントパスからの相対パスとして認識されます。親パス("..")の指定はできません。
- ena_abs
  クエリのファイルパスで絶対パスを許可するかどうかを boolean で指定します。省略時は false です。
返値
- cur_path
  引数を省略した場合、現在設定されているカレントパスを string で返します。

cr.setmethod

RPCサーバーに対してメソッドの追加・削除を行います。

書式
boolean cr.setmethod( string name, [number cmd, function function] )
記述例

-- メソッドの登録
res = cr.setmethod("USER", 0x40, function(cstr) ... end)

-- メソッドの削除
res = cr.setmethod("USER")

引数
- name
  追加または削除するメソッド名を string で指定します。既に同じ名前のメソッドがある場合は後から指定したものに更新されます。
  name のみを指定した場合、既に登録されているメソッドを削除します。
- cmd
  このメソッドに割り当てる識別番号を number で指定します。指定出来る範囲は 0x00 ～ 0x7f です。また 0x00 ～ 0x2f は組み込み用に予約されています。
  既に同じ識別番号のメソッドがある場合は後から指定したものに更新されます。
- function
  クエリから呼び出されるメソッドの本体となる関数を function で指定します。
  引数にはクエリのペイロードデータ部が string で渡されます。
返値
- res
  関数の処理結果を boolean で返します。成功の場合は true 、失敗の場合は false です。

cr.update

メソッド関数の中で、進捗情報のアップデートを行います。
この関数は cr.setmethod() で指定する関数以外からは呼ぶことができません。

書式
cr.update( number ... )
記述例

res = cr.setmethod("USER", 0x40, function(cstr)
    for i=1,100 do
      -- メソッドの処理 --
        ... 
      -- 進捗度の更新
      cr.update(i)
    end
  end)

引数
- ...
  進捗度を number で指定します。値の範囲は 0 ~ 100 です。
  メソッド内で複数の処理ステージを持つ場合は、任意の数だけ進捗度を指定することができます。
  進捗情報は進捗ステータスでJSON文字列として取得するため、多数のステージを持つ進捗情報はクライアントによっては正しいデータを取得できない場合があります。
返値
なし

cr.parse

クエリ文字列を解釈してメソッドを実行します。

書式
string cr.parse( [string query] )
記述例

res_json = cr.parse(query)

引数
- query
  実行するクエリ文字列を string で指定します。クエリ詳細はクエリリファレンスを参照してください。
  この引数を省略した場合はVERクエリが実行されます。
返値
- res_json
  メソッドの実行結果をJSON-RPCレスポンスの string で返します。詳細はJSONレスポンスを参照してください。

クエリリファレンス

エンコード

クエリは最大74バイトのバイナリパケットをBase64url (RFC4648) で文字列にエンコードしたものです。最大100文字のURI文字列になります。

*変換の例
  packet : 30 39 13 96 08 68 6f 73 74 74 65 73 74 5f 6f 6c 69 76 65 2e 72 62 66
    ↓
  query : MDkTlghob3N0dGVzdF9vbGl2ZS5yYmY

パケットフレーム

パケットは下記のに示すフォーマットでデータを格納します。

バイト
  +0   ID値(上位8bit)
  +1   ID値(下位8bit)
  +2   ペイロード長(5バイト目以降のデータ長を示す)
  +3   チェック値(ペイロードデータの各バイトを演算した値)
  +4   ペイロードデータ(FlashAir W-04では最大70バイト)
  :
 +73

ID値は16bitの符号なし整数値で、JSON-PRCのidフィールドの値です。
チェック値はペイロードデータの各バイトを次のような演算で計算した結果です。

for(xsum=0,i=0 ; i < n ; i++) {
    xsum = (byte[i] ^ ((xsum << 1) | ((xsum & 0x80)? 1 : 0))) & 0xff;
}

ファイルについて

クエリで指定するファイルはFlashAir側のストレージに格納されているものに限ります。
必要なファイルは予めカードに保存しておくか、FlashAir用のツール（あるいは upload.cgi ）でファイルを転送してください。
同様にクエリの結果として書き出されるファイルはFlashAirのストレージに保存されます。必要に応じてクライアント側にダウンロードしてください。

ファイルパスは次のような書き方ができます。

*カレントフォルダのファイルを指定
  "testfile2.bin"
  "./testfile3.hex"

*カレントフォルダ以下の子フォルダを指定
  "test/romdata.srec"

*ファイルをフルパスで指定（許可されている場合のみ）
  "/foo/bar/testfile1.rbf"

ファイル名、ファイルパス共に日本語を含む多バイト長文字は使用できません。

JSONレスポンス

クエリのレスポンスはJSON-RPCに則った形式で返されます。

正常レスポンス

{
  "jsonrpc" : "2.0",
  "result" : <boolean> or <number> or <string> or <object>,
  "id" : <number>
}

エラーレスポンス

{
  "jsonrpc" : "2.0",
  "error" : {
    "code" : <number>,
    "message" : <string>
  },
  "id" : <number>
}

プロパティ
- jsonrpc
  string で "2.0" の固定値が入ります。
- id
  クエリでリクエストしたID値が number で入ります。
- result
  正常終了の場合に結果が入ります。 boolean、number (32bit整数値)、string (Base64urlでエンコードされたバイナリ列)、object 等が格納されます。
- error
  エラーの場合は、result の代わりにこのオブジェクトを返します。
  - code : エラーコードが number で入ります。値はJSON-RPCに準拠します。
  - message : エラーメッセージがある場合は string で入ります。
エラーコード
- パースエラー
  error : {"code":-32700, "message":"Parse error"}
  クエリをデコードできなかった、または不正なパケット形式を検出した場合に返されます。
- メソッド呼び出しエラー
  error : {"code":-32601, "message":"Method not found"}
  メソッドが存在しない場合に返されます。
- メソッド実行時エラー
  error : {"code":-32000, "message":<エラーメッセージ>}
  メソッドの実行が失敗した場合に返されます。message キーには内部で返されるメッセージが string で入ります。

VERクエリ

ライブラリのバージョンを取得します。

このクエリのみ文字列なしで crs.lua を呼び出します。
レスポンスには id キーはありません。

返値プロパティ
- result
  RPCサーバーのバージョン情報を object で返します。
  - rpc_version : Canarium RPCのバージョンが string で入ります。
  - lib_version : Canarium Air I/Oのバージョンが string で入ります。
  - fa_version : FlashAirのファームウェアバージョンが string で入ります。

CHECKクエリ

FPGAがコンフィグレーション済みかどうかをチェックします。

ペイロードデータ

[0x01]

返値プロパティ
- result
  FPGAの状態を number で返します。
  - 1 : コンフィグレーションされている
  - 0 : 未コンフィグレーション状態
  - それ以外 : 予約

STATクエリ

現在のRPCサーバーやFlashAirの情報を返します。

ペイロードデータ

[0x02]

返値プロパティ
- result
  RPCサーバーやFlashAirの情報 object で返します。
  - current_path : RPCサーバーのカレントパスが string で入ります。
  - absolute_access : RPCサーバーで絶対パスでのアクセスの可否が boolean で入ります。
  - file_upload : ファイルアップロードが有効かどうかが boolean で入ります。
  - cid : FlashAirのカードユニークIDが string で入ります。
  - mac_address : FlashAirのMACアドレスが string で入ります。
  - ip_address : FlashAirのIPアドレスが string で入ります。
  - ip_mask : FlashAirのサブネットマスクが string で入ります。
  - netname : FlashAirのネット識別名が string で入ります。
  - appinfo : FlashAirで設定したAPPINFOがあればその文字列が string で入ります。
  - timezone : FlashAirで設定したタイムゾーンの値が number で入ります。

CONFクエリ

FPGAのコンフィグレーションを行います。
既に生成されたキャッシュファイルが存在する場合はそれを利用して、短縮コンフィグレーションを行います。

ペイロードデータ

[0x08 <filename>]

パラメータ
- filename
  コンフィグレーションするRBFファイル名を指定します。ファイル名の文字列をバイト列にして格納します。
返値プロパティ
- result
  完了で true を返します。

クエリ完了またはエラー発生までレスポンスが返らないため、クライアント側でタイムアウト処理時間には注意が必要です。

コンフィグレーション含め、実行時にキャッシュファイルを作成するため時間がかかります。必要に応じて進捗ステータスを取得してください。

FCONFクエリ

FPGAのコンフィグレーションを行います。
このクエリは、既にキャッシュファイルが存在する場合でも指定のコンフィグレーションファイルでキャッシュファイルを再生成して、FPGAコンフィグレーションを行います。

ペイロードデータ

[0x09 <filename>]

パラメータ
- filename
  コンフィグレーションするRBFファイル名を指定します。ファイル名の文字列をバイト列にして格納します。
返値プロパティ
- result
  完了で true を返します。

備考についてはCONFクエリを参照してください。

IOWRクエリ

Qsysモジュール（FPGA内部ロジックコア）のペリフェラルレジスタにデータを書き込みます。

ペイロードデータ

[0x10 0x55 <address> <wrdata>]

パラメータ
- address
  書き込みアドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
  アドレス値は32bitのワード境界に整列していなければなりません。
- wrdata
  書き込みデータを4バイトで指定します。格納順はネットワークバイトオーダーです。
返値プロパティ
- result
  完了で true を返します。

このクエリは、Avalon-MMのメモリバス（Qsysモジュール内部メモリ空間）で32bitワード単位のアトミックなライトアクセスを保証します。

IORDクエリ

Qsysモジュール（FPGA内部ロジックコア）のペリフェラルレジスタからデータを読み出します。

ペイロードデータ

[0x11 0x55 <address>]

パラメータ
- address
  読み出しアドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
  アドレス値は32bitのワード境界に整列していなければなりません。
返値プロパティ
- result
  読み出した値を number (32bit符号無し整数)で返します。

このクエリは、Avalon-MMのメモリバス（Qsysモジュール内部メモリ空間）で32bitワード単位のアトミックなリードアクセスを保証します。

MEMWRクエリ

Qsysモジュール（FPGA内部ロジックコア）の任意のメモリアドレスにバイトデータ列を書き込みます。

ペイロードデータ

[0x18 0x55 <address> <databyte>]

パラメータ
- address
  書き込み先頭アドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
- databyte
  書き込むデータ列をバイトアドレス順で格納します。最大長は64バイトです。
返値プロパティ
- result
  完了で true を返します。

MEMRDクエリ

Qsysモジュール（FPGA内部ロジックコア）の任意のメモリアドレスからバイトデータ列を読み出します。

ペイロードデータ

[0x19 0x55 <address> <size>]

パラメータ
- address
  読み出し先頭アドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
- size
  読み出すバイト数を2バイトで指定します。格納順はネットワークバイトオーダーです。
  指定可能な範囲は 1 ～　256です。
返値プロパティ
- result
  読み出したバイト列をBase64urlでエンコードした文字列が string で返されます。

BLOADクエリ

Qsysモジュール（FPGA内部ロジックコア）の任意のメモリアドレスにファイルイメージをロードします。

ペイロードデータ

[0x20 0x55 <address> <filename>]

パラメータ
- address
  書き込み先頭アドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
- filename
  ロードするファイル名を指定します。ファイル名の文字列をバイト列にして格納します。
返値プロパティ
- result
  完了で true を返します。

クエリ完了またはエラー発生までレスポンスが返らないため、クライアント側でタイムアウト処理時間には注意が必要です。必要に応じて進捗ステータスを取得してください。

BSAVEクエリ

Qsysモジュール（FPGA内部ロジックコア）の任意アドレスのメモリイメージをファイルに保存します。

ペイロードデータ

[0x21 0x55 <address> <imagesize> <filename>]

パラメータ
- address
  先頭アドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
- imagesize
  保存するメモリイメージのバイトサイズを4バイトで指定します。格納順はネットワークバイトオーダーです。
- filename
  保存先のファイル名を指定します。ファイル名の文字列をバイト列にして格納します。
  同名のファイルが既に存在していた場合は上書きされます。
返値プロパティ
- result
  完了で true を返します。

備考についてはBLOADクエリを参照してください。

LOADクエリ

Qsysモジュール（FPGA内部ロジックコア）のメモリアドレス空間に、IntelHEX形式またはモトローラS-record形式のROMデータファイルをロードします。

ペイロードデータ

[0x22 0x55 <offset> <filename>]

パラメータ
- offset
  オフセットアドレスを4バイトで指定します。格納順はネットワークバイトオーダーです。
  この値とROMデータファイルのアドレス値を加算したアドレスへ書き込みが行われます。0 を指定した場合、ROMデータファイルのアブソリュートアドレスとなります。
- filename
  ロードするファイル名を指定します。ファイル名の文字列をバイト列にして格納します。
  IntelHEX/S-recordのフォーマットは自動で認識されます。
返値プロパティ
- result
  完了で true を返します。

備考についてはBLOADクエリを参照してください。

進捗ステータス

クエリ処理中はRPCサーバーは応答を返さないため、処理に時間のかかるものについては別途進捗ステータスをリクエストすることができます。

進捗ステータスは command.cgi を利用して次のように要求します。LENの値はデフォルトで100です。

> GET /commang.cgi?op=130&ADDR=512&LEN=100

レスポンス
JSON形式で下記のようにデータが返ります。CGIの仕様上、JSONデータの最後に \00 のヌルバイト（文字列終了識別バイト）＋文字長（LENで指定する値）までのパディングデータが付加されることに注意してください。

{
  "key" : <number>,
  "id" : <number>,
  "cmd" : <number>,
  "progress": [<number>, <number>, ...]
}\00<指定データ数までのパディングデータ>

返値プロパティ
- key
  RPCサーバーで任意に割り振られたクエリ実行ナンバーが入ります。
- id
  クエリで指定したidキーの番号が入ります。
- cmd
  メソッドの識別番号（ペイロードの最初の１バイト）が入ります。
- progress
  メソッド内の進捗が配列として入ります。値は 0 ～ 100 の範囲でパーセンテージを示します。
  ほとんどのクエリでは１つの要素の配列となりますが、内部で複数の実行ステージを持つ場合は、それぞれのステージの進捗が入ります。
異なるドメインから運用する場合の注意
進捗ステータス取得はFlashAirの command.cgi を利用しているため、クロスオリジンHTTPリクエストではエラーが返ります。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

canarium_rpc_doc.md

canarium_rpc_doc.md

Canarium RPC Server

ライセンス

対象環境

使い方

FlashAir準備

RPC呼び出し

関数リファレンス

cr.version

cr.setpath

cr.setmethod

cr.update

cr.parse

クエリリファレンス

エンコード

パケットフレーム

ファイルについて

JSONレスポンス

VERクエリ

CHECKクエリ

STATクエリ

CONFクエリ

FCONFクエリ

IOWRクエリ

IORDクエリ

MEMWRクエリ

MEMRDクエリ

BLOADクエリ

BSAVEクエリ

LOADクエリ

進捗ステータス

Files

canarium_rpc_doc.md

Latest commit

History

canarium_rpc_doc.md

File metadata and controls

Canarium RPC Server

ライセンス

対象環境

使い方

FlashAir準備

RPC呼び出し

関数リファレンス

cr.version

cr.setpath

cr.setmethod

cr.update

cr.parse

クエリリファレンス

エンコード

パケットフレーム

ファイルについて

JSONレスポンス

VERクエリ

CHECKクエリ

STATクエリ

CONFクエリ

FCONFクエリ

IOWRクエリ

IORDクエリ

MEMWRクエリ

MEMRDクエリ

BLOADクエリ

BSAVEクエリ

LOADクエリ

進捗ステータス