概要

このマニュアルは、OpenCCVoice / DVSwitch Bot を運用する方向けの操作マニュアル（逆引き集）です。「こうしたいときは、これを打つ」を素早く引けるよう、各操作を「目的 → コマンド → 確認方法」のセットで記載しています。仕組みの説明は別冊『システム仕様書』を参照してください。

前提条件

本マニュアルは、以下の環境を前提としています。

• 対象システム：Raspberry Pi OS（Bookworm）＋ DVSwitch-Server ＋ デーモン分離版 Bot（V1.73）
• スクリプト配置：/opt/dvswitch_bot/bin/
• サービス名：dvswitch-bot（ハイフン）

まず覚える基本操作

迷ったらこの 4 つです。

状態を見ます。

sudo systemctl status dvswitch-bot --no-pager

再起動します（設定やスクリプトを変えた後）。

sudo systemctl restart dvswitch-bot

ログを流し見します（「Ctrl + C」で抜ける。bot は止まらない）。

sudo journalctl -u dvswitch-bot -f

設定を変えます（対話）。反映は再起動です。

sudo python3 /opt/dvswitch_bot/bin/bot_setup.py

sudo systemctl restart dvswitch-bot

運用フロー（全体像）

「設定を変えたい」「音声を変えたい」など、目的別の作業の流れです。

日常操作：起動・停止・状態確認

状態を確認する

sudo systemctl status dvswitch-bot --no-pager

見るポイントは以下のとおりです。

• Active: active (running)…正常に動いている
• Active: inactive (dead)…停止している
• Active: activating (auto-restart)…起動に失敗して再起動を繰り返している（設定不正を疑う。「トラブル対応」へ）

起動・停止・再起動

起動します。

sudo systemctl start dvswitch-bot

停止します。

sudo systemctl stop dvswitch-bot

再起動します（設定変更の反映に使う）。

sudo systemctl restart dvswitch-bot

自動起動（電源投入時に自動で立ち上がる設定）

自動起動を有効化します。

sudo systemctl enable dvswitch-bot

自動起動を無効化します。

sudo systemctl disable dvswitch-bot

現在の設定を確認します（enabled / disabled）。

sudo systemctl is-enabled dvswitch-bot

ログの見方

常駐中の Bot は画面に出力されず、すべて journal（システムログ）に記録されます。

リアルタイムで流し見する（最もよく使う）

sudo journalctl -u dvswitch-bot -f

-f は「流し続ける」という意味です。カーチャンク応答や時報が出る様子をそのまま眺められます。「Ctrl + C」で抜けます（Bot は止まらず、表示だけ終わる）。

直近のログをまとめて見る

直近 50 行を見ます。

sudo journalctl -u dvswitch-bot -n 50 --no-pager

今日のぶんを見ます。

sudo journalctl -u dvswitch-bot --since today --no-pager

直近 1 時間を見ます。

sudo journalctl -u dvswitch-bot --since "1 hour ago" --no-pager

ログの読み方（よく出るメッセージ）

エラーだけ拾う

sudo journalctl -u dvswitch-bot --since today --no-pager | grep -iE "error|!!|fail"

設定変更（受信時間・時刻案内・放送回数・ナイトモード・送出音量）

Bot 本体（dvswitch_bot.py）は編集しません。設定は原則 bot_setup.py で変えます。送出音量 TX_GAIN も bot_setup.py／ダッシュボードで設定できます（後述）。

現在の設定を確認する

sudo python3 /opt/dvswitch_bot/bin/bot_setup.py -s

設定値の表示と、有効性チェック（[OK] か [WARN]）が出ます。

設定を変更する（対話）

sudo python3 /opt/dvswitch_bot/bin/bot_setup.py

対話で以下を聞かれます（Enter で現在値を維持）。

時刻案内モード（TIME_SIGNAL_MODE）— V1.64〜

時報（時刻案内）の頻度を選べます。bot_config.json の TIME_SIGNAL_MODE で指定します（任意キー。未設定の旧設定は従来動作＝モード 1 として扱う）。

放送回数（ANNOUNCE_FREQ）の有効範囲はモードに依存します（正時 / 30 分は時刻案内が占有するため）。

変更を反映する（必須）

sudo systemctl restart dvswitch-bot

sudo journalctl -u dvswitch-bot -n 25 --no-pager

起動ログで設定が反映されているか確認します。

ナイトモードの動作

放送回数を例えば「2 回（:20, :40）」、N1=22、N2=5 と設定した場合は以下のとおりです。

ポイントは、N1（22 時）の時報と突入アナウンスは出るが、その後の同じ時間帯の定時メッセージは出さない点です。起動ログでは time_signal : suppress 23-05 / sched_message : suppress 22-05 と表示されます（カーチャンク応答は 24 時間動作し、ナイトモードの影響を受けません）。

送出音量（TX_GAIN）— 手動設定 / V1.68〜（上級者向け）

bot が送出するすべての音声（カーチャンク ID・時報・30 分案内・起動 / ナイト案内・定時メッセージ 001/002）の音量を、線形倍率 TX_GAIN（1.0＝等倍）で一律に調整できます。Analog_Bridge.ini の usrpGain と同じ表現で、主用途は減衰（1.0 未満）です。

設定手順（手動で JSON を編集）は以下のとおりです。

まず現在の設定を確認します。

cat /opt/dvswitch_bot/bot_config.json

エディタで TX_GAIN を追記します（例：0.7 に減衰）。"TX_GAIN": 0.7 を JSON に 1 行追加します（他のキーと同じ階層）。

sudo nano /opt/dvswitch_bot/bot_config.json

反映します。

sudo systemctl restart dvswitch-bot

sudo journalctl -u dvswitch-bot -n 25 --no-pager | grep -i "TX gain"

• 有効範囲：0.0 より大きく 5.0 以下。1.0 を超えると増幅（クリップに注意）。
• 値が不正（数値でない / 0 以下 / 範囲外）でも送出は止めず、等倍（1.0）にフォールバックして警告ログを出します。
• 起動ログに TX gain : 0.7 (減衰 / vol 効果を全送出に付与) のように表示されます。

音声の変更（固定 WAV・試聴）

コールサインや案内文を変えたいときは、固定 WAV を作り直します。運用を続けたまま（常駐させたまま）作り直せます。

カスタム音声（cstm）に差し替える — V1.73〜

bot が送出する intro（名乗り）・定時メッセージ 001・002 を、自前の WAV に個別に差し替えられます。標準ファイル（fixed_intro.wav／001.wav／002.wav）はそのまま残し、/opt/dvswitch_bot/ 直下に cstm_intro.wav／cstm_001.wav／cstm_002.wav（8000 Hz・モノラル・16-bit）を置きます。

有効化は 2 通りあります（どちらでも結果は同じです）。

• ダッシュボード：ブラウザでダッシュボードを開き、「変更モード」→「カスタム音声 — 差し替え」カードで使う項目にチェック →「保存」（自動でサービス再起動・反映）。
• 対話設定：sudo python3 /opt/dvswitch_bot/bin/bot_setup.py で intro／001／002 を個別に選びます。

intro をカスタムにすると、それを使う 3 か所（カーチャンク応答・起動アナウンス・ナイトアナウンスの名乗り）すべてに効きます。時報イントロ time_intro.wav は差し替え対象外です。

詳しい作成手順・つまずきポイントは GitHub リポジトリの カスタム音声.md を参照してください。

運用途中で固定 WAV を作り直す（対話）

cd /opt/dvswitch_bot/bin
sudo ./create_wav.sh

コールサイン・地名・定時メッセージ 1/2 を対話入力すると、英数字を自動でカナ変換し、/opt/dvswitch_bot/ 直下に WAV を生成（上書き）します（fixed_intro / fixed_outro / time_intro / 001 / 002）。

念のため停止します（任意）。

sudo systemctl stop dvswitch-bot

作り直します。

cd /opt/dvswitch_bot/bin && sudo ./create_wav.sh

作り直し後に再開します。

sudo systemctl start dvswitch-bot

通常は停止せずに作り直しても問題ありませんが、確実にしたいときの手順です。

生成された WAV を確認する

ls -la /opt/dvswitch_bot/*.wav

音声フォーマット（8000 Hz / 1ch / 16-bit）を確認します。

soxi /opt/dvswitch_bot/*.wav

ファイルの更新時刻が今になっていれば、上書きできています。

試聴する（実際に電波に乗せて聞く）

二重送信を避けるため、先に Bot を止めます。

sudo systemctl stop dvswitch-bot

python3 /opt/dvswitch_bot/bin/test_send.py /opt/dvswitch_bot/001.wav

python3 /opt/dvswitch_bot/bin/test_send.py /opt/dvswitch_bot/fixed_intro.wav

確認できたら Bot を戻します。

sudo systemctl start dvswitch-bot

作り直しに失敗した → 元の音声に戻す（復元）

cd /opt/dvswitch_bot/bin
sudo ./create_wav.sh -r

日付フォルダの一覧が出るので、戻したい番号を選びます。復元後は再起動不要で次の送出から反映されます。

古いバックアップをまとめて消したいときは以下を実行します（/opt/dvswitch_bot/bak/wav/ を全削除。確認あり）。

cd /opt/dvswitch_bot/bin
sudo ./create_wav.sh -d

DVSwitch 設定の変更（コールサイン・TGIF・TG）

コールサイン・DMR ID・TGIF パスワード・送信 TG を変えるときは dvs_config.sh を使います。3 つの ini を編集する前に自動でバックアップを取ります。

設定変更（対話）

cd /opt/dvswitch_bot/bin
sudo ./dvs_config.sh

対話入力します（Enter で現状維持）。

最後に「サービスを再起動しますか？（y/N）」と聞かれます。y で analog_bridge と mmdvm_bridge が再起動され、設定が反映されます。

バックアップから復元する

cd /opt/dvswitch_bot/bin
sudo ./dvs_config.sh -r

古いバックアップを全部消す

cd /opt/dvswitch_bot/bin
sudo ./dvs_config.sh -d

スクリプトの更新（GitHub から最新版を反映）

GitHub リポジトリのスクリプトを更新したら、実機にも反映します。

現行をバックアップ

sudo cp /opt/dvswitch_bot/bin/dvswitch_bot.py \
        /opt/dvswitch_bot/bin/dvswitch_bot.py.bak.$(date +%F_%H%M%S)

最新版を取得して上書き

cd /opt/dvswitch_bot/bin
BASE=https://raw.githubusercontent.com/ji2tab/OpenCCVoice-For-DVSwitch/main
curl -fsSL "$BASE/dvswitch_bot.py" -o dvswitch_bot.py
chmod +x dvswitch_bot.py

5 本まとめて取り直すなら以下を実行します。

cd /opt/dvswitch_bot/bin
for f in dvswitch_bot.py bot_setup.py test_send.py create_wav.sh dvs_config.sh; do
  curl -fsSL "$BASE/$f" -o "$f"
done
chmod +x *.py *.sh

バージョンを確認して再起動

人間向けの版表記を確認します。

grep -n "Document Version" /opt/dvswitch_bot/bin/dvswitch_bot.py | head -1

機械可読の固定バージョン行を確認します（V1.69〜。ダッシュボードはこちらを優先参照）。

grep -n '^version' /opt/dvswitch_bot/bin/dvswitch_bot.py | head -1

再起動して確認します。

sudo systemctl restart dvswitch-bot
sudo journalctl -u dvswitch-bot -n 25 --no-pager

起動ログのバージョン表記が更新されていれば反映成功です。

バックアップと復元

設定一式をまとめて保存する

mkdir -p ~/dvswitch_backup && cd ~/dvswitch_backup
sudo cp /opt/Analog_Bridge/Analog_Bridge.ini ./
sudo cp /opt/MMDVM_Bridge/MMDVM_Bridge.ini ./
cp /opt/dvswitch_bot/bin/dvswitch_bot.py ./
cp /opt/dvswitch_bot/bin/bot_setup.py ./
cp /opt/dvswitch_bot/bot_config.json ./
sudo cp /etc/systemd/system/dvswitch-bot.service ./ 2>/dev/null || true
cp /usr/share/hts-voice/mei/mei_normal.htsvoice ./
cd ~ && tar czf dvswitch_backup_$(date +%Y%m%d).tar.gz dvswitch_backup/

できた dvswitch_backup_YYYYMMDD.tar.gz を別の PC やクラウドに保管します。

ini だけ手早く戻す

dvs_config.sh -r（前述）が、ini のバックアップ / 復元には最も簡単です。

SD カードまるごとバックアップ（推奨・別 PC で）

Pi をシャットダウンし、SD を別 PC に挿して実行します。

デバイス名を確認します。

sudo fdisk -l

SD カードのイメージを取得します（/dev/sdX は確認した実際のデバイス名に置き換える）。

sudo dd if=/dev/sdX of=~/pi_backup_$(date +%Y%m%d).img bs=4M status=progress

イメージを圧縮します。

gzip ~/pi_backup_*.img

トラブル対応（逆引き）

よく使うコマンド早見表

サービス操作

sudo systemctl status dvswitch-bot --no-pager
sudo systemctl restart dvswitch-bot
sudo systemctl stop dvswitch-bot
sudo systemctl start dvswitch-bot

ログ

sudo journalctl -u dvswitch-bot -f
sudo journalctl -u dvswitch-bot -n 50 --no-pager

設定

sudo python3 /opt/dvswitch_bot/bin/bot_setup.py
sudo python3 /opt/dvswitch_bot/bin/bot_setup.py -s
sudo nano /opt/dvswitch_bot/bot_config.json
sudo systemctl restart dvswitch-bot

音声

cd /opt/dvswitch_bot/bin && sudo ./create_wav.sh
cd /opt/dvswitch_bot/bin && sudo ./create_wav.sh -r
python3 /opt/dvswitch_bot/bin/test_send.py /opt/dvswitch_bot/001.wav

DVSwitch 設定

cd /opt/dvswitch_bot/bin && sudo ./dvs_config.sh
cd /opt/dvswitch_bot/bin && sudo ./dvs_config.sh -r

バージョン確認

grep -n '^version' /opt/dvswitch_bot/bin/dvswitch_bot.py

関連サービス

sudo systemctl status md380-emu --no-pager
sudo systemctl restart analog_bridge mmdvm_bridge md380-emu

📝 執筆：JJ2TAB（尾張旭 DMR デジピーター 管理人）
🏛 JJ2YYK あいちデジタルコミュニケーションハムクラブ