Merge pull request #35 from brain-hackers/usb-eg

Write Explanation of USB Gadget on each OS

.editorconfig

@@ -3,3 +3,7 @@ root = true
 [*.html]
 charset = utf-8
 indent_size = 2
+end_of_line = lf
+
+[*.md]
+end_of_line = lf

.github/CODEOWNERS

@@ -1,2 +1,2 @@
-/_pages @Sasakura-ayato @puhitaku
-/_posts @Sasakura-ayato @puhitaku
+/_pages @Sasakulari @puhitaku
+/_posts @Sasakulari @puhitaku

README.md

@@ -1,4 +1,4 @@
 # wiki.brainux.org
 
-[How to edit](https://wiki.brainux.org/meta/meta-how-to-edit-wiki/)
+[How to edit](https://wiki.brainux.org/meta/how-to-edit-wiki/)
 

collections/_beginners/get-started.md

@@ -27,23 +27,18 @@ Linux ディストリビューションは、カーネルとそれ以外のソ
 
 内蔵ハードウェアの対応状況や使い方については[内蔵ハードウェア](#内蔵ハードウェア)をご覧ください。キーマップもそちらに掲載しています。
 
-|機種  |Linux 起動        |キーボード        |注釈|
+|機種  |Linux 起動        |キーボード        |デバイスツリー名|
 |:-----|:----------------:|:----------------:|:---|
 |PW-ACxxx, GCxxx, TC980||||
 |PW-G4000, G5000, G5100, A7000, A9000||||
-|PW-G4200, G5200 ~ 5300, A7200 ~ 7400, A9100 ~ 9300|:white_check_mark:|:white_check_mark:||
-|GX500, GX300|:white_check_mark:|:white_check_mark:|画面が非常に暗くなる|
-|PW-Sx1|:white_check_mark:|:white_check_mark:||
-|PW-Sx2|:white_check_mark:|:white_check_mark:||
-|PW-Sx3|:white_check_mark:|:white_check_mark:||
-|PW-Sx4|:white_check_mark:|:white_check_mark:||
-|PW-Sx5|:white_check_mark:|:white_check_mark:||
-|PW-Sx6|:white_check_mark:|:white_check_mark:||
-|PW-Sx7|:white_check_mark:|:white_check_mark:||
-|PW-HC4 ~ 6, H7700 ~ H9100|:white_check_mark:|:white_check_mark:||
-|PW-SR1 ~ 3|:white_check_mark:|:white_check_mark:||
-|PW-AA1 ~ 2|:white_check_mark:|:white_check_mark:||
-|PW-AJ1 ~ 2|:white_check_mark:|:white_check_mark:||
+|PW-G4200, G5200 ~ 5300, A7200 ~ 7400, A9100 ~ 9300, GX500, GX300|:white_check_mark:|:white_check_mark:|imx28-pwa7200|
+|PW-Sx1, HC4, SR1|:white_check_mark:|:white_check_mark:|imx28-pwsh1|
+|PW-Sx2, HC5|:white_check_mark:|:white_check_mark:|imx28-pwsh2|
+|PW-Sx3, HC6|:white_check_mark:|:white_check_mark:|imx28-pwsh3|
+|PW-Sx4, H7700, SR2|:white_check_mark:|:white_check_mark:|imx28-pwsh4|
+|PW-Sx5, H7800, AA1, AJ1|:white_check_mark:|:white_check_mark:|imx28-pwsh5|
+|PW-Sx6, H8000, AA2, AJ2|:white_check_mark:|:white_check_mark:|imx28-pwsh6|
+|PW-Sx7, H8100, H9100, SR3|:white_check_mark:|:white_check_mark:|imx28-pwsh7|
 |PW-x1, x2, ESxxxx, SR4||||
 
 

collections/_build/copy-sd-card.md

@@ -14,8 +14,8 @@ excerpt: ""
 
 # 前提
 
-- [U-Boot のビルド](/u-boot/u-boot-build/)にてU-Bootをビルドしていること
-- [Linux のビルド](/linux/linux-build/)にてLinuxをビルドしていること
+- [U-Boot のビルド](/build/uboot/)にてU-Bootをビルドしていること
+- [Linux のビルド](/build/linux/)にてLinuxをビルドしていること
 
 
 # パーティションを区切る

collections/_build/uboot.md

@@ -17,7 +17,7 @@ excerpt: ""
 
 # 環境の構築
 
-[Linux のビルド](/linux/linux-build/)の頁ですでに構築している場合は飛ばします。
+[Linux のビルド](/build/linux/)の頁ですでに構築している場合は飛ばします。
 
 
 ## 依存関係のインストール

collections/_linux/brain-config.md

@@ -26,3 +26,13 @@ $ sudo brain-config
 4. "Back" を押しトップメニューに戻ります
 5. "Finish" を選択すると再起動が促されるため再起動します
 6. 再起動したら容量が増えていることを `lsblk` コマンドを使って確認します
+
+
+# USB コントローラの動作モードを変更する
+
+上下左右キーと Enter キー（決定キー）を使って以下の手順に従って操作します。
+
+1. "Interface Options" を選択します
+2. "USB Switch the role of the USB Host Controller" を選択します
+3. USB ホストにしたい場合は "host" を、USB Gadget にしたい場合は "peripheral" を選択します
+4. トップメニューの "Finish" を選択、再起動します

collections/_meta/how-to-edit-wiki.md

@@ -101,8 +101,8 @@ $ npm run mdlint
 - master ブランチを pull して最新の本文を取得します
 - 新たにブランチを作成します
   - 後で Pull Request として提出するため、`master` ブランチには直接コミットしないでください
-- `_posts` ディレクトリにあるほかのファイルを参考にして md ファイルを追加します
-  - 例: `2038-1-19-doomsday.md`
+- `collections` ディレクトリにあるほかのファイルを参考にして md ファイルを追加します
+  - 例: `doomsday.md`
 - 記事内容を記述します
 - `npm run textlint` と `npm run mdlint` を実行し、エラーが出ないことを確認します
   - もし誤検知があった場合はルールを修正するかレビュアーと相談してください

collections/_tips/usb-ethernet-gadget.md

@@ -21,7 +21,15 @@ excerpt: PC と USB ケーブル1本で接続できる便利な仕組みとそ
 # USB コントローラの動作モードを変更する
 
 初期状態では Brain の USB コントローラはホストとして動作するため、このままではデバイスになることができません。
-2022年1月8日現在ではまだありませんが、コントローラの動作モードを簡単に切り替えるスクリプトを用意する予定です。
+コントローラの動作モードを切り替える方法には、brain-config というツールを使う方法と手動でデバイスツリーを書き換える方法があります。
+
+
+## 方法A. brain-config で変更する
+
+`brain-config` による動作モードの切り替え方法については [brain-config](/linux/brain-config) のページを参照してください。
+
+
+## 方法B. 手動で変更する
 
 手動で変更するには、以下の手順に従ってください。
 
@@ -33,16 +41,16 @@ excerpt: PC と USB ケーブル1本で接続できる便利な仕組みとそ
 
 2. 元のdtsをバックアップします
 
-   {機種名の数字}は適宜置き換えてください。（例:PW-SH5→imx28-pwsh5.dtb）
+   `{デバイスツリー名}`の箇所は、[対応機種の表](/beginners/get-started/#対応している機種)でお使いの機種を探して、対応する「デバイスツリー名」列の文字列で置き換えてください。（例:PW-SH5→imx28-pwsh5.dtb）
 
    ```sh
-   sudo cp /boot/imx28-pwsh{機種名の数字}.dtb /boot/imx28-pwsh{機種名の数字}.dtb.orig
+   sudo cp /boot/{デバイスツリー名}.dtb /boot/{デバイスツリー名}.dtb.orig
    ```
 
 3. dtbファイルをテキスト形式に変換します
 
    ```sh
-   dtc -I dtb -O dts /boot/imx28-pwsh{機種名の数字}.dtb > dts 2> /dev/null
+   dtc -I dtb -O dts /boot/{デバイスツリー名}.dtb > dts 2> /dev/null
    ```
 
 4. 設定を書き換えます
@@ -56,19 +64,22 @@ excerpt: PC と USB ケーブル1本で接続できる便利な仕組みとそ
    書き換え後は以下のようになります。
 
    ```diff
-   ahb@80080000 {
-           usb0: usb@80080000 {
-                   pinctrl-names = "default";
-                   pinctrl-0 = <&usb0_id_pins_a>;
-                   vbus-supply = <&reg_usb0_vbus>;
-   -               dr_mode = "host";
-   +               dr_mode = "peripheral";
-                   status = "okay";
-           };
+   usb@80080000 {
+           compatible = "fsl,imx28-usb\0fsl,imx27-usb";
+           reg = < 0x80080000 0x10000 >;
+           interrupts = < 0x5d >;
+           clocks = < 0x03 0x3c >;
+           fsl,usbphy = < 0x1f >;
+           status = "okay";
+           pinctrl-names = "default";
+           pinctrl-0 = < 0x20 >;
+           vbus-supply = < 0x21 >;
+   -       dr_mode = "host";
+   +       dr_mode = "peripheral";
    };
    ```
 
-   書き換えられたら保存してエディタを終了します。`Ctrl+O`の次に`Enter`を押して保存して、`Ctrl+X`で終了します。
+   書き換えたら保存してエディタを終了します。`Ctrl+O`の次に`Enter`を押して保存して、`Ctrl+X`で終了します。
 
 5. 編集したものをバイナリ形式に変換します
 
@@ -77,7 +88,7 @@ excerpt: PC と USB ケーブル1本で接続できる便利な仕組みとそ
    ```
 
    ```sh
-   sudo mv dtb /boot/imx28-pwsh{機種名の数字}.dtb
+   sudo mv dtb /boot/{デバイスツリー名}.dtb
    ```
 
 6. SDカードの第1パーティションアンマウントします
@@ -92,28 +103,28 @@ excerpt: PC と USB ケーブル1本で接続できる便利な仕組みとそ
    sudo reboot
    ```
 
-
-## コピペ用
-
 1〜3の手順をまとめると以下のようになります。
 
 ```sh
 sudo mount /dev/mmcblk1p1 /boot
-sudo cp /boot/imx28-pwsh{機種名の数字}.dtb /boot/imx28-pwsh{機種名の数字}.dtb.orig
-dtc -I dtb -O dts /boot/imx28-pwsh{機種名の数字}.dtb > dts 2> /dev/null
+sudo cp /boot/{デバイスツリー名}.dtb /boot/{デバイスツリー名}.dtb.orig
+dtc -I dtb -O dts /boot/{デバイスツリー名}.dtb > dts 2> /dev/null
 ```
 
 5〜7の手順をまとめると以下のようになります。
 
 ```sh
 dtc -I dts -O dtb dts > dtb 2> /dev/null
-sudo mv dtb /boot/imx28-pwsh{機種名の数字}.dtb
+sudo mv dtb /boot/{デバイスツリー名}.dtb
 sudo umount /boot
 sudo reboot
 ```
 
 
-# Brain に Ethernet Gadget を喋らせる
+# Ethernet Gadget を有効化する
+
+sysfs のファイル操作により Brain 上で Ethernet Gadget を有効化します。
+Brainux バージョン 2023-07-29-024604 以降では有効化処理が起動時に自動で実行されます。もし手動で有効化したい場合は以下の手順を参照してください。
 
 1. 以下のスクリプトを vi や nano でホームディレクトリに保存します
 
@@ -152,13 +163,131 @@ sudo reboot
    次回起動時からはこのスクリプトを都度実行します。
 
    ```sh
-   ./gadget.sh
+   sudo ./gadget.sh
    ```
 
 
-# PC側の対応作業
+# PC 側の対応作業
 
-Windows / Mac / Linux すべてで利用可能です。（注: 2021年2月23日現在、上記スクリプトでは Windows と macOS で認識しないことを確認しており、修正予定です）
+Windows / macOS / Linux すべてで利用可能です。
 
-PCを通してインターネットへ出るために、ネットワーク接続の共有設定が必要になります。OS ごとに設定方法は異なりますので、別途設定してください。
 
+## Windows 10 / 11 の設定
+
+1. USB コントローラの動作モードが `peripheral` に変更された Brain を PC に接続して Gadget を有効化します
+
+2. Windows と Brain を USB ケーブルで接続します
+
+   Brain の Ethernet Gadget が認識されていれば、デバイス マネージャーの「ほかのデバイス」グループに「RNDIS」が列挙されます。
+
+3. 「RNDIS」を右クリックしてコンテキストメニューを表示し「ドライバーの更新」を選択します
+
+   <img src="/assets/images/ether-win1.png" width=300px>
+
+4. 「ドライバーの検索方法」ダイアログで「コンピューターを参照してドライバを検索」を選択します
+
+   <img src="/assets/images/ether-win2.png" width=300px>
+
+5. 「共通ハードウェアの種類」から「ネットワーク アダプター」を選択します
+
+   <img src="/assets/images/ether-win3.png" width=300px>
+
+6. 製造元「Microsoft」からモデル「リモート NDIS 互換デバイス」を選択し「次へ」をクリックします
+
+   以降はセットアップ完了まで画面の指示に従ってください。
+
+   <img src="/assets/images/ether-win4.png" width=300px>
+
+7. 「ネットワーク接続」からアダプターの設定を変更します
+
+   - 設定にて「ネットワークとインターネット」→「ネットワークの詳細設定」→「アダプターのオプションを変更する」を選択します (Windows 10)
+
+      <img src="/assets/images/ether-win5.png" width=300px>
+
+   - 設定にて「ネットワークとインターネット」→「ネットワークの詳細設定」→「ネットワーク アダプター オプションの詳細」を選択します (Windows 11)
+
+      <img src="/assets/images/ether-win6.png" width=300px>
+
+      <img src="/assets/images/ether-win7.png" width=300px>
+
+8. Windows がインターネットの接続に使用しているアダプタ（Wi-Fi / イーサネット）を選択し「プロパティ」を開きます
+
+   <img src="/assets/images/ether-win8.png" width=300px>
+
+9. インターネットの共有設定をします
+
+   「共有」タブから「ネットワークのほかのユーザーに、このコンピューターのインターネット接続を通しての接続を許可する」を選択します。
+   加えて、「ホーム ネットワーク接続」プルダウンメニューで Ethernet Gadget に対応するアダプタを選択します。
+
+   <img src="/assets/images/ether-win9.png" width=300px>
+
+10. Brain からインターネットへの疎通を確認します
+
+   Brain からインターネットに `ping` などで到達できるか確認してください。
+
+
+## macOS の設定
+
+**注意**: 以下に記載する方法で Brain を接続する場合、macOS の システム整合性保護 (SIP) を解除する必要があります。システム整合性保護は、Mac 上の保護されたファイルを改ざんしようとする悪質なソフトウェアからデータを守るセキュリティ技術です。詳しくは、[Mac のシステム整合性保護について - Apple サポート](https://support.apple.com/ja-jp/HT204899) などを参照し、十分に理解してから実行してください。
+{: .notice--warning}
+
+1. macOS でカーネル拡張機能 (kext) を利用可能にします
+
+   2023年8月現在 Apple がサポートしている macOS では、kext の読み込みを有効化するために特別な設定が必要です。主な設定内容は以下の通りですが、詳細は macOS のバージョンにより異なるため、お使いの macOS に合わせた手順を検索して設定してください。
+
+   - csrutil による SIP の無効化
+   - システム拡張機能のユーザーによる管理の許可
+   - システム設定におけるシステム拡張機能の許可
+
+2. HoRNDIS をビルドします
+
+   ビルドに必要な Git や Xcode を事前に適宜インストールしてください。Xcode の初回起動では以下のコマンドが必要な場合があります。
+
+   ```sh
+   xcodebuild -license
+   xcodebuild -runFirstLaunch
+   ```
+
+   ターミナルを使って、以下の手順でビルドします。
+
+   ```sh
+   git clone https://github.com/thpryrchn/HoRNDIS.git -b BigSur
+   cd HoRNDIS
+   make
+   ```
+
+3. HoRNDIS をインストールします
+
+   `build/pkg` に `HoRNDIS-kext.pkg` が作成されているので、ダブルクリックして、指示に従いインストールします。
+
+4. USB コントローラの動作モードが `peripheral` に変更された Brain を PC に接続して Gadget を有効化します
+
+5. システム設定で、Brain に対応するネットワークインターフェースに対してインターネット共有を有効化します
+
+6. Brain からインターネットへの疎通を確認します
+
+   Brain からインターネットに `ping` などで到達できるか確認してください。
+
+## Linux の設定
+
+作業手順とスクリーンショットは Ubuntu を例として紹介します。
+
+1. USB コントローラの動作モードが `peripheral` に変更された Brain を PC に接続して Gadget を有効化します
+
+2. Ethernet Gadget のネットワーク設定を開きます
+
+   Ethernet Gadget が認識されていると、トップバー右のシステムメニューに「USB Ethernet」 もしくは 「Ethernet」 という名前の項目で列挙されます。その項目をクリックし、「Wired Settings」 をクリックします。
+
+   <img src="/assets/images/ether-linux1.png" width=300px>
+
+3. 歯車のアイコンをクリックします
+
+   <img src="/assets/images/ether-linux2.png" width=300px>
+
+4. 「IPv4」タブにある「Shared to other computers」を選択します
+
+   <img src="/assets/images/ether-linux3.png" width=300px>
+
+5. Brain からインターネットへの疎通を確認します
+
+   Brain からインターネットに `ping` などで到達できるか確認してください。