Programming language is python.
Although the complexity would require programming techniques as static types, interfaces, enumerations and private fields, python is easy to learn and is widely adopted in the Raspberry-Community.

GUI is web based.
As the client could be run in background, web based access is quite easy to use. Cherrypy with mako templates are used to implement the server side. On the fly graphics are svg-based. Event notifications are used to update the web client. This technique is supported by midori, epiphany and most browsers (not IE).

Configuration files are XML
Widely adopted in industry, easy to read, can be automatically formatted. Allows inline comments.

Configuration files are versioned.
Versioning allows to implement backward compatibility through releases.

GPIO names are BCM internal GPIO-scheme.
External names are mapped to internal numbers, allowing for flexibility. This mapping is configurable.

Basic frame for all configurations is the xml-preamble and the config tag.

<?xml version='1.0' encoding='utf-8' ?>
<config version='1.0'>
    <description>Basic empty configuration</description>
</config>

The config-tag is the 'frame' for more content. The description-tag contains some information about the project, purpose or whatever else might be needed to clearly identify the target system purpose of configuration.

In the samples in ./config, there are schema references for validation purposes. When the data are read by scratchClient, no validation is used (but they need to be xml-compliant).

	Feel free to add xml-comments <!-- comment --> whereever you want to have more information.

<?xml version='1.0' encoding='utf-8' ?>
<config version='1.0'>
    <description>Sample configuration</description>

    <adapter class='adapter.gpio.GpioOutput'  name='relais'>
        <description>Sample GPIO, here assumed to be a relais output</description>

        <gpio port='GPIO25'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' default='low' />
        </gpio>

        <input name='low'>
            <broadcast name='pin25low'/>
            < broadcast name='pin10off'/>
        </input>
        <input name='high'>
            < broadcast name='pin25high'/>
            < broadcast name='relaisOn'/>
        </input>
    </adapter>
    
</config>

The <adapter/> tag has the attributes

@class: python class name of the implementing code, mandatory

@name: a short name, identifying this adapter. Name is mandatory, needs to be unique in the configuration.

The <adapter/> tag has the child elements <description/> a description for the adapter, purpose, technical details or alike. <gpio/> each port pin adapter is using is listed here. Here, GPIO10 (this numbering is always BCM-related) is used, configured as an output. More on this later. <input/> Each input of an adapter needs a separate <input/> tag (when used, not used inputs do not need to be listed). The @name-Attribute is mandatory and corresponds to the method name of the adapter code.

<gpio/> uses elements <active/> and <default/> .

Active is the initial state the code sets the pin when initiated. Default is the state the code leaves the pin when the code is gracefully shut down. This is done by pressing ctrl-C in console, or sending SIGINT in linux.

The inputs an adapter exposes are mapped to broadcast events from scratch. These mappings are provided by <broadcast@name/> -Tags inside the input. The @name of the <broadcast/> is used as 'text' in the scratch broadcast blocks. In most cases, there will be only one command element, as the purpose is pretty clear.

The <broadcast@name/> can occur multiple times in one <config/> file, triggering multiple adapters by one broadcast from scratch. This feature can be used for a 'startAll' or 'stopAll'-feature for some adapers.

The broadcast names will be in most projects logical names, like 'relaisOn', 'led_green_off'.

The names are case sensitive, so 'relaisOn' and 'RelaisOn' are different. Be sure to use exactly the same spelling on scratch and adapter side, otherwise commands are discarded. At runtime, information on mapping of scratch broadcasts to adapters is printed to the console when the '-v', the verbose switch in the command line is applied.

The configuration class in the system checks for errors in the configuration and will provide (hopefully) meaningful hints on how to correct problems.

The following 'stepper' example shows some advanced features.

   <adapter class='adapter.stepper.Stepper' name='x-direction' >

        <description>Stepper class uses w0 for coil 0, 
                          w1 for coil 1 etc</description>

        <gpio port = 'GPIO14' alias='w0' >
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' default='high' />
        </gpio>
        <gpio port = 'GPIO15' alias='w1' >
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' default='high' />
        </gpio>
        <gpio port = 'GPIO17' alias='w2' >
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' default='high' />
        </gpio>
        <gpio port = 'GPIO18' alias='w3' >
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' default='high' />
        </gpio>

        <input name='start'>
            <broadcast name='startA'/>
        </input>
        <input name='stop'>
            <broadcast name='stopA'/>
        </input>
        <input_value  name='speed'>
            <variable name='speedA'/>
            <variable name='speed'/>
        </value>
    </adapter>

As the adapter uses four GPIO Pins, these <gpio/> -tags get an @alias-attribute to assign these pins to functionality inside the adapter.stepper.Stepper-class.

The <input/> tags are pretty clear, the <value/> -tag is providing configuration for values beeing sent from scratch to the adapter. In scratch 1.4, global variables are sent to the adapters. These names are defined with <variable /> tags similiar to inputs.

Adapters with output values (which should be transmitted to scratch) are using the <output_value/> -tag. A button sample is:

   <adapter class='adapter.gpio.GpioInput' name='button 22'>
        <!-- no description, urgg -->
        <gpio port = 'GPIO22'>
            <default dir='IN' pull='PUD_OFF' />
            <active dir='IN' pull='PUD_OFF'/>
        </gpio>
        <output_value name='button'>
            <sensor name='button22'/>
        </output>
        
        <parameter name='poll.interval' value='0.5' />

    </adapter>

The <output/> tag maps a logical name to a scratch sensor-update-name, here 'button22'. Here a 1-1 relation between output and command is assumed, as it is not useful to send one value to different variables in scratch.

        <parameter name='poll.interval' value='0.5' />

5.3.2.  Other features: webserver websocket plugin, html plugin

For one of the adapters (websocket), there was the need to have the embedded webserver to support custom websocket code and html pages.

To make this flexible, a plugin mechanism was implemented.

        <webserver>
            <!-- implement a web page  -->
            <route name='pendel' route='/adapter/pendel' />
            <html name='pendel' 
                  path='websocket/pendel.html' 
                  comment='positional sensor from a smartphone' />
        </webserver>

Tag <webserver/> groups the entries.

Tag <route/> defines the absolute path for the webapplication server to the websocket.

Tag route/@name a descriptive name

Tag route/@route an absolute path for the entry point of the websocket

The websocket protocol class is provided by the adapter and does not need configuration.

Tag <html/> defines the location of additional web pages. Links to these pages are added to main page.

Tag html/@name a descriptive name

Tag html/@path a relative path for the page. Place these pages to htdocs/static/html/..

Tag html/@comment a descriptive comment. May be empty.

The needed html pages are to be placed in htdocs/static/html/[html@path].

This is the 'injected' web link to the main page.

5.3.3.  Adapter lifecycle

Adapters get created (instantiated) by the configuration manager when reading the xml-file. When no errors occur, the configManager keeps the instance in a list of adapters for later reference.

Then parameters are set.

Adapters are started one after the other by setActive (True). There is no particular order within the adapters to get this event.

	If your application needs adapter 'A' to be startet after 'B', then most possibly you need a special implementation 'AB' which combines the two.

When set to active, adapters should start regular work. This means to setup the GPIO, starting threads and whatever else might be needed. Setting the GPIO can be done by using the base adapter class' methods.

Adapters stop operation by setActive(False). Then threads should be stopped in a timely manner (less than 0.1 sec), and GPIO should be reset to default state. The adapters base class provides mechanisms to setup GPIO. These can be overwritten to achieve other behaviour.

There is no live after setActive(False). The adapters will be destroyed later and the code stops to work.

CPU load
Adapters should not poll and send values too often. Faster than some 20 to 50 updates per second are a challenge for the system, as the socket connection and also scratch on the receiving end needs cpu-cycles to perform work. Currently, each sensor-update is send separately.

For the GPIO-Types, different libraries can be used: RPi.GPIO (default) or RPIO. RPIO has the ability to PWM drive the GPIO with DMA, producing stable pulses.

GPIO Pins are named in BCM-Notation (e.g. GPIOnn), Pin headers (e.g. P1-13V2 for Version2) or other (for a specific adapter, IKG.IO.3 is used). The naming configuration is in /scratchClient/config/portMapping.xml

    <adapter class='adapter.gpio.GpioStateOutput'  name='state'>
        <description>State display on IKG.IO.9</description>

        <gpio port='IKG.IO.9' alias='state'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
    </adapter>

SPI is a communication protocol for various devices. A concept of 'device handlers' is used to generalize the usage. When in a device multiple similiar data points are used, this is called 'channels'; used in e.g. ADC-devices.

6.2.1. WS2801 LED Stripe

SPI can be used to emulate a shift register, as needed by a LED Strip with WS2801-Chip. The adapter is adapter.spiadapter.WS2801_Adapter.

In the distribution, there is a sample scratch program for the WS2801-stripe.

Start scratch with command

scratch ~/scratchClient/scratch/ws2801/ws2801.sb

The program provides some colored fields which can be clicked and add their color name to a list. When the data shall be send to the stripe, press 'send'. The list is converted to a variable 'led' then.

The scratchClient adapter converts color names to RGB-values and sends them out to the SPI-hardware.

start scratchClient

cd ~/scratchClient
sudo python src/scratchClient.py -config scratch/ws2801/config_spi_ws2801.xml
                

For the hardware connection, see your vendors documentation on the stripe.

cd ~/scratchClient
sudo python src/scratchClient.py -config config/config_max31855.xml
            

6.2.5. MCP23S17 16-Bit IO Expander; PIFACE board

The MCP23S17 is a SPI connected port expander with 16 GPIO pins. The adapter adapter.mcp23s17.MCP23S17_Adapter controls this device.

6.2.5.1. Setup on a breadboard

6.2.5.2. PiFace board

The MCP23S17 is used on the PiFace board. The sample configuration config/config_mcp23s17.xml can be used to drive this board. When using piFace, then do NOT use GPIO25 (this is INTB in MCP23S17)

In scratch, create variables 'out_0', 'out_1' .. 'out_7' to drive the outputs. Values are '0', '1', 'true', 'false'. For the relais, the variables 'relais_0', 'relais_1' can be used. The variable 'all' sets all outputs in parallel.

scratchClient sends sensor values 'inp_0', 'inp_1', .. 'inp_7'; the values are '0' and '1'.

In the configuration file, the scratch names can be changed to be more useful. If for example a 'forwardMotor' is attached to relais_0, just rename 'relais_0' to 'forwardMotor'.

6.2.5.3. Configuration details

The device 23s17 allows to have up to 8 devices 'in parallel' on one SPI chip select. These devices have hardwired distinct slave adresses. In the configuration, this slave address must be given by the parameter '23s17.addr'.

        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        
        <!-- slave address must match the hard wired slave address 
             on the device [0..7] -->
             
        <parameter name='23s17.addr' value='0' />

The IO direction for the port pins is defined by <io/>-tags.

        <io id='GPA0' dir='out' />
        <io id='GPA1' dir='out' />
        <io id='GPA2' dir='out' />
        <io id='GPA3' dir='out' />

        <io id='GPA4' dir='out' />
        <io id='GPA5' dir='out' />
        <io id='GPA6' dir='out' />
        <io id='GPA7' dir='out' />

        <io id='GPB0' dir='in' pullup='weak' />
        <io id='GPB1' dir='in' pullup='weak' />
        <io id='GPB2' dir='in' pullup='weak' />
        <io id='GPB3' dir='in' pullup='weak' />

        <io id='GPB4' dir='in' pullup='weak' />
        <io id='GPB5' dir='in' pullup='weak' />
        <io id='GPB6' dir='in' pullup='weak' />
        <io id='GPB7' dir='in' pullup='weak' />

It is generally a good idea to define all of the port pins. Technically it is needed to define those which are used in the application. The id-values are predefined and must be used as seen here.

For ports defined as dir='out' outputs, the corresponding adapter input methods can be used:

        <input_value name='inputGPA4'>
            <!-- variable name is the name of the scratch variable 
                 which is send out to the adapter. -->
            <variable name='input_4'/>
        </input_value>
 

For ports defined as dir='in' inputs, the corresponding adapter output methods can be used:

        <output_value name='outputGPB2'>
            <sensor name='output_2'/>
        </output_value>
 

The variables send out from scratch are '0', '1' to set the output pin of the 23s17 to low, high.

The sensor values received from scratch are '0', '1' for the input pin of the 23s17 receiving low, high.

6.2.5.4. Start scratchClient

scratchClient startup does not need special considerations.

cd ~/scratchClient
sudo python src/scratchClient.py -C config/config_mcp23s17.xml
                

The file config/config_mcp23s17.xml is an example of a full functional configuration.

Temperature sensor DS1820 needs one gpio pin for the connection. The timing is quite strict, but a kernel driver is available.

Adapter adapter.w1_gpio.W1_DS1820 uses 'w1-gpio' kernel driver.

Connect ds1820 signal line to GPIO4, pullup needed 4k7 Ohm to 3.3V.

The adapter configuration sample is config/config_temperature_ds1820.xml . In this file, you need to configure the address of your ds1820.

The sample configurations contain a config file for this device. Start scratchClient with

cd ~/scratchClient
python src/scratchClient.py -c config/config_temperature_ds1820.xml

For this special purpose, no root permission is needed. The file written by the kernel driver is public for reading.

The adapter class adapter.remote.CommunicationAdapter provides scratch to scratch communication. There is a server process needed on the network [host, port=42002].

python src/scratchCommunicationServer.py

It is recommended to install scratchCommunicationServer on a machine with a fixed ip address. It can run in parallel to scratchClient on a machine.

The adapters are assigned to groups, so within one network the communication server keeps different groups separate from each other. Sample configuration is /scratchClient/config/config_remote_0.xml or config_remote_1.xml

Groups are useful when in a classroom environment where pairs of two exercise a communication sample, but only one scratchCommunicationServer is running. Then each group gets its own name, and interferences are avoided.

Broadcast signals defined as inputs to the adapter are propagated to all other registered adapters (except the one it came from). Outputs of the adapter are propagated towards local scratch.

6.5.1. How to setup configuration files.

A simple szenario is used for the explanation: In a school class, three computers with scratch should perform a chain reaction. 'computer_0' lights a LED and sends 'command_A' to 'computer_1'. When 'computer_1' receives this event, it lights a LED and sends 'command_B' to 'computer_2', which lights a LED.

With an UML sequence diagram, the process gets clear.

Good planning is needed for a successful setup.

For 'computer_0', there is only one outgoing event.

        <remote type='forward'>
            <broadcast name='command_A'/>  
        </remote>

For 'computer_1', there is one incoming event and one outgoing event.

        <remote type='forward'>
            <broadcast name='command_B'/>  
        </remote>
        <remote type='receive'>
            <broadcast name='command_A'/>  
        </remote>

Finally for 'computer_2', there is one incoming event.

        <remote type='receive'>
            <broadcast name='command_B'/>  
        </remote>

For each computer, prepare the appropriate config file and start scratchClient with it.

6.5.2. Sample Application 'railway control'

There is a sample implementation of a remote controllable railway track available. To operate this, you need two computers A and B on a network. It is not possible to have this running on one system only, as two scratch instances are needed and the server ports 42001 can't be adjusted. A screencast of this sample is available on youtube

Adjust hostaddress in scratch/remote/config_lokomotive_remote.xml and scratch/remote/config_lokomotive_remote_control.xml, it should contain IP-address or hostname of Computer A.

        <parameter name="server" value="192.168.2.102" />

Distribute this file to Computer A and Computer B.

6.5.2.1. Context Diagram

6.5.2.2.  Computer A

start scratch

scratch ~/scratchClient/scratch/remote/lokomotive_remote.sb

start scratchClient, in a terminal window.

cd ~/scratchClient
sudo python src/scratchClient.py -c scratch/remote/config_lokomotive.xml
                    

start server process in a terminal window:

cd ~/scratchClient
python src/scratchCommunicationServer.py

6.5.2.3. Computer B

start scratch

scratch ~/scratchClient/scratch/remote/lokomotive_remote_control.sb

Clicking on the arrows should set the corresponding track directions. But scratchClient needs to be started first. start scratchClient in a terminal window:

cd ~/scratchClient
sudo python src/scratchClient.py -config scratch/remote/config_lokomotive_control.xml

Commands from control panel on computer B scratch instance are transferred to computer A.

A dialplate as seen here has two switches.

The adapter adapter.encoder.GPIODialPlateEncoder is handling the plate. It needs two GPIO pins. Polling interval is changing for this adapter. When not used (contact 'nsa'), the polling interval is 0.2 sec. When active the polling interval is 5ms.

Barcode scanners are USB-connected devices.

These scanners typically can send codes by emulating HID-class devices. This makes usage from programs quite easy, but you loose input when the program goes to background and other programs get the focus.

Connecting these devices can be don eusing pyusb library. This library allows access to usb devices and, very important, can grab devices to be used exclusively by one program.

cd ~/scratchClient
python tools/usb/enum.py

DEVICE ID 0c2e:0200 on Bus 001 Address 007 =================
bLength : 0x12 (18 bytes)
bDescriptorType : 0x1 Device
bcdUSB : 0x110 USB 1.1
bDeviceClass : 0x0 Specified at interface
bDeviceSubClass : 0x0
bDeviceProtocol : 0x0
bMaxPacketSize0 : 0x8 (8 bytes)
idVendor : 0x0c2e
idProduct : 0x0200
bcdDevice : 0x5881 Device 88.81
iManufacturer : 0x1 Honeywell Scanning and Mobility
iProduct : 0x2 Honeywell Scanning and Mobility Scanner
iSerialNumber : 0x0
bNumConfigurations : 0x1
CONFIGURATION 1: 300 mA==================================
bLength : 0x9 (9 bytes)
bDescriptorType : 0x2 Configuration
wTotalLength : 0x22 (34 bytes)
bNumInterfaces : 0x1
bConfigurationValue : 0x1
iConfiguration : 0x3 HID Keyboard
bmAttributes : 0x80 Bus Powered
bMaxPower : 0x96 (300 mA)
INTERFACE 0: Human Interface Device ====================
bLength : 0x9 (9 bytes)
bDescriptorType : 0x4 Interface
bInterfaceNumber : 0x0
bAlternateSetting : 0x0
bNumEndpoints : 0x1
bInterfaceClass : 0x3 Human Interface Device
bInterfaceSubClass : 0x1
bInterfaceProtocol : 0x1
iInterface : 0x0
ENDPOINT 0x81: Interrupt IN ==========================
bLength : 0x7 (7 bytes)
bDescriptorType : 0x5 Endpoint
bEndpointAddress : 0x81 IN
bmAttributes : 0x3 Interrupt
wMaxPacketSize : 0x8 (8 bytes)
bInterval : 0xa

cd ~/scratchClient
sudo python src/scratchClient.py -c config_barcode

Blink is a small, USB based device with two RGB-LED.

Connecting this devices can be done using pyusb library. This library allows access to usb devices and, very important, can grab devices to be used exclusively by one program.

See chapter 'install pyusb' in barcode scanner chapter' for installation.

cd ~/scratchClient
sudo python src/scratchClient.py -c config_blink

The adapter is adapter.serialAdapter.RFID_Reader_Adapter, a sample config file is in config/config_ID12LA.xml.

RFID-Readers are available for 125kHz and 13.56MHz. For the 125kHz there are reader modules available from Innovations which contain also the antenna.

Connect the device to 3.3V and set format to ASCII. The data output goes to Rx-Input of Raspberry Pi.

The adapter sends an event when data are received from RFID-reader. This allows to trigger scripts in scratch when the same card or tag is used twice.

The adapter is adapter.serialAdapter.PicoBoard_Adapter, a sample is available in /config/config_picoBoard.xml.

Picoboard, available from sparkfun, is a USB/serial connected device which contains some sensors and a slider.

The serial protocol is using polling. Scratch or the adapter in scratchClient sends out a 0x01 to start data aquisition and transfer. The board responds by 9 datapackets.

As polling is used, the tx and rx-LED should flicker frequently.

This board is supported by scratch, so usually there is no need to use scratchClient.

There are situations where support by scratchClient is useful:

The sample configuration file config/config_picoBoard.xml uses the scratch names used from ScratchBoard.

If you need more than one picoboard, then

Arduino UNO has an USB connection, which supports serial connection to a host computer. The arduino can be used as a IO expander, connecting digital io lines, pwm, or adc-inputs directly to scratchClient. It also supports servo signals (pwm 50Hz, 1 to 2ms pulses).

The adapter and arduino sketch will also work with arduino nano, atmel328 processor.

With the USB-connection, the UNO provides 5V-compatible inputs/outputs. This is an advantage in some constellations. But do not connect these outputs to Raspberry Pi inputs directly.

The functionality presented here is not a bridge to mesh network, propagating events and sensor updates into the arduino. There is a custom arduino sketch needed which only exposes the IO resources, but does not allow for additional logic in arduino.

Configuration of the io-pins (direction, pullup, pwm, servo) and adc-pins (whether used or void) is controlled by scratchClient through configuration.

The scratch names used are configurable in configuration too. This is common functionality of the framework.

The code and configuration needed is in the scratchClient distribution.

6.14.2.  Step 2, Sample hardware setup.

This setup is a sample for what is possible with this setup. The configuration file allows for almost all the flexibility the atmel controller allows.

The hardware uses a potentiometer (2k to 10k are ok) on AD0. On D3, there is a button connected. The other side is having a 1k-Resistor to GND (just in case the output is configured as an output, this prevents damage to the IO).

Two LED are for output. The green LED is on a PWM-Output D5, so it can be dimmed.

This setup is a sample. The functionality of all the inputs and outputs are defined by configuration in scratchClient.

