-
Notifications
You must be signed in to change notification settings - Fork 1
/
create_scratch2_extensions_中文翻譯.txt
222 lines (124 loc) · 11.1 KB
/
create_scratch2_extensions_中文翻譯.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
----------------------------------
建立Scratch2.0擴充功能之不負責翻譯
----------------------------------
原始作者：John Maloney ，MIT Media Laboratory ，2013年9月
原文網址：http://wiki.scratch.mit.edu/w/images/ExtensionsDoc.HTTP-9-11.pdf
譯者：Wen-Hung Chang <beardad1975@gmail.com> ，2016年4月
翻譯原則：不採精確翻譯，以容易理解及實用為原則
【介紹】
Scratch2.0可以透過擴充功能來控制外部的裝置(如機器人套件，樂器等)，或是從外部感測器取得感測值(如感應板)。擴充功能幫Scrath增加了新的「命令積木」與「回報積木」((譯註：可想成感應值積木)，這些新增的積木可與裝置做互動。當啟用擴充功能時，新的積木會出現在「更多積木」區裡面。
由於瀏覽器的安全限制，Scratch2.0無法直接與硬體裝置溝通(譯註：Scratch一開始是Web版，且以Flash寫成)，所以擴充功能要透過另一個獨立執行的擴充程式。Scratch透過HTTP與擴充程式連結，然後擴充程式再與硬體裝置溝通。未來，一些擴充功能會以瀏覽器外掛的型式來做，但不在此詳述。(譯註：Scratch2離線版不使用瀏覽器外掛)
(譯註：擴充程式原文為helper app，為使文章易理解，而採此翻譯 )
這篇文章的讀者是針對Scratch2.0擴充功能開發者。內容提到了自訂積木檔格式(譯註：即.s2e檔)，Scratch與擴充程式的溝通協定及開發的步驟。
(譯註：自訂積木檔原文為Extension description file，為使文章易理解，而採此翻譯 )
【自訂積木檔 .s2e】
自訂積木檔是一個採用JSON格式的文字檔。(譯註：JSON來自Javascript，是Web常見的資料交換格式)，依Scratch2.0的習慣，採用.s2e的結尾副檔名。
在自訂積木檔中的JSON物件包括了擴充功能的名稱，用來與擴充程式通訊的TCP/IP的port號碼，和一個描述Scratch積木內容的串列
以下方為例：
{
"extensionName": "擴充示範",
"extensionPort": 12345,
"blockSpecs": [
[" ", "嗶一聲", "playBeep"],
[" ", "設定音量為 %n", "setVolume", 5],
["r", "目前音量值", "volume"]
]
}
擴充功能的名稱是「擴充示範」，擴充積木(Scratch)會用port 12345與擴充程式通訊。blockSpecs這個欄位描述了出現在「更多積木」區裡的自訂積木。在這個例子中，有3個自訂積木。第1個積木是會執行嗶一聲的命令積木；第2個是會設定音量的命令積木；第3個是可以讀取目前音量值的回報積木(譯註：可想成感應積木)
【積木的描述】
每個自訂積木是以下列的欄位陣列來決定
* 積木類型
* 積木格式
* 積木作用
* (非必需) 多個預設的參數值
以下依欄位分別說明
積木類型可使用下列的文字字串來決定
" " 命令積木 (譯註：內有一空格)
"w" 會等待的命令積木
"r" 數字回報積木(圓弧形積木)(譯註：回報積木可想成是感應值積木)
"b" 布林回報積木(六角型積木)
積木格式的值是一個文字字串，它會決定出現在積木上的文字與參數欄位，參數欄位會用一個以%開頭再加上一個英文字母來決定，如下：
%n 數字的參數欄位(圓弧型空格)
%s 文字的參數欄位(方型空格)
%b 布林值的參數欄位(六角型空格)
在上方的例子中，"設定音量為 %n" 會讓積木有個數字的參數欄位，在第2個積木描述的最後有個5，代表參數欄位的預設值是5，這個預設值在會在一開始就出現在積木上，讓使用者方便測試並給他們一個常見的參考值。
積木作用的值是一文字字串，這個欄位有兩種用法。對命令積木來說，值會被送到擴充程式，連同參數值一起,讓擴充程式來執行命令動作。對回報積木來說，這個值是個感應值的變數名稱，感應值會保留在Scratch內部，當我們執行回報積木，其實是會得到最後一次收到的感應值。
【選單參數】
命令積木與回報積木都可以使用選單參數，如下：
%m.menuName 不可編輯的選單參數
%d.menuName 可以編輯的選單參數
第1種會有個下拉式選單的欄位，如同Scratch原有的「廣播」積木。第2種會有個可編輯的數字欄位同時也有下拉選單，如同Scratch原有的「面向方向」積木。不論是哪種選單，在點號(.)後的是選單的名稱。至於選單的清單內容，是在積木定義的後面，再加上menu的欄位。比如說，如果是要使用微軟Kinect的擴充積木，可能會有如下的積木定義：
{
"extensionName": "Kinect",
"extensionPort": 12345,
"blockSpecs": [
["r", "取得 %m.bodyPart 部位的 %m.coordinate 座標位置", "position"]
],
"menus": {
"coordinate": ["x", "y", "z"],
"bodyPart": ["head", "shoulder", "elbow", "hand"]
}
}
在這個例子中，"position"回報積木有兩個選單，第一個選單coordinate可選座標xyz軸 , 另一個選單bodyPart是身體的部位，如head等。
擴充程式對帶著選單的回報積木所傳送的值，就是把回報積木的作用名稱以及所有的參數，用/字元連起來而已。在Kinect的例子裡，使用者手部的y軸座標位置，擴充程式傳回的字串是：
position/y/hand 247
這是個簡化過的例子。事實上Kinect可以追蹤許多身體部位，包括還可分得出身體左邊與右邊，甚至到4個人。選單參數可把原本Kinect可能需要超過100種的積木，簡化成1個帶有4個選單的積木。
【與擴充程式通訊】
擴充程式在背景執行，隨時待命讓Scratch來連接。(譯註：可想成是個Web伺服器)每個擴充程式都有個port號碼。Scratch經由本機上的這個port來找到擴充程式。
Scratch用HTTP協定來與擴充程式通訊。透過HTTP協定中的GET請求(request)，Scratch送出命令給擴充程式，而擴充程式會送回感應值給Scratch。因為通訊採的是標準的HTTP協定，你可以使用任何的瀏覽器來幫擴充程式進行測試與除錯。
【輪詢(Polling)】
為了獲得感應值，Scrath會送出poll命令給命擴充程式，如下：
/poll
擴充程式收到poll命令，會傳回一串感應名稱與感應值的資料，每一行可以有一組感應名稱與感應值。每一行的結尾字元為一個換行符號(0xA)，而且感應名稱與感應值中間要以一個空白字元分開。所以的文字資料都要經過URL編碼(譯註：某些特殊字元在網址會變成如%E2%82%AC)。Scratch大約每秒鐘送出30次poll命令給擴充程式。
以下是擴充程式回應poll的例子：
brightness 75
slider 17
【回報問題】
當你的擴充程式是配合某個硬體裝置時，有一個常見的問題是未連接的情況發生。擴充程式在回應Scratch的poll命令時，可以回報這個問題給使用者。回傳的文字會先以_problem開頭，加上一個空格，然後再加上說明問題的文字。如下例：
_problem The Sensor board is not connected.
【保留的感應值名稱】
Scratch使用特殊的感應值名稱，來回報硬體問題或是處理等待中的命令。這些變數會以一個底線字元開頭("_")，為避免衝突，自訂的感應值名稱，不要以底線字元開頭。
【命令】
命令和相關參數要以URL請求的方式送出(譯註：相當於網址中不包今主機名稱的部分)。用斜線字元/來做分隔。如下例：
/beep (不含參數的命令)
/setVolume/5 (有一個數字參數的命令)
文字參數要經過URL編碼，以符合URL要求
【等待命令】
有些命令必需等待硬體完成動作。比如說，有個積木的功能是：
啟動馬達3秒鐘
啟動馬達，等待3秒，然後再把它關掉。當這個積木在Scratch中使用，Scratch會等這個命令完成後，再執行下一塊積木(譯註：如同「廣播並等待」積木)。等待命令積木在定義時，類型要用"w"。
當等待積木執行時，Scratch會在所有的參數前，自動加上一個command_id的參數。以上方的例子來說，Scratch會送出：
/motorOn/2437/3
第一個參數2437是一個Scratch自動加上的id號碼，為了讓Scratch等待，擴充程式要在poll的回應中，加上一行來指出目前正在待待中的命令：
_busy 2437 ...
要以_busy開題，然後加上一串等待中的命令編號(以空白分開)。Scratch會讓原本的積木等待，直到Scratch收到poll的回應裡，在_busy行中，找不到這個編號(甚至是找不到_busy這一行字)，它就會知道命令已完成，讓原有等待積木的流程繼續進行。
【等待回報(等測感測值】
(譯註：在原文寫的這個功能，是未來會加入的功能，但至今日仍未看到此功能的實作，故略過不譯，有興趣可參考原文)
【重置命令】
藉由Scratch擴充可以控制馬達或是電子樂器。使用者如果要把硬體裝置重置(如關掉馬達，停掉電子樂器，重設硬體到初始狀態)，使用者可以在Scratch裡按下紅色停止按鈕。當按下停止按鈕時，Scratch會送出重置命令給所有擴充程式，如下：
/reset_all
當擴充程式收到這個命令，就可以關掉馬達，燈光，聲音，重設硬體。比如說使用者把電子樂器的音樂設為靜音，重設時，會回到預設音量。擴充程式也要停掉執行中的命令並清除等待命令。
【Cross-Domain policy requests】
(譯註：Scratch是以Flash寫成，這部分本來是要讓FLASH允許送出HTTP請求的機制，但是實測時發現不處理這部分，擴充程式也是可以運作，故略過不譯，有興趣可參考原文)
【建立並測試Scratch擴充】
(譯註：原文有一段提到未來會有擴充集中的library，讓大家分享，但因Scratch網站未實作，故略過不譯)
接下來是建立及測試Scratch擴充功能的步驟：
1.建立自訂積木檔(.s2e)
2.建立擴充程式並執行(譯註：這個最辛苦)
3.打開Scratch2離線編輯器
4.匯入自訂積木檔(在Scratch2裡，先按下shift鍵，再用滑鼠點選「檔案」，選擇「匯入實驗性HTTP擴充功能」，就可以匯入.s2e檔)
5.自訂的新積木會出現在「更多積木」區
6.不斷測試你的擴充功能
擴充程式可以用任何支援socket功能的程式語言，如Python, Node.js, Java, c等。
最後，Scratch團隊會幫一些通用的擴充保留socket號碼(譯註：Scratch目前未實作)
【發佈擴充程式】
(譯註：原文提到原本未來要建設線上的擴充library，目前但後來未實作，故略過不譯，有興趣請參考原文)
【協定摘要】
Scratch送出如下的命令給擴充程式：
/poll
/reset_all
擴充程式回應/poll請求，是以一或多行的內容(每行換行字元是0xA)。回應會包括下列這些內容。
- 感應值名稱與感應(以空白分隔)
- "_busy" 再加上一串等待命令的ID
- "_problem" 再加上發生問題的文字說明
(譯註：原文第4種仍未實作，不列出)