Edited at
IBM CloudDay 21

Node-REDのノードをつくる手順

今回は、公式サイトに掲載されているサンプルノードを基に、Node-REDのノードを自作する手順について説明します。

現在、Node-REDは月あたり4万ダウンロードされており、急速に普及しています。また年間300万台出荷されているRaspberry PiのOSの標準ソフトウェアにもなっています。Node-REDが普及が進んでいることの理由の1つとして、「ノードを自由に登録できる」ことによるコミュニティの力が影響していると考えます。現在、フローライブラリには、1000種類以上のノードが登録されており、様々な企業が自社のサービスの利用促進のためにノードを提供しています。

また、Node-REDのユーザ層は、コードが書けないユーザの方が大きく拡大するポテンシャルがあります。そのため、コードを書けるエンジニアは、自身が広めたいサービスやプログラムをエンジニアでないユーザにも使ってもらうよう、ノードを開発して提供しましょう。


ノードの構成するファイル

Node-REDのノードは、jsファイルとhtmlファイルの2つから構成されています。jsファイルには、Node.jsのプログラムが書かれており、受け取ったメッセージを基にどの様な処理を行い、どの様なメッセージを出力するかを記述します。htmlファイルは、Node-REDのフローエディタで表示されるプロパティ設定画面が記述されています。このhtmlファイルで表示したプロパティ設定画面で入力した設定値をjsファイルから呼び出して処理を行います。

what_is_node.png

※2016年6月のNode-RED Tech Talkのスライド

その他、フローライブラリに登録する際に必要なパッケージ化で用いるpackage.jsonファイル、ノードに表示するアイコンファイルを置くこともできます。


ノードの開発、公開手順

典型的なノードの開発、公開手順は以下の通りです。この記事では本手順に沿って説明をしてゆきます。

flow.png

(1) GitHub上にリポジトリを作成

(2) リポジトリをローカルに取得(git clone)

(3) ノードのプログラムを開発

(4) パッケージ化(npm init)、package.jsonを編集

(5) ローカルのNode-REDにノードをインストール(npm link)、動作確認

(6) README.mdファイルを編集

(7) GitHubへソースコードをアップロード(git push)

(8) npmへノードを公開(npm publish)

(9) 他のNode-RED環境にノードをインストールして動作確認


ノード開発に必要なもの

Windows PCまたはMacにて、以下のソフトウェアのインストールとアカウント作成を行います。


GitHub上にリポジトリを作成

https://github.com/ へアクセスし、GitHubアカウントでログインします。その後、右上の緑色のボタン「Create new repository」をクリックします。

github_newrepository.png

次の画面の「Repository name」の欄にノードのモジュール名を指定します。Node-REDのモジュール名は、「node-red-contrib-<任意の名前>」をという命名ルールがあります(ここでは、「node-red-contrib-zundokokiyoshi」という名前にしました)。

github_newrepository2.png

同時にREADME.mdファイルも作成できるため「Initialize this repository with a README」のチェックボックスを有効にします。「Add a license」のプルダウンメニューからライセンスを選択します(ここではNode-REDと同じApache-2.0を選択しました)。最後に「Create repository」ボタンをクリックします。すると、作成されたリポジトリの画面に遷移します。

github_newrepository3.png

次のgit cloneコマンドで用いるため、リポジトリのURL「https://github.com/<ユーザ名>/node-red-contrib-<任意の名前>.git」をクリップボードへコピーします。緑色の「Clone or download」のボタンをクリックして、「Copy to clipboard」ボタンをクリックします。


リポジトリをローカルに取得(git clone)

Git Bashを開いて以下のコマンドを実行し、カレントディレクトリをデスクトップにします。Mac OSの場合は、ターミナル上で操作を行ってください。


cd ~/Desktop


gitbash_cd.png

次に、クリップボードにコピーしたパスを用いて以下のコマンドを実行し、リポジトリを取得します。


git clone https://github.com/<ユーザ名>/node-red-contrib-<任意の名前>.git


gitbash_git_clone.png


ノードのプログラムを開発

デスクトップを参照すると「node-red-contrib-<任意の名前>」という名前のディレクトリができています。その中に、「node.js」と「node.html」いう2つのファイルを作成します。最初は、Node-REDのサイトに掲載されている大文字を全て小文字に変換するノードのサンプルコードを貼り付けます。


  • node.jsファイルにサンプルコードを貼り付け


node.js

module.exports = function(RED) {

function LowerCaseNode(config) {
RED.nodes.createNode(this,config);
var node = this;
node.on('input', function(msg) {
msg.payload = msg.payload.toLowerCase();
node.send(msg);
});
}
RED.nodes.registerType("lower-case",LowerCaseNode);
}

