scratch python插件_scratch插件开发文档

该楼层疑似违规已被系统折叠 隐藏此楼查看此楼

这个是开发scratch插件的文档，以下是英文原文，比较简单，所以也就没有翻译。

这是个好东西，懂的拿去。

Creating Scratch 2.0 Extensions

John Maloney

MIT Media Laboratory

September, 2013

NOTE 1: This specification supersedes all earlier drafts.

NOTE 2: This specification is still preliminary and may change.

Introduction

Scratch 2.0 can be extended to control external devices (e.g. robotics kits, musical instruments) and

to access data from external sensor hardware (e.g. sensor boards). A Scratch 2.0 extension extends

Scratch with a collection of command and reporter blocks that can be used to interact with a

particular device. When an extension is enabled, its blocks appear in the "More Blocks" palette.

Due to browser security restrictions, Scratch 2.0 cannot interact with hardware devices directly.

Instead, hardware extensions come with a helper app, a separate application that the user must

install and run on their computer. Scratch communicates with the helper app via HTTP requests,

and the helper app talks to the hardware. In the future, some extensions may package their helper

apps as browser plugins, but that mechanism is not described here.

This document is aimed at Scratch 2.0 extension developers. It describes the extension description

file format, the protocol used to communicate between Scratch extension helper apps, and the

extension development process.

Extension description file

