Cooper Maa

本篇將示範如何把 Arduino 變成一個實體的 Gmail Notifier，當 Gmail 信箱有未讀的信件時，LED 就會閃爍。

Arduino-LED     ygmlogo

材料表

• Arduino 主板一張
• LED x 1

把 LED 直接接到 Arduino 板子上就好，長腳接在 13 腳位，短腳接在 GND。

準備軟體環境

1) 到 ww.python.org 下載並安裝 Python - 我們的 Gmail 信箱檢查程式是用 Python 寫成的，所以需要 Python 執行環境。

2) 安裝 Python 的套件管理程式 easy_install 和 pip - 我們需要 pip 來安裝幾個 Python 套件。安裝辦法可以參考「安裝 easy_install 與 pip」。

3) 安裝 pyserial 與 feedparser 套件 – pyserial 是用來與 Arduino 通訊的套件，而 feedparser 則是用來檢查 gmail 信箱的套件。當你裝好 pip 套件管理程式後，接著執行下列指令把 pyserial 與 feedparser 裝起來：

pip install pyserial
pip install feedparser

Gmail Notifier

連到底下的位置下載 Gmail Notifier 程式:

http://bit.ly/UsG3wR

下載回來的是一個壓縮檔，解開後會看到這些檔案：

image

接著進行底下兩個步驟：

1) 把 prototype 資料夾下的 prototype.ino 上傳到 Arduino 板子上

2) 用編輯器打開 mail_notifier.py：

你需要修改幾個參數，包括 USERNAME, PASSWORD 與 Arduino 所在的 Serial port。

修改好後，最後只要輸入下列指令執行 mail_notifier.py，程式就會開始檢查 Gmail 信箱囉。程式預設是每 5 秒鐘檢查一次信箱，你可以自行調整。如果你發現 LED 會閃爍的話，就代表你的信箱裏有未讀的信件：

python mail_notifier.py

image

恭禧你，這樣就完成囉！

備註: Gmail Notifier 這支程式是以 extended-python-arduino-prototyping-api 為基礎修改而成的。

參考資料

• extended-python-arduino-prototyping-api
• 安裝 easy_install 與 pip
• Python gmail checker using IMAP4

在熟悉 Dropbox 的認證程序 (Authentication) 後，接著我們來學習如何上傳、條列與下載檔案。

你可以拿底下的範本來練習 (來自 Dropbox Python SDK Docs):

有關如何取得 App key 與 App secret，請參考「建立 app 取得 App key 與 App Secret」一文

上傳檔案

檔案的上傳很簡單:

put_file 這個 method 需要 2 個參數，第 1 個參數指定檔案在 Dropbox 上的存放路徑，第 2 個參數是一個 file object，也可以是 string。如果成功上傳，sample.txt 會被放在 app folder 或者 Dropbox 的根目錄下 (根據你的 app 的 access type 而定)。在 response 中，會有剛剛上傳的檔案的 metadata，內容會像這樣:

條列檔案或資料夾的 metadata

假設使用者 app folder 的檔案結構如下，裏面包含一個空的資料夾 Sample Folder 以及剛剛上傳的 sample.txt:

image

我們可以針對檔案或資料夾呼叫 metadata :

就會得到類似這樣的結果:

從 metadata 中你可以獲得很多資訊，例如完整的檔案路徑 (path)，file sizes (bytes)，上次修改日期 (modified) 等。

假如要知道資料夾有沒有變動，我們要自行保存並比較 hash。

下載檔案

檔案的下載也很簡單，只要呼叫 get_file_and_metadata :

get_file_and_metadata 會傳回兩個值，一個是檔案的資料，另一個是檔案的 metadata。你必須呼叫 .read() 才能取得檔案的內容。

總結

底下是本文的完整程式碼，使用之前記得先建一個 sample.txt，並且輸入你的 app ket, app secret 與 access type 。

參考資料

• Dropbox Python SDK Docs

