コグノスケ

JavaとM5Stamp C3とBluetooth LE - ビルド準備編

目次: Arduino

M5Stamp C3をBluetooth LEデバイスにして、Linux PCもしくはRaspberry PiなどのLinux SBCとお話する取り組みの続編です。

今回はbluez-dbusを使ったJavaアプリのビルド準備をします。目的は依存するライブラリが全て含まれた（つまり単独で実行可能な）JARファイルを生成することです。ビルドシステムは昔はAntでしたが今はMavenがメジャーでしょうか？Mavenは依存関係の解消が楽で良いですね。

アプリ開発そのものはテキストエディタでもIntelliJ IDEAやEclipseなどのIDEでも、お好きなツールを使っていただければ良いかと思います。

基本的な設定

ビルドを試すだけならJavaのソースコードは不要で、プロジェクトのディレクトリにpom.xmlを作成するだけで試せます。今回作成するアプリはbluez-dbusに依存するので依存設定を記述するdependenciesタグはこんな感じにします。

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.github.hypfvieh</groupId>
                <artifactId>bluez-dbus</artifactId>
                <version>0.1.4</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>com.github.hypfvieh</groupId>
            <artifactId>bluez-dbus</artifactId>
        </dependency>
    </dependencies>

Mavenでは記述を2つに分けるのが推奨のようです、例えば依存関係の記述ならdependenciesタグとdependencyManagementタグに分けます。特に大きなプロジェクトだと複数のpom.xmlに渡ってビルドの設定を記述することが増え、各pom.xmlのdependenciesタグの中でバージョンなどを何度も書くと間違うし更新漏れが発生します。トップレベルにあるpom.xmlのdependencyManagementタグの中でバージョンなどを定義し、子レベルにあるpom.xmlではdependenciesタグから参照する使い方が良いのだとか。

今回はpom.xmlが1ファイルしかないので分けなくても問題ありません。分けない方の例も挙げましょう。プラグイン設定も同様にpluginsタグとpluginMnagementタグの2つに分けますが、ここではあえて1つのpluginsタグに全て書きます。

        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-assembly-plugin</artifactId>
                <executions>
                    <execution>
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <phase>package</phase>
                        <configuration>
                            <descriptorRefs>
                                <descriptorRef>jar-with-dependencies</descriptorRef>
                            </descriptorRefs>
                            <archive>
                                <manifest>
                                    <mainClass>main.java.Main</mainClass>
                                </manifest>
                            </archive>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>

上記に出てくるmaven-assembly-pluginは依存ライブラリを全て含んだJARファイルを生成できるプラグインです。jar-with-dependenciesという定義済みのdescriptorRefを指定すると良いそうです。階層構造といい変な名前といい何かの呪文のようです、とても覚えられません。

テストの設定などを除けば、基本的には依存ライブラリ設定とプラグイン設定で最低限の役目は果たすはずです。ですがビルドしてみたらめっちゃハマりました。Mavenつらい……。

ハマりポイントその1 - maven-assembly-pluginのバージョン

バージョンを特に指定しない場合、現状maven-assembly-pluginは2.2-beta-5というバージョンになります。が、このバージョンは動作がおかしいようでmvn packageがビルドエラーになります。

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.211 s
[INFO] Finished at: 2024-02-19T19:40:23+09:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-assembly-plugin:2.2-beta-5:single (default) on project bluetooth-test: Failed to create assembly: Error creating assembly archive jar-with-dependencies: A zip file cannot include itself -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

エラーの原因が全くわかりません。Mavenのエラーメッセージは全般的に何が言いたいのかわからず、pom.xmlのデバッグは困難を極めます。色々調べたり試した限りでは、プラグインのバージョンを2.1に固定するとこの現象は発生しなくなることがわかりました。何だそりゃ？どういうことだ……？？

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-assembly-plugin</artifactId>
                <version>2.1</version>    ★★バージョン2.1に固定した★★
                <executions>
                    <execution>
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <phase>package</phase>
                        <configuration>
                            <descriptorRefs>
                                <descriptorRef>jar-with-dependencies</descriptorRef>
                            </descriptorRefs>
                            <archive>
                                <manifest>
                                    <mainClass>main.java.Main</mainClass>
                                </manifest>
                            </archive>
                        </configuration>
                    </execution>
                </executions>
            </plugin>