cd ~/scratchClient
python src/scratchClient -c config/config_arduino_uno.xml

6.14.5. Step 5, start scratch with sample program

There is a sample program in scratch/arduinoUno/arduino.sb

The program takes the button input and controls the red LED with it.

The value from the potentiometer is used to set the pwm-rate and dim the green LED.

LEGO powerfunctions provide an infrared controlled receiver with the possibility to connect to motors, lights and others. With an IR-LED connected to an arduino which is connected to a RPi which is connected (or hosting) scratch), it is possible to control these receivers with scratch.

Arduino UNO has an USB connection, which supports serial connection to a host computer.

The adapter and arduino sketch will also work with arduino nano, atmel328 processor.

With the USB-connection, the UNO provides 5V-compatible inputs/outputs. This is an advantage in some constellations. But do not connect these outputs to Raspberry Pi inputs directly.

An IR-LED (940nm wavelength) is needed, a resistor 220 Ohm limits current. This allows for short distance connections.

With a transistor like 2n2222 and a base resistor of 680Ohm, the power on the LED can be increased.

The scratch names used are configurable in configuration files. See the config file config/config_arduino_powerfunctions.xml

The arduino code for arduino IDE and configuration needed for scratchClient is in the scratchClient distribution.

cd ~/scratchClient
python src/scratchClient -c config/config_arduino_powerfunctions.xml

Twitter has an API which can be used by scratchClient. The adapter browses twitter for direct messages or by a hashtag and forwards these results to scratch.

Install python-twitter in python environment "sudo pip install python-twitter".

You need to obtain 'key' and 'secret' from twitter to access the API. Edit config/config_twitter.xml and insert values there.

Polling rate for twitter can be adjusted, but twitter.com imposes a rate limit. 60 sec are a good starting point.

It is configurable whether the adapter retrieves user message or searches messages for a term or both.

A properties file written by the adapter allows to retrieve only new messages. The messageId of last message read is persisted in this file. The file is in data folder, filename is configurable in config file.

Start scratchClient

cd ~/scratchClient
python src/scratchClient -c config/config_twitter.xml

A scratch sample is in scratch/twitter/twitter.sb

Messages from twitter can arrive at a faster rate than scratch can process, or messages can be identical, which makes them indistinguishable for scratch. To handle this situation a protocol is implemented between the twitter adapter and scratch: all messages are queued inside the adapter. For each message, the text is places in a sensor variable 'text' and a 'textAvailable' event is published. When scratch receives this event, it processes the data and answeres with a 'textAcknowledge' event.

The functionality is

7.1.1. Monitoring, Controlling

The adapter view receives updates from scratchClient. When broadcasts arrive, the connectors are highlighted. Values change are displayed. Most current events are listed on screen in a text list.

Broadcasts (input or output) can be stimulated by clicking to the connectors. Input broadcasts are sent to the adapter, output broadcasts are sent to scratch.

Values can be edited and send. Click on the connector, an input box will open and values are sent when enter key is pressed.

Input values are sent to the adapter, output values are sent to scratch. The web interface is build based on configuration.

The sample screen shot shows a servo adapter and two button adapters. 'servo_A' is a value sent from scratch to the adapter. Double click in this name opens an editor window for the value. 's0_pressed' is a broadcast sent from the button-adapter to scratch. Double clicking this name sends the broadcast to scratch.

The interface was verified to work with Midori, Firefox and Chrome.

The following installation procedures are for raspbian. Commands will vary for other platforms.

sudo apt-get update
sudo apt-get install python-pip python-dev
sudo pip install cherrypy routes mako ws4py RPIO spidev

tar xzvf scratchClient.tar.gz
			

cd ~/scratchClient
python src/scratchClient.py -h

sudo raspi-config
                    

sudo leafpad /etc/modprobe.d/raspi-blacklist.conf

#blacklist spi-bcm2708

lsmod | grep -e spi_bcm2708

					

sudo apt-get install python-smbus

sudo raspi-config
                    

sudo modprobe i2c-dev
                    

sudo leafpad /etc/modprobe.d/raspi-blacklist.conf

#blacklist i2c-bcm2708
					

lsmod | grep -e i2c
                    

i2c_dev                 6709  2
i2c_bcm2708             6200  0

                    

sudo apt-get install i2c-tools

sudo apt-get install festival

cd ~/scratchClient/RPIO2
sudo sh install.sh

In scratch, enable the 'remote network connection'. This is needed once for a project; this setting is persisted in the project file. Start with (user pi)

cd ~/scratchClient
sudo python src/scratchClient.py -config [config_file_name.xml]

For gpio access, SPI, I2C-adapters, it is usually required to run the program with root permissions. Some adapters run with 'normal' permissions, e.g. the text-to-speech adapter, websocket adapters or alike.

scratch needs to be started separately. Create a shell script if you need both programs scratchClient and scratch to be started with one command.

The code generates a 'scratchClient.pid'-File, which may remain in base directory. There for, start up in a dedicated home directory (~/scratchClient) is recommended.

	On one machine, the process may only be started once. If the process starts up, but quits after some 30 to 60 sec, then possibly another instance is running.

Use command line '-h' to see options.

cd ~/scratchClient
 python src/scratchClient.py -h

-host <ip>           Scratch Host ip or hostname, default 127.0.0.1
-port <number>       Port number, default 42001

