Longan Nanoを使ってみる 2 ～デバッガの環境設定～

# 前の記事
[Longan Nanoを使ってみる 1](https://qiita.com/BUBUBB/items/7ce85ada67a3f6d1944d)を参照してください

# デバッガの環境設定
ここでは、Sipeed Risk-V Debuggerの導入と、動作の確認を行う。

# 全体の目次
[Longan Nanoを使ってみる 1 ～ビルド環境の構築～](https://qiita.com/BUBUBB/items/7ce85ada67a3f6d1944d)
[Longan Nanoを使ってみる 2 ～デバッガの環境設定～](https://qiita.com/BUBUBB/items/864b2ef9404453810d5f)
　[Sipeed RISC-V Debugger](https://qiita.com/BUBUBB/items/61316a4df1d9f81e2864)
[Longan Nanoを使ってみる 3 ～デバッガの使用方法～](https://qiita.com/BUBUBB/items/8efa5989e7f16f67672e)
[Longan Nanoを使ってみる 4 ～printfを使ったデバッグ～](https://qiita.com/BUBUBB/items/b607a3eedc4b66e7a74f)
[Longan Nanoを使ってみる 5 ～ゲームのプロジェクトを作成～](https://qiita.com/BUBUBB/items/98d9c25120c0955d5200)
[Longan Nanoを使ってみる 6 ～文字出力～](https://qiita.com/BUBUBB/items/8dee2eabe78f38364674)
　[Longan Nanoを使ってみる ～FONTX2ファイルを作る～](https://qiita.com/BUBUBB/items/8760ac886423bf06be68)
[Longan Nanoを使ってみる 7 ～外枠とブロックを書く～](https://qiita.com/BUBUBB/items/96abb1158b413c9efd27)
　[Longan Nanoを使ってみる ～謎の画像表示関数～](https://qiita.com/BUBUBB/items/40b99468839e1daeebfb)
[Longan Nanoを使ってみる 8 ～ボールを動かす～](https://qiita.com/BUBUBB/items/92f4816af3c41ea13b9e)
[Longan Nanoを使ってみる 9 ～A/Dコンバータから入力～](https://qiita.com/BUBUBB/items/311c179f7d3a0e30495d)
[Longan Nanoを使ってみる 10 ～パドルを動かす～](https://qiita.com/BUBUBB/items/eb8149c68f6e5456e7ca)
[Longan Nanoを使ってみる 11 ～ボタンの入力](https://qiita.com/BUBUBB/items/2445940a6b0d2110ee04)
[Longan Nanoを使ってみる 12 ～ボールのロス～](https://qiita.com/BUBUBB/items/f8c6ff860de127c93cb9)
[Longan Nanoを使ってみる 13 ～ステージの遷移とゲームオーバー～](https://qiita.com/BUBUBB/items/f1ae81b835f55abe319e)
[Longan Nanoを使ってみる 14 ～PWMとサウンド～](https://qiita.com/BUBUBB/items/3b592078d30cfed0ec53)
[Longan Nanoを使ってみる 15 ～音楽を鳴らす～](https://qiita.com/BUBUBB/items/adb35e02209ad78dfa9b)
[Longan Nanoを使ってみる 16 ～とりあえずのまとめ～](https://qiita.com/BUBUBB/items/ba782ccc80f50b7ab8c3)

# 注意
このページは、quiita.com で公開されています。URLがqiita.com以外のサイト、例えばjpdebug.comなどのページでご覧になっている場合、悪質な無許可転載サイトで記事を見ています。正しいURLは、https://qiita.com/BUBUBB/items/7ce85ada67a3f6d1944d です。
無許可転載サイトでの権利表記（CC BY SA 2.5、CC BY SA 3.0とCC BY SA 4.0など）は、不当な表示です。
正確な内容は、qiitaのページで参照してください。

# Sipeed Risk-V Debugger
この記事では、DFUではなく[Sipeed Risk V Debugger](https://tang.sipeed.com/en/hardware-overview/rv-debugger/)を使用して開発を行う。

おおむね1200円～1500円前後で購入できる。

[スイッチサイエンス](https://www.switch-science.com/catalog/5712/)
[千石通商](https://www.sengoku.co.jp/mod/sgk_cart/detail.php?code=EEHD-5JEA)
[マルツ](https://www.marutsu.co.jp/pc/i/33122581/)


Sipeed Risk-V デバッガはFT2232Dそのまま、というもので、回路図は[Sipeedのページからダウンロード](https://github.com/kprasadvnsi/tang-doc/releases/download/1.0.0/FT2232D.Schematic.pdf)できる。 回路自体は秋月電子で売られている	[FD2232D USB シリアル2ch変換モジュール](https://akizukidenshi.com/catalog/g/gM-02990/)とほぼ同じなので、代用可能かもしれない。

ただ、Sipeed Risk-V Debuggerは金属のケースに入ったドングルなので別途ケーブルを用意しなくてもよいが、秋月のソレは Mini-USBだったり、基盤がむき出しだったり。値段はSipeed製のほうが安めないので、用途がLongan Nanoの開発だけであれば、RiskV Debuggerのほうが良いのではないかと思う。逆に、秋月版のほうは、バスパワー/外部電源の切り替えができたり、ロジックレベルを5/3.3Vで切り替えができたりする。（Sipeed製品はバスパワー、3.3V固定）ほかにも用途がある場合は秋月製品を選ぶほうがよさそう。


# 用意するもの

これまでの作業で必要だったもの
- Windows PC (Windows10/11)
- Longan Nano 本体
- microSD (16GBytes程度あれば十分すぎる)
- USB Type-Cケーブル （PCとLongan Nanoを接続する）

このページで新しく用意が必要なもの
- Sipeed Risk V Debugger(前述）
- 接続ケーブル。Debugger付属、もしくは自作（後述）



# Risk-V Debuggerの仕組み
Risk-Vデバッガは、基本的にはUSB-シリアル(RS-232C)変換器。使われているのは、FT2232Dという有名なICで接続すると、自動的にドライバが組み込まれて、WindowsからはCOMポートとして認識される。COMポート、と言っても若い人はわからないかもしれないが、大昔のコンピュータ同士やコンピュータと外部装置を結ぶための接続端子。今のUSBポートのご先祖様、と言ってもよい。

このドライバのままだとデバッガとしては動作しないので、標準に添付されたドライバの代わりに、WinUSBと呼ばれるこれもまた標準の汎用ドライバを使用するように変更する。WinUSBは、汎用的な用途のドライバで、シリアルポートのプロトコルに縛られない通信ができる。

WinUSBを使って、JTAGプロトコルで通信を行ってデバッグが行われる。

つまり、デバッガを使うために必要なステップは次のようになる。

1. 本体、ケーブルなど物理的に必要なものを用意する。
1. デバッガをWindowsにつなぎ、FT232Dとして認識できるようにする。
1. デバッガのポート（FT232Dは、標準で２つのCOMポートが用意されるので、そのうちの1つ目）のドライバをWinUSBに変更する。
1. Platform IOから書き込みにデバッガを使うように変更する。

# 開封とケーブルの接続
Sipeed RiskV Debuggerは、10pinのボックスヘッダがついており、一方、Longan Nanoは無理やり感のある８ピンが出ている。同じメーカなのだから、ピン配置に配慮があったり、つなぐだけというケーブルが同梱されていてもよいと思ったのだが、そんなことはなく、１ピンのバラケーブルがついてきた。

<img width="30%" alt="debugger1.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/ba22a92f-95f3-56ac-f467-980d94bc3a15.png">

このケーブルが妙にコシが強く、非常につなぎにくいが、次のように配線する。(GNDと3V3は省略した。NCは接続しない） Longan Nano側のR0、T0、R0や、Debugger側のRST、RXD、TXD、5Vは接続する必要はないが、printfデバッグをする際に使用するので、Longan-NanoのR0とDebuggerのTxD、Longan NanoのT0とDebuggerのRXDを結線しておく。

<img width="debugger2.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/5890b608-d422-0202-1078-45b034ca5614.png">


実際につないだところがこうなる(TXD/RXDは省略した）が、見ての通り非常にわかりにくく、また、少しストレスがかかるとはずれしてしまい、非常に不便。ずっとドングルを刺しっぱなしならそれでも我慢できるが、そこまでLonganに全精力をつぎ込むわけにはいかない。


<img width="50%" alt="DSC_1112.JPG" src ="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/7d922591-ed0d-e824-c161-6420ba8ac2bf.jpeg">

## 専用ケーブルの作り方

もし、手持ちに道具があるなら、専用のケーブルを作ってしまったほうが便利だと感じる。下の写真は適当に作ったケーブル。

![debugger4.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/17301868-e98c-a013-2877-8e239a401d02.png)

秋月電子であれば、次のような部品で簡単にコネクタを作ることもできる。

- [２×５（１０Ｐ）両端コネクタ付ＩＤＣリボンケーブル](https://akizukidenshi.com/catalog/g/gC-06972/) ￥150
- [コネクタ用ハウジング　２×４　（８Ｐ）](https://akizukidenshi.com/catalog/g/gC-12436/)　￥15
- [ケーブル用コネクタ　（１０個入）](https://akizukidenshi.com/catalog/g/gC-12160/)  ￥50 

なお、コネクタを作る際の工具はコレ。

- [精密圧着ペンチ　ＰＡ－２０](https://akizukidenshi.com/catalog/g/gT-12165/)  ￥3800

もちろん、工具を買うのが惜しい、などの場合、Longan Nano側のソケットは、圧着ではなくピンソケットと半田ごてを使って作ってもよい。それでも、製品付属のバラよりは使いやすいと思われる。（個人的な感想では、手間と出来栄え、頑丈さを考えると圧着工具を買う価値は十分あると思う）



## ケーブル作成時の注意事項

Sipeed Risk-V Debuggerには、いくつかのリビジョンがあるようだ。ケーブル作成時に注意が必要。

[Sipeed RISC-V Debugger](https://qiita.com/BUBUBB/items/61316a4df1d9f81e2864)を参照すること。


# PCへの接続とドライバの確認
DebuggerをPCに接続すると、COMポートとして標準ドライバで認識される。

<img width="50%" alt="debugger5.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/d63f821e-ca6d-3b6e-f117-3faa494d53a0.png">

ドライバは、FTDIとなる。（Windows10/11では標準で添付されている）

<img width="50%" alt="debugger6.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/a8a5d87a-1c1a-0142-c7ac-e9900c89bc79.png">

# ドライバの変更

次に、標準のFTDIドライバから、Microsoft製のWinUSB ドライバにドライバを変更する。[ツールを使わず、自力で導入](https://docs.microsoft.com/ja-jp/windows-hardware/drivers/usbcon/winusb-installation)もできるが、元に戻すことを考えるとツールを使ておいたほうが楽。

[UsbDriverTool](https://visualgdb.com/UsbDriverTool/)
[Zadig](https://zadig.akeo.ie/)

などが使用できる。

この記事では、USB Driver Toolを使用する。https://visualgdb.com/UsbDriverTool/　から、USB Driver Tool.exeをダウンロードし、実行する。解凍先を指定すると、UsbDriverToolというフォルダが作成される。

フォルダ内の、USBDriverTool.exeを、管理者権限で実行する。
<img width="70%" alt="debugger7.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/628741ab-17e8-6630-cec8-983589c90efa.png">

起動するとUSBデバイスの一覧が表示されるので、USB Serial Converter を選択する。この画面では、　USB Serial Converter Aを選択しているが、複数のFT2232Dデバイスが接続されている場合には、CとDなど、2つづつずれてくる可能性もある。その場合、デバイスを抜き差しして、Sipeed Risk V Debuggerが作成したエントリを探す必要がある。

デバイスを選択したら、Change driver typeをクリックする。

<img width="50%" alt="debugger8.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/4f25ecbb-2f71-6bbb-d69e-f96ddaf60a74.png">

選択したデバイスに現在登録されているドライバ（デフォルトでは、FTDIになっている）と、置き換え可能なドライバが一覧されているので、WinUSBに変更してInstallボタンをクリックする。

<img width="40%" alt="debugger9.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/ad7e0bdb-112b-7d07-6c73-88941c88c5eb.png">

前の画面に戻ると、（WinUSB)が追加され、ドライバが変更されていることが確認できる。

<img width="50%" alt="debugger10.png" SRC = "https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/e87c1d04-3638-5ac2-7dd1-13226c41d7f0.png">

何らかの理由で、ドライバをもとに戻したい場合（同じFT2232Dを使うデバイスが動作しなくなった、など）には、逆の操作を行い、FTDIドライバを選択する必要がある。



# 動作確認
最後に、Visual Studio Codeからプロジェクトをビルドし、Longan Nanoに転送、デバッガが動作していることを確認する。


## サンプルプロジェクトのインポート

Visual Studio Codeを起動し、画面左下の家のアイコンをクリックする。

![vscode1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/b60174e7-2191-77cc-430a-f06437abce5e.png)

Visual Studio codeのホームページが起動するので、Project Examplesをクリック。

<img width="50%" alt="vscode7.png" SRC="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/6a31521c-7b91-46f2-a697-071c8b80fa37.png">

Import Project Exampleのダイアログでは、Longan-nano-blinkを選択、Immportボタンをクリック。

<img width="50%" alt="vscode13.png" srC="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/1c4baa88-83db-b9b8-5960-b89ff61e25f2.png">

インポートが終了すると、プロジェクトを信用するかの問い合わせがあるので、信頼するのチェックボックスをチェック、[はい]をクリック。
<img width="50%" alt="vscode14.png" SRC="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/bf893d1e-c17b-4c69-31b4-e54eadbabf06.png">
プロジェクトがインポートされる。


## 設定ファイルの変更

左側ペイン（エクスプローラー）でplatformio.iniをダブルクリック。右側には、このプロジェクトの設定が表示される。

<img width="50%" alt="vscode15.png" SRC="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/f5ff9472-d3a2-16b6-2e71-38c589171734.png">

platformIOに、デバッグやビルドの時にRV Debuggerを使用することを示すため、次の2行を追加する。
upload_protocol = sipeed-rv-debugger
debug_tool = sipeed-rv-debugger


変更前

```
[env:sipeed-longan-nano]
platform = gd32v
framework = gd32vf103-sdk
board = sipeed-longan-nano
monitor_speed = 115200
```
変更後

```
[env:sipeed-longan-nano]
platform = gd32v
board = sipeed-longan-nano
framework = gd32vf103-sdk
monitor_speed = 115200
upload_protocol = sipeed-rv-debugger
debug_tool = sipeed-rv-debugger
```

## ビルドと転送

ステータスバーにある、右矢印ボタンをクリックする。このボタンを押すと、現在のプロジェクトがビルドされ、platformIO.iniに指定された方法（今回の場合、sipeed-rv-debuggerを指定した）で転送が行われる。
![vscode16.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2096509/b1532862-d01e-e96d-8a24-91457f729ee2.png)

コンソールには、ビルドの進捗が表示される。

```
 :
 :
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/gd32v/sipeed-longan-nano.html
PLATFORM: GigaDevice GD32V (1.2.1) > Sipeed Longan Nano
Info : flash size = 128kbytes
cleared protection for sectors 0 through 127 on flash bank 0
Info : JTAG tap: auto0.tap tap/device found: 0x790007a3 (mfg: 0x3d1 (GigaDevice Semiconductor (Beijing)), part: 0x9000, ver: 0x7)
Error: Trying to use configured scan chain anyway...
Warn : Bypassing JTAG setup events due to errors
** Programming Started **
auto erase enabled
wrote 7168 bytes from file .pio\build\sipeed-longan-nano\firmware.elf in 1.937121s (3.614 KiB/s)
** Programming Finished **
** Verify Started **
verified 6584 bytes in 0.337878s (19.030 KiB/s)
** Verified OK **
Info : Hart 0 unexpectedly reset!
Info : Note: Hart is halted due to the halt-on-reset bit is set,please continue your  program by appropriate debugger commands or operations!!
================================== [SUCCESS] Took 25.85 seconds ==================================
```

成功したら、Longan Nano上のLEDが赤く点滅する。


# 問題点の切り分け
Longan Nanoを接続し、電源供給がされているにもかかわらず、アップロードに失敗する場合、まずケーブルを疑う。

- Error: JTAG scan chain interrogation failed: all ones　…　この場合、TDOが常にHighになっているかを確認する。TDOと3.3Vが短絡していないかなど。問題ないなら、TDOをGNDに落としてアップロードする。エラーが　all ones　から all Zeros　に変わったらTDOのラインは正常。
- Error: JTAG scan chain interrogation failed: all zeros　…　All onesの逆。TDOが常にLowになっているかを確認する。TDOとGNDが短絡していないかなど。問題ないなら、TDOをHighにしてアップロードする。エラーが all zerosからAll onesに変わったらTDOのラインは正常。

TDOの接続が正しく、エラーが出る場合、ほかのラインが正しく接続されていないことでTDO出力がされていない可能性がある。ほかの線の接続を死ぬほど確認する。

ちなみに、今手元にあるうちのデバイスの一つが、ある日突然 TDOがGNDと短絡されてしまった。ICソケットから外すとき、ズボラをして長めのピンセットでエイっ、と外していたのが悪かったのか・・・
個体不良もあるので、Longan NanoのTDOとGND/3V3ピンの短絡は確認したほうが良いかもしれない。（電源を接続していない状態で短絡していない状態が正常）


# ここまででできたこと

Sipeed Risk-V DebuggerをPCとLongan Nanoの間に接続し、Longan Nanoでプログラムを実行できるようになった

# 次の記事に進む
[Longan Nanoを使ってみる 3 ～デバッガの使用方法～](https://qiita.com/BUBUBB/items/8efa5989e7f16f67672e)

# 関連記事
[Sipeed RISC-V Debugger](https://qiita.com/BUBUBB/items/61316a4df1d9f81e2864)