Remote Sensors Protocol

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.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:

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.