Merge pull request #109 from node-red-hitachi/wot-docs

Add documentation for WoT Thing Description support

Author: kazuhitoyokoi

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,17 +31,22 @@ 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).
 Because the command execution needs root permission, "sudo" is required before "npm install" command on macOS or Linux environment.
 
     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 <source file> -> 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 <location of node module>
+
+(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 <PNG file or stock 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.