# Movidius Neural Compute Stick tutorial <br /> Intel 神經運算棒-基礎教學
contributed by <`yanjiun`>
###### tags: `MvNCS`

---

## 硬體介紹
官方網站：[Intel® Movidius™ Neural Compute Stick](https://software.intel.com/en-us/movidius-ncs)

### 結論
==Accelerate Deep Learning Development At The Edge==
==Develop for High-Performance, Low-Power Devices==

Movidius NCS(Neural Compute Stick) 是 Intel 開發來使低性能的設備也能進行[神經網路](https://zh.wikipedia.org/wiki/%E4%BA%BA%E5%B7%A5%E7%A5%9E%E7%BB%8F%E7%BD%91%E7%BB%9C)運算，例如：Rasperry Pi ，FPGA 等嵌入式開發平台，他可以提供低功耗且有一定運算能力。

* 運算能力：CPU < NCS < GPU
* 功耗：NCS < CPU < GPU

### 硬體架構
NCS 是從 Intel® Movidius™ Myriad™ 2 vision processing unit ( VPU )所衍伸出來的一個產品。
VPU 是影像辨識專用處理器，與 GPU 有本質上的差別。
這裡不對 VPU 特性多做介紹，有興趣可以參考 [Intel® Movidius™ Myriad™ 2](https://www.movidius.com/myriad2)。

這顆 VPU 內建 4GB LPDDR3 快取記憶體、12個可程式化向量處理器( SHAVE )、以及 Leon 微處理器( SoC )，並採用 USB3 協定做通訊。
而應用端將透過提供的開發工具( NCAPI )與 VPU SoC溝通。

---

## 軟體開發介紹

### Software Development Kit ( NCSDK ) <br/> Intel 神經棒開發工具

官方說明文件：[Intel® Movidius™ Neural Compute SDK](https://movidius.github.io/ncsdk/)


NCSDK 是 Intel 提供給 MvNCS 的開發工具，用於快速部署神經網路在嵌入式平台。
NCSDK 包含三個硬體開發工具，以及一個給軟體開發 API（ for C/C++ or Python )。
* Toolkit ==僅提供 Tensorflow or Caffe 框架編譯==
* Compile : 將Caffe / TensorFlow 網絡和相關權重轉換為內部Intel®Movidius™編譯格式，以與Intel®Movidius™神經計算API一起使用。
* Profile : 提供逐層統計信息，以評估神經計算設備上Caffe / TensorFlow網絡的性能。
* Check : 比較在神經計算設備上運行網絡的推斷結果與用於網絡編譯驗證的Caffe / TensorFlow。
* API Framework ==僅提供 C/C++ or Python 語言開發==
* API : 神經計算API（NCAPI）提供了一個開發介面，用於載入網絡圖並在神經計算設備上運算。

你可以選擇 Full-SDK 或者 API-Only。前者會包含 Toolkit 開發工具，通常用於網路的開發與測試，後者用於載入開發完成的網路到裝置上運算。

==通常實際應用的嵌入是平台僅會安裝 API-Only==，但即便未安裝toolkit，API-only模式也讓您可以在Pi上開發各種app。API-only模式的限制在於無法剖析、檢查/驗證與編譯以及將神經網路編譯為二元graph檔。例如mvNCProfile、mvNCCheck與 mvNCCompile 都沒有安裝。

### 開發流程

* ==Note：注意，訓練神經網路不要用NCSDK==
1. Training ( Tensorflow or Caffe )
* 首先在擁有足夠運算能力的電腦進行神經網路的開發。
* 或者取得他人已經訓練完的神經網路資料

2. Profile, Tuning, Compile ( SDK Tools )
* 使用 Toolkit 進行分析、調整、編譯，最後編譯輸出 MvNCS可讀取的運算圖（ Graph ）。
* 這裡會需要上一步所得的訓練好的資料。
3. Prototyping ( SDK API for C/C++ or Python)
* 在最後要部署的平台上，使用 API 將上一步所調整好的神經網路運算圖載入 MvNCS 裝置上完成網路部署。
* 這裡要使用 API 撰寫程式將輸入資料以運算圖載入 MvNCS 裝置上運算，並且取得回傳值做相對應的操作。

---

## 開發環境要求

- [ ] Ubuntu* 16.04 作業系統、RPI3 Model B（樹莓派3）、或 Ubuntu 虛擬機擇一。
- [ ] [Git](https://git-scm.com/)
- [ ] Intel® Movidius™ Neural Compute Stick 硬體。
- [ ] Intel® Movidius™ Software Development Kit (SDK) Intel神經棒開發工具。

---

## 開始安裝 MvNCS 開發工具
官方已經將完整開發工具放在 Github 開源出來。

$ git clone -b ncsdk2 http://github.com/Movidius/ncsdk
$ cd ncsdk 
$ make install     <- Full-SDK
$ make api         <- API-Only

GNU Make 將會讀取 `/ncsdk` 下的 `Ｍakefile` 檔案，並自動安裝所有需要的軟體。
如果要刪除則在目錄下輸入 `$ make uninstall` 即可。
==使用 `$ make help` 可以看到可用功能與解說==
有興趣可以閱讀 `Makefile` 檔案。可以參考[GNU Make教學](https://zh.wikibooks.org/zh-tw/GNU_make/%E9%99%84%E9%8C%84/%E4%B8%80%E5%80%8B%E8%A4%87%E9%9B%9C%E7%9A%84Makefile%E5%AF%A6%E4%BE%8B)。

### 測試是否可以連接設備

$ cd ncsdk/examples/apps/hello_ncs_py    <- 這裡使用 python 
$ make help                              <- 觀看說明
$ make run                               <- 執行 hello_ncs.py

其他 example 也都可以玩看看，只要進去目錄輸入 `$make help` 看功能。

如果可以正常存取裝置會輸出以下內容：

making run
python3 hello_ncs.py;
Hello NCS! Device opened normally.
Goodbye NCS! Device closed normally.
NCS device working.

## MvNCS 開發工具
==所有 Toolkit 使用 `-h` 參數，可以看到說明檔案==

### Toolkit
Intel®Movidius™神經計算SDK提供了在開發計算機（主機系統）上分析，調整和編譯深度神經網絡（DNN）模型的工具。
* mvNCCompile
mvNCCompile是一個命令行工具，可將Caffe或TensorFlow 模型的網絡和權重文件編譯為®Movidius™圖形文件格式，該格式與 ®Movidius™NCSDK 和 NCAPI 兼容。
==`$ mvNCCompile -h`==
example: tensorflow

  mvNCCompile inception-v1.meta -s 12 -in=input -on=InceptionV1/Logits/Predictions/Reshape_1 -is 224 224 -o InceptionV1.graph

* mvNCCheck
mvNCCheck是一個命令行工具，用於檢查神 經計算設備上 Caffe 或 TensorFlow 神經網絡的有效性。
通過使用提供的網絡和適當的框架庫在設備和主機上的軟件中運行推斷來完成檢查。比較兩個推論的結果以確定網絡是否通過或失敗。前5個推斷結果作為輸出提供。此工具最適用於圖像分類網絡。
[延伸閱讀教學](https://movidius.github.io/blog/mvNCCheck/)
==`$ mvNCCheck -h`==
example: tensorflow

    mvNCCheck inception_v1.meta -s 12 -in=input -on=InceptionV1/Logits/Predictions/Reshape_1 -is 224 224 -cs 0,1,2

* mvNCProfile
mvNCProfile是一個命令行工具，可編譯網絡以與 ®Movidius™NCSDK 配合使用，在連接的神經計算設備上運行網路，並輸出文本和HTML配置文件報告。
分析數據包含有關網路性能的逐層統計信息。這有助於確定每層花費多少時間來縮小網絡的潛在變化，從而縮短總推理時間。
==`$ mvNCProfile -h`==
example: tensorflow

    mvNCProfile inception_v1.meta -s 12 -in input -on InceptionV1/Logits/Predictions/Reshape_1 -is 224 224

終端機會輸出以下資訊 (GoogLeNet範例)

Detailed Per Layer Profile
Layer      Name                                 MFLOPs    Bandwidth MB/s        time(ms)
========================================================================================
0          conv1/7x7_s2                        236.028           2505.00            5.63
1          pool1/3x3_s2                          1.806           1441.66            1.06
2          pool1/norm1                           0.000            712.67            0.54
3          conv2/3x3_reduce                     25.690            404.11            0.97
4          conv2/3x3                           693.633            316.67           11.55
5          conv2/norm2                           0.000            797.05            1.44
6          pool2/3x3_s2                          1.355           1495.52            0.77
7          inception_3a/1x1                     19.268            462.47            0.67
8          inception_3a/3x3_reduce              28.901            399.64            0.81
9          inception_3a/3x3                    173.408            333.13            4.52
10         inception_3a/5x5_reduce               4.817            793.78            0.37
11         inception_3a/5x5                     20.070            849.91            0.73
12         inception_3a/pool                     1.355            686.68            0.42
13         inception_3a/pool_proj                9.634            558.60            0.54
14         inception_3b/1x1                     51.380            470.46            0.95
15         inception_3b/3x3_reduce              51.380            472.93            0.94
16         inception_3b/3x3                    346.817            268.78            7.99
17         inception_3b/5x5_reduce              12.845           1098.70            0.36
18         inception_3b/5x5                    120.422            580.92            2.32
19         inception_3b/pool                     1.806            695.31            0.55
20         inception_3b/pool_proj               25.690            683.06            0.61
21         pool3/3x3_s2                          0.847           1305.34            0.55
22         inception_4a/1x1                     36.127            374.89            0.95
23         inception_4a/3x3_reduce              18.063            574.14            0.47
24         inception_4a/3x3                     70.447            320.50            2.09
25         inception_4a/5x5_reduce               3.011           1034.04            0.19
26         inception_4a/5x5                      7.526            616.84            0.31
27         inception_4a/pool                     0.847            630.87            0.28
28         inception_4a/pool_proj               12.042            661.36            0.36
29         inception_4b/1x1                     32.113            294.21            1.18
30         inception_4b/3x3_reduce              22.479            377.09            0.80
31         inception_4b/3x3                     88.510            313.94            2.58
32         inception_4b/5x5_reduce               4.817            838.52            0.26
33         inception_4b/5x5                     15.053            384.82            0.78
34         inception_4b/pool                     0.903            612.12            0.31
35         inception_4b/pool_proj               12.845            552.44            0.46
36         inception_4c/1x1                     25.690            486.52            0.65
37         inception_4c/3x3_reduce              25.690            488.53            0.65
38         inception_4c/3x3                    115.606            308.59            3.23
39         inception_4c/5x5_reduce               4.817            835.81            0.26
40         inception_4c/5x5                     15.053            387.14            0.78
41         inception_4c/pool                     0.903            614.42            0.31
42         inception_4c/pool_proj               12.845            550.52            0.46
43         inception_4d/1x1                     22.479            393.44            0.77
44         inception_4d/3x3_reduce              28.901            388.96            0.85
45         inception_4d/3x3                    146.313            428.44            2.80
46         inception_4d/5x5_reduce               6.423            725.47            0.31
47         inception_4d/5x5                     20.070            474.31            0.84
48         inception_4d/pool                     0.903            657.23            0.29
49         inception_4d/pool_proj               12.845            583.48            0.44
50         inception_4e/1x1                     52.986            309.60            1.47
51         inception_4e/3x3_reduce              33.116            279.09            1.28
52         inception_4e/3x3                    180.634            307.91            4.62
53         inception_4e/5x5_reduce               6.623            594.87            0.39
54         inception_4e/5x5                     40.141            416.06            1.20
55         inception_4e/pool                     0.931            636.86            0.31
56         inception_4e/pool_proj               26.493            477.56            0.68
57         pool4/3x3_s2                          0.367           1303.53            0.24
58         inception_5a/1x1                     20.873            631.79            0.77
59         inception_5a/3x3_reduce              13.046            657.84            0.50
60         inception_5a/3x3                     45.158            615.42            1.66
61         inception_5a/5x5_reduce               2.609            468.53            0.27
62         inception_5a/5x5                     10.035            554.62            0.50
63         inception_5a/pool                     0.367            540.50            0.14
64         inception_5a/pool_proj               10.437            593.71            0.47
65         inception_5b/1x1                     31.310            667.18            1.03
66         inception_5b/3x3_reduce              15.655            688.70            0.56
67         inception_5b/3x3                     65.028            799.92            1.79
68         inception_5b/5x5_reduce               3.914            459.85            0.33
69         inception_5b/5x5                     15.053            563.79            0.73
70         inception_5b/pool                     0.367            533.47            0.15
71         inception_5b/pool_proj               10.437            592.62            0.47
72         pool5/7x7_s1                          0.100            481.97            0.20
73         loss3/classifier                      0.002           2519.16            0.78
74         prob                                  0.003             10.62            0.18
----------------------------------------------------------------------------------------
           Total inference time                                                    88.66
----------------------------------------------------------------------------------------

並且輸出一個網頁如下

### API
使用 ®Movidius™NCSDK 進行推理的應用程序可以用 C / C ++ 或 Python 開發。NCAPI提供了一個程式介面，用於加載網絡圖並在神經計算設備上運行推理。
[Python API 文件](https://movidius.github.io/ncsdk/ncapi/ncapi2/py_api/readme.html)
[C / C++ API 文件](https://movidius.github.io/ncsdk/ncapi/ncapi2/c_api/readme.html)

---

## 手把手教學
[Neural Compute App Zoo](https://github.com/movidius/ncappzoo/) 這裡是官方收錄的應用。裡面有許多流行的神經網路，已經包裝好==Makefile==可以輕鬆使用。
我們可以挑選我們想要的網路來快速部署到你的環境。
==使用前記得看說明檔，有些應用有多個神經網路，需要多支 NCS 做平行運算。==

$ git clone https://github.com/movidius/ncappzoo.git
$ cd ncappzoo/
$ ls

底下有幾個目錄：
* apps：這裡有關方收錄的許多使用 NCS 實作的應用。
* caffe：這裡收錄使用 caffe 實作的神經網路，可將其編譯成 NCS 可讀取的格式。
* tensorflow：這裡收錄使用 tensorflow 實作的神經網路，可將其編譯成 NCS 可讀取的格式。
* data：除存測試神經網路的輸入測試資料。

詳細操作流程可以透過閱讀目錄裡的 ==`Makefile`== 。
在此大該說明開發流程：
1. 下載已完成之神經網路圖、以及訓練完成之權重資料。
2. 使用 mvNCCompile 將網路圖與權重資料編譯為 MvNCS 專用格式 `graph`。
3. 撰寫 python or c/c++ 呼叫 API Tool 將 graph 檔案上傳到 NCS 裝置。
4. 使用 API 做相對應得資料預先處理，並上傳到 NCS 運算，在接受 NCS 回傳值最相對應處理。