SAM Script API Reference for SAM Labs Hardware Blocks

LED Block — outputs colored light

The LED block lets you display any RGB color and control brightness. Use it for visual feedback, status indicators, or creative lighting effects.Connect: plug the LED block into your SAM hub or pair it over Bluetooth, then reference it by the name 'led'.

JavaScript
Python

// Connect to the LED block
const led = await SAM.connect('led');

// Set a color using red, green, blue values (0–255 each)
await led.setColor(255, 0, 128);

// Set brightness as a percentage (0–100)
await led.setBrightness(75);

// Turn the LED off
await led.turnOff();

# Connect to the LED block
led = sam.connect('led')

# Set a color using red, green, blue values (0–255 each)
led.set_color(255, 0, 128)

# Set brightness as a percentage (0–100)
led.set_brightness(75)

# Turn the LED off
led.turn_off()

Button Block — detects press and release

The button block registers when a user presses or releases its physical button. Use event callbacks to react in real time, or poll the current state when you need it.Connect: pair the button block and reference it by the name 'button'.

JavaScript
Python

// Connect to the button block
const btn = await SAM.connect('button');

// Run a function when the button is pressed
btn.onPress(() => {
  console.log('Button pressed!');
});

// Run a function when the button is released
btn.onRelease(() => {
  console.log('Button released!');
});

// Check whether the button is currently held down
const held = await btn.isPressed();
console.log('Is pressed:', held);

# Connect to the button block
btn = sam.connect('button')

# Run a function when the button is pressed
def on_press():
    print('Button pressed!')

btn.on_press(on_press)

# Run a function when the button is released
def on_release():
    print('Button released!')

btn.on_release(on_release)

# Check whether the button is currently held down
held = btn.is_pressed()
print('Is pressed:', held)

DC Motor Block — spins a wheel or motor

The DC motor block drives a continuous rotation motor. You can set its speed and direction independently, making it ideal for wheeled robots and conveyor-belt projects.Connect: pair the DC motor block and reference it by 'dcMotor' (JavaScript) or 'dc_motor' (Python).

JavaScript
Python

// Connect to the DC motor block
const motor = await SAM.connect('dcMotor');

// Set speed as a percentage (0–100)
await motor.setSpeed(80);

// Set direction: 'forward' or 'backward'
await motor.setDirection('forward');

// Stop the motor
await motor.stop();

# Connect to the DC motor block
motor = sam.connect('dc_motor')

# Set speed as a percentage (0–100)
motor.set_speed(80)

# Set direction: 'forward' or 'backward'
motor.set_direction('forward')

# Stop the motor
motor.stop()

Servo Block — rotates to a precise angle

The servo block moves to an exact angular position between 0° and 180°. Use it for robotic arms, steering mechanisms, or any project that needs controlled positional movement.Connect: pair the servo block and reference it by the name 'servo'.

JavaScript
Python

// Connect to the servo block
const servo = await SAM.connect('servo');

// Rotate to a specific angle (0–180 degrees)
await servo.setAngle(90);

# Connect to the servo block
servo = sam.connect('servo')

# Rotate to a specific angle (0–180 degrees)
servo.set_angle(90)

Light Sensor Block — measures ambient light

The light sensor block reads the brightness of the surrounding environment. You can poll it for a single reading or register a callback that fires whenever the value changes.Connect: pair the light sensor block and reference it by 'lightSensor' (JavaScript) or 'light_sensor' (Python).

JavaScript
Python

// Connect to the light sensor block
const light = await SAM.connect('lightSensor');

// Read the current light level (0–100)
const val = await light.getValue();
console.log('Light level:', val);

// React whenever the light level changes
light.onChange((newVal) => {
  console.log('New light level:', newVal);
});

# Connect to the light sensor block
light = sam.connect('light_sensor')

# Read the current light level (0–100)
val = light.get_value()
print('Light level:', val)

# React whenever the light level changes
def on_change(new_val):
    print('New light level:', new_val)

light.on_change(on_change)

Buzzer Block — plays tones and melodies

The buzzer block generates audio tones. You can specify a musical note name and duration, or supply a raw frequency in hertz for full control over the sound.Connect: pair the buzzer block and reference it by the name 'buzzer'.

JavaScript
Python

// Connect to the buzzer block
const buzz = await SAM.connect('buzzer');

// Play a musical note: note name and duration in milliseconds
await buzz.playNote('C4', 500);

// Play a raw frequency: Hz and duration in milliseconds
await buzz.playFrequency(440, 500);

# Connect to the buzzer block
buzz = sam.connect('buzzer')

# Play a musical note: note name and duration in milliseconds
buzz.play_note('C4', 500)

# Play a raw frequency: Hz and duration in milliseconds
buzz.play_frequency(440, 500)

Writing Scripts

Hardware

Projects

SAM Script API Reference for SAM Labs Hardware Blocks

Blocks

​Blocks

Blocks