本当に意味がわからないです。Mavenつらすぎる。

ハマりポイントその2 - 2回目のビルドとmaven-clean-plugin

次のハマりポイントはmvn packageを2回連続で実行すると下記のエラーが出て失敗することです。mvn-assembly-pluginどうなってんだお前……。

[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ bluetooth-test ---
[INFO] Building jar: /home/katsuhiro/ble-test/target/bluetooth-test-0.1.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.332 s
[INFO] Finished at: 2024-02-20T02:41:20+09:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-jar-plugin:2.4:jar (default-jar) on project bluetooth-test: Error assembling JAR: A zip file cannot include itself -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

なぜかmaven-jar-pluginがエラーを起こします。メッセージの意味がさっぱりわかりません。なぜかmaven-clean-pluginを追加して最初にcleanを実行すると現象が発生しなくなります。ビルド時のゴミが残っているのか？ビルドが毎回全てやり直しになるので遅いですけど、ビルドエラーよりはマシでしょう……。

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-clean-plugin</artifactId>
                <executions>
                    <execution>
                        <id>auto-clean</id>
                        <phase>initialize</phase>
                        <goals>
                            <goal>clean</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

やっとmvn packageが動作するようになりました。思い出していただきたいのは、Mavenの設定ファイルpom.xmlたった1つしか作っておらず、Java言語を1文字足りとも書いていないのにこの有様だということです。Mavenは著名ツールの割にエラーメッセージが意味不明すぎてつらいです。Maven使っている人はpom.xmlをどうやってデバッグしているんでしょうね？

ソースコード

ソースコードという程でもないですが、こちらからどうぞ。

•  上記の説明で使ったpom.xml（Mavenに渡すときはpom.xmlにリネームして使ってください）

JavaとM5Stamp C3とBluetooth LE - 導入編

目次: Arduino

以前の日記（2024年2月12日の日記参照）でM5Stamp C3をBluetooth LEデバイスにして、スマホのアプリとお話ができるようになりました。とくれば、次はM5Stamp C3とLinux PCもしくはRaspberry PiなどのLinux SBCとお話したくなります。

LinuxでBluetoothを扱う場合は、BlueZという実装を使います。BlueZはDBusというマシン内のイベントを配信するシステムに依存しており、軽く調べた感じではC言語からDBusを制御するのは結構大変そうです。Pythonだと簡単らしいですがGUIも実装したいんですよね。ちょっと悩みましたが久しぶりにJavaで書くことにしました。

素晴らしいことにJavaからBlueZを制御する場合、bluez-dbusという（bluez-dbusのリポジトリ）求めていた用途そのもののライブラリがあります。DBus制御は同作者さんのdbus-java（dbus-javaのリポジトリ）を使うようです。Unixソケットを使うライブラリにも依存しているようですね。

ちなみにbluez-dbusはJavaで実装されているものの、Javaの外の世界にOSやシステム依存（DBus、Unixソケットの存在に依存）があるため、Linuxでしか動作しないことに注意が必要です。用途次第ではWindowsやMacOSで動作しないと困るのでしょうけど、私が今回想定している用途ではLinux専用で問題ありません。ありがたくbluez-dbusを使わせていただきます。

bluez-dbusのドキュメント

ドキュメント（bluez-dbusのJavaDoc）を自分でビルドするのは大変なので、javadoc.ioを参照（Overview (bluez-dbus 0.1.4 API)）すると楽です。

ちなみにjavadoc.ioって何？と思ったらMavenに収容されているリポジトリのJavaDocを生成して公開してくれているサイトなのだそうです。ありがとうMavenプロジェクト、とても便利です。

LinuxでBluetooth LEデバイスをスキャンする

目次: Arduino

毎回BlueZというかhcitoolの使い方を忘れてググっているのでメモしておきます。

Bluetooth LEデバイスのスキャンはhcitool lescanです。Bluetoothアダプタが2つ以上あるなら-iオプション（-i hci0など）でアダプタを指定できます。lescanは別の機器Crtl+Cなどで止めるまで発見したBluetooth LEデバイスのMACアドレスが延々と流れ続けます。

デバイス情報を見る場合はhcitool leinfoです。

# hcitool leinfo (xx:xx:xx:xx:xx:xx)

Requesting information ...
        Handle: 55 (0x0037)
        LMP Version: 5.0 (0x9) LMP Subversion: 0x16
        Manufacturer: Espressif Incorporated ( ?鑫信息科技(上海)有限公司 ) (741)
        Features: 0x01 0xf9 0x01 0x00 0x00 0x00 0x00 0x00

M5Stamp C3のMACアドレスを指定して実行するとこんな情報が表示されました。SoCのESP32シリーズの製造元はEspressifなので合ってそうですね。

M5Stamp C3をBluetooth LE子機にする

目次: Arduino

M5Stamp C3はWi-FiとBluetooth LEが使えます。私はBluetooth規格は全く知らないですが、Arduino-ESP32にはBLEライブラリがあってお手軽にBluetooth LEによる通信ができます。Arduino-ESP32とは何者か？については以前の日記（2024年1月7日の日記参照）をご覧ください。

ライブラリがあるとはいえゼロからコードを書くのは結構大変です。しかし世の中にはArduino-ESP32 BLEのサンプル（ESP_32_BLE_Arduino）を公開している素敵なリポジトリがありまして、これを元に改造すると簡単です。ありがたいですね。

動作確認にはスマホを使います。Bluetooth LEに対応しているアプリならなんでも良いです。参考までに私はSerial Bluetooth Terminalというアプリ（Serial Bluetooth Terminal - Google Play）で確認しています。iPhoneは持ってないのでわかりません、アプリがあると思いますので頑張って探してください……。

TXとRXの割当

Arduino-ESP32 BLEのサンプル側はNordic nUARTのCharacteristic GATTのUUIDを使っていて、こんな設定になっています。

• 6E400001-B5A3-F393-E0A9-E50E24DCCA9E: Service GATT UUID
• 6E400002-B5A3-F393-E0A9-E50E24DCCA9E: RX（受信用、アプリから見たらWritable）Characteristic GATT UUID
• 6E400003-B5A3-F393-E0A9-E50E24DCCA9E: TX（送信用、アプリから見たらReadable）Characteristic GATT UUID

TXとRXがどちらから見た方向なのか混乱しますが、Serial Bluetooth TerminalのPredefined設定は賢いので間違えてTXとRXの定義が逆になっていても通信できてしまいます。

通信できれば問題ないとはいえ、正解を調べておいて損はないでしょう。Nordic Semiconductorのドキュメント（UART/Serial Port Emulation over BLE - Nordic Semiconductor Infocenter）を見ると、下記の記述があります。

This service exposes two characteristics: one for transmitting and one for receiving (as seen from the peer).

  - RX Characteristic (UUID: 6E400002-B5A3-F393-E0A9-E50E24DCCA9E)
    The peer can send data to the device by writing to the RX Characteristic of the service.
    ATT Write Request or ATT Write Command can be used. The received data is sent on the UART interface.
  - TX Characteristic (UUID: 6E400003-B5A3-F393-E0A9-E50E24DCCA9E)
    If the peer has enabled notifications for the TX Characteristic, the application can send data to the
    peer as notifications. The application will transmit all data received over UART as notifications.

RX Characteristic（UUID: 6E400002）の説明はsend data to deviceとあります。すなわちアプリ側にとってTXでありサンプル側にとってはRXとなるはずです。TXはその逆ですね。

• 6E400002-B5A3-F393-E0A9-E50E24DCCA9E: サンプルのRX Characteristic GATT UUID
• 6E400003-B5A3-F393-E0A9-E50E24DCCA9E: サンプルのTX Characteristic GATT UUID

• 6E400003-B5A3-F393-E0A9-E50E24DCCA9E: アプリから見たらRX方向
• 6E400002-B5A3-F393-E0A9-E50E24DCCA9E: アプリから見たらTX方向

とするのが正しそうですね。

気難しいM5Stamp C3のAutomatic Bootloader

目次: Arduino

M5Stamp C3の接続を変更したところ、Arduino Sketchが書き込めなくなってしまいました。こんなエラーで怒られます。

Sketch uses 1003156 bytes (76%) of program storage space. Maximum is 1310720 bytes.
Global variables use 38676 bytes (11%) of dynamic memory, leaving 289004 bytes for local variables. Maximum is 327680 bytes.
esptool.py v4.5.1
Serial port COM3
Connecting......................................

A fatal error occurred: Failed to connect to ESP32-C3: Wrong boot mode detected (0xc)! The chip needs to be in download mode.
For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html
Failed uploading: uploading error: exit status 2

回避策としてはboot modeを変えれば良いです。ジャンパーケーブルなどでGPIO 9をLowにして（隣のGNDと繋ぐと簡単）リセットします。リセットしたらジャンパーケーブルは外しましょう。GPIO 9はPull-upされているので、未接続だと勝手にHighになります。

M5Stamp C3のGPIO 9の位置

リセット後のシリアルに下記のようにROM serial bootloader for esptool Modeに入ったと表示されれば成功で、Arduinoなどから書き込みができる状態です。

ESP-ROM:esp32c3-api1-20210207
Build:Feb  7 2021
rst:0x1 (POWERON),boot:0x4 (DOWNLOAD(USB/UART0/1))
waiting for download

これでArduino Sketchが書き込みできますが、いちいちジャンパーケーブル挿してリセットなどやっていられません。面倒臭すぎます。そもそも今までそんなことしていませんでした。

Automatic Bootloader

M5Stamp C3が採用しているEspressif ESP32-C3というSoCの書き込みツールesptoolは、Automatic Bootloaderといって先ほど紹介した「GPIO 9をLowにしてリセット」という操作を不要にする機能、つまりDownload Modeに勝手に切り替えてSketchを書き込んで、Normal Bootしてくれる素敵な機能があります（Boot Mode Selection - ESP32-C3 - esptool.py latest documentation）。

とても便利なAutomatic Bootloaderですが、USB接続のトポロジーに敏感で結構気難しいやつだということがわかりました。私の環境ではUSBハブを介して接続すると発動しなくなります。なんでだー。

• CPU: AMD Ryzen 7 2700
• マザーボード: ASUS ROG STRIX B450-F GAMING
• OS: Windows 10 Pro 22H2
• USBポート: フロントパネル用ポート（オンボードコネクタから引き出すタイプ）

Automatic Bootloaderがうまく行くパターンはRootハブに直接接続したときです。接続例を示します。

Rootハブに直接M5Stamp C3を接続

うまく行くとログはこんな感じになります。

Sketch uses 1003156 bytes (76%) of program storage space. Maximum is 1310720 bytes.
Global variables use 38676 bytes (11%) of dynamic memory, leaving 289004 bytes for local variables. Maximum is 327680 bytes.
esptool.py v4.5.1
Serial port COM3
Connecting....
Chip is ESP32-C3 (revision v0.3)
Features: WiFi, BLE
Crystal is 40MHz
MAC: 84:f7:03:27:f8:14
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Configuring flash size...
（...以下略...）

うまく行かないパターンはUSBハブを介して接続したときです。接続例を示します。

USBハブを経由してM5Stamp C3を接続

ハブに依存するかもしれないと思い、USBハブはUSB 2.0とUSB 3.0のものを試しましたがどちらもダメでした。嫌な感じの挙動です。バグっぽいなー。

複数台接続はOK

もう一つの可能性として、M5Stamp C3を複数台繋ぐこと自体がだめな可能性を考えました。が、こちらは特に問題ありませんでした。せめてもの救いですね。

1台でも2台でも、USBハブを入れるとAutomatic Bootloaderが無効になってしまうようです。接続したい台数は3台なんですが、フロントポートは2つしかありません。困ったね……。

複数の音声ファイルのラウドネスを統一したい

目次: Python

PCやデジタル音楽プレーヤーで音楽を聞いていると、曲によって音量の大小が激しく違っていて鬱陶しいです。片や何も聞こえず、片やリスナーの耳を壊す勢いの爆音で同じ音量で聞き続けるのが困難です。

人が感じる音の大きさをラウドネス（Loudness）と呼びますけども、全ての曲のラウドネスを一定レベルに修正すれば、極端な沈黙や爆音を避け同じくらいの音量で楽しめるはずです。ラウドネスの修正を行うツールはffmpeg-normalizeが簡単でわかりやすかったです。Pythonで実装されていて内部ではffmpegのloudnormフィルターを使っているそうです。

インストール方法はpipを実行するだけで簡単です。ローカルのPython環境に影響が及ぶのが嫌な方はvenv（venv - 仮想環境の作成 - Python 3.12 ドキュメント）を作成し、仮想環境にインストールすると良いです。

$ python3 -m venv ./venv
$ source ./venv/bin/activate
$ pip install ffmpeg-normalize

基本的な使い方はffmpeg-normalize (入力ファイル名) -o (出力ファイル名)ですが、デフォルトパラメータがターゲットレベル-23LUFS、サンプリングレート192kHz、Matroska（拡張子.mkv）形式となっています。サンプリングレートとかは好み次第ですけど、ターゲットレベル-23LUFSはすっっっごい音が小さいです……。最初試したときに、音が消えてしまうぞ？おかしいなあ？？と悩みました。

これらの設定を変更するときは、-tオプションでターゲットレベルを、-arオプションでサンプリングレートを、-extオプションで出力形式を変更してください。

2パス処理を諦めないで

基本的にffmpeg-normalizeは2パス（1回目でファイル全体を解析、2回目でノーマライズ処理）でノーマライズを試みますが、曲のラウドネスの幅がターゲットLRA（Loudness Range、曲全体のラウドネスの幅、デフォルトは7.0LUFS）を超えると2パスのノーマライズを諦めてしまいます。

$ ffmpeg-normalize test.mp3

WARNING: Output directory 'normalized' does not exist, will create

★★↑出力ディレクトリを指定しないとnormalizedというディレクトリを自動的に作る


WARNING: Input file had loudness range of 7.8. This is larger than the loudness range target (7.0). Normalization will revert to dynamic mode. Choose a higher target loudness range if you want linear normalization. Alternatively, use the --keep-loudness-range-target or --keep-lra-above-loudness-range-target option to keep the target loudness range from the input.

★★↑2パスを諦めたよ、というWARNING


WARNING: In dynamic mode, the sample rate will automatically be set to 192 kHz by the loudnorm filter. Specify -ar/--sample-rate to override it.

★★↑2パスを諦めてdynamicモードになると192kHzで再エンコードし始める

WARNINGを見ると、この挙動を回避したければ--keep-lra-above-loudness-range-targetオプションを付けてねと書いてありますが、オプションによる悪影響の有無が良くわかりません。変換後の音楽をいくつか確認した限りでは、破綻やクリッピングが発生している様子はなさそうです、たぶん付けておいて良いのかな……？？

複数ファイルの扱い

複数のファイルを処理する際はシェルスクリプトを組んだほうが良いと思います。ffmpeg-normalizeに複数ファイルを渡すと1つのディレクトリ（デフォルトではnormalizedという名前のディレクトリ）に出力するからです。

例えばアルバムごとにディレクトリを分けて音声ファイルを格納している場合に困ります。ノーマライズ後のファイルが1つのディレクトリにまとめられてしまうと、再度アルバムのディレクトリに分配しなければならず面倒です。

for i in */*.flac; \
  do echo $i -----; \
  ffmpeg-normalize -t -14 --keep-lra-above-loudness-range-target \
    -ar 48000 -ext wav "$i" \
    -o "`echo $i | sed -e 's/flac\$/wav/g'`"; \
done

全アルバムディレクトリのflacを、ノーマライズしたwavに変換するならこんな感じです。適当スクリプトなので入力と出力を同じファイル名にできません。一度別名を経由して元の名前にリネームするように改造していただければと思います。