An extension description file is a text file in JSON format (http://www.json.org) that describes the

extension. By convention, a Scratch 2.0 extension file ends in .s2e.

The JSON object in the extension description file includes the extension's name, the TCP/IP port

number used to communicate with the extensions helper app, and a list of Scratch block

specifications.

Here is an example:

{ "extensionName": "Extension Example",

"extensionPort": 12345,

"blockSpecs": [

[" ", "beep", "playBeep"],

[" ", "set beep volume to %n", "setVolume", 5],

["r", "beep volume", "volume"],

]

}

This extension's name is "Extension Example" and it connects to its helper app on port 12345. The

"blockSpecs" field describes the extension blocks that will appear in the "More Blocks" palette. In

this case, there are three blocks: (1) a command block that plays a beep; (2) a command block that

sets the beep volume; and (3) a reporter (value-returning block) that reports the current beep

volume setting.

Block description

Each block is described by an array with the following fields:

* block type

* block format

* operation or remote variable name

* (optional) zero or more default parameter values

The block type is one of these strings:

" " - command block

"w" - command block that waits

"r" - number reporter block (round ends)

"b" - boolean reporter block (pointy ends)

The block format is a string that describes the labels and parameter slots that appear on the block.

Parameter slots are indicated by a word starting with "%" and can be one of:

%n - number parameter (round ends)

%s - string parameter (square ends)

%b - boolean parameter (pointy ends)

In the example, the "set beep volume to %n" takes one numeric parameter. The block description

for that command also includes a default value: 5. This default value will be displayed in the

parameter slot when that block appears in the palette. Default parameters allow users to easily test

blocks and suggest the range of a given parameter.

The operation field in a block specification is used in two ways. For command blocks, it is sent to

the helper application, along with any parameter values, to invoke an operation. For reporter

blocks, it is the name of a sensor variable. Sensor variable values are kept in a dictionary.

Executing a reporter block simply returns the most recently reported value for that sensor variable.

Menu parameters

Both command and reporter blocks can include menu parameters:

%m.menuName - menu parameter (not editable)

%d.menuName - editable number parameter with menu

The first of these provides a simple drop-down menu parameter slot, similar to the parameter of the

"broadcast" block. The second provides a numeric parameter slot with an auxiliary menu, similar to

the "point in direction" block. In both of these cases, the string after the period character is the

name of the menu. The contents of the menu are supplied by the optional "menu" field in the

extension descriptor. For example, a Microsoft Kinect extension might look like this:

{ "extensionName": "Kinect",

"extensionPort": 12345,

"blockSpecs": [

["r", "get %m.coordinate position of %m.bodyPart", "position"],

],

"menus": {

"coordinate": ["x", "y", "z"],

"bodyPart": ["head", "shoulder", "elbow", "hand"],

},

}

In this example, the "position" reporter block has two menus. One menu specifies the coordinate

(x, y, or z) and the other specifies the body part (head, shoulder, elbow, or hand).

The sensor name reported by the helper app for a reporter block with menu parameters is simply

the concatenation of the reporter's base name with all its parameters separated by forward slash

characters. In the Kinect example, the y position of the user's hand might be reported as:

position/y/hand 247

This example has been greatly simplified. The Kinect actually tracks many more body parts,

including both the left and right sides of the body, and up to four human figures. Menu parameters

allow the number of blocks needed for a Kinect extension to be collapsed from over a hundred

separate reporter blocks to, potentially, just a single block with four menu parameters.

Communicating with the helper app

A helper app runs in the background, ready for use by Scratch projects that uses that extension.

Each extension has a unique port number. Scratch looks for the helper app at the given port number

on the local computer.

Scratch communicates with the helper app using the HTTP protocol. Scratch sends commands to

the helper app and the helper app sends sensor values and status information back to Scratch via

HTTP GET requests. Since the protocol is standard HTTP, any browser can be used to test and

debug helper apps.

Polling

Scratch to retrieves sensor values and status information from the helper app by sending a poll

command:

/poll

In response to a poll command, the helper app sends back a list of (sensor name, value) pairs, one

pair per line. Each line in the poll response should end with a newline character (0xA) and the

sensor name and value should be separated by a space character. String values should be URL-

encoded. Scratch sends poll commands roughly 30 times per second.

Here's an example poll response:

brightness 75

slider 17

Reporting problems

A common problem with hardware extensions is that the required hardware is not attached to the

computer. The response to a poll request can include a problem report to help users troubleshoot. A

problem report consists of the string "_problem" followed by a space followed by a short

description of the problem. For example:

_problem The Scratch Sensor board is not connected.

Reserved sensor names

Scratch uses special sensor names to report extension problems, track busy commands, etc. These

special names always start with an underscore character ("_"). To avoid possible name conflicts

with potential future feature, extensions writers should avoid starting either command or sensor

names with an underscore.

Commands

A command and its parameters are formatted as a URL request, using the forward slash ("/") as a

separator. Some examples:

/beep (command with no parameters)

/setVolume/5 (command with a numeric parameter)

String parameters must be URL-encoded so that the request is a well-formed URL.

Commands that wait

Some commands wait until some action completes. For example, the block:

turn motor on for 3 seconds

turns on the motor, waits three seconds, then turns it off again. When this block is used in a script,

execution does not continue to the next block until the command completes. A command that waits

is indicated by the "w" block type in the command descriptor.

When a "w" command is invoked, Scratch adds a unique command_id parameter to the request

(before any other parameters). For example, for the motor command above Scratch would send:

/motorOn/2437/3

The first parameter, 2437, is a unique identifier for this invocation of the command. For the three

seconds that this command takes to complete, the helper app adds a busy line to the poll request:

_busy 2437 …

A busy line consists of the string "_busy" followed by a list of unique identifiers separated by

spaces. When Scratch gets a poll result that doesn't include 2437 in the busy line (or doesn't even

have a busy line), it knows that the command is complete and allows the script that invoked that

command to proceed.

Reporters that wait (future feature)

Note: This feature is not yet implemented because the Scratch interpreter does not yet support

reporter blocks that can suspend their thread until the result is ready.

In the future, the extension mechanism may be extended to support extension reporter blocks that

request data from the helper app and and wait until the result is returned before proceeding. To

handle such requests (sometime called a "blocking" request), Scratch will add a unique request_id

parameter to the request (before any other parameters). For example, a weather extension might

include a block to get the current temperature in a given city:

temperature in city_name

To get the temperature in Boston, this command would send the helper app a request like this:

/getTemperature/7639/Boston

The first parameter, 7639, is a unique request ID string. In response, the helper app would initiate a

request to get the weather information for Boston. Some time later, when the result of that request

is returned from the server, the helper app would include the following line in its response to the

next poll request:

_result 7639 82

This line consists of the special string "_result", the request ID, and the result value separated by

space characters. As with other sensor values, result value should be URL-encoded.

Reset command

Scratch extensions can control motors or music synthesizers. Users expect to be able to stop

everything -- turn off motors, silence music synthesizers, and reset hardware back to it's original

state -- by clicking the stop button in the Scratch editor. Thus, when the stop button is clicked,

Scratch sends a reset command to all active extensions:

/reset_all

In response to this command, the helper app should turn off motors, lights, sounds, etc. and reset

the hardware to its power-up state. For example, if the Scratch program had set the volume of

music synthesizer to zero, it should be reset to it's default level. The helper app should also cancel

any ongoing processes and clear its list of busy commands.

Cross-Domain policy requests

There's one other requirement for the helper app: it must respond to Flash's request for a cross-

domain policy file. This gives Flash permission to send HTTP requests to the helper app.

Flash sends the following request to the app:

/crossdomain.xml

The helper app must respond by sending a null-terminated policy file like this:

where is the port number of the helper app. Be sure to include a zero byte after the

policy file or Flash won't recognize it. Unfortunately, Flash doesn't allow a wildcard (asterisk) in

the "to-ports" field, so you have to fill that in with the correct port number. The example helper app

code shows how to handle a policy request.

Once Flash has received and checked the policy request, it can communicate with the helper app.

Building and Testing Extensions

The Scratch 2.0 extension mechanism is still under development. Eventually, the user will be able

to browse and import extensions from a library of published extensions, just as they currently

import costumes, backdrops, sprites and sounds from the Scratch media library, but that

mechanism is not yet implemented. Meanwhile, to allow extension development and testing, a

semi-hidden menu command can be used to import an extension from a local file.

Here are the steps for creating and testing a Scratch extension:

1. Create an extension description file

2. Create your helper app and start it

3. Open the Scratch 2 Offline Editor

4. Import the extension description (shift-click on "File" and select "Import Experimental

Extension" from the menu)

5. The new extension blocks will appear in the More Blocks palette

6. Test your extension and iterate!

Helper apps can be written in any language that supports server sockets, such as Python, Node.js,

Java, C, etc.

Eventually, the Scratch Team may assign socket numbers for popular extensions to avoid possible

conflicts. For now, any unused socket number over 1024 can be used.

Distributing Extensions

As of this writing, an extension distribution strategy is still being worked out. The Scratch team

will probably host a small library of "supported" extensions. Users will be able to browse and

select extensions from this library from within the Scratch editor, and will be able to download the

necessary helper app from the Scratch website. Supported extensions would be checked for quality

and safety by the Scratch team. There are likely be strict criteria for including an extension in the

Scratch-team supported extensions library, such as command set clarity and ease of use, size of the

potential audience, wide-spread availability of any associated hardware, and a long-term

commitment to support the extension.

To avoid potential confusion on the Scratch website, projects with unsupported extensions should

only be used with the Scratch Offline Editor and should be saved only locally, not uploaded to the

website. Extension developers can share their extensions by distributing copies of the extension

description file and helper app. Users would then use the "Import Experimental Extension"

command in the Offline editor to import the extension.

Protocol Summary

Scratch sends the following commands to a helper app:

/poll

/reset_all

The response to a /poll request is one or more lines separated by newline characters (0xA). The

response may include one or more of the following:

- a sensor name and value separated by whitespace

- "_busy" followed by a list of unique ID's for commands in progress

- "_problem" followed by a problem description

- "_result" followed by a unique ID and value (not yet implemented)

这里提供pdf电子版下载地址：http://www.scratch100.com/thread-4-1-1.html