Glossary
Input
Button
Description
A simple switch, press it to activate and release to de-activate.
How it works
When you press the button, it will send true, and when you release it, it will send false.
Dimmer
Description
A knob that you rotate from its minimum to its maximum value.
How it works
Sends a value between 0 and 100 depending on the position of the knob. Every time the state of the knob changes, a new message is sent (at most 1 message every 50ms). Turn the knob all the way anti-clockwise to reach 0, and all the way clockwise to reach 100.
Heat Sensor
Description
Sends the current temperature in degrees Celsius.
How it works
The SAM Heat sensor sends the temperature of the sensor in degrees Celsius. A new reading is displayed every time the temperature of the surrounding environment changes. It is accurate to +/- 3 degrees and works in the range 0-70ºC.
Light Sensor
Description
Sends out a low value in the dark and a high value in the light.
How it works
The light sensor provides light intensity readings. It will send 0 when no light is detected (complete darkness) and 100 when there is lots of light.
A new reading is displayed every time the light level of the surrounding environment changes.
Pressure Sensor
Description
Senses the amount of force. The harder you push, the higher the value it will send.
How it works
The Pressure Sensor sends the pressure applied to the flat circular part of the sensor. A new value is sent when the pressure applied changes.
The value is zero when no pressure is applied and the value is 100 when approximately 20N of force is applied.
Note that the sensor is technically measuring force (N), not pressure, and is optimised on the assumption that a human finger will be applying the force.
Proximity Sensor
Description
Senses distance. The closer the object, the higher the value.
How it works
The Proximity Sensor is composed of two components: one shines an infra-red (IR) beam and the other detects IR light. If an object is nearby, it will reflect the light from the beam, and therefore the sensor will know that there is a surface in its way. The value will be higher when there is an object nearby as more of the light gets reflected (100 when within 1-2cm of a light surface). This sensor works best in the range 0-10cm and when there is a small amount of ambient IR light. Note that a black surface will absorb all the IR light, instead of reflecting it, and therefore the block will not detect the surface.
Slider
Description
A handle that you move up and down from its minimum to its maximum value.
How it works
As the handle of the Slider moves, it sends numerical values between 0 and 100 (with 0 being completely to the left and 100 being completely to the right). Every time the state of the handle changes, a new message is sent (at most 1 message every 50ms).
Tilt Sensor
Description
Sends a true or false value when it discovers movement.
How it works
A Tilt Sensor sends a boolean value when it’s tilted along the axis running trough the length of the metal component. When the ball that you can hear inside the sensor is on one side, it will send true, and when it is on the other it will send false.
Output
Buzzer
Description
You can set its note and volume.
How it works
This block expects to receive a SAM Buzz value. When it does, it will play the specified note (see range of notes below) at the specified volume (0-100).
The range of notes supported are :
{ name: 'A3', midi: 69 }, { name: 'A#3', midi: 70 }, { name: 'B3', midi: 71 }, { name: 'C4', midi: 72 }, { name: 'C#4', midi: 73 }, { name: 'D4', midi: 74 }, { name: 'D#4', midi: 75 }, { name: 'E4', midi: 76 }, { name: 'F4', midi: 77 }, { name: 'F#4', midi: 78 }, { name: 'G4', midi: 79 }, { name: 'G#4', midi: 80 }, { name: 'A4', midi: 81 }, { name: 'A#4', midi: 82 }, { name: 'B4', midi: 83 }, { name: 'C5', midi: 84 }, { name: 'C#5', midi: 85 }, { name: 'D5', midi: 86 }
If you send a boolean true to the block, the note and volume specified in the settings menu will be played.
If you send a number, the number will dictate the volume and the note set in the settings menu will be played.
DC Motor
Description
The shaft of the motor spins around, you can set its direction and speed.
How it works
The SAM DC Motor can turn in both directions and at varying speeds.
If you send a boolean true to the block, it will start spinning at the speed and direction specified in the settings menu.
If you send a number to the block, it will start spinning in the direction specified in the settings menu at the speed sent (note that the speed must be at least 20 for the motor to start turning. 100 is maximum speed).
If you send the block 0 or false, the motor will stop spinning.
In order to set the direction of the motor, use the Direction block.
Servo
Description
The arm of the servo motor rotates back and forth around 180 degrees.
How it works
The servo is a motor with an arm that rotates 180 degrees. The position of the arm is set according to the number that it receives, where 0 means that the arm will be in its rest position, 50 means it will be at 90 degrees, and 100 means it will be at 180 degrees.
If you send a boolean true to the servo, it will go to the position as specified in the settings menu. if you send a boolean false, it will go to its rest position.
RGB Led
Description
A light with variable colour and brightness.
How it works
The SAM Light expects to receive the SAM Colour type.
If it receives a boolean true it will turn on at the colour and brightness specified in the settings menu. If it receives a boolean false, it will turn off.
If it receives a number it will turn on at the colour specified in the settings menu and the number received will dictate the brightness.
Vibration Motor
Description
Vibrates and hops around.
How it works
The Vibration block is a small unbalanced motor that creates a vibration effect (like the one in your own phone) by spinning.
The block has three different levels of vibration intensity. Sending a boolean true will activate the maximum vibration level. If a number is sent it will vibrate more and more intensely from the lowest number 1, to the highest number (100).
Sending a boolean true or number 0 will stop the block from vibrating.
Apps
Camera
Description
Need to take a selfie? This is the block you want.
How it works
When the camera block receives a positive value it takes a picture using the computer’s default camera, saves it in Documents > SAM > Camera and makes it available to the next block in the circuit.
If the picture has been taken successfully, the camera will emit boolean true. Note that it only saves the latest picture, and then continuously overwrites it.
If the block receives a non-positive value, it will emit boolean false. If the picture fails to take, no value will be emitted and an error message will be displayed in the bottom right hand corner of the canvas.
Keyboard
Description
Turn your keyboard keys to buttons
How it works
If the trigger key on the icon is pressed, it sends a boolean true when pressed and boolean false when the key is released. To change the trigger key, open up the settings and press a key. Trigger keys can only be letters or the space bar.
MIDI Out
Description
Send MIDI messages to a connected MIDI device
How it works
Connect your MIDI device to your computer and select it from the settings dropdown. The default port used is SAM Out.
If you connect a MIDI message or a Note block to this, it sends the MIDI message and note respectively.
Morse Code
Description
Converts text to Morse code.
How it works
The morse block will convert any received value to text, and then convert that text to Morse code. You can set the speed of the Morse code in the settings menu.
For the best results, send text to the input of this block and connect a light or a buzzer to the output to see it in Morse!
Sequencer
Description
Preset a tune to play on your buzzer.
How it works
Connect this block to your buzzer and preset a tune to play. Open the settings menu to create the tune by choosing the sequence of notes, volume and tempo.
Sending a positive value will initiate the sequencer to start sending the notes to the output. Sending a non-positive value will cause the sequence to stop.
Text
Description
Will emit the text value specified in the settings menu when it receives a positive value.
How it works
If you send this block any non-positive value, it will emit boolean value false. If you send this block a positive value, it will behave differently depending on the type of input that you send it. If you send it text, it will append the text specified in the settings menu to the text received and emit the resulting message. If you send it any other positive value, it will simply emit the message specified in the setting menu. You can embed the received value into the emitted message using the keyword %input% in the settings menu. For example, you can write “The received value is: %input%” and the emitted message will replace %input% with the actual value of the input (irrespective of its type).
Tweet In
Description
When it receives a tweet matching the criteria of the given search it will emit the tweet.
How it works
This block allows you to monitor Twitter for hash tags and mentions. Open the settings menu and enter the hashtags or names that you would like to listen for (separate them with spaces).
Every time the selected words are mentioned on Twitter, the block emits the twitter message that contains the selected words. 1 second later it sends a boolean false.
Note that you have to be authenticated to Twitter in order to use this app. You can do this by dragging the block onto the canvas and clicking ‘connect’ in the settings menu. You can always unlink your Twitter account from SAM by going to the right hand pane, selecting ‘Apps’ and then ‘Edit Apps’ and then the X next to Twitter.
Behaviour
Colour
Description
When it receives a positive value it will send out a colour value
How it works
This block will send the colour specified in the settings menu, when a true value is sent. When the value is a boolean, true will trigger. When the value is a number, a non-zero number will trigger.
Compare
Description
Allows you to compare incoming values to a predefined number.
How it works
This block will convert every input to a SAM Number and then compare that value with the one specified in the settings menu. If the comparison is true, the block will emit boolean true, otherwise it will emit boolean false.
Cycle Brightness
Description
This block behaves differently depending on the type of input it receives.
How it works
This block behaves differently depending on the type of input it receives. If the input is text, a buzz or a colour, the value will be converted to a boolean and behave as follows: every time time this block receives a positive value it will cycle between 3 numbers: 0 (off), 33 (medium brightness) and 100 (maximum brightness). When connected to a light the numbers get converted to the colour type according to the SAM conversion rules (link). When it receives a false value, it will emit a boolean false.
If the input is a number, it will not follow the same pattern. If the input number is 0-33 then 0 will be emitted, if the input number is 34-67 then 33 will be emitted, otherwise 100 will be emitted.
Cycle Colours
Description
When it receives a positive value it will send out a Red, Green then Blue colour value.
How it works
This block behaves differently depending on the type of input it receives. If the input is text, a buzz or a colour, the value will be converted to a boolean and behave as follows: every time time this block receives a positive value it will cycle between 3 colours: red, green and blue. When it receives a false value, it will emit a boolean false.
If the input is a number, it will not follow the same pattern. If the input number is 0-33 then red [100,0,0] will be emitted, if the input number is 34-67 then green [0,100,0] will be emitted, otherwise blue [0,0,100] will be emitted.
Cycle Frequency
Description
When it receives a value it will send one of three predefined notes.
How it works
This block behaves differently depending on the type of input it receives. If the input is text, a buzz or a colour, the value will be converted to a boolean and behave as follows: every time time this block receives a positive value it will cycle between 3 preset buzz values: note A3 (midi 69) at 30% volume, note D4 (midi 74) at 30% volume and note G4 (midi 79) at 30% volume. When it receives a false value, it will emit a boolean false. If the input is a number, it will not follow the same pattern. If the input number is 0-33 then note A3 (midi 69) at 30% volume will be emitted, if the input number is 34-67 then note D4 (midi 74) at 30% volume will be emitted, otherwise note G4 (midi 79) at 30% volume will be emitted.
Cycle Volume
Description
When it receives a value it will send out a predefined note at a low, medium and then high volume.
How it works
This block behaves differently depending on the type of input it receives. If the input is text, a buzz or a colour, the value will be converted to a boolean and behave as follows: every time time this block receives a positive value it will cycle between 3 preset buzz values: note A4 (midi 81) at 10% volume, note A4 (midi 81) at 30% volume and note A4 (midi 81) at 50% volume. When it receives a false value, it will emit a boolean false. If the input is a number, it will not follow the same pattern. If the input number is 0-33 then note A4 (midi 81) at 10% volume will be emitted, if the input number is 34-67 then note A4 (midi 81) at 30% volume will be emitted, otherwise note A4 (midi 81) at 50% volume will be emitted.
Direction
Description
When it receives a positive value it will send out a direction string
How it works
This block is specifically for connecting to a DC motor to control the direction it turns in.
When the block receives either “true” or a positive number, it will send the direction specified in the settings menu.
Filter
Description
Filter will only let values through that are between two specified numbers
How it works
The input to this block gets converted into a SAM Number. If its value lies within the bounds controlled in the settings menu, the converted value will be allowed to pass through. Otherwise, the number 0 will be emitted.
Inverse
Description
When it receives a value it will send out the inverse of that value.
How it works
It will output the inverse of the value that it receives.
A boolean true will be converted to false and vice versa.
If a number X is received, 100 - X will be returned.
If a SAM Colour type [X, Y, Z] is received, then it will return [100-X, 100- Y, 100-Z].
If a SAM Buzz type is received with volume X, then it will return the same note with volume 100 - X
Log
Description
Stores the values that it receives, you are able to download the log as a csv.
How it works
This block just passes everything right through it without changing the value. If you leave the log interval to 0, it will make a copy of and log every single value that it receives.
If the interval is increased, for example to 1 minute, it will log at most 1 value every minute (it will log the first value that it receives at the beginning of each minute).
Once your experiment is complete, you can download the log file in the cvs format. Simply open the settings menu and click on ‘Download file’
Map
Description
Converts a number to a new value depending on mapping specified in the settings menu.
How it works
Note
Description
When it receives a positive value it will send out a note
How it works
Connecting in
If a number is sent to the block, the block will be configured to send the note on the keyboard corresponding to that number.The block does not send the note until a boolean true is sent to it. If a boolean false is sent, then the note being sent is turned off.
Connecting out
If connected to a Buzzer, it will play the note sent.If connected to MIDI Out, it will send a MIDI Note. The SAM Note is limited to 17 notes. All MIDI notes are sent on MIDI Channel 1.
Number
Description
When it receives a boolean true it will send out a specified number.
How it works
If you send it a boolean true value, it will emit the value stored in the block. If you send any other data type, it will convert it to a number and update the value stored in the block. The value in the block will not be emitted unless you send a boolean true value.
On/Off
Description
Converts any value to a boolean.
How it works
This block will convert any type of input to a boolean and emit the boolean value obtained.
Switch
Description
If the hand is a positive value, then the other input values will be allowed to pass through.
How it works
This is a special block. It has two different types of input. One input is the hand that will control whether data from the other inputs will be allowed to flow through the block or not. You specify the block that will act as the hand in the settings menu. If the hand block sends a positive value, then the hand will push the switch down, closing the circuit, and allowing the values of the other input blocks to it to pass through the circuit.
Toggle
Description
When it receives a positive value it will toggle between sending out a true and false value.
How it works
Any input to this block gets converted to a SAM boolean value.
This block changes state (toggles between true and false) only when it receives boolean true values (it ignores false values).
Logic
AND
Description
Behaves like an AND logic gate.
How it works
The output will be a boolean true if all the inputs are positive values.
NAND
Description
Will send a false value only when all it inputs are trues.
How it works
This block will emit a boolean false when all of its inputs are true. In all other cases, it will emit false.
NOR
Description
When all inputs are false it will send out a true value.
How it works
When all inputs are false it will send out a true value.
OR
Description
Behaves like an OR logic gate.
How it works
This block will emit a boolean true when at least one of the inputs is a positive value.
XOR
Description
When only one of the values is positive it will let the values it will send out a true value.
How it works
This block will emit a boolean true when one and only one of its input values is true. In all other cases, it will emit false.
Timing
Counter
Description
This block counts up by one every time it receives a positive value.
How it works
Every time this block receives a positive value it will increment its internal counter value and send that value to the next block in the circuit.
The counter will stop counting when the value reaches 100. In order to reset the counter, send it text with value reset.
When it receives a non-positive value, it will ignore the value and not emit anything.
Delay
Description
Holds onto values for the time specified before allowing the message to continue.
How it works
This block only accepts boolean and number SAM types, all other values sent will be converted to the boolean type.
This block will store every value that it receives for the time indicated in the settings menu before emitting the value.
Hold
Description
Holds a value for a period of time.
How it works
This block will immediately trigger the value received, hold the value for the time indicated in the settings menu, then trigger a cancel value afterwards. The cancel value is a boolean false, if the trigger value is a boolean. Otherwise the cancel value is a number of 0.
Interval
Description
Alternatively sends true and false at specified time interval.
How it works
When it receives a positive value it starts alternatively sending true and false at the interval specified in the settings menu. When it receives a non-positive value it stops the interval and emits a boolean false value.
Time Trigger
Description
Sends out a true value at a specified time and date.
How it works
This block allows you to set a system in motion at a specific pre-defined time. When the time specified in the settings menu is reached, a boolean true value is emitted. 1 second later, it is followed by a boolean false.