/*!
  \page tutorial_page チュートリアル

  QRK を使ったプログラム開発について解説しています。

  - \ref tutorial_first
    - \ref tutorial_first_aim
    - \ref tutorial_first_coding
  \n \n
  - <b>チュートリアル</b>
    - \ref tutorial_move
    - \ref tutorial_scan
    - \ref tutorial_lua
  \n \n
  - \ref tutorial_more

  \section tutorial_first はじめに

  \subsection tutorial_first_aim QRK の目的

  QRK は、ロボットを研究目的でコアに使う人から、教育用にシミュレータのみを使う人まで、多くの人が使いやすいライブラリを目指しています。\n
  また、ライブラリ開発はオープンソースで行い、省コストで導入できるロボット開発環境を目指します。

  \subsection tutorial_first_coding QRK を用いたプログラムの開発スタイル

  このライブラリは、プログラム開発を効率的に行うことを目指して設計されています。\n
  主な特徴としては、

  - シミュレータを持ち、多くのバグを実機で実行する前に検証できる
  - シミュレーション動作と実機動作の切り替えは、引数で簡単に行える
  - 実機動作のデバッグ情報をシミュレータ上で表示できる
  - 実機動作のログを記録して、シミュレータ上で再生でき、問題が検証しやすい
  - Lua スクリプト用のライブラリも用意しており、再コンパイルの時間が短縮できる

  などがあります。

  \section tutorial_move ロボットが移動するプログラムの作成

  それでは、ロボットが移動するプログラムを作ってみましょう。\n
  ロボットは、まっすぐ進んで停止し、180 [deg] 回転して戻ってくるようにします。

  \image html move_sample_path.png 作成するプログラムの移動経路

  まずは、main() 関数を作ってみましょう。

  \code
#include <qrk_main.h>

using namespace qrk;


int main(int argc, char *argv[])
{
  // !!! 未実装

  return 0;
} \endcode

  ここまで入力したら move_sample.cpp というファイル名で保存し、コンパイルしてみます。

  \subsection tutorial_move_compile プログラムのコンパイル

  move_sample.cpp と同じフォルダに、move_sample.pro というファイルを作ります。

  <b>move_sample.pro</b>
  \verbatim
CONFIG += debug
QT += network opengl
TEMPLATE = app
TARGET =
DEPENDPATH += .
INCLUDEPATH += .

QMAKE_CXXFLAGS = `qrk-config --qt_cflags`
QMAKE_LIBS = `qrk-config --qt_libs`

# Input
SOURCES += move_sample.cpp \endverbatim

  あとは、

  \verbatim
% qmake
% make \endverbatim

  と入力すると、コンパイルが行われます。１度 qmake を実行した後は  make と入力するだけでコンパイルが行われます。

  \subsection tutorial_move_execute プログラムの実行

  では、プログラムを実行してみましょう。ターミナルか DOS プロンプトから以下のように入力します。(Linux の場合は ./move_sample というファイル名になります。)

  \verbatim
% ./debug/move_sample.exe \endverbatim

  まだ、何も処理を記述していないので、すぐに実行が終わると思います。\n
  では、次にシミュレータを起動するよう指定して実行してみましょう。プログラムの引数に -s を指定して実行します。

  \verbatim
% ./debug/move_sample.exe -s \endverbatim

  今度は、シミュレーション画面が表示されたと思います。\n
  (もし、シミュレーションしか実行しないのであれば simulation_only.txt という空のファイルを配置しておくことで -s の指定を省略できます。)

  \image html simulation_nothing.png 何もないシミュレーション画面

  シミュレータ上にロボットを配置するには、ロボットの種類や位置をシミュレータに指示する必要があり、それを記述しておくのが simulation_settings.lua というファイルです。\n
  ビーゴをシミュレータ上に配置するには、以下のように記述します。

  simulation_settings.lua
  \verbatim
-- シミュレーションの設定ファイル

-- 利用デバイスの初期化
-- !!! ビーゴを /dev/usb/ttyUSB という通信デバイスに割り当て、run という名前を付ける
-- !!! Windows の場合は /dev/usb/ttyUSB0 ではなく COM3 や COM4 などになります
DeviceManager():createDevice("/dev/usb/ttyUSB0", "BeegoDrive", "run")

-- デバイスを作成
-- !!! run を実際に生成する
DeviceManager():device("run"):activate()

-- デバイス位置を設定
-- !!! モデルの位置を設定する
local run = DeviceManager():model("run")
run:setPosition(Position(0, 0, deg(0)), nil, false) \endverbatim

  この設定ファイルを move_sample と同じフォルダに入れてシミュレータを起動すると、今度はロボットが表示されます。

  \image html simulation_beego.png シミュレータに配置されたロボット

  それでは、実際にプログラムを記述して、シミュレータ上で実行してみましょう。\n
  今回のプログラムは、以下のようになります。

  \include move_sample/move_sample.cpp

  シミュレーション実行したときの動画

  !!! 実行したときの動画サンプル

  シミュレーション上でロボットが移動して戻ってきたら、プログラムは正常に動作しています。\n
  ロボットを制御するプログラミングについては \ref samples_page をご覧下さい。

  - 今回作成したプログラムのソースコード
    - <a href="move_sample.tar.gz">move_sample.tar.gz</a>

  \section tutorial_scan 環境をスキャンするプログラムの作成

  前進している途中に、障害物があれば停止するプログラムを作成します。
  ロボットの前方の領域に障害物があれば、停止するようにします。

  \image html scan_sample_area.png 青いエリアで障害物を検出したら停止する

  作成したプログラム
  \include scan_sample/scan_sample.cpp

  では、障害物を配置してシミュレータ上で実行してみましょう。\n
  障害物を配置するよう記述したときの simulation_settings.txt は、以下のようになります。

  \include scan_sample/simulation_settings.lua

  !!! シミュレーションの実行画面

  今回の実行では、障害物が前方になかったので、まっすぐ進んだと思います。\n
  次は、円柱の位置をロボットの前方になるようにずらしてみましょう。

  \verbatim
-- 円柱
-- !!! 位置を (1000, -400) から (1000, -100) に変更
local cylinder = Cylinder(100, 300, 1.0)
cylinder:setPosition(Position(1000, -100, deg(0)), nil, false) \endverbatim

  変更したら、再度シミュレーションをしてみます。

  !!! シミュレーションの実行画面

  今回は、ロボットが障害物の手前で停止したと思います。\n
  このように、レーザレンジセンサを使ったプログラムもシミュレータ上で検証できます。

  - 今回作成したプログラムのソースコード
    - <a href="scan_sample.tar.gz">scan_sample.tar.gz</a>

  \section tutorial_lua Lua によるプログラムの作成

  !!! 動作の仕組みについて

  !!! C++ プログラムの準備

  !!! Lua スクリプトでの動作確認

  !!!

  Lua で提供されている関数を使うだけならば、再コンパイルは必要ありません。
  再コンパイルが必要になるのは、以下の場合です。

  - Lua にバインドされていない機能を使いたい場合
  - 自分で作った C/C++ の関数、クラスを取り込みたい場合

  シミュレーションを一時停止させておき、その間に Lua スクリプトを変更して実行を再開することすら可能です。

  \section tutorial_more より理解するために

  より QRK ライブラリを理解するには、下記リンク先の説明をご覧下さい。

  - \ref samples_page ... 各モジュールを用いたサンプルプログラムを紹介しています。
  - \ref class_list_page ... 各モジュールの API を確認できます。
  - \ref simulator_page ... シミュレーション動作について説明しています。
  - \ref robots_page ... 実機を動作させる方法についての説明です。
  - \ref detail_page ... QRK ライブラリの仕組みを説明します。
*/
