目次
Please check it.
この記事は 2026年 08 月時点 (以下、現在 / 現時点) の情報に基づいて記載しています。筆者は本記事を執筆した現時点において 株式会社ソラコム に所属していますが、本記事の内容は あくまでも筆者個人の見解に基づくものであり、所属する会社または組織とは一切関係ございません。
(参考)
「一般消費者が事業者の表示であることを判別することが困難である表示」の指定及び「『一般消費者が事業者の表示であることを判別することが困難である表示』の運用基準」の公表について
前提
atctl というツールを作ってみました。
この記事では、その開発メモと簡単な紹介を書いています。
実際に手元で AT コマンドを実行しながら気づいたことや、Apple Silicon Mac から USB モデムを扱う際の使い方を残した「技術メモ」に近い内容です。
自分用の備忘録的な位置づけではありますが、
- Apple Silicon Mac から USB モデムを操作したい
- macOS に
/dev/cu.*のシリアルデバイスが表示されず困っている - AT コマンドを調べながら実行する負担を減らしたい
- モデムの確認結果をログや診断証跡として残したい
といった方の参考になれば嬉しいです。
先日書いた SGP.32 対応 SORACOM Connectivity Hypervisor の記事でも、デバイス側の IMSI / ICCID や通信状態を確認するために開発途中の atctl を使っています。
atctl
実際に作成したものは以下になります。
atctl は、Apple Silicon Mac から USB セルラーモデムへ AT コマンドを送信・管理するための Rust 製 CLI / TUI です。
macOS が利用可能な /dev/cu.* シリアルデバイスを公開しない場合でも、libusb を使って USB インターフェースとエンドポイントへ直接アクセスします。
主な特徴は以下のとおりです。
USB モデムへ直接アクセス
/dev/cu.*が利用できない場合でも、USB インターフェースと bulk IN / OUT エンドポイントを利用して AT コマンドを送信できます。atctl devicesとatctl inspectで、現在接続されているデバイスやUSBディスクリプターを確認できます。
CLI と TUI の両方に対応
atctl send <COMMAND>で AT コマンドを直接実行できます。atctl tuiでは、デバイス、コマンド、Sequence、応答、ログを一つの画面で確認できます。
Preset と Sequence
- Preset は、信号強度やSIM状態などを確認する一つの AT コマンドを名前から実行できます。
- Sequence は、SMS送受信など複数の手順が必要な処理をまとめて実行できます。
AT コマンド実行時の確認とログ
- 状態変更や外部通信を伴う操作では、実行前に確認を表示します。
- 機微な値は初期状態でマスクされます。
- 通常の履歴とセッションログもマスク済みの状態で保存されます。
- raw診断証跡は、出力先と確認語を明示した場合だけ作成されます。
利用方法や詳細な仕様については、GitHubリポジトリのREADMEとドキュメントを参照してください。
動作確認環境
現時点で実機確認している環境は以下です。
| 項目 | 確認環境 |
|---|---|
| Mac | Apple Silicon Mac |
| USBモデム | SORACOM Onyx LTE USB Dongle |
| 内蔵モデム | Quectel EG25-G |
| USB ID | 0x2c7c:0x0125 |
| 確認したファームウェア | EG25GGBR07A08M2G |
この環境では、USBデバイスの検出、ATコマンドの直接実行、Preset、Sequence、TUI、PTYブリッジ、SMS送受信、Quectel / SORACOMのping・TCP確認を実機で確認しています。
これは確認済み環境を示すもので、すべてのUSBモデムやOSで動作することを表明するものではありません。
なぜ作ってみたのか？
きっかけは、Apple Silicon Mac に SORACOM Onyx を接続した際に、USBデバイスとしては認識されていても、利用できる /dev/cu.* が表示されないケースがあったことです。
通常、AT コマンドを試す場合は、次のようにシリアルデバイスを探します。
ls /dev/cu.*
ここにモデム用のデバイスが表示されれば、screen や cu などを使って AT コマンドを送信できます。
しかし、macOS の USB ツリーではモデムが見えているのに、利用できるシリアルデバイスが作成されない場合があります。
USB側の状態は、次のようなコマンドで確認できます。
system_profiler SPUSBHostDataType
USBデバイスとして見えていても /dev/cu.* がないと、一般的なシリアルターミナルでは接続先を指定できません。
そこで、シリアルデバイスの公開を前提とせず、libusb を使ってUSBインターフェースへ直接アクセスするツールとして atctl を作りました。
また、AT コマンドは単純に文字列を送ればよいだけではありません。
例えば、
- IMSI、IMEI、ICCIDなどの識別情報を読み取る
- APNやネットワーク選択状態を変更する
- モデムを再起動する
- SMSを送信する
- TCPソケットを開いてデータを送信する
といった操作があります。
確認用のコマンドと状態変更を伴うコマンドを同じ感覚で実行すると、意図せず通信状態を変更したり、機微な情報をログへ残したりする可能性があります。
そのため atctl では、USBアクセスだけではなく、
- コマンドを探す
- 内容を確認する
- 必要な値を入力する
- 影響のある操作を確認する
- 応答を確認する
- マスク済みログを残す
- 必要な場合だけraw診断証跡を収集する
という一連の流れまでまとめています。
実際に使ってみる
今回は、以下の流れで試してみます。
- Homebrewでインストールする
- USBモデムを確認する
- ATコマンドを直接送信する
- TUIを起動する
- PresetとSequenceを確認する
- PTYブリッジを利用する
やっていること自体はシンプルです。
まずモデムが見えていることを確認し、基本的な AT コマンドを送信します。その後、TUIやPreset、Sequenceなどを確認してみます。
インストール
Homebrewを使ってインストールします。
brew install uchimanajet7/atctl/atctl
Homebrew Formulaからインストールした場合、実行時に必要な libusb も一緒にインストールされます。
インストールできたら、バージョンを確認します。
atctl --version
インストール、更新、削除、GitHub Releaseからの手動実行については、以下のドキュメントを参照してください。
USBモデムを確認する
最初に、現在接続されているAT操作対象を確認します。
atctl devices
atctl devices では、USBディスクリプターをもとに、AT操作対象として利用できる可能性があるデバイスが表示されます。
表示内容には、以下のような情報が含まれます。
- Manufacturer
- Product
- VID / PID
- USB bus
- USB address
- Device class
想定したモデムが表示されない場合は、libusb から見えるすべてのUSBデバイスを確認できます。
atctl devices --all-usb
ただし、USBデバイスとして見えることや、bulk IN / OUT エンドポイントが存在することだけでは、そのインターフェースがATコマンド用であるとは判断できません。
詳細を確認する場合は、次のコマンドを利用します。
atctl inspect
inspect では、Configuration、Interface、Alternate Setting、Endpointなどを確認できます。
ATコマンドを送信する
モデムが確認できたら、基本的な AT コマンドを送信します。
atctl send AT
モデムが正常に応答すれば、OK が返ります。
続いて、モデム情報を確認します。
atctl send ATI
一つのATコマンドを直接実行したい場合は、同じ形で指定できます。
atctl send AT+CSQ atctl send AT+CEREG? atctl send AT+CGACT?
複数のUSBモデムが接続されている場合は、atctl devices に表示された bus と address を指定します。
atctl send AT \ --bus <BUS> \ --address <ADDRESS>
出力は初期状態でマスクされます。
明示的にマスクを解除した画面出力が必要な場合は --no-mask を利用できますが、IMSI、IMEI、ICCID、電話番号、SMS本文、認証情報などが表示される可能性があるため、取り扱いには注意が必要です。
TUIを使ってみる
ATコマンドを対話的に操作する場合は、TUIを起動します。
atctl tui
TUIでは、以下の情報を一つの画面で確認できます。
DevicesCategoriesCommands / SequencesStatusControlsResponseLogs
コマンドを名前やカテゴリーから探し、詳細を確認してから実行できます。
応答は Response に表示され、現在の実行状態は Status で確認できます。保存された履歴やセッションログもTUIから開けます。
なお、上のスクリーンショットでは確認用に Output masking: off となっていますが、通常はマスクが有効な状態で起動します。
ATコマンドに慣れていない場合や、目的のコマンド名を覚えていない場合は、まずTUIから試すのがわかりやすいと思います。
Presetを使ってみる
Presetは、一つのATコマンドを目的ごとの名前から実行するためのものです。
最初に一覧を確認します。
atctl preset list
例えば、信号強度を確認する signal-quality の内容は、次のコマンドで確認できます。
atctl preset show signal-quality
show はモデムへATコマンドを送信しません。
実際に実行する場合は、次のようにします。
atctl preset run signal-quality
製品に含まれるPresetには、以下のような確認があります。
- モデム応答
- メーカー、モデル、ファームウェア
- SIM PIN状態
- ネットワーク登録状態
- オペレーター
- 信号強度
- PDPコンテキスト
- SMS準備状態
- エラー情報
- モデム機能状態
状態変更を伴うPresetには、実行前の確認が表示されます。
Sequenceを使ってみる
Sequenceは、複数のATコマンド、プロンプト待ち、ペイロード送信、URC待ちなどをまとめた処理です。
一覧を確認します。
atctl sequence list
例えば、SMSを送信する sms-send-check の内容を確認します。
atctl sequence show sms-send-check
実行する場合は次のようにします。
atctl sequence run sms-send-check
対話実行では、送信先とSMS本文を入力し、実行内容と影響を確認してから送信します。
製品に含まれる標準Sequenceには、以下があります。
- SMS送信
- SMS受信・一覧
- SMS読み取り
- SMS返信
標準SMS操作を利用するために、利用者がSequence定義ファイルを作成する必要はありません。
GitHubリポジトリには、追加で読み込めるサンプルとして、Quectelのping・TCP確認や、SORACOM Ping Response Service・Unified Endpointを確認するSequenceも用意しています。
これらはQuectelやSORACOMに固有のサンプルとして明示的に読み込むもので、すべてのモデムで利用できる標準機能ではありません。
PresetとSequenceの詳細については、以下を参照してください。
自分自身でPresetやSequenceを作る場合には、GitHub リポジトリに参考として用意してある PresetとSequenceがありますので、それを参考にしてください。例えばAIに読み込ませるなどすれば利用できるかと思います
PTYブリッジを使ってみる
screen や cu などのターミナルツールを利用したい場合は、PTYブリッジを利用できます。
最初に、現在のUSB接続先を確認します。
atctl devices
表示された BUS と ADDRESS を指定してブリッジを起動します。
atctl bridge \ --symlink /tmp/atctl \ --bus <BUS> \ --address <ADDRESS>
別のターミナルから screen で接続します。
screen /tmp/atctl 115200
ここで指定している 115200 は、シリアルターミナルツールとの互換性のための値です。USBモデムとの物理的な通信速度を指定しているわけではありません。
PTYブリッジでも、ATコマンドの確認、マスク、raw診断証跡に関する保護は適用されます。
ATコマンドを扱うための確認とログ
ATコマンドには、情報を読むだけのものと、モデムの状態を変更するものがあります。
例えば、信号強度を確認する AT+CSQ と、モデムを再起動する可能性がある AT+CFUN=1,1 では影響が異なります。
atctl では、実行前に次の内容を確認できるようにしています。
- どのような影響があるか
- 機微な入力や出力を扱うか
- 操作を元に戻せるか
- どのような結果が起こり得るか
- 実行前の確認が必要か
既知の確認用コマンドはそのまま実行できますが、状態変更や外部通信を伴う操作では確認が表示されます。
通常の履歴とセッションログは、以下に保存されます。
~/.local/state/atctl/history.jsonl ~/.local/state/atctl/logs/<timestamp>.session.log
これらのログは初期状態でマスクされています。
一方、raw診断証跡には、マスクされていないUSB通信内容や機微な情報が含まれる可能性があります。そのため、自動的には作成されず、利用者が出力先を選択して raw-log の確認語を指定した場合だけ作成されます。
ATコマンドを初めて試す場合や、状態変更を伴う操作を行う場合は、安全ガイドも確認してください。
気づいたこと
/dev/cu.* がなくても、USB側から確認できる
macOSでシリアルデバイスが表示されないと、その時点でATコマンドの確認を諦めてしまいがちです。
ただし、USBデバイスとして認識され、利用可能なインターフェースとエンドポイントが確認できれば、libusb を経由して操作できる場合があります。
atctl devices と atctl inspect でUSB側の状態を確認できるようになったことで、単純に「見えない」で終わらず、次に何を確認するべきかがわかりやすくなりました。
TUIからコマンドを探せるのが便利
ATコマンドは種類が多く、メーカー固有コマンドもあります。
毎回マニュアルからコマンドを探して入力するよりも、目的やカテゴリーからPresetやSequenceを選び、詳細を確認してから実行できる方が楽です。
特に、
- SIMが利用できる状態か
- ネットワークに登録されているか
- 電波状態はどうか
- PDPコンテキストが有効か
- SMSの送受信ができるか
といった確認を順番に行う場合は、TUIが使いやすいと感じています。
具体的なユースケースだと、例えば SORACOM のユーザーガイドでは
以下のように データを送受信できない場合の詳細な調査方法 が記載されています
実際に実行して、実行結果を記録するとなった場合手軽に使えることは 大きなアドバンテージになると感じます。
実行方法が変わっても確認方法は揃っている
send、preset run、sequence run、TUI、PTYブリッジは、それぞれ操作方法が異なります。
ただし、実行内容の確認、状態変更時の確認、出力マスク、ログ、raw診断証跡の考え方は共通です。
コマンドラインで実行する場合とTUIで実行する場合で、機微な情報の扱いや確認方法が大きく変わらないようにしています。
最後の診断証跡まで残せる
通常のトラブルシューティングでは、マスク済みのResponseやセッションログで十分なケースが多いと思います。
それでも原因がわからない場合には、利用者が出力先を選択したうえでraw診断証跡を収集できます。
普段からrawデータを保存するのではなく、通常の確認と最終的な診断証跡を分けられる点は、ATコマンドを扱うツールとして重要だと感じています。
まとめ
今回は、Apple Silicon Mac から USB セルラーモデムへATコマンドを送信・管理するための atctl を紹介しました。
atctl では、以下のことができます。
libusbを利用したUSBモデムの検出と直接アクセス- USBインターフェースとエンドポイントの確認
sendによるATコマンドの直接実行- Presetによる一つの確認処理の実行
- SequenceによるSMSなどの複数手順の実行
- TUIによる対話操作
- PTYブリッジによる
screenやcuからの操作 - 実行内容の確認と、影響のある操作に対する確認
- 機微な情報のマスク
- 履歴、セッションログ、Response export
- 明示的に選択した場合だけ作成するraw診断証跡
現時点で実機確認しているのは、Apple Silicon MacとSORACOM Onyx LTE USB Dongleに内蔵されたQuectel EG25-Gの組み合わせです。
すべてのUSBモデムやOSでの動作を表明するものではありませんが、同じように、
「USBデバイスとしては見えているのに /dev/cu.* がない」
「ATコマンドを調べながら一つずつ確認するのが大変」
といった場面では、試してもらえればと思います。
日本語のREADMEも用意しています。
機会があれば、ぜひ試してみてください。
以上です。
