傳送模擬器主控台指令

每部執行中的虛擬裝置都提供主控台，可讓您查詢及控管模擬裝置環境。舉例來說，您可以在應用程式透過模擬器執行時，使用主控台管理通訊埠重新導向、網路特性和電話通訊事件。

如要執行下列指令，您必須有執行中的模擬器。如要進一步瞭解如何執行模擬器，請參閱「在 Android Emulator 上執行應用程式」及「透過指令列啟動模擬器」。

啟動及停止主控台工作階段

如要存取主控台並輸入指令，請在終端機視窗中使用 telnet 連線至主控台通訊埠，並提供您的驗證權杖。只要主控台顯示「OK」，就表示可以接受指令。主控台並不會提供一般的提示。

如何連線至執行中虛擬裝置的主控台：

  1. 開啟終端機視窗，然後輸入以下指令：
    2. telnet localhost console-port

    在獨立視窗中執行時，模擬器視窗標題會列出主控台通訊埠號碼，但在工具視窗中執行時不會。舉例來說，如果是使用主控台通訊埠 5554 的模擬器，則視窗標題可能是 Pixel8_API_34:5554。此外，adb devices 指令會顯示執行中的虛擬裝置及其主控台通訊埠號碼清單。詳情請參閱「查詢裝置」相關說明。

    注意：模擬器會監聽通訊埠 5554 至 5585 的連線，且僅接受來自 localhost 的連線。

  2. 主控台顯示 OK 後，輸入 auth auth_token 指令。

    3. 模擬器主控台會要求進行驗證，通過驗證後，您才能輸入主控台指令。auth_token 必須與主目錄中的 .emulator_console_auth_token 檔案內容相符。

    如果該檔案不存在，telnet localhost console-port 指令會建立該檔案，其中包含隨機產生的驗證權杖。如要停用驗證功能，請將權杖從 .emulator_console_auth_token 檔案中刪除，或是建立空白檔案 (如果檔案不存在)。

  3. 連線至主控台後，輸入主控台指令。

    4. 輸入 help、help command 或 help-verbose 可查看主控台指令清單，並瞭解特定指令。

  4. 如要結束主控台工作階段，請輸入 quit 或 exit。

工作階段範例如下：

$ telnet localhost 5554
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
Android Console: Authentication required
Android Console: type 'auth <auth_token>' to authenticate
Android Console: you can find your <auth_token> in
'/Users/me/.emulator_console_auth_token'
OK
auth 123456789ABCdefZ
Android Console: type 'help' for a list of commands
OK
help-verbose
Android console command help:
    help|h|?         Prints a list of commands
    help-verbose     Prints a list of commands with descriptions
    ping             Checks if the emulator is alive
    automation       Manages emulator automation
    event            Simulates hardware events
    geo              Geo-location commands
    gsm              GSM related commands
    cdma             CDMA related commands
    crash            Crashes the emulator instance
    crash-on-exit    Simulates crash on exit for the emulator instance
    kill             Terminates the emulator instance
    restart          Restarts the emulator instance
    network          Manages network settings
    power            Power related commands
    quit|exit        Quits control session
    redir            Manages port redirections
    sms              SMS related commands
    avd              Controls virtual device execution
    qemu             QEMU-specific commands
    sensor           Manages emulator sensors
    physics          Manages physical model
    finger           Manages emulator finger print
    debug            Controls the emulator debug output tags
    rotate           Rotates the screen clockwise by 90 degrees
    screenrecord     Records the emulator's display
    fold             Folds the device
    unfold           Unfolds the device
    multidisplay     Configures the multi-display
    nodraw           turn on/off NoDraw mode. (experimental)
    resize-display   resize the display resolution to the preset size
    virtualscene-image  customize virtualscene image for virtulscene camera
    proxy            manage network proxy server settings
    phonenumber      set phone number for the device


try 'help <command>' for command-specific help
OK
exit
Connection closed by foreign host.

模擬器指令參考資料

下表說明模擬器主控台指令，以及指令的參數和值。

表 1. 模擬器主控台指令

一般指令 說明
avd {stop|start|status|name} 查詢、控制及管理虛擬裝置，相關參數如下：
  • stop：停止執行裝置。
  • start：開始執行裝置。
  • status：查詢虛擬裝置狀態 (可能是 running 或 stopped)。
  • name：查詢虛擬裝置名稱。
avd snapshot {list|save name|load name|delete name} 利用快照儲存或還原裝置狀態，相關參數如下：
  • list：列出所有已儲存的快照。
  • save name：將快照儲存為 name。
  • load name：載入指定快照。
  • delete name：刪除指定快照。

以下範例會使用 firstactivitysnapshot 名稱儲存快照：

avd snapshot save firstactivitysnapshot
fold 摺疊裝置以顯示較小的螢幕設定 (如果是摺疊式裝置且目前未處於摺疊狀態)。
unfold 展開裝置以顯示較大的螢幕設定 (如果是摺疊式裝置且目前處於摺疊狀態)。
kill 終止虛擬裝置。
ping 檢查虛擬裝置是否正在執行。
rotate 將 AVD 以 45 度遞增量逆時針旋轉。
讓模擬器停止運作 說明
crash 在應用程式執行期間讓模擬器停止運作。
crash-on-exit 在應用程式結束時讓模擬器停止運作。
偵錯標記 說明
debug tags ...

啟用或停用模擬器特定部分的偵錯訊息。tags 參數必須是執行 emulator -help-debug-tags 時顯示的偵錯標記清單所含的值。如要進一步瞭解 -help-debug-tags 選項，請參閱常用選項的表格。

以下範例會啟用 radio 標記：

debug radio
通訊埠重新導向 說明
redir list 列出目前的通訊埠重新導向。
redir add protocol:host-port:guest-port 新增通訊埠重新導向，相關參數如下：
  • protocol：必須是 tcp 或 udp。
  • host-port：要在主機上開啟的通訊埠號碼。
  • guest-port：要在模擬器上將資料轉送過去的通訊埠號碼。
redir del protocol:host-port 刪除通訊埠重新導向。
  • protocol：必須是 tcp 或 udp。
  • host-port：要在主機上開啟的通訊埠號碼。
地理位置 說明

將 GPS 定位傳送至模擬器，設定向模擬器中執行的應用程式回報的地理位置。

您可以在虛擬裝置執行時立即發出下列任一 geo 指令。模擬器會建立模擬位置提供者，藉此設定您輸入的位置。這個提供者會回應由應用程式設定的位置事件監聽器，同時也會向 LocationManager 提供位置資訊。所有應用程式都可呼叫 LocationManager.getLastKnownLocation("gps") 查詢位置管理員，取得模擬裝置目前的 GPS 定位。
geo fix longitude latitude [altitude] [satellites] [velocity] 將簡易 GPS 定位傳送至模擬器。longitude 和 latitude 必須以十進制度數指定。請使用介於 1 到 12 之間的數字，指定要用於判斷位置的 satellites 數量，並指定 altitude (以公尺為單位) 和 velocity (以節為單位)。
geo nmea sentence 將 NMEA 0183 句子傳送至模擬裝置，就像從模擬 GPS 數據機傳送一樣。sentence 的開頭必須是「$GP」。目前僅支援「$GPGGA」和「$GPRCM」句子。以下範例是 GPGGA (全球定位系統定位資料) 句子，可取得 GPS 接收器的時間、位置和定位資料：
geo nmea $GPGGA ,hhmmss.ss,llll.ll,a,yyyyy.yy,a,x,xx,x.x,x.x,M,x.x,M,x.x,xxxx
假硬體事件 說明
event types 列出所有假事件類型。如果事件包含代碼，右側的括號中會列出代碼數量。

event types
event <type> can be an integer or one of the following aliases:
    EV_SYN
    EV_KEY    (405 code aliases)
    EV_REL    (2 code aliases)
    EV_ABS    (27 code aliases)
    EV_MSC
    EV_SW     (4 code aliases)
    EV_LED
    EV_SND
    EV_REP
    EV_FF
    EV_PWR
    EV_FF_STATUS
    EV_MAX
OK

event send types [types ...] 傳送一或多個假事件類型。
event codes type 列出指定假事件類型的事件代碼。
event send type[:code]:[value] [...] 傳送一或多個包含選用代碼和代碼值的假事件。

如要找出要傳送的確切事件，您可以使用 adb 指令，同時手動按下模擬器上的按鈕。

以下是按下電源鍵時產生的事件：

adb shell getevent -lt

/dev/input/event12: EV_KEY       KEY_POWER            DOWN
/dev/input/event12: EV_SYN       SYN_REPORT           00000000
/dev/input/event12: EV_KEY       KEY_POWER            UP
/dev/input/event12: EV_SYN       SYN_REPORT           00000000
敬上 例如，如要模擬長按電源鍵， 兩個 EV_KEY 事件： 
event send EV_KEY:KEY_POWER:0
OK
event send EV_KEY:KEY_POWER:1
OK

event text message 傳送用於模擬按鍵操作的字元字串。訊息必須是 UTF-8 字串。系統會根據目前的裝置鍵盤將萬國碼 (Unicode) 訊息進行反向對應，並自動捨棄不支援的字元。
電源狀態控制項 說明
power display 顯示電池和充電器狀態。
power ac {on|off} 將 AC 充電狀態設為 on 或 off。
power status {unknown|charging|discharging|not-charging|full} 將電池狀態變更為指定狀態。
power present {true|false} 設定電池有無狀態。
power health {unknown|good|overheat|dead|overvoltage|failure} 設定電池健康狀態。
power capacity percent 將剩餘電量狀態設為 0 到 100 之間的百分比。
網路連線狀態 說明
network status 檢查網路狀態以及目前的延遲和速度特徵。
network delay latency

變更模擬的網路延遲時間。

模擬器可讓您模擬各種網路延遲程度，在較貼近實際運作狀況的環境中測試應用程式。您可以在模擬器啟動時設定延遲程度或範圍，也可以在應用程式透過模擬器執行時，使用主控台變更延遲時間。

網路 latency 必須採用下列其中一種格式 (數字的單位為毫秒)：

網路延遲時間格式：

  • gprs：GPRS，使用介於 150 至 550 之間的延遲時間範圍。
  • edge：EDGE/EGPRS，使用介於 80 至 400 之間的延遲時間範圍。
  • umts：UMTS/3G，使用介於 35 至 200 之間的延遲時間範圍。
  • none：沒有延遲。
  • num：模擬指定的延遲時間 (以毫秒為單位)。
  • min:max：模擬指定的延遲時間範圍。

如要在模擬器啟動時設定延遲時間，請使用 -netdelay 模擬器選項，並提供支援的 latency 值 (如前述「網路延遲時間格式」清單所示)。例如：

emulator -netdelay gprs
emulator -netdelay 40,100

如要在模擬器執行期間變更網路延遲時間，請連線至主控台，然後使用 netdelay 指令，並提供前述「網路延遲時間格式」清單中任一支援的 latency 值。

network delay gprs
network delay 40 100
network speed speed 模擬器可讓您模擬各種網路傳輸速率。

您可以在模擬器啟動時設定傳輸速率或範圍，也可以在應用程式透過模擬器執行時，使用主控台變更速率。

網路 speed 必須採用下列其中一種格式 (數字的單位為千位元/秒)：

網路速度格式：

  • gsm：GSM/CSD，所用的上傳速度為 14.4，下載速度為 14.4。
  • hscsd：HSCSD，所用的上傳速度為 14.4，下載速度為 43.2。
  • gprs：GPRS，所用的上傳速度為 40.0，下載速度為 80.0。
  • edge：EDGE/EGPRS，所用的上傳速度為 118.4，下載速度為 236.8。
  • umts：UMTS/3G，所用的上傳速度為 128.0，下載速度為 1920。
  • hsdpa：HSDPA，所用的上傳速度為 348.0，下載速度為 14,400.0。
  • lte：LTE，所用的上傳速度為 58,000，下載速度為 173,000。
  • evdo：EVDO，所用的上傳速度為 75,000，下載速度為 280,000。
  • full：無速度限制，但實際速度會因電腦連線速度而異。
  • num：以千位元/秒為單位，統一設定確切的上傳和下載速率。
  • up:down：以千位元/秒為單位，分別設定確切的上傳和下載速率。

如要在模擬器啟動時設定網路速度，請使用 -netspeed 模擬器選項，並提供支援的 speed 值 (如前述「網路速度格式」清單所示)。例如：

emulator -netspeed gsm @Pixel_API_26
emulator -netspeed 14.4,80 @Pixel_API_26

如要在模擬器執行期間變更網路速度，請連線至主控台，然後使用 network speed 指令，並提供前述「網路速度格式」清單中任一支援的 speed 值。

network speed 14.4 80
network capture {start|stop} file 將封包傳送至檔案。以下清單說明相關參數和參數值：
  • start file：開始將封包傳送至指定檔案。
  • stop file：停止將封包傳送至指定檔案。
電話通訊模擬 說明
Android Emulator 提供專屬的 GSM 和 CDMA 模擬數據機，可讓您在模擬器中模擬電話通訊功能。舉例來說，您可以使用 GSM 模擬來電，以及建立和終止數據連線。CDMA 則可用來提供訂閱來源和偏好的漫遊清單。Android 系統會完全以處理實際通話的方式處理模擬通話。模擬器不支援通話音訊。
gsm {call|accept|cancel|busy} phonenumber gsm 的參數如下：
  • call：模擬 phonenumber 的來電。
  • accept：接聽 phonenumber 的來電，並將通話狀態變更為 active。只有在通話目前處於 waiting 或 held 狀態時，您才能將通話狀態變更為 active。
  • cancel：終止 phonenumber 的來電或外撥通話。
  • busy：結束打給 phonenumber 的外撥通話，並將通話狀態變更為 busy。只有在通話目前處於 waiting 狀態時，您才能將通話狀態變更為 busy。
gsm {data|voice} state data state 指令會變更 GPRS 數據連線的狀態，data voice state 指令則會變更 GPRS 語音連線的狀態，如下所示：
  • unregistered：無法連上網路。
  • home：使用區域網路，非漫遊。
  • roaming：使用漫遊網路。
  • searching：正在搜尋網路。
  • denied：僅可撥打緊急電話。
  • off：與 unregistered 相同。
  • on：與 home 相同。
gsm hold 將通話狀態變更為 hold。只有在通話目前處於 active 或 waiting 狀態時，您才能將通話狀態變更為 hold。
gsm list 列出所有來電和外撥通話及其狀態。
gsm status 回報目前的 GSM 語音/數據狀態，會是 voice 和 data 指令說明中所列的值。
gsm signal {rssi|ber} 變更下一個 15 秒更新期回報的訊號強度 (rssi) 和位元錯誤率 (ber)。以下清單說明相關參數和參數值：
  • rssi 的範圍介於 0 到 31 之間，99 表示不明。
  • ber 的範圍介於 0 到 7 之間，99 表示不明。
gsm signal-profile num 設定訊號強度設定檔。num 是介於 0 到 4 之間的數字。
cdma ssource source 設定目前的 CDMA 訂閱來源，其中 source 是包含 CDMA 電信業者訂閱者及其值的網路許可清單，相關說明如下：
  • nv：從非可變動的 RAM 讀取訂閱項目。
  • ruim：從可移除的使用者身分識別模組 (RUIM) 讀取訂閱項目。
cdma prl_version version 轉儲目前的偏好漫遊清單 (PRL) 版本。版本號碼會用於 PRL 資料庫，該資料庫包含系統選取與獲取程序中使用的資訊。
管理模擬器中的感應器 說明
這些指令與 AVD 中可用的感應器相關。除了使用 sensor 指令以外，您也可以在模擬器的「Virtual sensors」畫面中，透過「Accelerometer」和「Additional sensors」分頁查看及調整相關設定。
sensor status 列出所有感應器及其狀態。以下是 sensor status 指令的輸出範例：
sensor get sensor-name 取得 sensor-name 的設定。以下範例會取得加速感應器的值：
sensor get acceleration
acceleration = 2.23517e-07:9.77631:0.812348

以冒號 (:) 分隔的 acceleration 值指的是虛擬感應器的 x、y 和 z 座標。

sensor set sensor-name value-x:value-y:value-z 設定 sensor-name 的值。以下範例會將加速感應器設為 x、y 和 z 值 (以冒號分隔)。
sensor set acceleration 2.23517e-07:9.77631:0.812348
簡訊模擬 說明
sms send sender-phone-number textmessage 產生模擬的傳入簡訊。以下清單說明相關參數和參數值：
  • sender-phone-number：包含任意數字字串。
  • textmessage：簡訊內容。

以下範例會將「hi there」訊息傳送至 4085555555 這支電話號碼： 

sms send 4085555555 hi there

主控台會將簡訊轉寄至 Android 架構，再由該架構將其傳送至模擬器中負責處理簡訊的應用程式 (例如「訊息」應用程式)。如果傳送 10 個數字，應用程式會將其格式化為電話號碼。長短數字字串會依您傳送的方式顯示。
指紋模擬 說明
finger touch fingerprint-id 模擬手指觸碰感應器的情形。
finger remove 模擬手指移開的情形。

想瞭解如何使用這些指令，請參閱以下的「指紋模擬和驗證」一節。

指紋模擬和驗證

圖 1. 指紋驗證畫面。

使用 finger 指令模擬及進行應用程式指紋驗證程序。您必須使用 24.3 以上版本的 SDK 工具和 Android 6.0 (API 級別 23) 以上版本。

如要模擬及進行指紋驗證程序，請按照下列步驟操作：

  1. 如果您還沒有指紋 ID，請在模擬器中註冊新指紋，方法是依序選取「Settings」>「Security」 >「Fingerprint」，然後按照註冊指示操作。
  2. 將應用程式設為接受指紋驗證。完成這項設定後，裝置會顯示指紋驗證畫面。
  3. 應用程式顯示指紋驗證畫面時，前往主控台並輸入 finger touch 指令和您建立的指紋 ID。系統會模擬手指觸碰的情形。
  4. 接著輸入 finger remove 指令，模擬手指移開的情形。

    應用程式應該會有所回應，就好像使用者觸碰指紋感應器並移開手指一樣。