> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# SAM Script API Reference for SAM Labs Hardware Blocks

> Complete reference for all SAM Labs hardware blocks supported in SAM Script. Includes LED, button, DC motor, servo, light sensor, and more.

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.

<Note>
  All JavaScript `connect` calls are asynchronous — remember to use `await` inside an `async` function. Python calls are synchronous and can be used directly.
</Note>

## Blocks

<AccordionGroup>
  <Accordion title="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'`.

    <Tabs>
      <Tab title="JavaScript">
        ```js theme={null}
        // 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();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        # 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()
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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'`.

    <Tabs>
      <Tab title="JavaScript">
        ```js theme={null}
        // 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);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        # 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)
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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).

    <Tabs>
      <Tab title="JavaScript">
        ```js theme={null}
        // 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();
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        # 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()
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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'`.

    <Tabs>
      <Tab title="JavaScript">
        ```js theme={null}
        // Connect to the servo block
        const servo = await SAM.connect('servo');

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

      <Tab title="Python">
        ```python theme={null}
        # Connect to the servo block
        servo = sam.connect('servo')

        # Rotate to a specific angle (0–180 degrees)
        servo.set_angle(90)
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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).

    <Tabs>
      <Tab title="JavaScript">
        ```js theme={null}
        // 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);
        });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        # 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)
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="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'`.

    <Tabs>
      <Tab title="JavaScript">
        ```js theme={null}
        // 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);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        # 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)
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>