[教學] 認識 MicroPython (四) - 使用 ampy 取代 WebREPL

先前在「認識 MicroPython (二) - 啟用 WebREPL 遠端 WebSocket 服務」一節中，曾經介紹利用 WebREPL 上傳檔案到NodeMCU的方法，這個方法需要在瀏覽器下面操作，而且只有簡單的上傳、下載檔案的功能，比較適合初學MicroPython的時候使用。當你開始寫更複雜的程式，去控制 NodeMCU 之後，往往需要頻繁修改、上傳檔案， WebREPL 操作起來會覺得比較繁瑣，而且這個服務本身，也佔用較多 NodeMCU 的效能。此時，若是能使用命令列指令的工具，會讓上傳、下載程式，以及檔案管理變得更直覺簡單。"ampy"  就是這樣一個簡單的命令列工具，透過 MicroPython 預設的 REPL 界面，用你熟悉的 ftp 指令，去維護、查看 NodeMCU裡面的檔案，功能簡單強大。

安裝 ampy (adafruit  micropython python tool)

ampy 已經收錄在 PyPI 裡面了，因此你只要在Linux的終端機，或是Windows的「命令提示字元」（開始 → Windows 系統 → 命令提示字元），簡單下一個 pip 的指令就可以快速安裝 ampy：

pip install adafruit-ampy

如果你的電腦有共存舊版 python，則可以用以下指令：

pip3 install adafruit-ampy

安裝完成之後，只要輸入 ampy --help，就能看到這個指令的相關參數：

Usage: ampy [OPTIONS] COMMAND [ARGS]...

  ampy - Adafruit MicroPython Tool

  Ampy is a tool to control MicroPython boards over a serial connection.

  Using ampy you can manipulate files on the board's internal filesystem and

  even run scripts.

Options:

  -p, --port PORT    Name of serial port for connected board.  Can optionally

                     specify with AMPY_PORT environment variable.  [required]

  -b, --baud BAUD    Baud rate for the serial connection (default 115200).

                     Can optionally specify with AMPY_BAUD environment

                     variable.

  -d, --delay DELAY  Delay in seconds before entering RAW MODE (default 0).

                     Can optionally specify with AMPY_DELAY environment

                     variable.

  --version          Show the version and exit.

  --help             Show this message and exit.

Commands:

  get    Retrieve a file from the board.

  ls     List contents of a directory on the board.

  mkdir  Create a directory on the board.

  put    Put a file or folder and its contents on the board.

  reset  Perform soft reset/reboot of the board.

  rm     Remove a file from the board.

  rmdir  Forcefully remove a folder and all its children from the board.

  run    Run a script and print its output.

看看 NodeMCU裡面有哪些檔案

將 NodeMCU 用一條 microUSB 線連接到電腦之後，確定一下是否連線成功。在Linux系統的終端機輸入以下指令：

lsusb

Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

Bus 003 Device 002: ID 2109:3431 VIA Labs, Inc. Hub

Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub

Bus 001 Device 007: ID 1a86:7523 QinHeng Electronics HL-340 USB-Serial adapter

就會看到 HL-340 USB-Serial adapter 這個 NodeMCU 的裝置，此時在 /dev 目錄下，會出現 ttyUSB0 的 COM port 節點。

ls /dev/ttyUSB*

/dev/ttyUSB0

查看 NodeMCU 裡面的檔案

ampy -p /dev/ttyUSB0 ls

/boot.py

/main.py

/webrepl_cfg.py

在 Windows 系統，可以去裝置管理員查看，目前 NodeMCU 是位於那一個 COM port。

按下鍵盤的 Win+R 組合鍵，然後文字方塊中輸入 devmgmt.msc，按 Enter 鍵打開裝置管理員。以我的例子來說，目前 NodeMCU v3 在 COM3 這個串列埠 (USB-SERUSL CH340)：

位於 COM3 的 NodeMCU (CH340 USB-Serial晶片)

接著打開「命令提示字元」Win+R，然後輸入 cmd 。

在命令提示字元視窗中，執行以下指令：

ampy -p COM3 ls

/boot.py
/main.py
/webrepl_cfg.py

設定預設連接埠

每次要多打 -p 這個連接埠的參數有些麻煩，因此 ampy 讓你可以預設參數，如果你每次連接 NodeMCU都是在同一個 USB 插孔，而且不會偶爾多插其他 USB-SERIAL 的裝置，那建議你預設連接埠。

在 Linux 系統，只要在你的使用者的根目錄下，建立一個叫做 .ampy 的檔案，並在檔案中加入這個內容：

# Please fill in your own port, baud rate, and delay

AMPY_PORT=/dev/ttyUSB0

