ScratchRadio Programming

Program Structure

All Scratch Radio programs will have the same underlying structure consisting of two distinct phases. The radio setup phase is used to configure the way the radio will operate by connecting various radio blocks together. The radio operation phase then activates the radio and allows the radio to transmit and receive radio signals as required.

There are three Scratch Radio blocks which are used to control these phases of operation – the reset, start and stop blocks. The reset block is used to discard any previous radio configuration and prepare the radio at the start of the setup phase. Once the radio has been configured, the start block is used to activate the radio at the start of the operation phase. Finally, the stop block is used to halt the radio at the end of the operation phase. This means that all Scratch Radio programs will have a structure similar to the one shown below:

Note that the stop block halts radio processing but leaves the radio configuration specified in the setup phase intact. This means that any GUI windows associated with the configuration are left open and the radio can be restarted by using another start block if required. If this behaviour is not required, the reset block can be used instead of the stop block. This will cause the radio processing to be halted and the radio configuration together with all associated GUI windows will be discarded.

It is possible to determine whether the radio is in the operation phase by monitoring the radio running status flag that is provided by the Scratch Radio extension. This may be used as a Boolean value in Scratch expressions in order to make them conditional on the operational state of the radio. A simple example that waits for the radio to be activated and then waits for it to be deactivated is shown below:

Flow Graph Setup

The setup phase of a Scratch Radio program is used to connect various radio blocks together into a data flow graph to create a complete radio system. Scratch Radio blocks which may be used during the setup phase are indicated by the use of a flow graph icon at the left hand side of the Scratch block. These icons have the following meanings:

Source		This icon is used to indicate that the flow graph block is a data input. When the radio is active, data will be received from some external data producer and emitted at the output of the block.
Sink		This icon is used to indicate that the flow graph block is a data output. When the radio is active, data will be accepted at the input to the block and emitted to some external data consumer.
Process		This icon is used to indicate that the flow graph block is a data processing block. When the radio is active, data will be accepted at the input of the block and processed, with the transformed data being emitted at the output of the block.
Tap		This icon is used to indicate that the flow graph block taps into the data being produced elsewhere in the flow graph and replicates it at the output of the block.

A valid flow graph is created by connecting data flow blocks in a particular manner. Every data flow should start with a source block. Source blocks must not be immediately preceded by another source, process or tap block and must be immediately followed by a process or sink block. Multiple process blocks may then be chained together, ending with a sink block. The net effect is that the data flow icons ‘connect’ to give a visual indication of the data flow. A simple example which shows a radio source being filtered and output to a display sink block is shown below:

Each flow graph block is assigned a name which is used to refer to the block elsewhere. Names must be unique for a given radio configuration and must not contain any spaces. In the case of the preceding example the data source is called lime-source, the low pass filter block is called lp-filter and the spectrum display is called spectrum. In conjunction with the data flow tap block, this allows the output of a named block to be replicated so that the same data source can be used in two parallel data flows.

In general, tap blocks can be treated in a similar manner to conventional source blocks – so they must not be immediately preceded by another source, process or tap block and must be immediately followed by a process or sink block. The preceding example can be expanded to include a spectrum display of the unfiltered input by using a tap block and specifying its signal source as being lime-source, as shown in the following Scratch program:

In addition to the block name, each data flow block may have a number of configurable parameters which can be used to parameterise the block behaviour. Each data flow block is also restricted in terms of the type of data supported at its input and/or output. The configuration options and supported data types are described in detail in the block library documentation here: ScratchRadio:Library

Note that since Scratch Radio is at an early stage of development, error checking for duplicate block names and invalid block parameters or connections is not supported within the Scratch environment. Therefore the logs from the GNU Radio terminal window should be used as an indication of whether a given radio configuration contains errors.

Interacting With Scratch Radio

During the operation phase, Scratch Radio supports interaction with the active data flow graph via two dedicated blocks – the message source and message sink blocks. The message source block acts as a data flow source of short text messages (up to 255 characters) that can then be processed by the configured radio blocks. Similarly the message sink acts as a data flow sink for short text messages that are generated by the configured radio blocks and passed back to the Scratch environment. In order to demonstrate the way in which these blocks are used it is possible to connect them in a loopback configuration as shown below:

In order to send a text message the send message block can be used once the radio has been started. As an example, the following program segment will wait until the radio is running and then send ‘Hello World’ messages at five second intervals until the radio is stopped:

In order to receive a text message, the receive message block can be used once the radio has been started. This block is similar to a variable block and should be used in Scratch expressions. It differs from a conventional variable block in that it will only be evaluated once for each new message that is received. This means that a program segment containing the receive message block will always pause waiting for new messages when none are currently available. As an example, the following program segment will wait until the radio is running and then report every received message until the radio is stopped:

Combining the three program segments illustrated in this section will give a complete Scratch program that sets up a message loopback in GNU Radio, transmits “Hello World” messages via the message source component and then receives the messages via the message sink component. Running the program should result in the Scratch Cat ‘thinking’ about the messages as they are received: