はじめよう

はじめに

本書では初めてKC4-C-100A/KC4-C-101A(以下、本製品)をご利用する方を対象に利用開始までの手順を解説します。

本製品の特徴

本製品は様々な機器に接続し各種クラウドと容易に連携出来るIoTゲートウェイです。様々な機器やクラウドに接続するには個別の設定や制御が必要となりますが、本製品では設定や制御を定義した「レシピ」を適用することによりかんたんに対応することが出来ます。

front

レシピとは

本製品では汎用IoTゲートウェイとしての機能を持たせる為に、接続する機器やクラウドに対して振る舞いを変更出来る仕組みを備えております。この振る舞いの内容を定義したものを「レシピ」と呼び、レシピを入れ替える事で様々なシーンで活用が出来ます。

利用シーンに合ったレシピを取得/作成するには３つの方法があります。

front_recipe

本書ではこれらを行う手順をステップを追って説明していきます。

※ブロックを構成して作るビジュアルプログラミングをブロックプログラミングと定義しています。

ご利用までのステップ

本製品をご利用頂くためのステップとして、以下の順番で説明します。

  1. セットアップ
    必要なツールのインストールと最新のファームウェアへの更新を案内します。
  2. レシピ実行
    レシピ紹介ページから選択したレシピを機器に入れる方法を案内します。
  3. ブロックプログラミング
    「通知ランプを光らせる」を題材にブロックプログラミングの始め方を案内します。
  4. レシピ言語
    「加速度センサーの値を表示する」を題材にレシピ言語の始め方を案内します。
  5. 機器の操作と取扱い
    機器の電源やSIMの入れ方等の基本的な扱い方を案内します。

ブロックとレシピ言語で出来ること

ブロックプログラミングは制御を簡単に扱えるように機能を絞り込んでいます。レシピ言語はC言語プログラミングのような構成で細かな制御が可能となります。用途によって使い分けをお願いします。

以下に、ブロックプログラミングとレシピ言語の機能をまとめます。

front_block_lang

セットアップ

はじめる準備

本ステップを開始するにあたり、以下の機材の準備をお願いします。

インストール

本製品にレシピを書き込む「キッティングツール」とレシピを作成する「レシピツール」のセットアップを行います。

a. WSL2の導入

本製品のツールはWSL2(Windows Subsystem for Linux 2)上で動作します。このため、お使いのパソコンにWSL2のインストールが必要です。

WSL2は管理者権限でのPowerShellまたはコマンドプロンプト上から次のコマンドを入力してインストールを行います。(下図はコマンドプロンプトからの実行例です。)

a-1. コマンドプロンプトを管理者権限で実行
wsl_command

a-2. WSL2のインストールを実施
WSLのインストールは既定でWSL2が設定されています。
コマンドプロンプト上で「wsl --install」を入力します。
wsl_install

a-3. コンピュータの再起動
WSL2のインストールを行なった後にコンピュータの再起動を行います。

※WSL2インストールの詳細は、Windows公式のガイドラインを参考にしてください。

b. ツールのインストール

インストーラーをダウンロードしてインストールを実行します。インストーラーの中にはキッティングツールとレシピツールの両方が含まれています。

b-1. インストーラーのダウンロード
弊社ホームページからインストーラーをダウンロードします。

tool_download
※ダウンロードには必要事項の入力が必要となります。

b-2. インストーラーの実行
ダウンロードした以下のファイルをダブルクリックして実行します。
tool_file

画面の指示に従って、インストールを進めてください。
tool_install
セットアップウィザードの完了画面にて「完了」押下でインストール終了です。

b-3. インストール結果の確認
コマンドプロンプト上で「wsl -l -v」コマンドを実行し、下図のように表示されているかを確認してください。
wsl_version

b-4. キッティングツールの起動確認
インストールが完了すると、デスクトップにキッティングツールツールのアイコンが表示されています。
tool_icon
このアイコンをダブルクリックして、キッティングツールを起動します。
起動に成功すると下図のウィンドウが開きます。
tool_kitting
キッティングツールは起動時に機器の接続を確認に行きます。機器が接続されていない場合は「デバイスが接続されていません」のポップアップが出ます。

b-5. レシピツールの起動確認
インストーラでインストールをすると、キッティングツールとレシピツールの両方がインストールされています。レシピツールはキッティングツールの「レシピツール起動」ボタンから起動します。
tool_recipe
レシピツールはブラウザ上で動作します。このためレシピツールを起動するとブラウザが起動されて、その上でレシピツールの画面が表示されます。

ファームウェアのアップデート

本製品のファームウェアは定期的にアップデートがあります。本製品をご利用頂く前には必ずファームウェアアップデートをお願い致します。ここではファームウェアのアップデートの手順を説明します。

a. 機器とPCの接続

本製品にACアダプターを接続をして電源投入後、パソコンとUSB Type-Cケーブルで接続します。(下図のように接続をします。)

fw_connect

a-1. 電源投入後の機器の動き
本製品に電源が入るとLEDが点灯します。
起動時は以下のような動きとなります。
fw_led_initial

a-2. キッティングツールからの認識
接続した機器をキッティングツールから認識を行います。
キッティングツールの「更新」ボタンを押下します。
fw_kitting_connect
機器が認識されると左図の様に認識した機器が一覧の中に追加されます。(複数台接続している場合は複数台認識されます。)

b. ファームウェアのアップデート

最新のファームウェアは機能の追加や機能改善が含まれており、弊社ホームページ上に公開されています。

b-1. ファームウェアのダウンロード
弊社ホームページからファームウェアをダウンロードします。
fw_download

b-2. ファームウェアのファイル確認
ファームウェアのファイルは以下のファイル名となります。(xxx部はバージョン)
fw_file
zipファイル形式となりますが、展開せずにこのまま使用します。

b-3. ファームウェアの更新
キッティングツールを使ってファームウェアを更新します。
「ファームウェア更新」を選択後に切り替わった画面で、ダウンロードをしたファームウェアを指定して「書込む」を選択します。
fw_update
書込みが開始されると機器のLEDが３色点滅を始めます。書込みが完了すると「ファームウェア書込み完了」のポップアップが表示されると更新成功です。
fw_update2

b-4. ファームウェアバージョンの確認
更新したファームウェアバージョンは「MCU」の数字で確認が出来ます。
書き込んだバージョンに更新されていることを確認ください。
fw_update3

レシピ実行

本製品はレシピを書き込む事で振る舞いを変更出来ます。ここでは既存のレシピを書き込んで動作を確認していきます。

レシピの選択

レシピ紹介ページからダウンロード
弊社ホームページのレシピ紹介ページでは、用途ごとにレシピの作り方と完成したレシピを紹介しています。この中から一つ完成したレシピをダウンロードして機器への書込みを行います。
recipe_hp

ここでは加速度センサーを使ったレシピを使用していきます。
ホームページ上にある「書込み用レシピ実行ファイル」をダウンロードします。
ダウンロードは「こちら」からも直接行えます。

レシピ実行ファイル
機器へ書込みが出来るレシピは「レシピ実行ファイル」となります。
recipe_file
レシピ実行ファイルはzip形式となっており、展開せずに使用します。

レシピの書込み

キッティングツールからレシピの書込み
レシピの書込みはキッティングツールを用いて行います。
「レシピ更新」を選択後に切り替わった画面で、書込みたいレシピ実行ファイルを指定して「書込む」を選択します。
recipe_write
書込みが開始されると機器のLEDが３色点滅を始めます。書込みが完了すると「レシピ実行ファイル書込み完了」のポップアップが表示されます。
recipe_write

レシピの実行

キッティングツールでレシピを書き込んだ後は自動的に機器が再起動して、書き込んだレシピが実行されます。
レシピ実行の確認
ここでは加速度センサーのレシピの書込みを行いましたので、下図のように機器を傾けると表示が変わる動きが確認出来ればレシピは正しく実行されています。
recipe_exe

ブロックプログラミング

ここからは「ブロックプログラミング」を始める為のチュートリアルです。

通知ランプ(LED)の点滅

ここではブロックプログラムで通知ランプを操作するレシピを作成します。
block_front

レシピツールの立ち上げ

ブロックプログラミングはブラウザから利用します。
キッティングツールの「レシピツールを起動」ボタンから起動します。

block_start
ブラウザが立ち上がり画面が表示されたら「開始」を押下します。

レシピの新規作成

レシピ一覧画面から「レシピの新規作成」を押下します。
新規作成画面に「LEDテスト」を入力して「新規作成」を押下します。

block_new

レシピ作成画面

新規のレシピ画面が表示されます。
左のツールバーから必要なブロックを引き出して組み立てて行きます。
block_new_window

ブロックの組み立て

以下のようにブロックを組み立てていきます。
組み立て後にメニューの保存を押下します。
block_movie

レシピ実行ファイルの作成

「ホーム」ボタンを押下後に、一覧画面に戻ります。
block_home

一覧画面の右側のメニュから「レシピ実行ファイル作成」を選択します。
block_exe

結果のログが出力された後、「一覧へ」を押下します。
block_log

レシピ実行ファイルのエクスポート

「レシピ実行ファイルのエクスポート」ボタンを押下して、「レシピ実行ファイル」をエクスポートします。レシピ実行ファイルは「exec-file.zip」となります。
block_download

レシピの書込み

キッティングツールツールにて「レシピ更新」を選択後に切り替わった画面で、エクスポートした「exec-file.zip」を指定して「書込む」を選択します。

recipe_write
書込みが開始されると機器のLEDが３色点滅を始めます。書込みが完了すると「レシピ実行ファイル書込み完了」のポップアップが表示されます。
recipe_write

レシピの実行

書込みが完了すると、自動的に再起動となりレシピが実行されます。
本製品のLEDが点滅することが確認できたら完了です。

block_finish

レシピツールの終了

ブロックプログラミングを終了するには、ブラウザのウィンドウを閉じると共に、キッティングツールから「レシピツール終了」を押下します。
block_recipe_end
レシピツールはWSL2上で動作している為、ブラウザを終了しただけではWSL2は終了しません。WSL2はCPUリソースを消費することからブロックプログラミングを終了するタイミングでは「レシピツール終了」を押下してWSL2も終了してください。

ブロックプログラミングリファレンス

ブロックプログラミングを更に詳しく知りたい方は、ユーザーガイドの「ブロックプログラミング」の章をご参照ください。

レシピ言語

ここからは「レシピ言語」を始める為のチュートリアルです。

加速度センサーの数値表示

レシピ言語を用いて加速度センサーの数値を表示するレシピを作成します。

SDKのダウンロード

レシピ言語を始めるにあたりSDKのダウンロードを行います。

lang_sdk
ダウンロードしたSDKはzip形式となっています。これを任意のディレクトリに展開します。(ここではC:\KC4-C-SDK\recipeとしました。)

コマンドプロンプトからビルド

レシピ言語はコマンドライン上からレシピツールを操作します。
以下のようにコマンドプロンプトを起動し、SDKのフォルダに移動します。

lang_sdk

レシピビルド用のバッチファイル「recipe_build.bat」を実行します。
lang_build

バッチファイルが実行されると自動的にWSL2が起動されて、その上のレシピツールでビルドが実行されます。
lang_build2
以上でレシピ言語のビルド環境が確認出来ました。続いてコードを記述していきます。

サンプルコードの利用

SDKのフォルダは以下の通りとなります。
ビルド対象になるのが「レシピ言語フォルダ」となるため、サンプルコードフォルダから必要なファイルをレシピ言語フォルダにコピーして利用します。

lang_folder

このチュートリアルでは、サンプルコード「90_チュートリアル」の中の「9001_レシピ言語をはじめよう_導入編」-「uapp_1.krs」を利用します。

lang_file

拡張子の.krsは、レシピ言語のソースコードを意味します。
この「uapp_1.krs」を「レシピ言語フォルダ」にコピー/貼付け(上書き)します。

lang_copy

コードの内容確認

コピーした「uapp_1.krs」をテキストエディタで開きます。
ここではコードの編集は行いませんが、コードの中身を確認していきます。
コードを俯瞰すると、以下のような配置場所になります。

lang_code

[インクルード部]
利用するAPIに必要なインクルードを指定します。

//////////////////////////////////////////////////////////////////
// include header file //
//////////////////////////////////////////////////////////////////
#ifdef C_SYNTAX
#include "basicInformation.h"
#endif // C_SYNTAX
#include "taskid.h"
#include "eventLib.h"
#include "svitem.h"
#include "logAPI.h"
#include "kcSystemAPI.h"
#include "sensorAPI.h"
#include "olcAPI.h"

「basicinformation.h」はAPIの説明が入ったヘッダファイルです。エディタによる静的解析時にAPIの内容が参照可能となります。
全てのインクルードの入ったヘッダファイルの「kc4.h」も提供していますので、手間なく一つのインクルードで定義することも可能です。

#include "kc4.h"

[定義部]
デファイン定義やグローバル変数を定義します。このコードではグローバル変数は無いですが、internal variableのコメントの下に記述します。

//////////////////////////////////////////////////////////////////
// internal define //
//////////////////////////////////////////////////////////////////
// 内部非同期イベント
#define UNSYNC_EVENT_INIT 0
// 加速度センサポーリングイベント
#define UNSYNC_EVENT_ACC_POLL 1

// データ通知インターバルタイム(msec)
#define POLLING_INTERVAL 500

//////////////////////////////////////////////////////////////////
// internal variable //
//////////////////////////////////////////////////////////////////
//ここにグローバル変数定義

[オプション部]
オプションはタスクで確保するメモリーのサイズ等を定義します。オプションの詳細は「レシピ言語ガイド」を参照ください。

//////////////////////////////////////////////////////////////////
// event driven task process //
//////////////////////////////////////////////////////////////////
options {
    StackSize = 700;
}

[イベントループ部]
イベントループ部ではタスクが受信するイベントの処理分岐を記載します。rcplib_SV_Read()はタスクへのイベントが入るまで待ちの状態になり、イベントを受信したタイミングで待ちが解除されます。この時event_idにイベント番号がるため、そのイベントで分岐処理を行います。該当イベント処理終了後は再び冒頭のrcplib_SV_Read()に戻りイベント待ち状態となります。

#ifdef C_SYNTAX
void main_loop(){
    WAIT_REQUEST_EVENT_QUEUE
#endif // C_SYNTAX
    rcplib_TASK_InitArg();

    uint16 event_id;
    event_id = rcplib_SV_Read(ENGINE_SVITEM_ID_TASKEVENTITEM_EVENT_ID);

    // 初期化
    if(event_id == UNSYNC_EVENT_INIT) {
        event_init();
    }
    // 加速度センサポーリング時のデータ取得関数
    else if(event_id == UNSYNC_EVENT_ACC_POLL) {
        event_notification_poll(rcplib_TASK_GetArg(0), rcplib_TASK_GetArg(1), rcplib_TASK_GetArg(2),
                                rcplib_TASK_GetArg(3), rcplib_TASK_GetArg(4), rcplib_TASK_GetArg(5));
    }
    // 強制停止通知
    else if(event_id == EAPI_EVENT_TASK_ENTER_FORCESTOP) {
        KCS_NotifyReadyShutdown();
    }
    // 強制停止解除通知
    else if(event_id == EAPI_EVENT_TASK_RESUME_FORCESTOP) {
    }
    // 機能制限通知
    else if(event_id == EAPI_EVENT_TASK_ENTER_LIMIT) {
    }
    // 機能制限解除通知
    else if(event_id == EAPI_EVENT_TASK_RESUME_LIMIT) {
    }
#ifdef C_SYNTAX
}
#endif // C_SYNTAX

[タスクのイベント処理部]
イベント処理の実部を記載する場所となります。ここでの関数は前記イベントループから呼ばれます。タスクは基本的にはイベントドリブンで動作する仕組みとなるので、ここのイベント処理部で無限ループで待つような処理を記載するとシステム全体が不安定となる可能性があるのでご注意ください。

サンプルコードの内容は、event_init()で加速度センサーの初期設定と動作開始を行います。加速度センサーが動作を開始すると500msごとに測定完了イベントを通知してきます。イベントを受信したタスク側はイベントループ内の分岐処理からevent_notification_poll()をコールして、その関数内で取得した加速度センサーの値を表示します。

//////////////////////////////////////////////////////////////////
// event function //
//////////////////////////////////////////////////////////////////
// 初期化
func event_init() {

    // ODR周波数:26Hz
    ACC_SetDeviceMeasure(ACC_HIGH_PERF, ACC_ODR3_026Hz);
    // ポーリング実施
    ACC_StartPolling(POLLING_INTERVAL, UNSYNC_EVENT_ACC_POLL);

    OLC_DisplayChar(OLC_CHAR_FORCE,0,0,"               ");
    OLC_DisplayChar(OLC_CHAR_FORCE,18,0,"               ");

    return(0);
}

// 加速度センサの値を表示する
func event_notification_poll(int16 acc_x, int16 acc_y, int16 acc_z,
                    float acc_f_x, float acc_f_y, float acc_f_z) {
    // 表示する際の文字用の変数
    str ch_x[18];
    str ch_y[18];
    str ch_z[18];

    // センサの値を小数で表示 単位[G]
        rcplib_FORMAT_String(ch_x, "x:%5.3f ", acc_f_x/1000);
        rcplib_FORMAT_String(ch_y, "y:%5.3f ", acc_f_y/1000);
        rcplib_FORMAT_String(ch_z, "z:%5.3f ", acc_f_z/1000);
        rcplib_STR_Cat(ch_x, ch_z);
        OLC_DisplayChar(OLC_CHAR_FORCE,0,0,ch_x);
        OLC_DisplayChar(OLC_CHAR_FORCE,18,0,ch_y);

    return(0);
}

[追加関数部]
このサンプルコード内では特に記載はしていませんが、ここに必要な内部で使用する関数等をここに記載していきます。

※説明のために関数の場所などを分けていますが、実際は関数の位置はこの配置でなくても問題ありません。(途中のコメント等が意味を持つセパレータになっているわけではありません。)

ビルドの実行

ソースコードが変更されましたので、再度ビルドを行います。
lang_build

lang_build2

ビルドが成功するとレシピ言語フォルダに「レシピ実行ファイル」(rcp_compress.zip)が作成されています。ビルドエラー等があると新しいファイルが出来ていない可能性があるため、タイムスタンプを確認してください。

lang_build3

レシピ実行ファイルの書込み

完成したレシピ実行ファイル(rcp_compress.zip)をキッティングツールから書込みます。下図の通り「レシピ更新」からファイルを選択後に「書込む」を選択します。

recipe_write
書込みが開始されると機器のLEDが３色点滅を始めます。書込みが完了すると「レシピ実行ファイル書込み完了」のポップアップが表示されます。
recipe_write

レシピ実行の確認

書込みが完了すると、自動的に再起動となりレシピが実行されます。
レシピが実行されると、下図のように画面に加速度センサーの値が0.5秒ごとに表示がされます。
recipe_exe

機器と加速度センサーの軸は以下のとおりです。
上下左右に傾けながら値の確認してください。
recipe_exe2

ソフトウェア開発ガイドでは各機能やAPIの使い方の詳しい説明がありますので、参考にしながら新しいレシピの開発を行なってみてください。

レシピ言語の終了

レシピ言語の開発を終了するには、コマンドプロンプトを閉じるだけではなく、WSL2の終了も行います。レシピ言語をビルドするバッチファイルはWSL2を起動しますが、WSL2はコマンドプロンプトを終了しても一緒に終了をしないため、以下の「wsl --shutdown」コマンドを実行します。
recipe_wsl

レシピ言語リファレンス

レシピ言語を更に詳しく知りたい方は、ユーザーガイドの「レシピ言語ガイド」及び、「ソフトウェアリファレンス」をご参照ください。また、SDKのサンプルコードの中には説明のドキュメントも入っていますので、合わせて参照ください。

機器の操作と取扱い

本製品の操作と取扱い方を説明します。

電源、再起動、リカバリーモード

a.電源ON
本製品の電源は、ACアダプターまたは16ピンコネクタのVAUXからの電源投入となります。
power
ACアダプタと16ピンコネクタの両方同時の電源投入は出来ません。

b.起動動作
製品に電源が入ると自動的に起動します。起動時の振る舞いは以下の通りです。
power_on

c.電源OFF
電源OFFはボタンを４秒以上押下します。
power_off
※USB Type-CでPCと接続されている時は電源OFFが出来ません。

d.再起動
本製品を強制再起動をかけるには、ボタンを13秒以上押下します。
ボタンを離したタイミングで再起動動作に入ります。
power_reset

