(Fixed some headers.)
(Automated edit: fixed 2 style guidelines)
 
(26 intermediate revisions by 13 users not shown)
Line 1: Line 1:
<!--
+
{{obsolete feature}}{{other version|1.3/1.4|2.0|title=Scratch Extension Protocol (2.0)|noversion=yes}}
John Maloney
+
The '''Remote Sensors Protocol''' or '''Scratch Extension Protocol''' is an experimental extension feature that allows interaction between Scratch (1.3+) and other programs.
September 2, 2008
 
  
document rewritten, required info?
+
== Introduction ==
-->
 
The '''Remote Sensors Protocol''' or '''Scratch Extension Protocol''' is an experimental extension feature that allows interaction between Scratch verion 1.3 and up and other programs.
 
 
 
''This article is a rewritten version of the document "Scratch Extension Protocol" (John Maloney, September 2 2008)''
 
 
 
==Introduction==
 
  
 
Three kinds of interaction are supported:
 
Three kinds of interaction are supported:
  
* sharing broadcasts (in both directions)
+
* Sharing [[broadcast]]s (in both directions)
* virtual sensors
+
* Virtual sensors
* Scratch's global variables are made visible
+
* Scratch's global [[variable]]s are made visible
  
<!--
 
This document describes this mechanism in sufficient detail to allow people to write their own programs that interact with Scratch in any programming language that supports sockets, such as Python, Java, Ruby, ActionScript, or Squeak.
 
-->
 
 
==Protocol==
 
==Protocol==
  
The experimental extension feature is enabled using the right-button menu on one of the two [[Sensing Blocks|sensor blocks]]. When remote sensors are enabled, Scratch listens for connections on port 42001.  
+
The experimental extension feature is enabled using the right-button menu on one of the two [[Sensing Blocks|sensor blocks]]. When remote sensors are enabled, Scratch listens for connections on TCP port 42001.
  
 
Once a connection is established, messages are sent in both directions over the socket connection.
 
Once a connection is established, messages are sent in both directions over the socket connection.
  
Each message consists of a four-byte size field, most-significant byte first, followed by the message itself:
+
Each message consists of a four-byte "size" field, most-significant byte first, followed by the message itself:
  
<size: 4 bytes><msg: size bytes>
+
<pre><size: 4 bytes><msg: size bytes></pre>
  
 
The four-byte size field is not counted as part of the message size. Thus, an empty message is four zero bytes.
 
The four-byte size field is not counted as part of the message size. Thus, an empty message is four zero bytes.
  
==Message Types==
+
== Message Types ==
  
 
The message up to the first whitespace character (any byte <= 32) is a case-insensitive message type string that is used to decide how to handle the message.
 
The message up to the first whitespace character (any byte <= 32) is a case-insensitive message type string that is used to decide how to handle the message.
Line 38: Line 28:
 
Clients should extract and check the message type string from a message before doing further processing. The set of message types will be extended over time, so client code should be written to skip messages with types that it does not understand. Messages may eventually be used to transmit large amounts of binary data in arbitrary formats. Thus, clients must be prepared to handle (and possibly discard) large messages.
 
Clients should extract and check the message type string from a message before doing further processing. The set of message types will be extended over time, so client code should be written to skip messages with types that it does not understand. Messages may eventually be used to transmit large amounts of binary data in arbitrary formats. Thus, clients must be prepared to handle (and possibly discard) large messages.
  
==Common Message Types==
+
== Common Message Types ==
  
 
Most message types contain human-readable strings made up of the following elements:
 
Most message types contain human-readable strings made up of the following elements:
  
* unquoted single-word strings (cat, mouse-x)
+
* Unquoted single-word strings (cat, mouse-x)
* quoted strings ("a four word string", "embedded ""quotation marks"" are doubled")
+
* Quoted strings ("a four word string", "embedded ""quotation marks"" are doubled")
* numbers (1, -1, 3.14, -1.2, .1, -.2)
+
* Numbers (1, -1, 3.14, -1.2, .1, -.2)
* booleans (true or false)
+
* Booleans (true or false)
  
Words and strings are encoded in UTF-8. (Note: ASCII is a subset of UTF-8).
+
Words and strings are encoded in UTF-8. {{note|[[wikipedia:ASCII|ASCII]] is a subset of [[wikipedia:UTF-8|UTF-8]].}}
  
 
Here are the two most useful message types:
 
Here are the two most useful message types:
  