image.png


  • node.htmlファイルにサンプルコードを貼り付け


node.html

<script type="text/javascript">

RED.nodes.registerType('lower-case',{
category: 'function',
color: '#a6bbcf',
defaults: {
name: {value:""}
},
inputs:1,
outputs:1,
icon: "file.png",
label: function() {
return this.name||"lower-case";
}
});
</script>

<script type="text/x-red" data-template-name="lower-case">
<div class="form-row">
<label for="node-input-name"><i class="icon-tag"></i> Name</label>
<input type="text" id="node-input-name" placeholder="Name">
</div>
</script>

<script type="text/x-red" data-help-name="lower-case">
<p>A simple node that converts the message payloads into all lower-case characters</p>
</script>


image.png


パッケージ化(npm init)

リポジトリにカレントディレクトリを移し、パッケージを作るnpm initコマンドを実行します。


cd ~/Desktop/node-red-contrib-<任意の名前>

npm init


gitbash_npm_init.png

npm initコマンドでの設定項目は以下の通りです。

#
設定項目
設定内容

1
name
ノードのモジュール名を指定します。デフォルトの「node-red-contrib-<任意の名前>」でOKです。

2
version
ノードのバージョンを指定します。最初は1.0.0で良いため、デフォルト値を用います。

3
description
ノードの説明を記述します。ここで記述した説明は、フローライブラリやNode-REDのノードのインストール画面で表示されます。

4
entry point
ノードのプログラムのファイル名を指定します。デフォルトの「node.js」のままでOKです。

5
test command
何も記述せずエンターを押してください。

6
git repository
GitHubのリポジトリのURLを指定します。デフォルトで入力されているURLでOKです。

7
keywords
フローライブラリやNode-REDのインストール画面の検索で用いるキーワードをカンマ区切りで指定します。フローライブラリに登録したい場合は「node-red」を忘れずに入力してください。

8
author
ノードの開発者名を指定します。npmアカウントと同じユーザ名を入力します。

9
license
ノードのライセンスを指定します。ここではNode-REDと同じライセンスである「Apache-2.0」を指定しました。

以上の設定を入力し、最後の確認で「yes」を入力します。もしここで処理が長時間終わらない場合は、Ctrl+cで抜けてください(処理は正しく行われるようです)。npm initコマンドにより、package.jsonファイルが生成されます。


package.jsonを編集

package.jsonには、手動でNode-RED固有の設定を追加する必要があります。package.jsonファイルをテキストエディタで開き、以下の様に"name"や"version"と並列して「"node-red":{"nodes":"{"lower-case":"node.js"}},」の部分を追加します。末尾のカンマを忘れずに追加してください。


package.json

{

"name": "node-red-contrib-zundokokiyoshi",
"version": "1.0.0",
(省略)
"node-red" : {
"nodes": {
"lower-case": "node.js"
}
},
(省略)
}

テキストエディタでNode-RED固有の設定を追加した様子は以下の通りです。選択部分を手動で追加しました。

image.png


ローカルのNode-REDにノードをインストール(npm link)

次にローカルのNode-RED上に、作成したノードを追加します。Git Bash上で以下のコマンドを入力し、ノードの追加とNode-REDの起動を行います。


cd ~/Desktop/node-red-contrib-<任意の名前>

npm link

cd ~/.node-red

npm link node-red-contrib-<任意の名前>

node-red


※~/.node-redは、フローのやインストールしたノードが保存されるディレクトリです。Node-REDを初めて実行した時に作成されますので、存在しない場合は一度Node-REDを起動してください。

gitbash_npm_link.png

ノードがインストールできているか確認するため、ブラウザからhttp://localhost:1880 にアクセスし、Node-REDのフローエディタを表示します。左側のパレットの機能グループの中に「lower case」という青色のノードが登場していれば、自作ノードのインストール成功です。

nodered_newnode.png


ノードの処理や見た目をカスタマイズする

次にインストールしたノードをカスタマイズしてみましょう。jsファイルやhtmlファイルの修正を行った際は、Node-REDを一旦終了し、再度起動することで変更が反映されます。ノードは例えば、以下の様な変更を行うことができます。


ノード名を変更する

ノードの名前がサンプルプログラムの「lower-case」のままであるため、この名前を他の名前に変更します。その変更を行うには以下の3つの操作を行います。


  • pakcage.jsonで使われている「lower-case」を「kiyoshi-node」に変更

vscode_modify_package_json.png


  • node.jsファイルで使われている「lower-case」を「kiyoshi-node」に変更

image.png


  • node.jsファイルで使われている「LowerCaseNode」2ヵ所を「KiyoshiNode」に変更

image.png


  • node.htmlで使われている「lower-case」4ヵ所を「kiyoshi-node」に変更

image.png

Node-REDを再起動すると、正しく名前が変更されていることを確認できます(ここでは「lower-case」から「kiyoshi node」へ変更されました)。

nodered_node_name.png


ノードの処理を変更する

主にノードの処理を行うコードは、以下の部分です。この「msg.payload = msg.payload.toLowerCase();」の部分を書き換えるのみで、ノードの処理を変更できます。


node.js

        (省略)

node.on('input', function(msg) {
msg.payload = msg.payload.toLowerCase();
node.send(msg);
}
(省略)

このソースコードでは、ノードがメッセージがを受け取ると、「function(msg)」関数が呼び出されます。その時、メッセージのデータは変数msgに入ります。次にノード特有の処理を行い、変数msg内のデータを加工した後、「node.send(msg);」で後続のノードにメッセージを引き継ぎます。ほぼfunctionノードの末尾に書く「return msg;」が「node.send(msg);」に変わるだけのイメージです(ここでは、Node.js版ズンドコキヨシのコードを使わせて頂きました)。


node.js

module.exports = function(RED) {

function KiyoshiNode(config) {
RED.nodes.createNode(this,config);
var node = this;
node.on('input', function(msg) {
var phrase = 'ズンズンズンズンドコ';
var generated = '';
do {
var choice = ['ズン', 'ドコ'][Math.random() * 2 | 0];
msg.payload = choice;
node.send(msg);
generated = (generated + choice).substr(- phrase.length);
} while (generated !== phrase);
msg.payload = 'キ・ヨ・シ!';
node.send(msg);
});
}
RED.nodes.registerType("kiyoshi-node",KiyoshiNode);
}

テキストエディタ上で選択した部分が変更した行になります。

vscode_zundoko_node.png

Node-REDを再起動し、ノードの動作を確認します。デバッグタブを見ると、処理を変更したノードが正しく動作しているようです(Node.jsなので稀に順番が変わります)。

nodered_zundoko_node.png


ノードのアイコンを変更する

公式サイトのページを参考に、ノードのアイコンを変更します。ノードのアイコンを変更するには、node.htmlファイルの"icons"の設定を変更します。Node-REDはデフォルトで以下の様なアイコンを持っています。

nodered_icons.png

ここでは、マイクの様に見えなくもない"light.png"を指定します。

vscode_change_icon.png

Node-REDを再起動すると、ノードのアイコンがファイルからマイクに変更されていることを確認できました。

nodered_zundoko_node2.png


ノードの色を変更する

ノードの色の変更はアイコンの変更と同じように、node.htmlファイルの"color"の設定を変更します。ここでは"yellow"を指定しました。

vscode_change_color.png

Node-REDを再起動してフローエディタを確認すると、正しく黄色のノードになりました。

nodered_zundoko_node3.png


その他の設定項目

その他、htmlファイルを編集して、プロパティ画面変更や、ポートラベリングの表示の設定、自作アイコンの設定なども行えますので試してみてください。

自作ノードの開発手順はここまでです。以降はノードをフローライブラリに登録する手順になります。


README.mdファイルを編集

ノードをフローライブラリに公開するには、ノードの説明を記載したREADME.mdファイルを作成する必要があります。README.mdファイルは十分書かれているかクローラに自動判定されており、一定文字数以上の内容を書かないとフローライブラリに登録されないようです。言語は日本語でも大丈夫ですが、英語の方が多くのユーザに親切です。例えば以下の内容を記載します。


  • 概要説明

  • 使用方法

  • スクリーンショット

  • 本ノードを用いたサンプルフロー

  • 前提環境

  • 更新履歴

ここでは、アルゴリズムの概要を書きました。

vscode_readme.png


GitHubへソースコードをアップロード (git push)

node.html, node.js, package.json, README.md, LICENSEの5つのファイルがあることを確認し、GitHub上のリポジトリへソースコードを置きます。

image.png

ソースコードをアップロードするには、以下のコマンドを実行します。


cd ~/Desktop/node-red-contrib-<任意の名前>

git add -A

git commit -m "The first commit"

git push


※git commitでメールアドレスとユーザ名を求められた場合は、以下のコマンドを実行してください。


git config --global user.email "<メールアドレス>"

git config --global user.name "<ユーザ名>"


※git pushでGitHubへのログインを求められた場合は、GitHubアカウントのユーザ名とパスワードを入力してください。

image.png

正しく操作が行われると、GitHub上のリポジトリにファイルが登場します。

image.png


npmへノードを公開 (npm publish)

最後に、ノードをモジュールとして公開するために、npmコマンドを用いてアップロードします。


cd ~/Desktop/node-red-contrib-<任意の名前>

npm adduser

npm publish


※npm adduserにてユーザ名、パスワード、メールアドレスを入力した後、長時間コマンドが終了しない場合は、Ctrl+cでコマンドを終了してください(ユーザ登録は正しく行われるようです)。

※npm publishを実行するには、前回よりバージョン番号を上げる必要があります。そのため、2回目以降のnpm publishを実行する際は、事前にpachage.jsonを編集してバージョン番号を上げてください。

vscode_npm_publish.png

正しく登録できると、https://www.npmjs.com/package/node-red-contrib-<任意の名前>というURLにて公開されます。

image.png

15分~1時間ほど待つと、フローライブラリのクローラが新規にnpmに登録されたノード見つけ出し、フローライブラリにも登録されます。同時に他の全てのNode-REDのフローエディタからノードをインストールできるようになります。

7bea500a-b18e-299a-aff1-1d56f02fc5d4.png


フローライブラリに登録されない場合の対処方法

フローライブラリに自作ノードが登録されない場合は、以下の(1)~(4)を試してみてください。

(1) ノードを構成するファイルが存在するか確認

「README.mdファイルの内容が十分か」「package.jsonのkeywordsにnode-redが登録されているか」「LICENSEファイルが存在するか」などを確認してください。

(2) 再度npm publishを実行

フローライブラリのクローラが正しく動作せず、フローライブラリに反映されないことがあります。その際は、package.jsonのバージョンを上げて再度npm publishを実行して上手く登録できるか試してみてください。

(3) libraries.ioに登録依頼を提出

フローライブラリのクローラは、内部でhttps://libraries.io というライブラリ登録サイトを参照しています。そのため、本サイトに自作ノードが登録されていないと、フローライブラリに登録されません。以下のスクリーンショットの様に、https://libraries.io へアクセスし、自作ノード名で検索しても結果が出ない場合は、「report it as a bug」をクリックします。

addflowlibrary.png

GitHubのIssueのページに飛ぶため、ノードを登録してほしいと記載します。しばらく経つと中の人が手動で登録してくれます。libraries.io に登録されてもフローライブラリに登録されない場合は、(2)のnpm publishを再度実行してみます。

addflowlibrary2.png

(4) フローライブラリのサイト管理者へ連絡

以上の方法で解決できない場合は、Node-REDのGoogle GroupsSlack上でフローライブラリのサイト管理者へ連絡し、手動で登録してもらいます。例えば、過去に以下のスレッドの様に手動での登録をお願いしている方もいらっしゃいました。

https://groups.google.com/forum/#!topic/node-red/rZAw_sxrJio


公開したノードを削除する方法

公開したノードを削除したい場合は、以下のコマンドを実行します(削除は公開してから24時間以内のみ行えるようです)。


cd ~/Desktop/node-red-contrib-<任意の名前>

npm unpublish --force node-red-contrib-<任意の名前>


フローライブラリからノードを削除したい場合は、package.jsonのkeywordsの中からnode-redを削除した後、バージョン番号を上げてnpm publishを実行します(反映されるまでに1日ほど時間がかかる時もあるようです)。


他のNode-RED環境にノードをインストール

開発したノードが他の環境でも正しく動作するか確認するため、IBM Cloud版Node-REDやRaspberry Pi版Node-RED等にノードをインストールしてみます(ここではIBM Cloud版Node-REDを使いました)。

image.png

パレット管理から登録したキーワードで検索し、ノードをインストールします。デバッグタブにメッセージが出力され、IBM Cloud版Node-REDでも正しく動作することを確認できました。

image.png


最後に

Node-REDのノードが簡単に開発、公開できることを理解して頂けたと思います。既存のソフトウェアでもNode.jsのSDKがあれば簡単にノード化することができます。またREST APIはrequestモジュールを使い簡単にノード化できます。ぜひノードを沢山開発してフローライブラリさらに充実させましょう。


その他ノード開発で参考になりそうな記事

Swaggerやfunctionノードから、ノードを自動生成するツールの使い方です。必要最小限のJavaScriptやHTMLのコーディングで開発できるため、素早くノードを開発できます。

同じ公式ドキュメントを基にしているため、ほぼ手順は同じ内容です。特にREST APIを問い合わせるrequestモジュールを使い方が参考になります。

本記事では説明を省略したjsファイルやhtmlファイルのソースコードを丁寧に説明されています。

パッケージ化せずIBM Cloud版Node-REDに自作ノードを追加する手順です。ノードを一般に公開したくないケースで便利と思います。

ノード開発中のハマりポイントの回避方法を説明してくださってます。