AMPY_BAUD=115200

由於 NodeMCU MicroPython 的 REPL 預設 Baud Rate 是 115200 bps，ampy 也是一樣，因此第二行可以不用。

建立好之後，你就可以忽略 -p 這個參數了，方便多了：

ampy ls

/boot.py
/main.py
/webrepl_cfg.py

在 Windows 中，不是用 .ampy 這個檔案，而是要設定在環境變數裡面。

鍵盤按 Win+R 組合鍵，輸入 SystemPropertiesAdvanced，開啟系統內容的進階設定，點擊下面「環境變數」的按鈕，然後新增一個使用者變數：

預設 COM3 跟 NodeMCU 通訊

下載檔案 get

ampy 下載檔案的指令 get，其實等於 Linux 的 cat 或 Windows 的 type，只會印出檔案內容，而不像 ftp 會直接存檔。

查看 boot.py 檔案內容：

ampy get boot.py

# This file is executed on every boot (including wake-boot from deepsleep)

#import esp

#esp.osdebug(None)

import uos, machine

#uos.dupterm(None, 1) # disable REPL on UART(0)

import gc

gc.collect()

import webrepl

webrepl.start()

你也可以直接把內容存檔：

ampy get boot.py > boot.py

就可以存在目前的目錄，檔名是 boot.py 

目前，WebREPL已經用不到了，所以可以把最後兩行，用 # 標記為註解，而不要執行

#import webrepl

#webrepl.start()

上傳檔案 put

跟 ftp 指令一樣，用上傳指令 put，把剛剛去到 WebREPL 新的 boot.py 上傳至 NodeMCU：

ampy put boot.py

然後再看一次內容：

ampy get boot.py

# This file is executed on every boot (including wake-boot from deepsleep)

#import esp

#esp.osdebug(None)

import uos, machine

#uos.dupterm(None, 1) # disable REPL on UART(0)

import gc

gc.collect()

#import webrepl

#webrepl.start()

原來的 boot.py 已經被新檔蓋過去了。 

刪除檔案 rm

跟 Linux 的指令一樣，要刪除 NodeMCU 上面的檔案，執行 ampy rm：

ampy rm main.py

把 main.py 刪除

建立、刪除子目錄 mkdir rmdir

ampy  沒有 cd (change directory) 這個指令，因此建立子目錄之後，如果你要上傳檔案到子目錄，必須在你自己的電腦中，建立一樣的子目錄，然後上傳的時候，把整個子目錄上傳，比方說，子目錄 foo中，有一個名叫 bar.py 的檔案。你必須上傳整個子目錄：

ampy put foo

ampy ls

/boot.py

/foo

/main.py

/webrepl_cfg.py

ampy ls foo

/foo/bar.py

執行 Python 模組 run

比方說，你寫了一個 python 模組，hello.py：

class hello:

    def sayhello(self):

        print('Hello, Sir!')

if __name__ == "__main__":

    myword = hello()

    myword.sayhello()

想要測試看看，你便可以用 run 這個指令來處理。上傳 hello.py 到 NodeMCU之後，執行測試這個檔案：

ampy run hello.py

Hello, Sir!

執行時，要確定你目前命令提示字元的工作目錄中，也有包含這個 hello.py 的檔案，才能夠使用 run，在別的目錄不行。 

這個執行功能，很適合測試、除錯單一的 Python模組，在程式中使用的 print() 指令，可以在執行 run 之後印出。

NodeMCU 重開機 reset

假如，你更改了 boot.py 還是 main.py 的內容，然後要驗證更改的結果，那麼你可以執行 reset 這個指令，重開機 (電源沒有關掉的狀況，執行 soft reboot），跟你在 REPL 環境，按下 Ctrl-D 一樣。

ampy reset

結語

以後，你便可以用 ampy 來快速上傳、更改程式了。不過，要注意的是，如果你用終端機程式，連線進去 NodeMCU 的 REPL，此時因為 COM 被佔用，而無法執行 ampy，記得執行 ampy 前，要把目前連線 NodeMCU 的終端機程式，如 Putty 關閉。

另外，要注意避免在程式迴圈中執行 print 指令，這樣將導致 COM port 一直有雜亂的字串傳來，導致 ampy 無法使用，甚至連 REPL 也進不去了。

未來會教你怎麼在 Micro Python 裡面，利用 UDP 通訊協定，把那些要 Debug 用的字串，透過 Wifi 傳送到你的電腦，這樣就算不用 print 指令，也可以從遠端知道程式發生了什麼狀況。

前篇：認識 MicroPython (三) - 移植 Blink 範例程式到 NodeMCU

後篇：待續