* broadcast <string>
+
* Broadcast ''<string>''
* sensor-update <var-name_1> <new-value_1> ...
+
* Sensor-update ''<nowiki><var-name_1> <new-value_1></nowiki>'' ...
  
 
A sensor update message includes one or more (variable name, value) pairs. Variable names are strings. Values can be either numbers or quoted strings.
 
A sensor update message includes one or more (variable name, value) pairs. Variable names are strings. Values can be either numbers or quoted strings.
Line 58: Line 48:
 
Here is an example:
 
Here is an example:
  
sensor-update "note" 60 "seconds" 0.1
+
<pre>sensor-update "note" 60 "seconds" 0.1
broadcast "play note"
+
broadcast "play note"</pre>
  
 
The first message sets the value of two virtual sensors named "note" and "seconds". The second broadcasts the "play note" message. A Scratch script might respond to this broadcast by playing a note as specified by the sensor values.
 
The first message sets the value of two virtual sensors named "note" and "seconds". The second broadcasts the "play note" message. A Scratch script might respond to this broadcast by playing a note as specified by the sensor values.
  
Scratch sends these two message types when broadcasts or global variable changes occur. Scratch also responds to these messages. Broadcast messages sent to Scratch cause a broadcast to occur. Sensor-update messages update the values of virtual sensors available in the sensor block drop-down menu.
+
Scratch sends these two message types when broadcasts or global variable changes occur. Scratch also responds to these messages. Broadcast messages sent to Scratch cause a broadcast to occur. Sensor-update messages update the values of virtual sensors available in the sensor [[Blocks|block]] drop-down menu.
 +
 
 +
[[Category:Scratch Program]]
 +
[[Category:Scratch Extensions]]
 +
[[Category:Scratch Networking]]

Latest revision as of 06:13, 27 January 2019

Archive.png This article or section documents something not included in the current version of Scratch (3.0). It is only useful from a historical perspective.
This article or section documents an outdated version of Scratch (version 1.3/1.4). For this article in Scratch 2.0, see Scratch Extension Protocol (2.0).

The Remote Sensors Protocol or Scratch Extension Protocol is an experimental extension feature that allows interaction between Scratch (1.3+) and other programs.

Introduction

Three kinds of interaction are supported:

  • Sharing broadcasts (in both directions)
  • Virtual sensors
  • Scratch's global variables are made visible

Protocol

The experimental extension feature is enabled using the right-button menu on one of the two sensor blocks. When remote sensors are enabled, Scratch listens for connections on TCP port 42001.

Once a connection is established, messages are sent in both directions over the socket connection.

Each message consists of a four-byte "size" field, most-significant byte first, followed by the message itself:

<size: 4 bytes><msg: size bytes>

The four-byte size field is not counted as part of the message size. Thus, an empty message is four zero bytes.

Message Types

The message up to the first whitespace character (any byte <= 32) is a case-insensitive message type string that is used to decide how to handle the message.

Clients should extract and check the message type string from a message before doing further processing. The set of message types will be extended over time, so client code should be written to skip messages with types that it does not understand. Messages may eventually be used to transmit large amounts of binary data in arbitrary formats. Thus, clients must be prepared to handle (and possibly discard) large messages.

Common Message Types

Most message types contain human-readable strings made up of the following elements:

  • Unquoted single-word strings (cat, mouse-x)
  • Quoted strings ("a four word string", "embedded ""quotation marks"" are doubled")
  • Numbers (1, -1, 3.14, -1.2, .1, -.2)
  • Booleans (true or false)

Words and strings are encoded in UTF-8.

Note Note: ASCII is a subset of UTF-8.

Here are the two most useful message types:

  • Broadcast <string>
  • Sensor-update <var-name_1> <new-value_1> ...

A sensor update message includes one or more (variable name, value) pairs. Variable names are strings. Values can be either numbers or quoted strings.

Here is an example:

sensor-update "note" 60 "seconds" 0.1
broadcast "play note"

The first message sets the value of two virtual sensors named "note" and "seconds". The second broadcasts the "play note" message. A Scratch script might respond to this broadcast by playing a note as specified by the sensor values.

Scratch sends these two message types when broadcasts or global variable changes occur. Scratch also responds to these messages. Broadcast messages sent to Scratch cause a broadcast to occur. Sensor-update messages update the values of virtual sensors available in the sensor block drop-down menu.

Cookies help us deliver our services. By using our services, you agree to our use of cookies.