前幾天把玩了一下 Dropbox SDK 範例，有網友反應，說 Dropbox 官方的 web_upload_app.py 是可以上傳檔案到 Dropbox，但是如果檔名裏有中文，上傳就會失敗。我發現，不只 web_upload_app.py，cli_client.py 也有同樣的問題。

我做了一個新的版本，用這個版本，現在就算檔名有中文也沒問題了。你可以點底下的連結下載檔案:

cli_client.py

web_upload_app.py

我是拿 dropbox-python-sdk-1.5.1 的版本來改的，底下摘要說明我修改的地方:

cli_client.py

這支程式我只動到兩三行，全部都在 DropboxTerm 的 do_put() method 裏。新舊版程式碼對照如下 (註: 簡單起見，底下拿掉了程式文件說明):

舊版:

新版:

web_upload_app.py

這支程式只動到 ExampleHandler 的 upload_page() method。新舊版程式碼對照如下:

舊版:

新版:

參考資料

• 把玩 Dropbox SDK 範例

這篇說明如何用 Python SDK 去跟 Dropbox 進行認證。Dropbox 用的認證通訊協定是 OAuth 1.0 (Open Authentication Protocol)。網路上有很多的資料和 libraries 可以讓你用 OAuth 去跟 Dropbox 認證，但我們不必從零開始，因為 Dropbox 提供的 Python SDK 很簡單，只要三個步驟就可以搞定。

註: 本文內容大部份取自 Dropbox developers 網站

在開始之前，我們必須先做兩件準備工作：

第 1 件: 準備 App key 和 App secret

首先，你必須準備好 app key 和 app secret 以及 app 所用的 access type:

# Get your app key and secret from the Dropbox developer website
APP_KEY = 'INSERT_APP_KEY_HERE'
APP_SECRET = 'INSERT_SECRET_HERE'

# ACCESS_TYPE should be 'dropbox' or 'app_folder' as configured for your app
ACCESS_TYPE = 'INSERT_ACCESS_TYPE_HERE'

第 2 件: 建立認證用的 session 物件

接著我們必須建立一個 session 物件。session 物件主要是負責認證的工作。在建立 session 物件時，記得把 App key, App secret 和 access type 一併傳入，同時引用 Dropbox SDK 的 libraries:

# Include the Dropbox SDK libraries
from dropbox import client, rest, session

# Create a session object for holding OAuth authentication info
sess = session.DropboxSession(APP_KEY, APP_SECRET, ACCESS_TYPE)

1. 取得 request token
2. 使用者授權給 reqeust token
3. 用 request token 來交換 access token

Step 1: 取得 request token

取得 request token 的方法很簡單，只要呼叫 obtain_request_token 這個 SDK method 即可:

request_token = sess.obtain_request_token()

Step 2: 使用者授權給 reqeust token

取得 request token 後，接著就要請使用者授權給 app。方法是導引使用者到 Dropbox 網站取得他的同意，request token 要傳到 build_authorize_url 建立一個授權用的 URL，像這樣:

url = sess.build_authorize_url(request_token)
print "url:", url
print "Please visit this website and press the 'Allow' button, then hit 'Enter' here."
raw_input()

上面只是印出 URL 然後請使用者在授權完畢後按個 Enter 鍵，這是為了方便說明，在實際的應用中，通常我們會直接顯示 Dropbox 的認證網頁，而且可能會順便傳入一個 callback URL，以便在使用者同意授權之後就直接跳轉回到你的應用程式。

當使用者瀏覽 build_authorize_url 產生的 URL 時，Dropbox 會確認使用者以他的帳戶登入，並且呈現一個像底下這樣徵詢同意的畫面:

image

為了避免有心人士非法取得授權，Dropbox 提供的 requst token 使用壽命只有 5 分鐘，所以如果使用者沒有在 5 分鐘之內授權，request token 就會失效，必須重新取得。

Step 3: 用 request token 來交換 access token

一旦取得使用者的授權，我們就可以拿 request token 來交換 access token，方法是透過 obtain_access_token 這個 SDK method:

