Skip to main content
SAM Script gives you a consistent API to control every SAM Labs hardware block. Connect a block by name, then call methods on the object it returns. The examples below show the full API for each block type in both JavaScript and Python.
All JavaScript connect calls are asynchronous — remember to use await inside an async function. Python calls are synchronous and can be used directly.

​
Blocks

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'.
// 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();
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'.
// 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);
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).
// 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();
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'.
// Connect to the servo block
const servo = await SAM.connect('servo');

// Rotate to a specific angle (0–180 degrees)
await servo.setAngle(90);
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).
// 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);
});
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'.
// 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);