From 21ab1c95d601e32a26008319de1066785d145583 Mon Sep 17 00:00:00 2001 From: Kunihiko Toumura Date: Thu, 7 May 2020 19:04:56 +0900 Subject: [PATCH] add documentation for WoT Thing Description support --- docs/index.md | 143 +++++++++++++++++++++++++++++++++++++++++++++-- docs/index_ja.md | 141 ++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 274 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 6acfecb..1ff898a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ Node generator ---- -Node generator is a command line tool to generate Node-RED nodes based on various sources such as an OpenAPI document or a Function node. +Node generator is a command line tool to generate Node-RED nodes based on various sources such as an OpenAPI document, a Function node or [Web of Things Thing Description](https://www.w3.org/TR/wot-thing-description/). It helps developers dramatically reduce the time to implement Node-RED nodes. ## Use cases @@ -31,9 +31,14 @@ Node generator can generate an original node from a subflow that contains the fl And Node-RED users can easily share their original node with other Node-RED users via flow library. #### (4) Connection to devices -Web of Things (WoT) is a standard specification to connect IoT devices. -Node generator will support the Web of Things specification to create original nodes. -Currently, there is [a slide](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/images/Plugfest-Bundang-WoT.pdf) and [a screenshot](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/result-hitachi.md) of the prototype implementation on GitHub. +IoT application developers wants to concentrate their effort to +create value from connected devices, and not to go into +detail of implementation. To abstract out these detail, +W3C Web of Things (WoT) provides mechanism to formally describe +interfaces of IoT devices. In WoT, a device interface is +described by Thing Description, and Node generator will support the Thing Description to create original nodes. +Using Node generator, application developers can handle a node +in Node-RED as an avatar of a device. ## How to use Node generator To install Node generator to your local PC, you need to input the following "npm install" command on command prompt (Windows) or terminal (macOS/Linux). @@ -41,7 +46,7 @@ Because the command execution needs root permission, "sudo" is required before " npm install -g node-red-nodegen -The current version of Node generator supports function node and OpenAPI document as source files. +The current version of Node generator supports function node, OpenAPI document and WoT Thing Description as source files. node-red-nodegen creates a node from the file which is specified in the argument of the command as follows. node-red-nodegen -> The command tool outputs the node from the source file @@ -50,6 +55,7 @@ The following documentation explains methods of creating nodes from two types of - [How to create a node from OpenAPI document](#how-to-create-a-node-from-openapi-document) - [How to create a node from function node](#how-to-create-a-node-from-function-node) + - [How to create a node from WoT Thing Description](#how-to-create-a-node-from-wot-thing-description) ## Generated files which node package contains The following is a typical directory structure of the node package generated by Node generator. @@ -711,6 +717,133 @@ The following example is the procedure to generate a node from the function node -> You can use format-date node on your Node-RED flow editor. +## How to create a node from WoT Thing Description +You can specify the URL or file path of a Thing Description (TD) as the first argument of the node-red-nodegen command. If you use the URL for retrieve a TD, or the file whose extension isn't ".jsonld", you should specify the `--wottd` option. And, if you get a TD using URL, you can also specify `--lang` option to get a TD of the specific language, if exist. + +(1) Generate node using node-red-nodegen command + + node-red-nodegen td.jsonld + +Node-RED users typically import the generated node to the palette of Node-RED flow editor using the following procedures. + +(2) Change current directory to Node-RED home directory (Typically, Node-RED home directory is ".node-red" under the home directory) + + cd ~/.node-red + +(3) Locally install the module + + npm install + +(4) Start Node-RED + + node-red + +(5) Access the Node-RED flow editor (http://localhost:1880) + +-> You can see the generated node on the palette (in an "Web of Things" category, if not specified by command-line option) of the Node-RED flow editor. + +(6) Drag and drop the generated node to the workspace + +(7) Configure the node + +- Interaction: which interaction do you want to use? +- Name: what is the name of the interaction? +- Access: when you use a property, what kind of interaction do you want? (Read/Write/Observe) +- Form: which pair of authentication method and end point do you want to use? +- Token or Username/Password: if the end point needs credential for access, specify it. +- Node name: you can specify the display name of the node + +(8) Create a flow on the Node-RED flow editor + +- Property: + - To read a property, send any message to the node, and the result will emitted as msg.payload. + - To write to property, send the value to be written as msg.payload. + - When you observe a property, the node periodically emits the property value as msg.payload. +- Action: + - To invoke an action, send message to a node with arguments in msg.payload. +- Event: + - The node emits messages when event occurred. Event is stored in msg.payload. + +(9) Run the flow + +### Command line options +If you want to customize the generated node, the following procedures and command line options will be helpful. + +#### Module name +Node generator uses "node-red-contrib-" as the default prefix for the module, and default node name is created from "name" property in TD. +If you want to change the default module name, you can specify the module name using `--module` or `--prefix` option. + + node-red-nodegen td.jsonld --module wotmodule + node-red-nodegen td.jsonld --prefix node-red-wot + +#### Node name +In the case of the node generated from Thing Description, "name" property in TD is used as the generated node's name. +Node generator will replace uppercase characters and spaces with hyphens to convert appropriate name for npm module and Node-RED node. + +If you want to change the default name, you can set the node name using `--name` option. +If "name" property contains a double-byte character instead of alphabet and number, you need to specify the node name using `--name` option in order for Node generator to generate the name correctly. + + node-red-nodegen td.jsonld --name new-node-name + +#### Version +By default, Node generator uses "version" property as the module version number. + +When you update the version number of the module without incrementing the version number in Thing Description, you need to specify `--version` option. +A conflict error will occur when you publish a module that has the same version number as the previously published module when using "npm publish" command. +In this case, the `--version` option needs to be specified to update the version number of the module. + + node-red-nodegen td.jsonld --version 0.0.2 + +#### Keywords +`--keywords` is a useful options for keywords of the module in the flow library. +On the flow library website, visitors can search the module using keywords. +For example, if you want to use "lamp" as a keyword, you can specify the word using `--keyword` option. +By default, Node generator uses "node-red-nodegen" as a keywords. + + node-red-nodegen td.jsonld --keywords lamp + +To add more than two keywords, you can also use comma-separated keywords. + + node-red-nodegen td.jsonld --keywords lamp,led + +If "--keywords node-red" is specified when you publish the generated node, your node will be registered on the flow library and you can install the node via Node-RED flow editor. + + node-red-nodegen td.jsonld --keyword lamp,led,node-red + +#### Category +On the palette of Node-RED flow editor, the generated node is in "Web of Things" category by default. +To change the category, you can use `--category` option. +For example, the node generated from the following command can be viewed in the "analysis" category on the Node-RED flow editor. + + node-red-nodegen td.jsonld --category analysis + +#### Node icon +Node generator command supports `--icon` option to specify icon file for the generated node. +You can use PNG file path or [file name of stock icons](https://nodered.org/docs/creating-nodes/appearance) for the option. The icon should have white on a transparent background. + + node-red-nodegen td.jsonld --icon + + +#### Node color +By default, Node generator uses default node color defined in the node templates. If you need to change it, you can use the `--color` option of the command line. The option value should be the sequence of the hexadecimal numbers ("RRGGBB" formats) which represents node color. + + node-red-nodegen td.jsonld --color FFFFFF + +#### Node information in info tab +Node generator automatically generates the node information in the info tab using the following properties in Thing Description + +- description: Node description: +- title/description/forms in properties/actions/events: Interaction description +- support: Support Information +- links: References + +If you want to modify node information in info tab, you can manually edit the generated HTML file. + +#### README +To explain the details of the node, you can write documentation in a README.md file. +The documentation will be used in the flow library website if you publish your node on the flow library. +The Node generator outputs the template file of README.md so you can just modify it. + ## Known Issues - In the Node generator command, you cannot use --tgz option and --icon option simultaneously because it has an asynchronous problem. - The value of `info.title` in the OpenAPI document has to start with an alphabet (not a number) because it will be used in the variable name in the generated code. diff --git a/docs/index_ja.md b/docs/index_ja.md index d7c568e..c321bf1 100644 --- a/docs/index_ja.md +++ b/docs/index_ja.md @@ -1,6 +1,6 @@ ノードジェネレータ ---- -ノードジェネレータは、OpenAPIドキュメントやfunctionノードなどのソースコードからNode-REDのノードを生成するためのコマンドラインツールです。 +ノードジェネレータは、OpenAPIドキュメント、[Web of Things Things Description](https://www.w3.org/TR/wot-thing-description/)やfunctionノードなどのソースコードからNode-REDのノードを生成するためのコマンドラインツールです。 このツールを使用すると、ノード開発者はNode-REDノードの実装時間を大幅に短縮できます。 @@ -34,9 +34,14 @@ Node-REDユーザは、サブフローを独自のノードとしてカプセル そして、Node-REDユーザは、フローライブラリを介して、生成したノードを他のNode-REDユーザと容易に共有できます。 #### (4) デバイスへの接続 -Web of Things (WoT)は、IoTデバイスを接続するための標準仕様です。 -ノードジェネレータはWeb of Thingsの定義から独自のノードを開発することを支援します。 -現在のところ、GitHub上にプロトタイプ実装の[スライド](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/images/Plugfest-Bundang-WoT.pdf)と[スクリーンショット](https://github.com/w3c/wot/blob/master/plugfest/2018-bundang/result-hitachi.md)があります。 +IoTアプリケーションの開発者は、接続したデバイスをつかった価値の創出に +注力したいのであり、その実装の詳細に手間をかけたくありません。 +実装の詳細を抽象化するために、W3C Web of Things (WoT)はIoTデバイスがもつ +インタフェースを抽象化するための枠組みを提供しています。 +WoTではデバイスのインタフェースはThing Descriptionとして記述され、 +ノードジェネレータはこのThing Descriptionから独自ノードを生成できます。 +ノードジェネレータを使うことで、アプリケーションの開発者は +Node-RED上のノードをデバイスのアバターとして使うことができます。 ## ノードジェネレータの使い方 @@ -45,7 +50,7 @@ Web of Things (WoT)は、IoTデバイスを接続するための標準仕様で npm install -g node-red-nodegen -ノードジェネレータの現在のバージョンは、functionノードとOpenAPIドキュメントをソースファイルとしてサポートしています。 +ノードジェネレータの現在のバージョンは、functionノード、OpenAPIドキュメントとWoT Thing Descriptionをソースファイルとしてサポートしています。 ノードジェネレータのコマンドであるnode-red-nodegenは、以下の様にコマンドの引数で指定したファイルをノードに変換します。 node-red-nodegen -> コマンドツールは、ソースファイルからノードを出力します @@ -54,6 +59,7 @@ Web of Things (WoT)は、IoTデバイスを接続するための標準仕様で - [OpenAPIドキュメントからノードを生成する方法](#how-to-create-a-node-from-openapi-document) - [functionノードからノードを生成する方法](#how-to-create-a-node-from-function-node) + - [Thing Descriptionからノードを生成する方法](#how-to-create-a-node-from-wot-thing-description) ## ノードパッケージ内のファイル @@ -719,6 +725,131 @@ functionノードに外部モジュールをロードする場合、Node-REDユ -> Node-REDフローエディタ上でformat-dateノードを使用できます。 + +## Thing Descriptionからノードを生成する方法 +node-red-nodegenコマンドの最初の引数として、Thing Description(TD)のURL又はファイルパスを指定できます。URL、または拡張子が".jsonld"でないファイルを指定する場合は、`--wottd`オプションをつける必要があります。また、もしURL指定でTDを取得する場合には、`--lang`オプションをつけることで指定した言語のTDを取得することもできます。 + +(1) node-red-nodegenコマンドを使用してノードを生成 + + node-red-nodegen td.jsonld + +Node-REDユーザは通常、以下の手順で生成したノードをNode-REDフローエディタのパレットにインポートします。 + +(2) カレントディレクトリをNode-REDのホームディレクトリに変更（通常、Node-REDのホームディレクトリは、ホームディレクトリの下の".node-red"です） + + cd ~/.node-red + +(3) モジュールをローカルにインストール + + npm install + +(4) Node-REDを起動 + + node-red + +(5) Node-REDフローエディタにアクセス (http://localhost:1880) + +-> 生成されたノードがNode-REDフローエディタのパレットに表示されます(コマンドラインオプションで指定してなければ、"Web of Things"カテゴリ内にあるはずです)。 + +(6) 生成されたノードをワークスペースにドラッグアンドドロップ + +(7) ノードを設定する + +- Interaction: 利用する相互作用 +- Name: 相互作用の名前 +- Access: プロパティにアクセスする場合、読み/書き/監視のどのアクセスを行うか? +- Form: どの認証方法・エンドポイントを使うか? +- TokenまたはUsername/Password: もしエンドポイントのアクセスに認証が必要であれば、必要な情報をセットする +- Node name: フローエディタで表示されるノードの名前を指定する + +(8) Node-REDフローエディタでフローを作成 + +- プロパティの利用法: + - プロパティを読むためには、任意のメッセージをノードに送ると、それをトリガーとしてデバイスに問い合わせが行われ、結果がmsg.payloadに入ったメッセージとして出力されます。 + - プロパティに書き込むためには、書き込む内容をmsg.payloadにいれたメッセージをノードに送ります。 + - プロパティを監視するように設定すると、ノードは定期的にプロパティの値をmsg.payloadに入れたメッセージを出力します。 +- アクションの利用法: + - アクションを起動するためには、必要な引数をmsg.payloadに入れたメッセージをノードに送ります。 +- イベントの利用法: + - イベントが発生すると、ノードはイベント内容をmsg.payloadに入れたメッセージを出力します。 + +### コマンドラインオプション +生成したノードをカスタマイズする場合は、次の手順やコマンドラインオプションが役立ちます。 + +#### モジュール名 +ノードジェネレータは、モジュール名のデフォルトのプレフィックスとして "node-red-contrib-"を使用します。またノード名はTDの"name"プロパティから取られます。 +デフォルトのモジュール名を変更したい場合は、`--module`又は`--prefix`オプションを使用してモジュール名を指定できます。 + + node-red-nodegen td.jsonld --module wotmodule + node-red-nodegen td.jsonld --prefix node-red-wot + +#### ノード名 +Thing Descriptionから生成したノードの場合、Thing Descriptionの"name"プロパティを生成ノードの名前として使用します。 +ノードジェネレータは、npmモジュールとNode-REDノードで利用できる適切な名前を変換するために、大文字とスペースをハイフンに置き換えます。 + +デフォルト名を変更する場合は、`--name`オプションを使用してノード名を設定できます。 +特に、"name"プロパティにアルファベットと数字の代わりに2バイト文字を含む場合、ノードジェネレータがノードを正しく生成できないため、`--name`オプションを使用してノード名を指定します。 + + node-red-nodegen td.jsonld --name new-node-name + +#### バージョン +デフォルトでは、ノードジェネレータはモジュールのバージョン番号として "version"プロパティを使用します。 + +Thing Descriptionのバージョン番号をインクリメントせずにモジュールのバージョン番号を更新する場合は、`--version`オプションを指定します。 +特に、"npm publish"コマンドを使用して、以前公開したモジュールと同じバージョン番号を持つモジュールを公開すると、競合エラーが発生します。 +この場合、モジュールのバージョン番号を更新するには、`--version`オプションを指定します。 + + node-red-nodegen td.jsonld --version 0.0.2 + +#### キーワード +`--keywords`は、モジュールのキーワードのために用いる便利なオプションです。 +フローライブラリのWebサイトで、訪問者はこのキーワードを使用してモジュールを検索します。 +例えば、 "lamp"をキーワードとして使用する場合は、`--keywords`オプションを使用して単語を指定できます。 +デフォルトでは、ノードジェネレータは "node-red-nodegen"をキーワードとして使用します。 + + node-red-nodegen td.jsonld --keywords lamp + +2つ以上のキーワードを追加するには、コンマ区切りのキーワードを使用することもできます。 + + node-red-nodegen td.jsonld --keywords lamp,led + +生成したノードを公開する前に"--keywords node-red"を指定すると、ノードはフローライブラリに登録でき、Node-REDフローエディタでノードをインストールできます。 + + node-red-nodegen td.jsonld --keyword lamp,led,node-red + +#### カテゴリ +Node-REDフローエディタのパレットでは、生成したノードはデフォルトとして「Web of Things」カテゴリに入ります。 +カテゴリを変更する場合は、`--category`オプションを用います。 +例えば、次のコマンドが出力するノードは、Node-REDフローエディタの「分析」カテゴリに入ります。 + + node-red-nodegen td.jsonld --category analysis + +#### ノードアイコン +ノードジェネレータのコマンドは、生成されるノードのアイコンファイルを指定するための`--icon`オプションをサポートしています。 +オプションにはPNGファイルパス、または[ストックアイコンのファイル名](https://nodered.org/docs/creating-nodes/appearance)を使用できます。アイコンは透明な背景上に白色で表示したPNGファイルである必要があります。 + + node-red-nodegen td.jsonld --icon + +#### ノードの色 +ノードジェネレータはデフォルトでノードテンプレートで定義されたノードの色を使用します。変更する必要がある場合は、コマンドラインの`--color`オプションを使用できます。オプションには、ノードの色を表す16進数("RRGGBB"形式)の文字列を指定できます。 + + node-red-nodegen td.jsonld --color FFFFFF + +#### 情報タブ内のノードの情報 +ノードジェネレータは、Thing Descriptionの次のプロパティを使用して、情報タブにノードの情報を自動的に生成します。 + +- description: ノードの説明 +- 各相互作用のtitle/description/form: 相互作用の説明 +- support: サポート情報 +- links: 参考情報 + +情報タブのノード情報を変更したい場合は、生成されたノードのHTMLファイルの最後のセクションを編集します。 + +#### README +ノードの詳細を説明は、README.mdというファイルに書きます。 +フローライブラリにノードを公開すると、フローライブラリのWebサイトは、ノードのページで本ファイルを表示します。 +ノードジェネレータはREADME.mdのテンプレートを出力するので、ファイルを変更するだけです。 + ## 既知の問題点 - ノードジェネレータのコマンドでは、非同期の問題があるため、--tgzオプションと--iconオプションを同時に使用することはできません。 - OpenAPIドキュメントの値`info.title`は生成されたコードの変数名として使われるため、アルファベットの文字（数字ではない）で始める必要があります。