M5Module-LLM Arduino ドライバーライブラリ API ドキュメントです。
M5ModuleLLMは Module LLM を初期化するために使用され、内部メンバを提供して LLM の各ユニットを迅速に初期化し、独自のニーズに応じてアプリケーションを構築するのに便利です。
class M5ModuleLLM {
public:
bool begin(Stream * targetPort);
bool checkConnection();
void update();
m5_module_llm::ApiSys sys;
m5_module_llm::ApiLlm llm;
m5_module_llm::ApiAudio audio;
m5_module_llm::ApiTts tts;
m5_module_llm::ApiTts melotts;
m5_module_llm::ApiKws kws;
m5_module_llm::ApiAsr asr;
m5_module_llm::ApiAsr yolo;
m5_module_llm::ApiVad vad;
m5_module_llm::ApiWhisper whisper;
m5_module_llm::ApiDepthAnything depthanything;
m5_module_llm::ModuleMsg msg;
m5_module_llm::ModuleComm comm;
private:
};
関数プロトタイプ:
bool begin(Stream* targetPort);
機能説明:
入力パラメーター:
返り値:
関数プロトタイプ:
bool checkConnection();
機能説明:
sys.ping
指令を送信し、Module LLM の接続状態をチェックする。入力パラメーター:
返り値:
関数プロトタイプ:
void update();
機能説明:
入力パラメーター:
返り値:
M5ModuleLLM
の内部メンバー ApiSys sys
は、SYS ユニットを制御してシステムリセットなどの操作を実行するために使用されます。
関数プロトタイプ:
int ping();
機能説明:
sys.ping
コマンドを送信し、Module LLM の接続状態をチェックする。入力パラメーター:
返り値:
関数プロトタイプ:
int reset(bool waitResetFinish = true);
機能説明:
sys.reset
指令を送信し、ソフトウェアサービスをリセットする。入力パラメーター:
返り値:
関数プロトタイプ:
int reboot();
機能説明:
sys.reboot
指令を送信し、システムをリセットする。入力パラメーター:
返り値:
注意:この関数は 1.3 以降のバージョンでは非推奨となり、内部で自動的に設定されるようになりました。
M5ModuleLLM
の内部メンバ ApiAudio audio
は、Audio ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiAudioSetupConfig_t config = ApiAudioSetupConfig_t(), String request_id = "audio_setup");
機能説明:
入力パラメーター:
ApiAudioSetupConfig_t config:
struct ApiAudioSetupConfig_t {
int capcard = 0;
int capdevice = 0;
float capVolume = 0.5;
int playcard = 0;
int playdevice = 1;
float playVolume = 0.15;
};
パラメータ | 説明 | 入力値 |
---|---|---|
capcard | マイクのサウンドカードのインデックス | システムデフォルトのサウンドカード:0 |
capdevice | マイクデバイスのインデックス | 板載のシリコンマイク:0 |
capVolume | 入力音量 | 0.0~10.0 (1<volume はゲインを上げます、デフォルト値は 0.5) |
playcard | スピーカーのサウンドカードのインデックス | システムデフォルトのサウンドカード:0 |
playdevice | スピーカーデバイスのインデックス | 板載のスピーカー:1 |
playVolume | 出力音量 | 0.0~10.0 (1<volume はゲインを上げます、デフォルト値は 0.5) |
返り値:
M5ModuleLLM
の内部メンバ ApiCamera camera
は、Camera ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiCameraSetupConfig_t config = ApiCameraSetupConfig_t(), String request_id = "camera_setup");
機能説明:
入力パラメーター:
ApiCameraSetupConfig_t config:
struct ApiCameraSetupConfig_t {
String response_format = "camera.raw";
String input = "/dev/video0";
bool enoutput = false;
int frame_width = 320;
int frame_height = 320;
};
パラメータ | 説明 | 入力値 |
---|---|---|
input | UVC のインデックス | "/dev/video0" |
enoutput | シリアル出力画像データの有無 | 有効: true 無効: false |
frame_width | キャプチャ画像の幅 | 320 |
frame_height | キャプチャ画像の高さ | 320 |
返り値:
M5ModuleLLM
の内部メンバー ApiKws kws
は、KWS ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiKwsSetupConfig_t config = ApiKwsSetupConfig_t(),
String request_id = "kws_setup",
String language = "en_US");
機能説明:
入力パラメーター:
ApiKwsSetupConfig_t config:
struct ApiKwsSetupConfig_t {
String kws = "HELLO";
String model = "sherpa-onnx-kws-zipformer-gigaspeech-3.3M-2024-01-01";
String response_format = "kws.bool";
String input = "sys.pcm";
bool enoutput = true;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | 英語モデル: "sherpa-onnx-kws-zipformer-gigaspeech-3.3M-2024-01-01" 中国語モデル: "sherpa-onnx-kws-zipformer-wenetspeech-3.3M-2024-01-01" |
kws | KWS 喚起語テキスト設定 | 中国語 / 英語の混合は許可されません。英語は大文字で入力してください |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
返り値:
M5ModuleLLM
の内部メンバ ApiVad vad
は、VAD ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiVadSetupConfig_t config = ApiVadSetupConfig_t(), String request_id = "vad_setup");
機能説明:
入力パラメーター:
ApiVadSetupConfig_t config:
struct ApiKwsSetupConfig_t {
String model = "silero-vad";
String response_format = "vad.bool";
String input = {"sys.pcm", "kws.1000"};
bool enoutput = true;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | モデル: "silero-vad" |
input | 入力 | KWS 喚起入力: "kws.xxx"(kws ユニットの work_id を入力) 板載マイク入力: "sys.pcm" UART ストリーム入力: "vad.wav.stream.base64" |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
返り値:
M5ModuleLLM
の内部メンバー ApiAsr asr
は、ASR ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiAsrSetupConfig_t config = ApiAsrSetupConfig_t(), String request_id = "asr_setup",
String language = "en_US");
機能説明:
入力パラメーター:
ApiAsrSetupConfig_t config:
struct ApiAsrSetupConfig_t {
String model = "sherpa-ncnn-streaming-zipformer-20M-2023-02-17";
String response_format = "asr.utf-8.stream";
String input = ["sys.pcm", "kws.1000"];
bool enoutput = true;
float rule1 = 2.4;
float rule2 = 1.2;
float rule3 = 30.0;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | 英語モデル: "sherpa-ncnn-streaming-zipformer-20M-2023-02-17" 中国語モデル: "sherpa-ncnn-streaming-zipformer-zh-14M-2023-02-23" |
response_format | 出力形式 | 通常出力: "asr.utf-8" ストリーミング出力: "asr.utf-8.stream" |
input | 入力 | KWS 喚起入力: "kws.xxx"(kws ユニットの work_id を入力) ボード内蔵マイク入力: "sys.pcm" UART ストリーミング入力: "asr.wav.stream.base64" |
rule1 | 喚起から内容未認識までのタイムアウト時間 | 単位:秒 |
rule2 | 認識最大間隔時間 | 単位:秒 |
rule3 | 認識最長タイムアウト時間 | 単位:秒 |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
返り値:
M5ModuleLLM
の内部メンバーApiWhisper whisper
は、Whisper ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiWhisperSetupConfig_t config = ApiWhisperSetupConfig_t(), String request_id = "asr_setup",
機能説明:
Input パラメーター:
ApiWhisperSetupConfig_t config:
struct ApiAsrSetupConfig_t {
String model = "whisper-tiny";
String response_format = "asr.utf-8";
String input = [ "sys.pcm", "kws.1000", "vad.1001" ];
String language = "en";
bool enoutput = true;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | モデル: "whisper-tiny" |
response_format | 出力形式 | 通常出力: "asr.utf-8" |
input | 入力 | KWS 喚起入力: "kws.xxx"(入力 kws ユニットの work_id) ボード内蔵マイク入力: "sys.pcm" UART ストリーム入力: "asr.wav.stream.base64" |
language | 言語認識に使用する言語 | デフォルト “en” 選択可能な値: “zh”, "ja" |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
返り値:
M5ModuleLLM
の内部メンバー ApiLlm llm
は、LLM ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiLlmSetupConfig_t config = ApiLlmSetupConfig_t(), String request_id = "llm_setup");
機能説明:
入力パラメーター:
struct ApiLlmSetupConfig_t {
String prompt;
String model = "qwen2.5-0.5B-prefill-20e";
String response_format = "llm.utf-8.stream";
String input = ["llm.utf-8", "kws.1000"];
bool enoutput = true;
int max_token_len = 127;
};
パラメータ | 説明 | 入力値 |
---|---|---|
response_format | 出力形式 | 通常出力: "llm.utf-8" ストリーミング出力: "llm.utf-8.stream" |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
model | 変換モデル | プリセットモデル "qwen2.5-0.5B-prefill-20e" |
max_length | 最大出力トークンを設定(最大返信推論テキスト長) | 最大値: 1023 |
input | 入力 | ASR 入力: "asr.xxx"(asr ユニットの work_id を入力) UART 入力: "llm.utf-8" KWS 喚起割り込み: "kws.xxx"(kws ユニットの work_id を入力) |
prompt | モデル初期化システムプロンプト | String |
返り値:
llm_work_id
: LLM ユニット work ID関数プロトタイプ:
int inference(String work_id, String input, String request_id = "llm_inference");
機能説明:
M5ModuleLLM.msg
の responseMsgList
リストコンテナに入ります。入力パラメーター:
返り値:
MODULE_LLM_OK
/ Error Code関数プロトタイプ:
int inferenceAndWaitResult(String work_id, String input, std::function<void(String&)> onResult, uint32_t timeout = 5000, String request_id = "llm_inference");
機能説明:
入力パラメーター:
返り値:
MODULE_LLM_OK
/ Error CodeM5ModuleLLM
の内部メンバー ApiVlm vlm
は、VLM ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiVlmSetupConfig_t config = ApiVlmSetupConfig_t(), String request_id = "vlm_setup");
機能説明:
入力パラメータ:
struct ApiVlmSetupConfig_t {
String prompt;
String model = "internvl2.5-1B-ax630c";
String response_format = "vlm.utf-8.stream";
String input = ["vlm.utf-8", "kws.1000"];
bool enoutput = true;
int max_token_len = 1023;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | 事前設定モデル "internvl2.5-1B-ax630c" |
response_format | 出力形式 | 通常出力: "vlm.utf-8" ストリーミング出力: "vlm.utf-8.stream" |
input | 入力 | ASR 入力: "asr.xxx"(asr ユニットの work_id を入力) UART 入力: "llm.utf-8" KWS 喚起中断: "kws.xxx"(kws ユニットの work_id を入力) |
max_length | 最大出力トークンを設定 (最大返却推論テキスト長) | 最大値: 1023 |
prompt | モデル初期化システムプロンプト | String |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
返り値:
vlm_work_id
: VLM ユニット work ID関数プロトタイプ:
int inference(String work_id, String input, String request_id = "vlm_inference");
機能説明:
M5ModuleLLM.msg
内のresponseMsgList
リストコンテナに入ります。入力パラメーター:
返り値:
MODULE_LLM_OK
/ Error Code関数プロトタイプ:
int inferenceAndWaitResult(String work_id, String input, std::function<void(String&)> onResult,
uint32_t timeout = 5000, String request_id = "vlm_inference");
機能説明:
入力パラメーター:
返り値:
MODULE_LLM_OK
/ Error CodeM5ModuleLLM
の内部メンバー ApiTts tts
は、TTS ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiTtsSetupConfig_t config = ApiTtsSetupConfig_t(), String request_id = "tts_setup");
機能説明:
入力パラメータ:
ApiTtsSetupConfig_t config:
struct ApiTtsSetupConfig_t {
String model = "single_speaker_english_fast";
String response_format = "sys.pcm";
String input = ["tts.utf-8.stream", "kws.1000"];
bool enoutput = false;
bool enaudio = true;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | 英語モデル: "single_speaker_english_fast" 中国語モデル: "single_speaker_fast" |
input | 入力 | LLM 入力: "llm.xxx"(入力 llm ユニットの work_id) UART 入力: "tts.utf-8" UART ストリーミング入力: "tts.utf-8.stream" KWS 喚起割り込み: "kws.xxx"(入力 kws ユニットの work_id) |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
enaudio | スピーカー再生を有効にする | 有効: true 無効: true |
返り値:
関数プロトタイプ:
int inference(String work_id, String input, uint32_t timeout = 0, String request_id = "tts_inference");
機能説明:
入力パラメータ:
返り値:
M5ModuleLLM
の内部メンバー ApiMelotts melotts
は、Melotts ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiMelottsSetupConfig_t config = ApiMelottsSetupConfig_t(), String request_id = "melotts_setup",
String language = "en_US");
機能説明:
入力パラメータ:
ApiMelottsSetupConfig_t config:
struct ApiMelottsSetupConfig_t {
String model = "melotts_zh-cn";
String response_format = "sys.pcm";
std::vector<String> input = {"tts.utf-8.stream"};
bool enoutput = false;
bool enaudio = true;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | 中国語と英語のモデル: "melotts_zh-cn" 中国語のモデル: "single_speaker_fast" |
input | 入力 | LLM 入力: "llm.xxx"(llm ユニットの work_id を入力) UART 入力: "melotts.utf-8" UART ストリーミング入力: "melotts.utf-8.stream" |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
enaudio | スピーカー再生を有効にする | 有効: true 無効: true |
返り値:
関数プロトタイプ:
int inference(String work_id, String input, uint32_t timeout = 0, String request_id = "tts_inference");
機能説明:
入力パラメーター:
返り値:
M5ModuleLLM
の内部メンバ ApiYolo yolo
は、Yolo ユニットの初期化と設定を制御するために使用されます。
関数プロトタイプ:
String setup(ApiYoloSetupConfig_t config = ApiYoloSetupConfig_t(), String request_id = "yolo_setup");
機能説明:
入力パラメーター:
ApiYoloSetupConfig_t config:
struct ApiYoloSetupConfig_t {
String model = "yolo11n";
String response_format = "yolo.box.stream";
std::vector<String> input = {"yolo.jpeg.base64"};
bool enoutput = true;
};
パラメータ | 説明 | 入力値 |
---|---|---|
model | 変換モデル | 検出モデル: "yolo11n" 姿勢モデル: "yolo11n-pose" 手の姿勢モデル: "yolo11n-hand-pose" |
response_format | 出力形式 | 検出出力: "yolo.box.stream" 姿勢出力: "yolo.pose.stream" |
input | 入力 | UVC 入力: "camera.xxx"(カメラユニットの work_id を入力) UART ストリーム入力: "yolo.jpeg.base64.stream" |
enoutput | UART 出力を有効にする | 有効: true 無効: false |
返り値:
M5ModuleLLM
の内部メンバー ModuleMsg msg
は、Module LLM から返される様々な情報をキャッシュするために responseMsgList
コンテナを提供しています。以下のケースを参考に、メインループで返される結果をループ処理して取得します。
void loop()
{
module_llm.update();
// Handle response msg
for (auto& msg : module_llm.msg.responseMsgList) {
// KWS msg
if (msg.work_id == kws_work_id) {
Serial.printf(">> Keyword detected\n");
}
// ASR msg
if (msg.work_id == asr_work_id) {
if (msg.object == "asr.utf-8.stream") {
// Parse and get asr result
JsonDocument doc;
deserializeJson(doc, msg.raw_msg);
String asr_result = doc["data"]["delta"].as<String>();
Serial.printf(">> %s\n", asr_result.c_str());
}
}
}
module_llm.msg.responseMsgList.clear();
}
M5ModuleLLM_VoiceAssistant
は、LLM 音声アシスタントのインスタンスを迅速に作成し、KWS(音声喚起)->ASR(音声をテキストに変換)->LLM(大規模言語モデル推論)->TTS(テキストを音声に変換)を迅速に実現するために使用されます。
M5ModuleLLM
のインスタンスをコンストラクタに渡し、対応するイベントのコールバック関数を登録するだけで、音声アシスタントの作成が完了します。/*
* SPDX-FileCopyrightText: 2024 M5Stack Technology CO LTD
*
* SPDX-License-Identifier: MIT
*/
#include <Arduino.h>
#include <M5Unified.h>
#include <M5ModuleLLM.h>
M5ModuleLLM module_llm;
M5ModuleLLM_VoiceAssistant voice_assistant(&module_llm);
/* On ASR data callback */
void on_asr_data_input(String data, bool isFinish, int index)
{
M5.Display.setTextColor(TFT_GREEN, TFT_BLACK);
M5.Display.printf(">> %s\n", data.c_str());
/* If ASR data is finish */
if (isFinish) {
M5.Display.setTextColor(TFT_YELLOW, TFT_BLACK);
M5.Display.print(">> ");
}
};
/* On LLM data callback */
void on_llm_data_input(String data, bool isFinish, int index)
{
M5.Display.print(data);
/* If LLM data is finish */
if (isFinish) {
M5.Display.print("\n");
}
};
void setup()
{
M5.begin();
M5.Display.setTextSize(2);
M5.Display.setTextScroll(true);
/* Init module serial port */
Serial2.begin(115200, SERIAL_8N1, 16, 17); // Basic
// Serial2.begin(115200, SERIAL_8N1, 13, 14); // Core2
// Serial2.begin(115200, SERIAL_8N1, 18, 17); // CoreS3
/* Init module */
module_llm.begin(&Serial2);
/* Make sure module is connected */
M5.Display.printf(">> Check ModuleLLM connection..\n");
while (1) {
if (module_llm.checkConnection()) {
break;
}
}
/* Begin voice assistant preset */
M5.Display.printf(">> Begin voice assistant..\n");
int ret = voice_assistant.begin("HELLO");
if (ret != MODULE_LLM_OK) {
while (1) {
M5.Display.setTextColor(TFT_RED);
M5.Display.printf(">> Begin voice assistant failed\n");
}
}
/* Register on ASR data callback function */
voice_assistant.onAsrDataInput(on_asr_data_input);
/* Register on LLM data callback function */
voice_assistant.onLlmDataInput(on_llm_data_input);
M5.Display.printf(">> Voice assistant ready\n");
}
void loop()
{
/* Keep voice assistant preset update */
voice_assistant.update();
}
enum ModuleLLMErrorCode_t {
MODULE_LLM_OK = 0,
MODULE_LLM_RESET_WARN = -1,
MODULE_LLM_JSON_FORMAT_ERROR = -2,
MODULE_LLM_ACTION_MATCH_FAILED = -3,
MODULE_LLM_INFERENCE_DATA_PUSH_FAILED = -4,
MODULE_LLM_MODEL_LOADING_FAILED = -5,
MODULE_LLM_UNIT_NOT_EXIST = -6,
MODULE_LLM_UNKNOWN_OPERATION = -7,
MODULE_LLM_UNIT_RESOURCE_ALLOCATION_FAILED = -8,
MODULE_LLM_UNIT_CALL_FAILED = -9,
MODULE_LLM_MODEL_INIT_FAILED = -10,
MODULE_LLM_MODEL_RUN_FAILED = -11,
MODULE_LLM_MODULE_NOT_INITIALISED = -12,
MODULE_LLM_MODULE_ALREADY_WORKING = -13,
MODULE_LLM_MODULE_NOT_WORKING = -14,
MODULE_LLM_NO_UPDATEABLE_MODULES = -15,
MODULE_LLM_NO_MODULES_AVAILABLE_FOR_UPDATE = -16,
MODULE_LLM_FILE_OPEN_FAILED = -17,
MODULE_LLM_WAIT_RESPONSE_TIMEOUT = -97,
MODULE_LLM_RESPONSE_PARSE_FAILED = -98,
MODULE_LLM_ERROR_NONE = -99,
};