e.リカバリーモード
レシピがリセットを繰り返す等でキッティングツールに繋がらなくなる場合は、ボタンを押しながら電源を投入するとリカバリーモードに入ります。リカバリーモードはレシピを起動せずに立ち上がるモードで、このモードからキッティングツールに接続が出来ます。
power_recovery

SIMの挿入

LTE通信を利用するにはSIMの挿入が必要となります。
SIMの挿入場所は下図のように本体カバーを開けた中にあります。

sim_1
sim_2

SIMを挿入後に本体カバーを閉めて完了です。

SIM挿入後に機器の電源を入れるとディスプレイにアンテナピクトが表示されますのでご確認ください。
apn_4

※nanoSIMカードの抜き差しは電源オフの状態で行ってください。
※nanoSIMカードの向きに注意してください。
※nanoSIMカードを抜くとキャリア網との通信ができなくなります。

APNの設定

SIMを利用するには通信事業者のAPN(アクセスポイント名)設定が必要となります。APNはキッティングツールから設定することが出来ます。キッティングツールを起動後に機器を選択し「設定値読込み/書込み」を選択後、画面切り替わり後「読込み」を押下します。
apn_1

「設定項目」のAPN欄を選択して、APNの内容を入力します。
APNはFOTA用とレシピ用と２つありますが、２つとも同じものを入力します。
apn_2

[APN部の入力]
APN部にはPDP TypeとAPNの２つのパラメータを入力します。
入力ルールは、項目はカンマ「,」区切り、文字列はダブルクオーテーションで囲みます。
PDP Typeには３つの種類があります。

PDP Type 設定値
IPv4（IP） 1
IPv6 2
IPv4v6 3

PDP Typeが 「IPv4(IP)」、APNが「testapn.jp」の場合以下となります。

1,"testapn.jp"

[認証パラメータ部の入力]
認証パラメータ部には、「ユーザー名」、「パスワード」、「認証タイプ」の３つのパラメータを入力します。
入力ルールは、項目はカンマ「,」区切り、文字列はダブルクオーテーションで囲みます。
認証タイプには以下の４つの種類があります。

認証方法 設定値
なし 0
PAP 1
CHAP 2
PAP or CHAP 3

ユーザー名が「user」、パスワードが「pass」、認証方法が「PAP or CHAP」の場合は以下となります。

"user","pass",3

APN設定を「利用する」にチェックを入れて、APNと認証パラメータを入力後に「書込み」を押下します。
apn_3

書込み終了後に機器が再起動し、設定が端末に反映されます。

通知ランプ

通知ランプは機器の状態を示します。システム側の状態を示すと共にブロックプログラムやレシピ言語からも利用出来ます。
led

システムから通知ランプで状態を表示するタイミングは以下の通りです。

通知ランプ 本製品の状態
緑色 点灯 電源オン中（起動後消灯）
赤色 点灯 電源オフ中（電源オフ後消灯）
橙色 点灯 設定読込み/書込み時（キッティングツール利用時）
リカバリーモード時
赤色 点滅 温度異常などの異常発生時
緑→橙→赤 点滅 レシピ/ファームウェア更新中

ボタン操作

ボタンは時計画面や状態画面の表示としてシステムから利用すると共に、ブロックプログラムやレシピ言語からも利用出来ます。

button

押し続ける時間 本製品動作
1秒未満 ディスプレイに時計や状態画面表示されます。
1秒以上 4秒未満 システムでは未使用。(レシピから利用できます。)
4秒以上 13秒未満 電源をオフします（USB Type-C非接続時のみ）
13秒以上 強制的に再起動します (ボタン離した時点で再起動)

ディスプレイ

ディスプレイの表示は、本製品の動作状況を表示する「時計画面」と本製品の設定状態を表示する「状態画面」の2種類あります。ボタンを押下することで表示を切り替えます。

display

display_status

ディスプレイに表示される内容とアイコンの意味は以下の通りです。

display_icon1

display_icon2

エラーコード 意味
E00 制限温度を検知
E01 FOTA更新用ファームウェア不正(署名確認エラー)
E02 FOTA更新用ファームウェア不正(データ復号エラー)
E03 FOTA更新用ファームウェア不正(鍵不一致エラー)

エラーコードに対しての復旧方法は、「KC4-C_ハードウェアリファレンス」を参照してください。