-c <configfile>
-config <configfile> Name of config xml-file, default config.xml
                     There is a lookup strategy used (add xml extension when needed,
                     literal, then config/, ../config; then add 'config_' to
                     filename and then literal, config/, ../config

-C <configfile>      Name of config xml-file, default config.xml
                     There is NO lookup strategy used, only literal.

-gpioLib             set the gpiolibrary, default 'RPi_GPIO_GPIOManager'
                     deprecated, will be ignored.

web gui switches

-nogui               do not show GUI
-guiRemote           allows remote access to GUI web page,
                     default is local access only

debug and test switches

-forceActive         force active mode, even if GPIO library is
                     not available.
-validate            Validate config and terminate.

-h
-help                print command line usage and exit
-v                   verbose logging
-d                   debug logging
-license             print license and exit.
-changes             print changes list

Most of the commands are quite self-explaining. If you want to see more information on screen, use verbose switch. Debugging switch shows even more, but then logging uses a lot of CPU.

config:For config file lookup, there is a lookup policy available. The first file found wins the game:

add xml extension when not available.

add prefix 'config_' to filename if no path is given.

With this policy, file names can be abbreviated.

host: if scratch is located on a different computer, then give the target address here.

port: generally not needed to use a different port.

nogui: does not start the web app server inside scratchClient. Less memory usage.

guiRemote: allows remote access to web gui.

validate: check the config file for correctness.

Stop with ctrl-c in console. Takes up to a minute till all background threads quit.

If for any reason the code refuses to quit, get the processId and kill the process

sudo ps -ef | grep python
sudo kill -9 [processId]
				

Some common problems in running scratchClient are, that no sensor inputs are arriving in scratch. Check the following list for possible problems.

Scratch will read inputs from scratchClient faster than these are processed internally. The effect is that scratch is displaying old data. In this case, decrease update rates of polling sensors and work on performance of scratch code.

When auto start for scratch is needed, there are things to execute

Starting scratch and scratchClient can be in any order. Starting does not need to be manual, but can be from init.d or other

scratch presentation [scriptname]

scratch presentation [scriptname] -display :0

8.5.2.  Enable remote connection (without user interaction)

When a project uses remote connection, this is stored in the project file and enabled again when project is reloaded. Unfortunately, there is some user interaction needed to enable it.

In newer scratch releases for raspberry (e.g. 2015-11-11), there is a config file setting which bypasses this dialog.

remoteconnectiondialog = 0

Look for file home/pi/.scratch.ini and add this statement. If this file is not available, just create it.

	Files starting with '.' are hidden files in linux. With filemanager, enable 'show hidden files' in order to see this file.

ScratchClient and scratch usually run on same machine, but other scenario are possible.

8.6.1. Local setup

In general, scratchClient and scratch will run on same machine.

No special command line switches are needed to support this scenario.

Table 8.1. Firewall settings

Module	Port	computerA
NA	NA	NA

8.6.2. Distributed setup A

scratchClient and scratch can run on different machines. I use this scenario, when debugging scratch code on a more performant machine than a raspberry pi.

When starting scratchClient, use the '-host'-command line parameter and add the ip-address (or hostname) of the machine where scratch is located. Of course, these two machines need to be connected by a network.

Table 8.2. Firewall settings

Module	Port	computerA	computerB
scratch	42001	out	in

8.6.3. Distributed setup B

scratchClient and scratch can run on different machines. The browser used to look into the monitoring gui of scratchClient can be used from a third machine.

When starting scratchClient, use the '-host'-command line parameter and add the ip-address (or hostname) of the machine where scratch is located. Use '-guiRemote' to allow remote access for browser. Of course, these machines need to be connected by a network.

Table 8.3. Firewall settings

Module	Port	computerA	computerB	computerC
scratch	42001	out	in
browser	8080	in		out

When you need a new adapter, not provided in the list. Add a new file to Directory 'adapter' named myadapter.py (choose the name according to the functionality). Place a class there named MyAdapter (again, choose your functional name). Derive it from adapter.Adapter, and place __init__ and command methods, as well as the output methods. Produce the xml-configuration for this, and give it a try. Testing new Adapters: add your adapter config to an xml-file, start the code in simulation mode with gui. If configurationManager reads the config successfully, you will be able to place commands and values to the input side, and see what happens to the simulated gpio.

Then stop and restart in real live mode. This will attach the gpios and drive whatever is attached there.

Using other gpio-driver as Rpi.GPIO

There are people using Wiring, or other python libraries to access Gpio on the pi. Copy RPiGpio.py, which is a wrapper for the RPI-GPIO, and copy to a 'MyGPio.py'-File. In the new file, modify the imports and the method content to whatever is needed to run your library. On the command line, use -gpio [yourGpioPath], for this example it is „adapter.MyGpio“. Generally, as this is running as a standalone client, with most probably no other code in parallel, this will be rarely needed.

GPIO names used are configurable in config/portMapping.xml. This file maps the gpioNumbers from BCM numbering to other names, either GPIO-, PIN-numbers or whatever else needed. GPIO08 is GPIO numbering in BCM style.

    <port gpioNumber='8' name='GPIO08' />

IKG.IO.3 is used for a special adapter-board.

    <port gpioNumber='18' name='IKG.IO.3' />

Pin header names. The version-ambiguities are resolved by appending the version number to the port name

    <port gpioNumber='0' name='P1-03V1' />
    <port gpioNumber='2' name='P1-03V2' />

The mapped names can be used in config files.

The code is developed and tested in python 2.7.3.

Some checks have been performed with python3 and pypy. If there are problems in these environment, then please let me know.

External libraries are

SPI, I2C, TextToSpeech as needed.

Scratch is Version 1.4, as there the remote sensor protocol is available. As of now (juli 2013), I do not know about plans to have this sensor network in scratch 2.0.

GNU General Public License

Copyright (C) 2013, 2014 Gerhard Hepp

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA

AD-Interface for ADS1015.

AD-Interface for ADS1015.

Class

adapter.i2cAdapter.ADC_ADS1015_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.i2cAdapter.ADC_ADS1015_Input'  name='adc_A2'>
        <description>ADC-Value from ADS1015 (single ended)</description>
        <output_value name='adc'>
            <sensor name='adc_A2'/>
        </output_value>
        
        <parameter name='poll.interval' value='0.05' />
       
        <!-- bus is '1' for RPi Release 2 -->
        <parameter name='i2c.bus' value='1' />
        
        <!-- address is '0x48' for adafruit ADS1015 -->
        <parameter name='i2c.address' value='0x48' />
        
        <parameter name='adc.channel' value='2' />
    </adapter>
		

ADC interface MCP3008, 8 channel ADC

Interface to adc MCP3008, 10bit.

Class

adapter.adc_zone.ADC_MCP3008_10_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.adc.ADC_MCP3008_10_Input'  name='adc_A'>
        
        <description>ADC-Value</description>
        
        <output_value name='adc'>
            <sensor name='adcA'/>
        </output_value>
        
        <parameter name='poll.interval' value='0.066' />
        <parameter name='poll.band' value='2' />
        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        <!-- channel 0..7 -->
        <parameter name='adc.channel' value='7' />
    </adapter>

		

ADC interface MCP3202

Interface to adc MCP3202, 10bit.

Class

adapter.adc.ADC_MCP3202_10_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.adc.ADC_MCP3202_10_Input'  name='adc_A'>
        
        <description>ADC-Value</description>
        
        <output_value name='adc'>
            <sensor name='adcA'/>
        </output_value>
        
        <parameter name='poll.interval' value='0.066' />
        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        <parameter name='adc.channel' value='0' />
    </adapter>
		

ADC interface MCP3202, zone value mapping

Interface to adc MCP3202, 10bit. The input values are mapped to zones.

Zone values can be used for threshold values, e.g. 0..511 to 0, 512..1023 to 1023.

Zone values can be used for value mapping, e.g. 0..99 to 'left', 100..923 to 'middle', 924..1023 to 'right'.

Class

adapter.adc_zone.ADC_MCP3202_10_Zone_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.adc_zone.ADC_MCP3202_10_Zone_Input'  name='adc_A_Zone'>
        
        <description>ADC-Value</description>
        
        <output_value name='adc'>
            <sensor name='adcA_zone'/>
        </output_value>
        
        <zone from='0' to='99' value='left'/>
        <zone from='100' to='923' value='middle'/>
        <zone from='924' to='1023' value='right'/>
        
        
        <parameter name='poll.interval' value='0.066' />
        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        <parameter name='adc.channel' value='0' />
    </adapter>

		

ADC interface MCP3202

Interface to adc MCP3202, 12bit.

Supports averaging (filter).

Class

adapter.adc.ADC_MCP3202_12_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.adc.ADC_MCP3202_12_Input'  name='adc_A'>
        
        <description>ADC-Value</description>
        
        <output_value name='adc'>
            <sensor name='adcA'/>
        </output_value>
        
        <parameter name='filter.depth' value='8' />

        <parameter name='poll.interval' value='0.066' />
        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        <parameter name='adc.channel' value='0' />
    </adapter>
		

Drives a bipolar stepper motor.

Bipolar steppers need four half bridge drivers, e.g. LM293

Class

adapter.stepper.BipolarStepper

Input Events

Input Values

Sample configuration

   <adapter class='adapter.stepper.BipolarStepper' name='stepper'>
        
        <description>stepper control</description>
        
        <gpio port='GPIO25' alias='br0.0'>
            <default dir='OUT' pull='PUD_OFF'  />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>
        <gpio port='GPIO24' alias='br0.1'>
            <default dir='OUT' pull='PUD_OFF'  />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>
        
        <gpio port='GPIO23' alias='br1.0'>
            <default dir='OUT' pull='PUD_OFF'  />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>
        <gpio port='GPIO18' alias='br1.1'>
            <default dir='OUT' pull='PUD_OFF'  />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>

        <gpio port='GPIO22' alias='en0'>
            <default dir='OUT' pull='PUD_OFF'  />
            <active dir='OUT' pull='PUD_OFF' default='high' />
        </gpio>
        <gpio port='GPIO27' alias='en1'>
            <default dir='OUT' pull='PUD_OFF'  />
            <active dir='OUT' pull='PUD_OFF'  default='high' />
        </gpio>

        <input name='startMotor'>
            <broadcast name='startMotor'/>
        </input>
        
        <input name='stopMotor'>
            <broadcast name='stopMotor'/>
        </input>

        <input_value name='speed'>
            <variable name='speed'/>
        </input_value>
        
        <input_value name='target'>
            <variable name='target'/>
        </input_value>

    </adapter>
		

USB adapter for blink-device.

'blink(1)' is a small USB-device with two LED. See https://blink1.thingm.com/

The color commands do not use the device timed fade.

Needs installation of pyusb.

Class

adapter.usbAdapter.Blink_Adapter

Sample configuration

   <adapter class='adapter.usbAdapter.Blink_Adapter'  name='blink_1'>
        <description></description>

        <!--  led_0 is 'all led' -->
        <input_value name='led_0'>
            <variable name='led_all'/>
            <variable name='led_0'/>
        </input_value>

        <input_value name='led_1'>
            <variable name='led_1'/>
        </input_value>
        
        <input_value name='led_2'>
            <variable name='led_2'/>
        </input_value>
        
    </adapter>

Remote communication adapter.

Needs the scratchCommunicationServer to be started.

For the configuration, an adapter-specific syntax is used.

There is a limit on inputs, max 32 commands are supported.

Class

adapter.remote.CommunicationAdapter

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.remote.CommunicationAdapter' name='communication_adapter'>
        
        <!-- Adapter uses native Syntax -->
        <description>Remote communication adapter. </description>

        <!--  these commands are received from scratch and forwarded to a remote attached scratchClient -->
        <remote type='forward'>
        
            <broadcast name='command_B'/>  
        </remote>

        <!--  these commands are received from a remote attached scratchClient and sent to local scratch -->
        <remote type='receive'>
            <broadcast name='command_A'/>
        </remote>
        
        <parameter name="group" value="groupA"  />
        <parameter name="server" value="192.168.2.108" />

    </adapter>

DMA based PWM adapter.

Needs installation of RPIO2-package.

Supports 0..100% pwm signals.

Class

adapter.dma_pwm.DMA_PWM

Input Values

Parameter (mandatory)

Sample configuration

  <adapter class='adapter.dma_pwm.DMA_PWM'  name='rgb_B'>
        <description>Sample DMA PWM, needs installation of RPIO2-package.</description>

        <gpio port='IKG.IO.5'>
            <default dir='OUT'  default='high' />
            <active dir='RESERVED' />
        </gpio>

        <input_value name='rate'>
            <variable name='rgb_A_B'/>
        </input_value>

        <parameter name='frequency' value='50' />
        <parameter name='rate' value='50' />
    </adapter>

DMA based PWM adapter with two specific pwm values.

Needs installation of RPIO2-package.

Class

adapter.dma_pwm.DMA_PWM_ON_OFF

Input Events

Parameter (mandatory)

Sample configuration

DMA based PWM adapter with input range specific for servo.

Needs installation of RPIO2-package.

Supports 50Hz, 1 to 2ms pwm.

Class

adapter.dma_pwm.DMA_PWMServo

Input Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.dma_pwm.DMA_PWMServo'  name='servo_pwm'>
        <description>Sample DMA PWM, needs installation of RPIO2-package.</description>

        <gpio port='GPIO23'>
            <default dir='OUT'  default='high' />
            <active dir='RESERVED' />
        </gpio>

        <input_value name='rate'>
            <variable name='servo_A'/>
        </input_value>

        <parameter name='frequency' value='50' />
        <parameter name='rate' value='50' />
        <parameter name='value.inverse' value='true' />
        
    </adapter>

Interface to 'festival'

festival is a text to speech package. It allows to dynamically 'speak out' text.

Class

adapter.textToSpeech.Festival_Adapter

Input Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.textToSpeech.Festival_Adapter'  name='festival'>
        <description>text output</description>

        <input_value name='speech'>
            <variable name='speak'/>
        </input_value>
        
        <parameter name="queue.max" value="5"  />

    </adapter>
		

Interface for a 7-Segment LED

drives 7 GPIO pins for a 7 segment LED.

Class

adapter.adapters.Gpio7segment

Input Values

Sample configuration

   <adapter class='adapter.gpio.Gpio7segment'  name='s7'>
        <description>7 Segment driver</description>

        <gpio port='GPIO25' alias='a'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <gpio port='GPIO24' alias='b'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <gpio port='GPIO23' alias='c'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <gpio port='GPIO18' alias='d'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <gpio port='GPIO22' alias='e'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <gpio port='GPIO27' alias='f'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <gpio port='GPIO17' alias='g'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='high' />
        </gpio>
        
        <input_value name='value'>
            <variable name='siebensegment'/>
        </input_value>
        
        <input_value name='seg_a'>
            <variable name='seg_A'/>
        </input_value>
        <input_value name='seg_b'>
            <variable name='seg_B'/>
        </input_value>
        <input_value name='seg_c'>
            <variable name='seg_C'/>
        </input_value>
        <input_value name='seg_d'>
            <variable name='seg_D'/>
        </input_value>
        <input_value name='seg_e'>
            <variable name='seg_E'/>
        </input_value>
        <input_value name='seg_f'>
            <variable name='seg_F'/>
        </input_value>
        <input_value name='seg_g'>
            <variable name='seg_G'/>
        </input_value>
    </adapter>
    

Reads a GPIO pin

Deprecated, use GpioEventInput instead.

Reads a GPIO pin; sends events. Output can be inverted.

Class

adapter.gpio.GpioButtonInput

Output Event

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.gpio.GpioButtonInput' name='button_s0'>
        <!-- no description, urgg -->
        <gpio port='GPIO25'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'/>
        </gpio>
        
        <output name='button_pressed'>
            <broadcast name='s0_pressed'/>
        </output>
        <output name='button_released'>
            <broadcast name='s0_released'/>
        </output>
        
        <parameter name='poll.interval' value='0.05' />
        <parameter name='value.inverse' value='true' />

    </adapter>
    
		

Decodes a legacy rotary telephone dialplate.

the two switches 'nsi', 'nsa' are connected.

The decoding is time dependent.

Class

adapter.encoder.GPIODialPlateEncoder

Output Values

Sample configuration

   <adapter class='adapter.encoder.GPIODialPlateEncoder'  name='dial_A'>
        <description>Wählscheibe.
        Anschluss: NSI (Impuls) 
                   NSA (Drehschalter)
        </description>

        <gpio port='GPIO24' alias='nsi'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'   />
        </gpio>
        <gpio port='GPIO18' alias='nsa'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'   />
        </gpio>

        <output_value name='number'>
            <sensor name='numberA'/>
        </output_value>
        
    </adapter>
		

Decodes a rotary encoder.

initial value is 0; is incremented or decremented.

Class

adapter.encoder.GPIOEncoder

Output Values

Sample configuration

   <adapter class='adapter.encoder.GPIOEncoder'  name='encoder_A'>
        <description>Drehencoder</description>

        <gpio port='GPIO22' alias='p0'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'   />
        </gpio>
        <gpio port='GPIO27' alias='p1'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'   />
        </gpio>

        <output_value name='position'>
            <sensor name='positionA'/>
        </output_value>

        <parameter name='poll.interval' value='0.005' />

    </adapter>

		

Reads a GPIO pin

Reads a GPIO pin; sends events. Output can be inverted.

Class

adapter.gpio.GpioEventInput

Output Event

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.gpio.GpioButtonInput' name='button_s0'>
        <!-- no description, urgg -->
        <gpio port='GPIO25'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'/>
        </gpio>
        
        <output name='button_pressed'>
            <broadcast name='s0_pressed'/>
        </output>
        <output name='button_released'>
            <broadcast name='s0_released'/>
        </output>
        
        <parameter name='poll.interval' value='0.05' />
        <parameter name='value.inverse' value='true' />

    </adapter>
    
        

Read a GPIO pin

Read a GPIO pin; sends values '0' and '1'. Output can be inverted.

Class

adapter.gpio.GpioInput

Output Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.gpio.GpioInput' name='schalter_s1'>
        
        <gpio port='GPIO24'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'/>
        </gpio>
        <output_value name='button'>
            <sensor name='s1'/>
        </output_value>
        
        <parameter name='poll.interval' value='0.05' />
        <parameter name='value.inverse' value='true' />
    </adapter>

    
		

Output to a GPIO pin

writes to a GPIO pin.

Class

adapter.gpio.GpioOutput

Input Events

Sample configuration

    <adapter class='adapter.gpio.GpioOutput'  name='led0'>
        <description>LED0</description>

        <gpio port='GPIO25'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <input name='low'>
            <broadcast name='led0_OFF'/>
        </input>
        <input name='high'>
            <broadcast name='led0_ON'/>
        </input>
    </adapter>
    

Output to a GPIO pin

outputs a pwm signal to a pin.

Input 'rate' : float, 0.0 to 100.0

Configuration 'frequency': float, [Hz]

Uses soft-pwm with RPI.GPIO.

Class

adapter.gpio.GpioOutputPWM

Input Values

Parameter (mandatory)

Sample configuration

       <adapter class='adapter.gpio.GpioOutputPWM'  name='pwm_25'>
        <description>Sample GPIO PWM</description>
        <gpio port='GPIO25'>
            <default dir='OUT'  default='low' />
            <active dir='RESERVED' />
        </gpio>
        <input_value name='rate'>
            <variable name='rate_25'/>
        </input_value>
        <parameter name='frequency' value='30' />
        <parameter name='rate' value='15' />
    </adapter>
    
		

dim an output pin or set it off.

outputs a pwm signal to a pin (rate when high; 0 when low).

Fixed level only.

Class

adapter.gpio.GpioOutputPWM_ON_OFF

Input Events

Parameter (mandatory)

Sample configuration

        <adapter class='adapter.gpio.GpioOutputPWM_ON_OFF'  name='led0'>
        <description>LED0</description>

        <gpio port='GPIO.25'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
        <input name='low'>
            <broadcast name='led0_OFF'/>
        </input>
        <input name='high'>
            <broadcast name='led0_ON'/>
        </input>
    </adapter>

    
		

Output to a GPIO pin

outputs a pwm signal to a pin.

Input 'rate' : float, 0.0 to 100.0

Configuration 'frequency': float, [Hz]

Uses soft-pwm with RPI.GPIO; may produce jitter on signals.

Class

adapter.gpio.GpioOutputPWMServo

Input Values

Parameter (mandatory)

Sample configuration

<adapter class='adapter.gpio.GpioOutputPWMServo'  name='servo_pwm'>
        <description>Sample GPIO PWM</description>

        <gpio port='GPIO23'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='RESERVED' />
        </gpio>

        <input_value name='rate'>
            <variable name='servo_A'/>
        </input_value>

        <parameter name='frequency' value='50' />
        <parameter name='rate' value='50' />
    </adapter>

    
		

scratch connection status

displays scratch connection status to a GPIO pin.

scratchclient not started: undefined

scratchclient started: low

no connection: high

connection: blink

Class

adapter.gpio.GpioStateOutput

Sample configuration

    <adapter class='adapter.gpio.GpioStateOutput'  name='state'>
        <description>State display on GPIO04</description>

        <gpio port='GPIO04' alias='state'>
            <default dir='OUT'  default='low' />
            <active  dir='OUT'  default='low' />
        </gpio>
    </adapter>
    

Read a GPIO pin; sends configurable values. Output can be inverted.

Input is polled by 'poll.interval'. When a value change is detected, a value is aquired. The value gets inverted if 'value.inverse'==true. Then the configured definitions for 0 or 1 are applied from 'value.0' or 'value.1'

Class

adapter.gpio.GpioValueInput

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.gpio.GpioValueInput' name='valueGPIO'>
       
        <gpio port='GPIO25'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'/>
        </gpio>
        
        <output_value name='value'>
            <sensor name='namedGPIO_A'/>
        </output_value>
        
        
        <parameter name='poll.interval' value='0.08' />
        <parameter name='value.inverse' value='false' />
        
        <parameter name='value.0' value='switched_OFF' />
        <parameter name='value.1' value='switched_ON' />

    </adapter>
		

Read an USB HID device.

Provides scan results from a barcode scanner.

Class

adapter.usbAdapter.HIDScanner_Adapter

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.usbAdapter.HIDScanner_Adapter' name='barcode scanner'>
        
        <description>Provides scan results from a barcode scanner.</description>

        <output_value name='scan'>
            <sensor name='barcode'/>
        </output_value>

        <parameter name="usb.idVendor"  value="0x0c2e"  />
        <parameter name="usb.idProduct" value="0x0200"  />

    </adapter>
		

IR Distance sensor

Interface to Sharp GP2Y0A21YK IR Distance sensor on adc MCP3202, 10bit.

Calculates linearization; averaging the last 5 values.

Class

adapter.adc.IRDistanceInput

Output Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.adc.IRDistanceInput'  name='irDistanceA'>
        <description>IR-Distance Sensor</description>

        <output_value name='distance'>
            <sensor name='distanceA'/>
        </output_value>

        <parameter name='poll.interval' value='0.066' />
        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        <parameter name='adc.channel' value='0' />
        <parameter name='filter.use' value='true' />
        <parameter name='filter.depth' value='5' />

    </adapter>
		

Interface to linux operation command line

Allows the usage of linux shell scripts.

Class

adapter.linux.Linux_Adapter

Input Events

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.linux.Linux_Adapter'  name='sampleB'>
        <description>linux os command execution</description>

        <input name='trigger'>
            <broadcast name='scrot'/>
        </input>
        
        <parameter name="os.command" value="scrot"  />
        <parameter name="queue.max" value="5"  />
    </adapter>
		

Play wav files with aplay.

Linux only.

Class

adapter.linux.Linux_APLAY_Adapter

Input Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.linux.Linux_APLAY_Adapter' name='sampleA'>
        <description>linux aplay execution</description>

        <input_value name='sound'>
             <variable name='wave'/>
        </input_value>
        
        <parameter name="aplay.device" value="sysdefault:CARD=Device"  />
        <parameter name='sound.dir' value='/opt/sonic-pi/etc/samples' /> 
        <parameter name="queue.max" value="5"  />
    </adapter>

record wav files with arecord.

Linux only.

Class

adapter.linux.Linux_ARECORD_Adapter

Input Events

Input Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.linux.Linux_ARECORD_Adapter' name='sampleA'>
        <description>linux arecord execution</description>

        <input_value name='sound'>
             <variable name='wave'/>
        </input_value>
        
        <input name='start_record'>
         <broadcast name='start'/>
        </input>
        
       <input name='stop_record'>
         <broadcast name='stop'/>
        </input>
        
        
        <parameter name="aplay.device" value="sysdefault:CARD=Device"  />
        <parameter name="aplay.rate"   value="16000"  />
        <parameter name='sound.dir' value='/home/pi/temp' /> 
        <parameter name='timeout' value='60' /> 
    </adapter>

Interface for a specch recognition process.

Linux only. Needs installation of a speech recognition system,e.g. pocketsphinx. This system is writing text to stdout.

The design is to use pocketsphinx in batch mode.

Class

adapter.linux.Linux_ASR_Adapter

Input Events

Output Event

Output Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.linux.Linux_ASR_Adapter' name='sampleA'>
        <description>linux speech recoginition with pocketsphinx</description>

        <input name='execute'>
            <broadcast name='execute' />
        </input>

        <output name='complete'>
            <broadcast name='finished' />
        </output>

        <input name='textAcknowledge'>
            <broadcast name='ack' />
        </input>

        <output name='textAvailable'>
            <broadcast name='listen' />
        </output>

        <output_value name='text'>
            <sensor name='text' />
        </output_value>

        <output_value name='status'>
            <sensor name='status' />
        </output_value>

        <!-- ${sound.dir} is filled from 'sound.dir'; ${sound.file} is filled from 'sound.file' -->
        <parameter 
           name='command.line'
           value='pocketsphinx_continuous -hmm /usr/local/share/pocketsphinx/model/en-us/en-us -lm 0609.lm -dict 0609.dic -samprate 16000/8000/48000 -logfn /dev/null -infile ${sound.dir}/${sound.file}' />

        <parameter name='sound.dir' value='/home/pi' />
        <parameter name='sound.file' value='sample.wav' />
        <!--
            Text received is internally queued. When queue data are getting too old, these are discarded.
            Timeout is configured here in sec.
            The timeout is used for scenario, where the acknowledge protocol is not yet implemented and
            data are accumulated in internal queue.  
        -->
        <parameter name='timeout' value='60' />
    </adapter>

Interface for Luminosity sensor BH1750

Interface for Luminosity sensor BH1750

Values are in lx (lux)

Class

adapter.i2cAdapter.Luminosity_BH1750_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.i2cAdapter.Luminosity_BH1750_Input'  name='luminosity'>
        <description>Luminosity-Value from BH1750</description>
        
        <output_value name='luminosity'>
            <sensor name='luminosity'/>
        </output_value>
        
        <parameter name='poll.interval' value='0.5' />
       
        <!-- bus is '1' for RPi Release 2 -->
        <parameter name='i2c.bus' value='1' />
        
        <!-- Depending on address select, the bus address is 
             '0x23' for BH1750 
             '0x5c' for BH1750 
             -->
        <parameter name='i2c.address' value='0x23' />
    </adapter>
		

Thermoelement processor MAX31855

Class

adapter.spiAdapter.MAX31855_Adapter

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.spiAdapter.MAX31855_Adapter'  name='thermoelement'>
        
        <description>Temperatures
        SPI-connected.
        </description>
        
        <output_value name='temp_wire'>
            <sensor name='temp_ext'/>
        </output_value>
        
        <output_value name='temp_intern'>
            <sensor name='temp_int'/>
        </output_value>

        <output_value name='temp_error'>
            <sensor name='temp_error'/>
        </output_value>

        <!-- polling time for external device -->
        <parameter name='poll.interval' value='0.5' />

        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
    </adapter>
		

MCP23S17 Port Expander

Controls MCP23S17 Port expander, as used on piFace-Board.

input_value methods in python are dynamically generated like inputGPA4 for io@dir=out

output_value methods in python are dynamically generated like outputGPB2 for io@dir=in

see the config/config_mcp23s17.xml example for namespace usage in xml.

Class

adapter.mcp23s17.MCP23S17_Adapter

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.mcp23s17.MCP23S17_Adapter' name='MCP23S17'>
      
        <!-- this is the setup for piface -->
        <!-- input_value methods in python are dynamically generated like inputGPA4 for io@dir=out -->

        <input_value name='inputGPA0'>
            <variable name='out_0' />
            <variable name='relais_0' />
            <variable name='all' />
        </input_value>

        <input_value name='inputGPA1'>
            <variable name='out_1' />
            <variable name='relais_1' />
            <variable name='all' />
        </input_value>
        
        <input_value name='inputGPA2'>
            <variable name='out_2' />
            <variable name='all' />
        </input_value>

        <input_value name='inputGPA3'>
            <variable name='out_3' />
            <variable name='all' />
        </input_value>

        <input_value name='inputGPA4'>
            <variable name='out_4' />
            <variable name='all' />
        </input_value>

        <input_value name='inputGPA5'>
            <variable name='out_5' />
            <variable name='all' />
        </input_value>

        <input_value name='inputGPA6'>
            <variable name='out_6' />
            <variable name='all' />
        </input_value>

        <input_value name='inputGPA7'>
            <variable name='out_7' />
            <variable name='all' />
        </input_value>

        <!-- output_value methods in python are dynamically generated like outputGPB2 for io@dir=in -->

        <output_value name='outputGPB0'>
            <sensor name='in_0' />
        </output_value>

        <output_value name='outputGPB1'>
            <sensor name='in_1' />
        </output_value>

        <output_value name='outputGPB2'>
            <sensor name='in_2' />
        </output_value>

        <output_value name='outputGPB3'>
            <sensor name='in_3' />
        </output_value>

        <output_value name='outputGPB4'>
            <sensor name='in_4' />
        </output_value>

        <output_value name='outputGPB5'>
            <sensor name='in_5' />
        </output_value>

        <output_value name='outputGPB6'>
            <sensor name='in_6' />
        </output_value>

        <output_value name='outputGPB7'>
            <sensor name='in_7' />
        </output_value>

        <parameter name='poll.interval' value='0.05' />

        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
        <!-- slave address must match the hard wired slave address on the device -->
        <parameter name='23s17.addr' value='0' />

        <!-- this is the setup for piface -->
        
        <io id='GPA0' dir='out' />
        <io id='GPA1' dir='out' />
        <io id='GPA2' dir='out' />
        <io id='GPA3' dir='out' />

        <io id='GPA4' dir='out' />
        <io id='GPA5' dir='out' />
        <io id='GPA6' dir='out' />
        <io id='GPA7' dir='out' />

        <io id='GPB0' dir='in' pullup='weak' />
        <io id='GPB1' dir='in' pullup='weak' />
        <io id='GPB2' dir='in' pullup='weak' />
        <io id='GPB3' dir='in' pullup='weak' />

        <io id='GPB4' dir='in' pullup='weak' />
        <io id='GPB5' dir='in' pullup='weak' />
        <io id='GPB6' dir='in' pullup='weak' />
        <io id='GPB7' dir='in' pullup='weak' />

    </adapter>
		

PianoHat Adapter.

Installation procedures for pianohat required.

Supports button presses and releases.

Class

adapter.Cap1188Adapter.PianoHat_CAP1188_Adapter

Output Event

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.Cap1188Adapter.PianoHat_CAP1188_Adapter' name='piano_adapter'>
        
        <description>pimoroni piano hat</description>

        <output name='broadcast_00_on'><broadcast name='button_00'/></output>
        <output name='broadcast_01_on'><broadcast name='button_01'/></output>
        <output name='broadcast_02_on'><broadcast name='button_02'/></output>
        <output name='broadcast_03_on'><broadcast name='button_03'/></output>
        <output name='broadcast_04_on'><broadcast name='button_04'/></output>
        <output name='broadcast_05_on'><broadcast name='button_05'/></output>
        <output name='broadcast_06_on'><broadcast name='button_06'/></output>
        <output name='broadcast_07_on'><broadcast name='button_07'/></output>
        <output name='broadcast_08_on'><broadcast name='button_08'/></output>
        <output name='broadcast_09_on'><broadcast name='button_09'/></output>
        <output name='broadcast_10_on'><broadcast name='button_10'/></output>
        <output name='broadcast_11_on'><broadcast name='button_11'/></output>
        <output name='broadcast_12_on'><broadcast name='button_12'/></output>
        <output name='broadcast_13_on'><broadcast name='button_13'/></output>
        <output name='broadcast_14_on'><broadcast name='button_14'/></output>
        <output name='broadcast_15_on'><broadcast name='button_15'/></output>

        <output name='broadcast_00_off'><broadcast name='button_00_off'/></output>
        <output name='broadcast_01_off'><broadcast name='button_01_off'/></output>
        <output name='broadcast_02_off'><broadcast name='button_02_off'/></output>
        <output name='broadcast_03_off'><broadcast name='button_03_off'/></output>
        <output name='broadcast_04_off'><broadcast name='button_04_off'/></output>
        <output name='broadcast_05_off'><broadcast name='button_05_off'/></output>
        <output name='broadcast_06_off'><broadcast name='button_06_off'/></output>
        <output name='broadcast_07_off'><broadcast name='button_07_off'/></output>
        <output name='broadcast_08_off'><broadcast name='button_08_off'/></output>
        <output name='broadcast_09_off'><broadcast name='button_09_off'/></output>
        <output name='broadcast_10_off'><broadcast name='button_10_off'/></output>
        <output name='broadcast_11_off'><broadcast name='button_11_off'/></output>
        <output name='broadcast_12_off'><broadcast name='button_12_off'/></output>
        <output name='broadcast_13_off'><broadcast name='button_13_off'/></output>
        <output name='broadcast_14_off'><broadcast name='button_14_off'/></output>
        <output name='broadcast_15_off'><broadcast name='button_15_off'/></output>

        <parameter name="auto_leds" value="true"  />

    </adapter>

Interface to PicoBoard by USB-connection

PicoBoard is an USB-connected interface board, serial style. It provides a slider, button, sound sensor, light sensor and resistor-measuring inputs.

This board is fairly well supported by scratch directly. Use this adapter, if you need two of them, or need to have a look to raw values.

Class

adapter.serialAdapter.PicoBoard_Adapter

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.serialAdapter.PicoBoard_Adapter'  name='picoboard'>
        <description>Send receive text messages</description>
        
        <output_value name='slider'>
            <sensor name='slider'/>
        </output_value>
        
        <output_value name='light'>
            <sensor name='light'/>
        </output_value>
        
        <output_value name='sound'>
            <sensor name='sound'/>
        </output_value>
        
        <output_value name='button'>
            <sensor name='button'/>
        </output_value>
        
        <output_value name='sensorA'>
            <sensor name='resistance-A'/>
        </output_value>
        
        <output_value name='sensorB'>
            <sensor name='resistance-B'/>
        </output_value>
        
        <output_value name='sensorC'>
            <sensor name='resistance-C'/>
        </output_value>
        
        <output_value name='sensorD'>
            <sensor name='resistance-D'/>
        </output_value>
        
        <parameter name='serial.device' value='/dev/ttyUSB0' />
        <parameter name='serial.baud' value='38400' />

        <parameter name='picoBoard.raw' value='false' />
       
    </adapter>
		

Interface for air pressure sensor BMP085

Environmental sensor air pressure and temperature

Class

adapter.i2cAdapter.Pressure_BMP085_Input

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.i2cAdapter.Pressure_BMP085_Input'  name='pressure'>
        <description>Pressure-Value from BMP085
        Connected to I2C-Bus.
        </description>
        
        <output_value name='pressure'>
            <sensor name='pressure'/>
        </output_value>

        <output_value name='temperature'>
            <sensor name='temperature'/>
        </output_value>
        
        <parameter name='poll.interval' value='2.5' />
       
        <!-- bus is '1' for RPi Release 2 -->
        <parameter name='i2c.bus' value='1' />
        
        <!-- Depending on address select, the bus address is '0x77' for BMP085 -->
        <parameter name='i2c.address' value='0x77' />
    </adapter>
		

Interface for Luminosity sensor BH1750

16-channel, 12-bit PWM Fm+ I2C-bus LED controller

Class

adapter.i2cAdapter.PWM_PCA9685

Input Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.i2cAdapter.PWM_PCA9685' name='16-channel PWM'>
        <description>DEMO for the PCA adapter.</description>


        <!-- the scratch variable names are simply the method names here. Could be more useful... -->
        <input_value name='channel_0'>
            <variable name='channel_0' />
        </input_value>
        
        <input_value name='channel_1'>
            <variable name='channel_1' />
        </input_value>
        
        <input_value name='channel_2'>
            <variable name='channel_2' />
        </input_value>
        
        <input_value name='channel_3'>
            <variable name='channel_3' />
        </input_value>
        
        <input_value name='channel_4'>
            <variable name='channel_4' />
        </input_value>
        
        <input_value name='channel_5'>
            <variable name='channel_5' />
        </input_value>
        
        <input_value name='channel_6'>
            <variable name='channel_6' />
        </input_value>
        
        <input_value name='channel_7'>
            <variable name='channel_7' />
        </input_value>
        
        <input_value name='channel_8'>
            <variable name='channel_8' />
        </input_value>
        
        <input_value name='channel_9'>
            <variable name='channel_9' />
        </input_value>
        
        <input_value name='channel_10'>
            <variable name='channel_10' />
        </input_value>
        
 
        <input_value name='servo_0'>
            <variable name='servo_0' />
        </input_value>
        
        <input_value name='servo_1'>
            <variable name='servo_1' />
        </input_value>
        
        <input_value name='servo_2'>
            <variable name='servo_2' />
        </input_value>
        
        <input_value name='servo_3'>
            <variable name='servo_3' />
        </input_value>
        
        <input_value name='servo_4'>
            <variable name='servo_4' />
        </input_value>
        
        <input_value name='servo_5'>
            <variable name='servo_5' />
        </input_value>
        
        <input_value name='servo_6'>
            <variable name='servo_6' />
        </input_value>
        
        <input_value name='servo_7'>
            <variable name='servo_7' />
        </input_value>
        
        <input_value name='servo_8'>
            <variable name='servo_8' />
        </input_value>
        
        <input_value name='servo_9'>
            <variable name='servo_9' />
        </input_value>
        
        <input_value name='servo_10'>
            <variable name='servo_10' />
        </input_value>
        
 
        <!-- frequency 50Hz is used for servo  -->
        <!-- frequency in range 1526 Hz to 24 Hz  -->
        
        <parameter name='frequency' value='50' />
        
        <!-- bus is '1' for RPi Release 2 -->
        <parameter name='i2c.bus' value='1' />
        
        <!-- Depending on address select, the bus address is 
             '0x40' for all address lines low. 
             -->
        <parameter name='i2c.address' value='0x40' />
        
    </adapter>
		

18 channel, 8-bit PWM I2C-bus LED controller

18 channel, 8-bit PWM I2C-bus LED controller PIGLOW board from pimoroni

Class

adapter.i2cAdapter.PWM_SN3218

Input Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.i2cAdapter.PWM_SN3218' name='18-channel PWM'>
        <description>DEMO for the SN3218 adapter. This is the device used by the piglow-board</description>


        <input_value name='channel_00'>
            <variable name='channel_00' />
            <variable name='all' />
            <variable name='branch_0' />
        </input_value>

        <input_value name='channel_01'>
            <variable name='channel_01' />
            <variable name='all' />
            <variable name='branch_0' />
        </input_value>

        <input_value name='channel_02'>
            <variable name='channel_02' />
            <variable name='all' />
            <variable name='branch_0' />
        </input_value>

        <input_value name='channel_03'>
            <variable name='channel_03' />
            <variable name='all' />
            <variable name='branch_0' />
        </input_value>

        <input_value name='channel_04'>
            <variable name='channel_04' />
            <variable name='all' />
            <variable name='branch_1' />
        </input_value>

        <input_value name='channel_05'>
            <variable name='channel_05' />
            <variable name='all' />
            <variable name='branch_1' />
        </input_value>

        <input_value name='channel_06'>
            <variable name='channel_06' />
            <variable name='all' />
            <variable name='branch_1' />
        </input_value>

        <input_value name='channel_07'>
            <variable name='channel_07' />
            <variable name='all' />
            <variable name='branch_1' />
        </input_value>

        <input_value name='channel_08'>
            <variable name='channel_08' />
            <variable name='all' />
            <variable name='branch_1' />
        </input_value>

        <input_value name='channel_09'>
            <variable name='channel_09' />
            <variable name='all' />
            <variable name='branch_1' />
        </input_value>

        <input_value name='channel_0A'>
            <variable name='channel_0A' />
            <variable name='all' />
            <variable name='branch_2' />
        </input_value>

        <input_value name='channel_0B'>
            <variable name='channel_0B' />
            <variable name='all' />
            <variable name='branch_2' />
        </input_value>

        <input_value name='channel_0C'>
            <variable name='channel_0C' />
            <variable name='all' />
            <variable name='branch_0' />
        </input_value>

        <input_value name='channel_0D'>
            <variable name='channel_0D' />
            <variable name='all' />
            <variable name='branch_2' />
        </input_value>

        <input_value name='channel_0E'>
            <variable name='channel_0E' />
            <variable name='all' />
            <variable name='branch_0' />
        </input_value>

        <input_value name='channel_0F'>
            <variable name='channel_0F' />
            <variable name='all' />
            <variable name='branch_2' />
        </input_value>

        <input_value name='channel_10'>
            <variable name='channel_10' />
            <variable name='all' />
            <variable name='branch_2' />
        </input_value>

        <input_value name='channel_11'>
            <variable name='channel_11' />
            <variable name='all' />
            <variable name='branch_2' />
        </input_value>

        <!-- bus is '1' for RPi Release 2 -->
        <parameter name='i2c.bus' value='1' />

        <!-- address is fixed for this device -->
        <parameter name='i2c.address' value='0x54' />

    </adapter>
		

Interface to Innovation ID-2LA, ID-12LA, ID-20LA, by Raspberry serial-connection

Set protocol to ASCII !

Power the device by 3.3V, and use Rx-Input of RaspberryPi

After data have been send, an event is send by the adapter.

Class

adapter.serialAdapter.RFID_Reader_Adapter

Output Event

Output Values

Parameter (mandatory)

Sample configuration

        <adapter class='adapter.serialAdapter.RFID_Reader_Adapter'  name='rfidReader'>
        <description>Read a tag from INNOVATIONS ID-12LA or alike</description>
        
        <output_value name='data'>
            <sensor name='rfid'/>
        </output_value>
        <output name='data_event'>
            <broadcast name='rfid_available'/>
        </output>
         
        <parameter name='serial.device' value='/dev/ttyAMA0' />
        <parameter name='serial.baud' value='9600' />

    </adapter>

Send start broadcast event at connection start.

Send start broadcast event at connection start

Can be configured to send arbitrary events on connection start.

Class

adapter.broadcast.ScratchStartclickedAdapter

Sample configuration

    <adapter class='adapter.broadcast.ScratchStartclickedAdapter'  name='startClick'>
        <output name='command'>
            <broadcast name='scratch-startclicked'/>
        </output>
        <description>Send startclicked</description>
    </adapter>

		

Sense-Hat Adapter.

Installation procedures for senseHat required.

Supports LED, sensors and orientation.

setPixel_xy: depends on setting x_pos, y_pos and color values.

clearPixel_xy: depends on setting x_pos, y_pos.

Class

adapter.senseHat_adapter.SenseHat_Adapter

Input Events

Input Values

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.senseHat_adapter.SenseHat_Adapter' name='astro-pi'>
        
        <!-- -->
        
        <description>SenseHat. LED environmental sensors, orientation</description>

        <input name= 'clear'>
            <broadcast name='sense_led_clear'/>
        </input>
        
        <input name= 'setPixel_xy'>
            <broadcast name='sense_led_xy_on'/>
        </input>
        
        <input name= 'clearPixel_xy'>
            <broadcast name='sense_led_xy_off'/>
            <!--  there is a flaw in the sample scratch code which
                  has partial misspelling of one event, so add this wrong name too -->
            <broadcast name='semse_led_xy_off'/>
        </input>
 
        <!--  variables for setting pixels -->
        
        <input_value name='pixelX'>
            <variable name='x_pos'/>
        </input_value>
        
        <input_value name='pixelY'>
            <variable name='y_pos'/>
        </input_value>
        
         <input_value name='color'>
            <variable name='color'/>
        </input_value>
 
        <!--  environmental sensors from adapter to scratch -->
        
        <output_value name='temperature'>
            <sensor name='temperature'/>
        </output_value>
        
        <output_value name='pressure'>
            <sensor name='pressure'/>
        </output_value>
        
         <output_value name='humidity'>
            <sensor name='humidity' />
        </output_value>
        
        <!--  IMU sensors from adapter to scratch -->
        
         <output_value name='orientation_pitch'>
            <sensor name='orientation_pitch' />
          </output_value>
        
         <output_value name='orientation_roll'>
            <sensor name='orientation_roll' />
        </output_value>
        
         <output_value name='orientation_yaw'>
            <sensor name='orientation_yaw' />
        </output_value>
        
        
        <!-- polling time for external device -->
        <parameter name='poll.interval' value='0.1' />
        
        
    </adapter>

ServoBlaster driver

Servoblaster runs as daemon servod in the background and needs to be started manually.

See servoblaster doku for assignment of channel index numbers to GPIO pins.

Class

adapter.servoblaster.ServoBlaster

Input Values

Sample configuration

   <adapter class='adapter.servoblaster.ServoBlaster'  name='servoblaster'>
        <description>servoblaster for 8 channels. See servoblaster doku for 
        assignment of channel index numbers to GPIO pins.</description>

        
        <!--  looks strange, but could do some renaming for scratch variables here  -->
        <input_value name= 'servo_0'>
            <variable name='servo_0'/>
        </input_value>
        <input_value name= 'servo_1'>
            <variable name='servo_1'/>
        </input_value>
        <input_value name= 'servo_2'>
            <variable name='servo_2'/>
        </input_value>
        <input_value name= 'servo_3'>
            <variable name='servo_3'/>
        </input_value>
        <input_value name= 'servo_4'>
            <variable name='servo_4'/>
        </input_value>
        <input_value name= 'servo_5'>
            <variable name='servo_5'/>
        </input_value>
        <input_value name= 'servo_6'>
            <variable name='servo_6'/>
        </input_value>
        <input_value name= 'servo_7'>
            <variable name='servo_7'/>
        </input_value>
    </adapter>
		

Send current system time values (second, minute, hour, day, month, year) to scratch.

System time is not available in scratch 1.4. The adapter provides current system time.

Class

adapter.broadcast.TimeAdapter

Sample configuration

   <adapter class='adapter.broadcast.TimeAdapter' name='currentSystemTime'>
        
        <description>System time for Scratch 1.4</description>
        
        <output_value name='second'>
            <sensor name='time.second'/>
        </output_value>
        
        <output_value name='minute'>
            <sensor name='time.minute'/>
        </output_value>
        
        <output_value name='hour'>
            <sensor name='time.hour'/>
        </output_value>
        
        <output_value name='day'>
            <sensor name='time.day'/>
        </output_value>
        
        <output_value name='month'>
            <sensor name='time.month'/>
        </output_value>
        
        <output_value name='year'>
            <sensor name='time.year'/>
        </output_value>

        <parameter name='poll.interval' value='0.2' />

    </adapter>
		

Reading twitter messages by 'term' or 'hashname'.

Read twitter messages by hashtag name 'term'. Needs credentials from twitter to work.

Needs installation of 'python-twitter'.

Class

adapter.twitterAdapter.Twitter_Adapter

Input Events

Output Event

Output Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.twitterAdapter.Twitter_Adapter' name='twitter'>
        <description>text output from twitter messages</description>

        <input name='textAcknowledge'>
            <broadcast name='ack' />
        </input>

        <output name='textAvailable'>
            <broadcast name='listen' />
        </output>

        <output_value name='text'>
            <sensor name='text' />
        </output_value>

        <output_value name='status'>
            <sensor name='status' />
        </output_value>

        <parameter name='twitter.consumer_key' value='' />
        <parameter name='twitter.consumer_secret' value='' />
        <parameter name='twitter.access_token_key' value='' />
        <parameter name='twitter.access_token_secret' value='' />

        <parameter name='twitter.term' value = '#raspberrytweet' />
        <parameter name='twitter.datafile' value= 'data/twitter_data.json' />
        
        <!--  twitter account has limits on polling rate 
              15 requests per 15 minutes are allowed. See twitter.com for details. 
              if you see messages 'Rate limit exceeded', then increase this parameter -->
        <parameter name='twitter.pollrate' value= '60' />
        
        <parameter name='twitter.read.direct' value= 'true' />
        <parameter name='twitter.read.term' value= 'true' />
        
        <!-- scratch will ignore those messages received earlier than 'scratch.timeout' -->
        <parameter name='scratch.timeout' value= '60' />

    </adapter>

Drives an unipolar stepper motor.

The adapter does all the low level step pattern management and receives target position and speed values from scratch. This achieves faster steps than controlling single step events from scratch.

When a position is reached, a 'stopped' signal is issued.

Class

adapter.stepper.UnipolarStepperModule

Input Events

Input Values

Output Event

Sample configuration

   <adapter class='adapter.stepper.UnipolarStepperModule' name='stepper'>

        <description>stepper control for unipolar stepper
        </description>

        <gpio port='GPIO25' alias='br0.0'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' />
        </gpio>
        <gpio port='GPIO24' alias='br0.1'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' />
        </gpio>

        <gpio port='GPIO23' alias='br1.0'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' />
        </gpio>
        <gpio port='GPIO18' alias='br1.1'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF' />
        </gpio>
        
        <input name='reset_8'>
            <broadcast name='reset_8' />
        </input>

        <input name='reset_4'>
            <broadcast name='reset_4' />
        </input>
        <input_value name='speed'>
            <variable name='speed' />
        </input_value>

        <input_value name='target'>
            <variable name='target' />
        </input_value>
        
        <!-- signal added 2016-05-08 -->
        <output name='complete'>
            <broadcast name='position_reached'/>
        </output>
        
    </adapter>
		

Drives an unipolar stepper motor.

Driver for an unipolar stepper, where drive patterns are controlled by scratch. This is quite slow, but allows for teaching the basics.

Class

adapter.stepper.UnipolarStepperStep

Input Values

Sample configuration

   <adapter class='adapter.stepper.UnipolarStepperStep' name='stepper'>
        
        <description>stepper control for unipolar stepper
        Allows for discrete switch signals br0.0, br0.1, br1.0, br1.1
        or binary inputs 'pattern', e.g b0001, b0011, ...
        </description>
        
        <gpio port='GPIO25' alias='br0.0'>
            <default dir='OUT' pull='PUD_OFF' default='low'  />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>
        <gpio port='GPIO24' alias='br0.1'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>
        
        <gpio port='GPIO23' alias='br1.0'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>
        <gpio port='GPIO18' alias='br1.1'>
            <default dir='OUT' pull='PUD_OFF' default='low' />
            <active dir='OUT' pull='PUD_OFF'/>
        </gpio>

        <input_value name='br0_0'>
            <variable name='br0.0'/>
        </input_value>
        <input_value name='br0_1'>
            <variable name='br0.1'/>
        </input_value>
        <input_value name='br1_0'>
            <variable name='br1.0'/>
        </input_value>
        <input_value name='br1_1'>
            <variable name='br1.1'/>
        </input_value>
        
        <input_value name='binaryPattern'>
            <variable name='pattern'/>
        </input_value>
        
    </adapter>
		

Interface to ArduinoUNO by USB-connection

Inputs and outputs depend on configuration. See comments in sample configuration.

Class

adapter.arduino.UNO_Adapter

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.arduino.UNO_Adapter' name='UNO'>
        
        <!-- input and output methods in python are dynamically generated like 
             - inputD4  for io@dir=out   [0..1]
             - servoD6  for io@dir=servo [0..180]
             - pwmD6    for io@dir=pwm   [0..255]
             - outputD3 for io@dir=in    [0..1]
        -->
         <!-- digital input values are inputs for the adapter (but outputs for arduino) -->
        
        <input_value name='inputD4'>
            <variable name='redLED' />
        </input_value>

        <input_value name='inputD5'>
            <variable name='greenLED' />
        </input_value>

        <output_value name='outputD3'>
            <sensor name='button' />
        </output_value>

        <!-- output_value methods in python are dynamically generated like outputADA0 for analog@dir=in -->
        <!-- AD-Values are outputs for the adapter (but inputs for arduino) -->
        
        <output_value name='outputADA0'>
            <sensor name='potentiometer_0' />
        </output_value>

        <!--  on windows, use COMn, e.g. COM6  -->
        <!--  on raspberry, use /dev/ttyn, e.g. /dev/ttyAMA0  -->
        
        <parameter name='serial.device' value='COM6' />
        <parameter name='serial.baud' value='115200' />

        <!-- this is the setup for an UNO arduino -->
        
        <!-- do not use D0, D1 (serial  lines)  -->
        <!-- @dir = void, pwm, in, out, servo --> 
        <io id='D0' dir='void' />
        <io id='D1' dir='void' />
        
        <!--  3,5,6,10,11 may be pwm -->
        <io id='D2' dir='out' />
        <io id='D3' dir='in' pullup='on' />

        <io id='D4' dir='out' />
        <io id='D5' dir='pwm' />
        
        <io id='D6' dir='out' />
        <io id='D7' dir='out' />

        <io id='D8' dir='in' pullup='on' />
        <io id='D9' dir='in' pullup='on' />
        <io id='D10' dir='in' pullup='on' />
        <io id='D11' dir='in' pullup='on' />

        <io id='D12' dir='in' pullup='on' />
        
        <!--  do not use D13 (onboard LED)  -->
        
        <io id='D13' dir='void' />
        
        <analog id='A0' dir='in'  />
        <analog id='A1' dir='void'  />
        <analog id='A2' dir='void'  />
        <analog id='A3' dir='void'  />
        <analog id='A4' dir='void'  />
        <analog id='A5' dir='void'  />

    </adapter>
		

Interface to ArduinoUNO by USB-connection

Controls LEGO Powerfunctions sending by IR transmitter.

Needs sketch 'arduino/power_functions' on arduino. An infrared LED needs to be connected from PIN12 by a current limiting diode to 5V. When arduino is not on 5V, look for documentation.

The command choosen for powertools have timeout enabled; refresh is handled in adapter.

Values sent are -7 to 7; BRAKE is a special command.

Class

adapter.arduino.UNO_POWERFUNCTIONS_Adapter

Input Values

Parameter (mandatory)

Sample configuration

   <adapter class='adapter.arduino.UNO_POWERFUNCTIONS_Adapter' name='UNO'>
        <!--  Sample arduino communication. Needs arduino sketch programmed in arduino. -->

       
        <input_value name='CHANNEL_1_A'>
            <variable name='c_1_A' />
        </input_value>
       <input_value name='CHANNEL_1_B'>
            <variable name='c_1_B' />
        </input_value>
       <input_value name='CHANNEL_2_A'>
            <variable name='c_2_A' />
        </input_value>
       <input_value name='CHANNEL_2_B'>
            <variable name='c_2_B' />
        </input_value>
       <input_value name='CHANNEL_3_A'>
            <variable name='c_3_A' />
        </input_value>
       <input_value name='CHANNEL_3_B'>
            <variable name='c_3_B' />
        </input_value>
       <input_value name='CHANNEL_4_A'>
            <variable name='c_4_A' />
        </input_value>
       <input_value name='CHANNEL_4_B'>
            <variable name='c_4_B' />
        </input_value>
        
        
        <!-- ==================================================== -->
        <!--  on windows, use COMn, e.g. COM6  -->
        <!--  on raspberry, use /dev/ttyn, e.g. /dev/ttyAMA0  -->
        
        <!-- 
            <parameter name='serial.device' value='/dev/ttyUSB0' />
        -->
             <parameter name='serial.device' value='COM6' />
         
        <parameter name='serial.baud' value='115200' />


    </adapter>

        

DS1820 and related devices, using w1-gpio driver

Needs w1-gpio driver.

Class

adapter.w1_gpio.W1_DS1820

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.w1_gpio.W1_DS1820'  name='temp_DS1820'>
        <description>Temp values from DS1820</description>
        
        <output_value name='temperature'>
            <sensor name='ds18b20'/>
        </output_value>
        
        <parameter name='poll.interval' value='1.0' />
        
        <!-- start kernel driver g1-gpio 
             base dir /sys/bus/w1/devices 
        -->
        <parameter name='w1.device' value='10-0008023b57b9' />
    </adapter>
		

X, Y-Values from an orientation sensor

X, Y-Values from an orientation sensor on a smartphone, sent through some javascript, websocket to RPI. There is the need of a web page providing the javascript too.

Class

adapter.websocket.WebsocketXY_Adapter

Output Event

Output Values

Sample configuration

<adapter class='adapter.websocket.WebsocketXY_Adapter'  name='XY'>
        <description>X, Y-Values from an orientation sensor</description>
        
        <output_value name='xValue'>
            <sensor name='goto_X'/>
        </output_value>
        
        <output_value name='yValue'>
            <sensor name='goto_Y'/>
        </output_value>
        
        <output_value name='cntValue'>
            <sensor name='counter'/>
        </output_value>
        
        <output name='click'>
            <broadcast name='click_event'/>
        </output>
        
        <webserver>
            <!-- implement a web socket link 'route'  -->
            <route name='pendel' route='/adapter/pendel' />
            
            <!--  implement a link on start page of web server -->
            <html name='pendel' path='websocket/pendel.html' comment='positional sensor from a smartphone' />
        </webserver>
        
    </adapter>
		

SHT15 or alike humidity sensors

Provides scan results from a barcode scanner.

Class

adapter.wire_gpio.Wire_SHTx

Output Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.wire_gpio.Wire_SHTx'  name='Humidity'>
        <description>Humidity-Value from SHT15</description>

        <gpio port='GPIO23' alias='clock'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'   />
        </gpio>
        
        <gpio port='GPIO24' alias='data'>
            <default dir='IN' pull='PUD_UP'  />
            <active dir='IN' pull='PUD_UP'   />
        </gpio>
        
        <output_value name='humidity'>
            <sensor name='humidity'/>
        </output_value>
        
        <output_value name='temperature'>
            <sensor name='temperature'/>
        </output_value>
        
        <!--  poll time min 1 sec (self heating permits max 1 measurement per sec) -->
        <parameter name='poll.interval' value='2' />
       
    </adapter>
		

WS2801-LED chain driver

Streaming out Bytes to a WS2801-Device. To keep it simple, the input variable is a concatenated list of color names 'red', 'darkred', 'green', 'blue', yellow', 'pink'. Could also be #rrggbb-hex values, but not implemented for simplicity. Separators are blank.

Class

adapter.spiAdapter.WS2801_Adapter

Input Values

Parameter (mandatory)

Sample configuration

    <adapter class='adapter.spiAdapter.WS2801_Adapter'  name='led_stripe'>
        
        <description>LED Stripe of 50 </description>
        
        <input_value name='led'>
            <variable name='led'/>
        </input_value>
        
        <parameter name='led.length' value='50' />
        
        <parameter name='spi.bus' value='0' />
        <parameter name='spi.device' value='0' />
    </adapter>