Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/reference/tech-notes/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ Use these pages for platform-specific instructions, advanced setup, and known li
- [Convert from 2.1.3 to 3.0.0](./convert-2-1-3-to-3-0-0.md)
- [Set Up Bluetooth on the Modalix SoM DevKit](./bluetooth.mdx)
- [Install ROS 2 on the Modalix SoM DevKit](./ros2.mdx)
- [Use a USB WiFi Adapter on the Modalix SoM DevKit](./wifi.mdx)
146 changes: 146 additions & 0 deletions docs/reference/tech-notes/wifi.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
---
title: Use a USB WiFi Adapter on the Modalix SoM DevKit
description: Build the MediaTek MT7921AU driver for platform 3.0, install its firmware, and connect the Modalix SoM DevKit to WiFi with nmcli.
sidebar_position: 7
---

# Use a USB WiFi Adapter on the Modalix SoM DevKit

The Modalix SoM DevKit has no built-in WiFi. You can add it with a USB WiFi adapter. This note uses an adapter with the MediaTek MT7921AU chip, which supports WiFi 6E on 2.4 GHz, 5 GHz, and 6 GHz. The platform 3.0 kernel includes the Linux wireless stack, but not the driver for this chip, so you build the driver, install it with the chip's firmware, and then connect with NetworkManager.

## Before You Start

You need:

- A Modalix SoM DevKit with platform version **3.0**. To check, run `cat /etc/buildinfo` on the DevKit.
- A USB WiFi adapter with the MediaTek MT7921AU chip (USB ID `0e8d:7961`), for example the [BrosTrend AXE3000](https://www.amazon.com/dp/B0F6MY7H62). Other MT7921AU adapters work the same way.
- Internet access on the DevKit, through Ethernet, to install packages.
- A Linux host with Docker and `git`, to build the driver, and SSH access from the host to the DevKit.

Plug the adapter into a USB port on the DevKit, then check that the DevKit detects it:

```console
sima@modalix:~$ lsusb | grep 0e8d:7961
Bus 002 Device 003: ID 0e8d:7961 MediaTek Inc. Wireless_Device
```

## 1. Build the Driver on the Host {#build}

Build the `mt7921u` driver and the `mt76` modules it depends on from the SiMa.ai kernel source, with the DevKit's own kernel configuration. The build runs in a Debian container that has the same compiler as the DevKit's kernel.

Run these commands **on the host**. Replace `<devkit-ip>` with the DevKit's IP address.

1. Check out the kernel source commit tested for this procedure, then save the DevKit's kernel configuration:

```bash
git init simaai-linux &&
git -C simaai-linux fetch --depth 1 https://github.com/SiMa-ai/simaai-linux.git 65aba29989da02d7612da5484dbbcd50643fdd60 &&
git -C simaai-linux checkout --detach FETCH_HEAD &&
ssh sima@<devkit-ip> 'zcat /proc/config.gz' > board.config
```

2. Build the modules:

```bash
docker run --rm -v "$PWD":/w -w /w/simaai-linux debian:trixie bash -c '
apt-get update && apt-get install -y gcc-aarch64-linux-gnu make bc flex bison libssl-dev libelf-dev python3 kmod &&
export ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- LOCALVERSION=-modalix &&
cp ../board.config .config &&
scripts/config --module MT7921U &&
make olddefconfig &&
make -j"$(nproc)" modules_prepare &&
make -j"$(nproc)" M=drivers/net/wireless/mediatek/mt76 KBUILD_MODPOST_WARN=1 modules'
```

The build prints warnings about unresolved symbols. They are expected: the symbols are in the `cfg80211` and `mac80211` modules that are already on the DevKit.

3. Check that the build made seven modules:

```bash
find simaai-linux/drivers/net/wireless/mediatek/mt76 -name '*.ko'
```

You get `mt76.ko`, `mt76-usb.ko`, `mt76-connac-lib.ko`, `mt792x-lib.ko`, `mt792x-usb.ko`, `mt7921-common.ko` and `mt7921u.ko`.

4. Copy them to the DevKit:

```bash
scp $(find simaai-linux/drivers/net/wireless/mediatek/mt76 -name '*.ko') sima@<devkit-ip>:/tmp/
```

## 2. Install the Driver and Firmware on the DevKit {#install}

Run the commands below **on the DevKit**.

1. Install the modules, and update the module index:

```console
sima@modalix:~$ sudo mkdir -p /lib/modules/$(uname -r)/updates/mt76
sima@modalix:~$ sudo mv /tmp/mt7*.ko /lib/modules/$(uname -r)/updates/mt76/
sima@modalix:~$ sudo depmod -a
```

2. Install the adapter's firmware and the wireless regulatory database:

```console
sima@modalix:~$ sudo apt-get update
sima@modalix:~$ sudo apt-get install -y firmware-mediatek wireless-regdb
```

3. Load the driver:

```console
sima@modalix:~$ sudo modprobe mt7921u
```

From now on, the driver loads by itself whenever the adapter is plugged in, including at boot.

4. Check that the adapter has a wireless interface:

```console
sima@modalix:~$ nmcli device status
DEVICE TYPE STATE CONNECTION
end0 ethernet connected end0-dhcp
wlxe84e06afdb5e wifi disconnected --
```

The interface name starts with `wlx`, followed by the adapter's MAC address. If it does not appear, check the driver messages with `sudo dmesg | grep mt7921u`. They show the firmware version when the firmware loads.

## 3. Connect to a WiFi Network {#connect}

Use `nmcli`, the NetworkManager command-line tool, on the DevKit.

1. Scan for networks:

```console
sima@modalix:~$ sudo nmcli device wifi rescan
sima@modalix:~$ nmcli device wifi list
```

2. Connect. Replace `<SSID>` and `<password>` with the network's name and password:

```console
sima@modalix:~$ sudo nmcli device wifi connect "<SSID>" password "<password>"
```

NetworkManager saves the connection, and reconnects to it at every boot.

3. Check the connection:

```console
sima@modalix:~$ nmcli device status
sima@modalix:~$ ip -4 -br addr show
sima@modalix:~$ ping -c 3 -I wlxe84e06afdb5e 8.8.8.8
```

Replace `wlxe84e06afdb5e` with your interface name.

To choose a network from a menu instead, run `sudo nmtui` and select **Activate a connection**.

If the DevKit is also connected through Ethernet, the Ethernet connection stays the default route. NetworkManager gives WiFi a lower priority.

## Limitations {#limitations}

- **Firmware updates remove the driver.** The modules are built for the running kernel. After you update the DevKit firmware, build and install them again.
- **Other adapters need their own driver.** This note covers the MediaTek MT7921AU. Other chips need a different kernel driver and firmware.
- **6 GHz is not tested.** The adapter supports 6 GHz, but this note was tested on 2.4 GHz and 5 GHz only. Whether you can use 6 GHz also depends on your country's rules.
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ sidebar_position: 1
- [2.1.3 から 3.0.0 にバージョンアップします。](./convert-2-1-3-to-3-0-0.md)
- [BluetoothをModalix SoM DevKitに設定します。](./bluetooth.mdx)
- [ROS 2 を Modalix SoM DevKit にインストールします。](./ros2.mdx)
- [Modalix SoM DevKit で USB WiFi アダプターを使用する](./wifi.mdx)
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
---
title: "Modalix SoM DevKit で USB WiFi アダプターを使用する"
description: "プラットフォーム 3.0 向けに MediaTek MT7921AU ドライバーをビルドし、ファームウェアをインストールして、nmcli で Modalix SoM DevKit を WiFi に接続します。"
sidebar_position: 7
---

# Modalix SoM DevKit で USB WiFi アダプターを使用する

Modalix SoM DevKit には WiFi が内蔵されていません。USB WiFi アダプターを使用すると WiFi を追加できます。このノートでは、2.4 GHz、5 GHz、6 GHz で WiFi 6E に対応する MediaTek MT7921AU チップを搭載したアダプターを使用します。プラットフォーム 3.0 のカーネルには Linux ワイヤレススタックが含まれていますが、このチップ用のドライバーは含まれていません。そのため、ドライバーをビルドし、チップのファームウェアと一緒にインストールしてから、NetworkManager で接続します。

## 始める前に

必要なもの:

- プラットフォームバージョン **3.0** の Modalix SoM DevKit。確認するには、DevKit で `cat /etc/buildinfo` を実行します。
- MediaTek MT7921AU チップを搭載した USB WiFi アダプター(USB ID `0e8d:7961`)。たとえば [BrosTrend AXE3000](https://www.amazon.com/dp/B0F6MY7H62) です。ほかの MT7921AU アダプターも同じ手順で使用できます。
- パッケージをインストールするための、Ethernet 経由での DevKit のインターネット接続。
- ドライバーをビルドするための Docker と `git` を備えた Linux ホスト、およびホストから DevKit への SSH アクセス。

アダプターを DevKit の USB ポートに接続し、DevKit がアダプターを検出していることを確認します。

```console
sima@modalix:~$ lsusb | grep 0e8d:7961
Bus 002 Device 003: ID 0e8d:7961 MediaTek Inc. Wireless_Device
```

## 1. ホストでドライバーをビルドする {#build}

SiMa.ai のカーネルソースから、DevKit 自身のカーネル設定を使用して、`mt7921u` ドライバーと、それが依存する `mt76` モジュールをビルドします。ビルドは、DevKit のカーネルと同じコンパイラーを持つ Debian コンテナー内で実行されます。

以下のコマンドを**ホスト上で**実行します。`<devkit-ip>` は DevKit の IP アドレスに置き換えてください。

1. この手順で動作確認したカーネルソースのコミットをチェックアウトし、DevKit のカーネル設定を保存します。

```bash
git init simaai-linux &&
git -C simaai-linux fetch --depth 1 https://github.com/SiMa-ai/simaai-linux.git 65aba29989da02d7612da5484dbbcd50643fdd60 &&
git -C simaai-linux checkout --detach FETCH_HEAD &&
ssh sima@<devkit-ip> 'zcat /proc/config.gz' > board.config
```

2. モジュールをビルドします。

```bash
docker run --rm -v "$PWD":/w -w /w/simaai-linux debian:trixie bash -c '
apt-get update && apt-get install -y gcc-aarch64-linux-gnu make bc flex bison libssl-dev libelf-dev python3 kmod &&
export ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- LOCALVERSION=-modalix &&
cp ../board.config .config &&
scripts/config --module MT7921U &&
make olddefconfig &&
make -j"$(nproc)" modules_prepare &&
make -j"$(nproc)" M=drivers/net/wireless/mediatek/mt76 KBUILD_MODPOST_WARN=1 modules'
```

ビルド中に未解決シンボルに関する警告が表示されます。これは想定どおりです。これらのシンボルは、DevKit にすでに存在する `cfg80211` および `mac80211` モジュールに含まれています。

3. ビルドで 7 つのモジュールが作成されたことを確認します。

```bash
find simaai-linux/drivers/net/wireless/mediatek/mt76 -name '*.ko'
```

`mt76.ko`、`mt76-usb.ko`、`mt76-connac-lib.ko`、`mt792x-lib.ko`、`mt792x-usb.ko`、`mt7921-common.ko`、`mt7921u.ko` が得られます。

4. これらを DevKit にコピーします。

```bash
scp $(find simaai-linux/drivers/net/wireless/mediatek/mt76 -name '*.ko') sima@<devkit-ip>:/tmp/
```

## 2. DevKit にドライバーとファームウェアをインストールする {#install}

以下のコマンドを**DevKit 上で**実行します。

1. モジュールをインストールし、モジュールインデックスを更新します。

```console
sima@modalix:~$ sudo mkdir -p /lib/modules/$(uname -r)/updates/mt76
sima@modalix:~$ sudo mv /tmp/mt7*.ko /lib/modules/$(uname -r)/updates/mt76/
sima@modalix:~$ sudo depmod -a
```

2. アダプターのファームウェアとワイヤレス規制データベースをインストールします。

```console
sima@modalix:~$ sudo apt-get update
sima@modalix:~$ sudo apt-get install -y firmware-mediatek wireless-regdb
```

3. ドライバーを読み込みます。

```console
sima@modalix:~$ sudo modprobe mt7921u
```

以降は、起動時を含め、アダプターを接続するたびにドライバーが自動的に読み込まれます。

4. アダプターにワイヤレスインターフェースがあることを確認します。

```console
sima@modalix:~$ nmcli device status
DEVICE TYPE STATE CONNECTION
end0 ethernet connected end0-dhcp
wlxe84e06afdb5e wifi disconnected --
```

インターフェース名は `wlx` で始まり、その後にアダプターの MAC アドレスが続きます。表示されない場合は、`sudo dmesg | grep mt7921u` でドライバーのメッセージを確認してください。ファームウェアが読み込まれると、メッセージにファームウェアのバージョンが表示されます。

## 3. WiFi ネットワークに接続する {#connect}

DevKit で、NetworkManager のコマンドラインツールである `nmcli` を使用します。

1. ネットワークをスキャンします。

```console
sima@modalix:~$ sudo nmcli device wifi rescan
sima@modalix:~$ nmcli device wifi list
```

2. 接続します。`<SSID>` と `<password>` は、ネットワークの名前とパスワードに置き換えてください。

```console
sima@modalix:~$ sudo nmcli device wifi connect "<SSID>" password "<password>"
```

NetworkManager は接続を保存し、起動するたびにその接続に再接続します。

3. 接続を確認します。

```console
sima@modalix:~$ nmcli device status
sima@modalix:~$ ip -4 -br addr show
sima@modalix:~$ ping -c 3 -I wlxe84e06afdb5e 8.8.8.8
```

`wlxe84e06afdb5e` は、お使いのインターフェース名に置き換えてください。

代わりにメニューからネットワークを選択するには、`sudo nmtui` を実行して **Activate a connection** を選択します。

DevKit が Ethernet でも接続されている場合、Ethernet 接続がデフォルトルートのままになります。NetworkManager は WiFi に低い優先度を割り当てます。

## 制限事項 {#limitations}

- **ファームウェアを更新するとドライバーが削除されます。** モジュールは実行中のカーネル向けにビルドされています。DevKit のファームウェアを更新した後は、モジュールを再度ビルドしてインストールしてください。
- **他のアダプターには専用のドライバーが必要です。** このノートは MediaTek MT7921AU を対象としています。他のチップには、別のカーネルドライバーとファームウェアが必要です。
- **6 GHz はテストしていません。** アダプターは 6 GHz に対応していますが、このノートは 2.4 GHz と 5 GHz でのみテストしています。6 GHz を使用できるかどうかは、お住まいの国の規制にもよります。
Original file line number Diff line number Diff line change
Expand Up @@ -13,3 +13,4 @@ sidebar_position: 1
- [2.1.3에서 3.0.0으로 변환합니다.](./convert-2-1-3-to-3-0-0.md)
- [Modalix SoM DevKit에 Bluetooth를 설정합니다.](./bluetooth.mdx)
- [ROS 2를 Modalix SoM DevKit에 설치합니다.](./ros2.mdx)
- [Modalix SoM DevKit에서 USB WiFi 어댑터를 사용합니다.](./wifi.mdx)
Loading
Loading