# This will fail if the user didn't visit the above URL and hit 'Allow'
access_token = sess.obtain_access_token(request_token)

access token 就是 app 之後用來向 Dropbox 發任何 API requests 所需的，必須妥善保存。如果把 access token 保存起來的話，你就不需要再重覆前面這些步驟，除非使用者重新安裝你的 app。

好了，認證工作完成後，接下來就簡單了，當你要存取使用者的 Dropbox 資源時，只要把 session 物件傳給 DropboxClient 就可以了。例如，當我們呼叫 account_info 時，這個 method 就會回傳一個以 dictionary 保存的使用者的帳戶資訊:

client = client.DropboxClient(sess)
print "linked account:", client.account_info()

底下是用 pprint 印出帳戶資訊的一個例子:

image

總結

當你看到這邊，你就已經學會 Dropbox API 的認證，這是使用 Dropbox API 最基本而且也是最重要的一堂課。底下是完整的範例:

參考資料

• Adding authentication to your app

Dropbox 官方 Python SDK 附帶了一些範例，位於 example 資料夾中：

image

其中 cli_client.py 是一個 Dropbox 的指令介面工具，而 web_upload_app.py 則可以讓你透過 Web 上傳檔案到 Dropbox，這兩個範例很適合入門，我們來看怎麼使用這兩個範例。

設定 App key 與 App secret

要執行這些範例，我們需要修改範例程式填入事先申請的 App key 與 App secret，並且輸入 app 所用的 access type:

# XXX Fill in your consumer key and secret below
# You can find these at http://www.dropbox.com/developers/apps
APP_KEY = 'XXX'
APP_SECRET = 'XXX'
ACCESS_TYPE = 'app_folder' # should be 'dropbox' or 'app_folder' as configured for your app

有關如何取得 App key 與 App secret，請參考「建立 app 取得 App key 與 App Secret」一文。

cli_client.py

cli_client.py 是一個 Dropbox 的指令介面工具，可以讓使用者以指令的方式上傳下載檔案。cli_client.py 的使用方法大致如下：

Step 1: 執行方式：

python cli_client.py

Step 2: 載入程式後，可以下 help 指令看有哪些指令可用：

image

Step 3: 第一次使用必須輸入 login 進行登入：

image

如上圖紅框處，輸入 login 後會自動產生一個 URL，請複製貼到瀏覽器上訪問這個 URL，接著 Dropbox 會詢問你要不要授權給 app，此時請點選 Allow:

image

授權後，網頁會出現成功的訊息：

image

Step 4: 回到 cli_client.py 的畫面，按下 Enter 鍵，這時候 Dropbox 會出多 Apps > a-demo-app 這一層資料夾：

image

Step 5: 之後便可以下指令來操作使用者的 a-demo-app 這個資料夾的內容了。你可以下 account_info 指令取得帳戶資訊：

image

下載檔案要用 get 指令，上傳檔案用 put 指令，要刪除檔案或資料夾用 rm 指令。至於指令的用法請用 help 指令查看說明文件。

web_upload_app.py

web_upload_app.py 是一個可以讓你透過 Web 上傳檔案到 Dropbox 的工具。web_upload_app.py 的使用方法大致如下：

Step 1: 執行方式：

python web_upload_app.py

執行後，程式會要求你打開瀏覽器連到 http://localhost:8000

image
▲ Web Server 預設開啟在 port 8000，你可以再加一個參數自行決定要用哪個 port number

Step 2: 打開瀏覽器連到 http://localhost:8000

image

Step 3: 一樣，Dropbox 會詢問你要不要授權給 app，此時請點選 Allow:

 image

Step 4: 通過授權後，會看到一個上傳檔案用的網頁介面：

image

在這個網頁介面上，你可以上傳檔案，例如我上傳了一個 Main.c：

image

上傳完畢後，過沒多久，我的 Dropbox 就同步收到剛剛上傳的檔案了。(檔案路徑會是在 Dropbox 的 Apps > a-demo-app > Main.c)

在原來的 web_upload_app.py 視窗中，你可以看到所有的 HTTP Requests:

image

參考資料

• 建立 app 取得 App key 與 App Secret
• 安裝 Python SDK

如下表，Dropbox 官方提供了 iOS, Android, Python, Ruby, Java 以及 OS X 等 SDK，你可以從中選一個喜歡的來使用。除了官方的 SDK，社群成員也貢獻了使用其它程式語言寫成的 Third party SDKs，你可以這個頁面裏找到。在這篇我將說明 Python SDK 的安裝，我所用的環境是 Windows 7:

Step 1: 連到 Dropbox SDK 這個頁面，如下圖所示，點選 Python 右手邊的 Dropbox+ 圖示:

image
▲ 後來發現，其實點左手邊的語言或環境也可以下載 SDK

Step 2: 這時候會跳出底下這個小視窗，直接點選 "Add to Dropbox":

image

接著 Python SDK 就會裝到你的 Dropbox。如下圖，Dropbox 會多出 "dropbox-python-sdk-1.5.1" 這個資料夾:

image

而 "dropbox-python-sdk-1.5.1" 資料夾裏的檔案結構如下:

image

Step 3: 開一個 DOS 視窗，並切到 "dropbox-python-sdk-1.5.1" 資料夾，然後輸入底下指令安裝 Python SDK (注意! 在執行下列指令前，你必須先刪掉 build 這個檔，不然安裝會失敗) :

python setup.py install

Python SDK 的安裝就這麼簡單，安裝好後，你就可以用拿到的 App key 和 App secret 來存取 Dropbox API。

在 example 資料夾中有一些可供參考的 sample scripts，其中 cli_client.py 是一個 Dropbox 的指令介面工具，而 web_upload_app.py 則可以讓你透過 Web 上傳檔案到 Dropbox。下一篇我將說明如何使用這兩支工具。

參考資料

• 建立 app 取得 App key 與 App Secret

easy_install 跟 pip 都是 Python 的套件管理程式，有了它們，在使用 Python 開發程式的時候會帶來不少方便。

easy_install 和 pip 有什麼不一樣？據 pip 官網的說法，pip 改善了不少 easy_install 的缺點，如此說來 pip 應該是略勝一籌，不過它還不能夠完全取代對方，因為目前有很多套件還是得用 easy_install 安裝。

底下說明如何在 Windows 上安裝與使用 easy_install 與 pip，我假設你系統上已經安裝了 Python。

easy_install 的安裝與使用

連到底下的網址下載 setuptools，根據你的 Python 環境使用適合的版本 :

http://pypi.python.org/pypi/setuptools

例如我在 Windows 上跑 Python 2.7，所以我下載 setuptools-0.6c11.win32-py2.7.exe 回來安裝。安裝程式會把 easy_install 裝到 Python 的 Scripts 資料夾下 (例如 C:\Python27\Scripts)，安裝好之後，建議你把 Scripts 資料夾加到 PATH 環境變數裏。

easy_install 安裝與移除套件的基本使用方式如下：

安裝套件：

easy_install PackageName

更新套件：

easy_install -U PackageName

移除套件：

easy_install -m PackageName

顯示說明：

easy_install --showhelp

pip (pip installs packages) 的安裝與使用

pip 的安裝方法：

easy_install pip

有趣的是，pip 可以透過 easy_install 安裝，而且也會裝到 Scripts 資料夾下。

安裝套件：

pip install PackageName

更新套件：

pip install -U PackageName

移除套件：

pip uninstall PackageName

搜尋套件：

pip search PackageName

顯示說明：

pip help

當你裝好一個套件後，可以開個指令視窗確認有沒有安裝成功，以 pysqlite 套件為例：

image

假如你沒看到任何錯誤訊息，代表安裝是成功的，便可以開始在你的 Python 程式裏使用 pysqlite 套件。

參考資料

• Python 套件管理程式簡介
• Easy Install
• pip