What SwayForm Teaches

SwayForm is built around the idea that robotics makes more sense when students can see code turn into physical motion. The Learning Hub introduces programming, control, vision, and system design through real robot behaviors.

Programming through robot behavior

Students use Python to define poses, trigger motions, adjust timing, and create behavior sequences. Instead of writing code that only prints output to a terminal, students write code that moves a physical system.

ROS 2-style system thinking

The hub introduces robotics software concepts such as nodes, topics, publishers, subscribers, services, launch files, and motion commands. These ideas are explained through SwayForm examples, not as abstract definitions.

Motion and safe control

Students learn that robot joints cannot be commanded randomly. Every motion has to respect safe limits, timing, physical spacing, and the difference between a smooth behavior and a sudden unsafe movement.

Vision and interaction

SwayForm uses a RealSense camera for demos and labs that connect perception to behavior. Students can explore simple user detection, target zones, and camera-assisted interaction without pretending the robot has perfect human-level understanding.

Debugging real systems

Students learn that robotics is not only about writing code. They also learn to read terminal output, check whether a process is running, source a workspace, stop a motion safely, and understand why hardware may not behave exactly as expected.

How Students Use This Hub

The Learning Hub is meant to be used directly by students. A teacher or club lead can introduce the activity, but students should be able to open the hub, follow the steps, and understand what they are changing.

The basic student workflow

File Structure

SwayForm examples are organized so students can tell the difference between official demo programs, editable lab files, and supporting robot code.

Demo programs

Demo programs are finished examples. Students can run them to see what the robot does, then read the walkthrough to understand how the behavior works.

~/ros2_ws/src/swayform_demos/
├── wave_demo.py
├── vision_handshake.py
├── look_and_point.py
├── rock_paper_scissors.py
└── dollar_snack_exchange.py

Student labs

Student labs are guided activities. These are the files students are expected to open, edit, test, and improve.

~/ros2_ws/src/swayform_labs/
├── lab_01_hello_motion.py
├── lab_02_servo_limits.py
├── lab_03_gesture_sequence.py
├── lab_04_head_tracking.py
├── lab_05_button_motion.py
├── lab_06_realsense_detection.py
├── lab_07_hand_pose_timing.py
├── lab_08_base_rotation.py
├── lab_09_motion_locking.py
└── lab_10_mini_demo_challenge.py

Recommended editing rule

Students should not rewrite official demos during the first session. Run the demo first, read the code, then copy the important idea into a lab file or student workspace.

Safety Notes

SwayForm is designed for classroom robotics learning, but it is still a physical robot. Students should treat every moving part with care.

VS Code + SSH

Students use VS Code and SSH so they can work with the robot like a real development system. Code runs on the robot, but students can edit and launch it from their laptop.

What SSH means

SSH lets a laptop open a secure terminal session on the robot. Instead of plugging in a monitor and keyboard, students connect remotely and run commands from their own computer.

Why VS Code is used

VS Code gives students a familiar editor, file browser, terminal, and remote connection workflow. It lets students open the robot workspace, inspect files, edit lab code, and run commands without switching tools constantly.

Example connection

Open the workspace

Source the workspace

Run a first demo

Connecting to the Robot

Before students run demos, they need to make sure their laptop can communicate with SwayForm.

Running a Demo

Demos are finished example behaviors. They are meant to show students what the robot can do before students start editing lab code.

Basic run flow

Before running

Stopping Motion Safely

Students should know how to stop a behavior before they start changing code. A safe stop is part of the workflow, not an emergency-only action.

Normal stop

If the demo is running in a terminal, use the normal keyboard interrupt.

After stopping

If the robot does not move correctly

Stop the script first. Then check whether the correct file was edited, the workspace was sourced, and another behavior is not already controlling the robot.

Demo Code Library

The Demo Code Library contains finished example behaviors that students can run before they start writing their own. Each ready demo includes what the robot does, what students learn, the hardware involved, a run command, and a small code walkthrough.

Ready demos

These demos are intended to be run, inspected, and lightly modified.

Coming soon

These slots are reserved for future classroom demos. They should appear in the hub, but should not pretend to be finished.

Demo 01: Wave

The robot raises one arm and performs a simple wave motion using a timed servo sequence. The behavior is simple on purpose: students can clearly see how a few target positions become a physical gesture.

What it does

Students learn how a script can move a joint group, pause between poses, repeat a motion, and return the robot to a neutral position.

Hardware used

• Shoulder servo
• Elbow servo
• Optional wrist or hand motion
• Motion controller node

Concepts covered

• Joint targets
• Servo angles
• Timed motion
• Smooth movement
• Safe limits
• Running a script from terminal

Run command

Starter code

The complete starter file below is structured the same way a real robotics script is structured. Read through it before running it so you understand what each section does.

"""
Demo 01: Wave

Purpose:
Run a simple waving behavior using safe arm poses.

What this teaches:
- How a behavior script connects to the motion layer
- How joint targets create physical motion
- Why safe poses and delays matter
- How to return the robot to idle after a demo
"""

from time import sleep
from swayform.motion import MotionClient


# -----------------------------
# Student-adjustable settings
# -----------------------------

WAVE_CYCLES = 3
WAVE_DELAY_SECONDS = 0.35

RIGHT_ARM_RAISED = {
    "shoulder_pitch": 42,
    "shoulder_roll": 18,
    "elbow_pitch": 70,
}

WRIST_LEFT = -25
WRIST_RIGHT = 25


def move_to_wave_start(motion: MotionClient) -> None:
    """
    Move the robot from idle into a safe raised-arm position.
    This should happen before the wrist starts waving.
    """
    motion.safe_pose("idle")
    sleep(0.5)

    motion.move_joint_group("right_arm", RIGHT_ARM_RAISED)
    sleep(0.8)


def perform_wave(motion: MotionClient, cycles: int) -> None:
    """
    Move the wrist left and right several times.
    The arm stays raised while the wrist creates the wave motion.
    """
    for _ in range(cycles):
        motion.move_joint("right_wrist_yaw", WRIST_LEFT)
        sleep(WAVE_DELAY_SECONDS)

        motion.move_joint("right_wrist_yaw", WRIST_RIGHT)
        sleep(WAVE_DELAY_SECONDS)


def return_to_idle(motion: MotionClient) -> None:
    """
    Always return the robot to a known safe pose after the demo.
    """
    motion.safe_pose("idle")


def main() -> None:
    motion = MotionClient()

    try:
        motion.lock_behavior("wave_demo")
        move_to_wave_start(motion)
        perform_wave(motion, WAVE_CYCLES)
    finally:
        return_to_idle(motion)
        motion.unlock_behavior("wave_demo")


if __name__ == "__main__":
    main()

Code walkthrough

Try changing this

• Change the number of wave cycles.
• Make the wave slower or faster.
• Try the left arm instead of the right arm.
• Add a small head turn during the wave.

Demo 02: Vision Handshake

The robot uses the RealSense camera to detect that a user is in front of it, moves its arm into a handshake pose, waits briefly, and then returns to idle.

What students learn

Students learn how camera input can trigger robot motion and why robots need conservative movement when interacting near people.

Hardware used

• RealSense camera
• Arm servos
• Optional hand servo
• Motion node

Concepts covered

• RealSense camera input
• User presence detection
• Perception-triggered behavior
• Human-robot interaction
• Motion locking
• Returning to neutral pose

Run command

Starter code

This version uses a timeout so the demo does not wait forever. Read the function names before running to understand the flow: wait, detect, execute, return home.

"""
Demo 02: Vision Handshake

Purpose:
Use a simple RealSense-based presence check to trigger a handshake pose.

Important:
This is a vision-assisted classroom demo. It does not claim perfect hand
detection or human-level understanding.
"""

from time import sleep, time
from swayform.motion import MotionClient
from swayform.vision import RealSenseInput


DETECTION_TIMEOUT_SECONDS = 10
HANDSHAKE_HOLD_SECONDS = 2.0

HANDSHAKE_POSE = {
    "shoulder_pitch": 38,
    "shoulder_roll": 10,
    "elbow_pitch": 82,
    "wrist_yaw": 0,
}


def wait_for_user(camera: RealSenseInput, timeout: float) -> bool:
    """
    Wait until the camera reports a user inside the interaction zone.
    Returns True if a user is found, otherwise False.
    """
    start_time = time()

    while time() - start_time < timeout:
        if camera.user_in_interaction_zone():
            return True

        sleep(0.1)

    return False


def run_handshake(motion: MotionClient) -> None:
    """
    Move into a conservative handshake pose, wait briefly,
    then return to idle.
    """
    motion.move_joint_group("right_arm", HANDSHAKE_POSE)
    sleep(HANDSHAKE_HOLD_SECONDS)
    motion.safe_pose("idle")


def main() -> None:
    motion = MotionClient()
    camera = RealSenseInput()

    motion.safe_pose("idle")
    print("Waiting for user...")

    user_detected = wait_for_user(camera, DETECTION_TIMEOUT_SECONDS)

    if not user_detected:
        print("No user detected. Returning to idle.")
        motion.safe_pose("idle")
        return

    try:
        motion.lock_behavior("vision_handshake")
        run_handshake(motion)
    finally:
        motion.unlock_behavior("vision_handshake")
        motion.safe_pose("idle")


if __name__ == "__main__":
    main()

Code walkthrough

Try changing this

• Change how long the robot holds the handshake pose.
• Add a small head nod before the arm moves.
• Add a spoken prompt if speakers are connected.
• Adjust the detection distance.

Demo 03: Look and Point

The robot turns its head toward a detected target zone, then points one arm in that direction. This teaches students how perception can trigger a physical response.

What students learn

Students learn that robot behavior often happens in stages: sense something, decide where it is, move the head, then move the arm.

Hardware used

• RealSense camera
• Neck yaw and pitch servos
• Shoulder and elbow servos
• Motion node

Concepts covered

• Camera frame coordinates
• Head yaw and pitch
• Mapping vision to motion
• Pointing gesture
• Behavior sequencing

Run command

Starter code

This version separates look and point into two functions so students can test each step individually. The robot always looks before it points.

"""
Demo 03: Look and Point

Purpose:
Detect a rough target zone (left / center / right) from the camera,
turn the head toward it, then point one arm in that direction.

Important:
The target zone is a simplified classroom abstraction.
This demo teaches vision-to-motion mapping, not production-level
object detection.
"""

from time import sleep
from swayform.motion import MotionClient
from swayform.vision import RealSenseInput


HEAD_TURN_DEGREES = 25
HEAD_PITCH = 5
POINT_HOLD_SECONDS = 1.5

ZONE_HEAD_ANGLES = {
    "left":   {"neck_yaw": -HEAD_TURN_DEGREES, "neck_pitch": HEAD_PITCH},
    "center": {"neck_yaw":  0,                 "neck_pitch": HEAD_PITCH},
    "right":  {"neck_yaw":  HEAD_TURN_DEGREES, "neck_pitch": HEAD_PITCH},
}

ZONE_ARM_POSES = {
    "left":   "point_left",
    "center": "point_center",
    "right":  "point_right",
}


def look_at_zone(motion: MotionClient, zone: str) -> None:
    """Turn the head toward the detected zone."""
    head_angles = ZONE_HEAD_ANGLES.get(zone, ZONE_HEAD_ANGLES["center"])
    motion.move_joint_group("head", head_angles)
    sleep(0.4)


def point_at_zone(motion: MotionClient, zone: str) -> None:
    """Move the arm into the pointing pose for the detected zone."""
    arm_pose = ZONE_ARM_POSES.get(zone, "point_center")
    motion.safe_pose(arm_pose)
    sleep(POINT_HOLD_SECONDS)


def main() -> None:
    motion = MotionClient()
    camera = RealSenseInput()

    motion.safe_pose("idle")

    target_zone = camera.get_target_zone()
    print(f"Detected zone: {target_zone}")

    try:
        motion.lock_behavior("look_and_point")
        look_at_zone(motion, target_zone)
        point_at_zone(motion, target_zone)
    finally:
        motion.safe_pose("idle")
        motion.unlock_behavior("look_and_point")


if __name__ == "__main__":
    main()

Code walkthrough

Try changing this

• Change the target zone thresholds.
• Point with the left arm instead of the right arm.
• Add a short pause before pointing.
• Make the robot look back at the user after pointing.

Demo 04: Rock Paper Scissors

The robot plays rock-paper-scissors with the user. It counts down, chooses rock, paper, or scissors, moves its hand into the selected pose, and compares the result.

What students learn

Students learn how robot behaviors can include randomness, user input, hand pose presets, branching logic, and a repeated game loop.

Hardware used

• Hand and finger servos
• Optional speaker for countdown
• Optional RealSense camera for camera-assisted mode

Concepts covered

• Random choice
• Hand pose presets
• Branching logic
• User interaction
• Game loop
• Optional vision classification

Run command

Starter code

This version uses a game loop so students can run multiple rounds without restarting. Each round is a clean sequence: countdown, choose, move, judge.

"""
Demo 04: Rock Paper Scissors

Purpose:
Play a round of rock-paper-scissors with the user. The robot picks randomly.

Important:
This version uses keyboard input for the user's choice.
A camera-assisted version can be added later using gesture detection.
Do not describe this as perfect hand-recognition unless that is implemented.
"""

import random
from time import sleep
from swayform.motion import MotionClient
from swayform.audio import AudioPrompt


VALID_CHOICES = ["rock", "paper", "scissors"]
COUNTDOWN_SECONDS = 1.0
POSE_HOLD_SECONDS = 1.5
ROUNDS_TO_PLAY = 3

WINS_AGAINST = {
    "rock": "scissors",
    "scissors": "paper",
    "paper": "rock",
}


def countdown(audio: AudioPrompt) -> None:
    """Say rock, paper, scissors aloud before the reveal."""
    for word in ["Rock", "Paper", "Scissors", "Shoot!"]:
        audio.say(word)
        sleep(COUNTDOWN_SECONDS)


def get_user_choice() -> str:
    """Prompt the user and validate their choice."""
    while True:
        raw = input("Your move (rock / paper / scissors): ").strip().lower()
        if raw in VALID_CHOICES:
            return raw
        print(f"Please enter one of: {', '.join(VALID_CHOICES)}")


def judge(robot: str, user: str) -> str:
    """Return 'robot', 'user', or 'tie'."""
    if robot == user:
        return "tie"
    if WINS_AGAINST[robot] == user:
        return "robot"
    return "user"


def play_round(motion: MotionClient, audio: AudioPrompt) -> str:
    """Run one complete round. Returns winner: 'robot', 'user', or 'tie'."""
    robot_choice = random.choice(VALID_CHOICES)
    user_choice = get_user_choice()

    countdown(audio)

    motion.set_hand_pose("right_hand", robot_choice)
    sleep(POSE_HOLD_SECONDS)

    result = judge(robot_choice, user_choice)
    print(f"Robot: {robot_choice}  |  You: {user_choice}  |  Result: {result}")

    motion.set_hand_pose("right_hand", "relaxed")
    return result


def main() -> None:
    motion = MotionClient()
    audio = AudioPrompt()

    scores = {"robot": 0, "user": 0, "tie": 0}

    motion.safe_pose("idle")

    for round_num in range(1, ROUNDS_TO_PLAY + 1):
        print(f"\n--- Round {round_num} ---")
        winner = play_round(motion, audio)
        scores[winner] += 1

    print(f"\nFinal score — Robot: {scores['robot']}  You: {scores['user']}  Ties: {scores['tie']}")
    motion.safe_pose("idle")


if __name__ == "__main__":
    main()

Code walkthrough

Try changing this

• Make the game best of three rounds.
• Add sound effects or a countdown.
• Add head movement when the robot wins or loses.
• Add a scoreboard variable.

Demo 05: Dollar Bill Snack Exchange

A classroom interaction demo where the user gives the robot a bill, the robot assumes the bill is $1, places it to the side, then gives or pushes a small snack item toward the user.

Example setup

Place a light snack item, such as a small chip packet, on the table near the robot. The user places a bill in front of the robot. The robot moves the bill to one side, reaches toward the snack item, and presents or pushes it toward the user.

What students learn

Students learn how a larger robot behavior can be broken into states. The robot is not doing one magic action; it is moving through a controlled sequence.

Hardware used

• RealSense camera
• Arm servos
• Hand servos
• Small tabletop object
• Optional speaker

Concepts covered

• Human-robot interaction
• Sequenced manipulation
• Simple object handoff
• Vision or manual trigger
• Safe arm movement
• State machine thinking

Run command

State machine

• IDLE
• WAIT_FOR_BILL
• ACCEPT_BILL
• PLACE_BILL_ASIDE
• PICK_SNACK
• HAND_SNACK_TO_USER
• RETURN_HOME

Starter code

This version uses an enum.Enum state machine so every stage of the interaction is named. Students can add print statements to each state transition to see the sequence in the terminal.

"""
Demo 05: Dollar Bill Snack Exchange

Purpose:
A classroom interaction demo where the user places a bill near the robot,
the robot accepts it, sets it aside, then presents a snack item.

Important:
This is not real payment processing or currency validation.
The robot assumes every bill is a $1 bill.
This demo is for supervised classroom interaction only.
"""

import enum
from time import sleep, time
from swayform.motion import MotionClient
from swayform.vision import RealSenseInput
from swayform.audio import AudioPrompt


BILL_WAIT_TIMEOUT = 15.0
BILL_HOLD_SECONDS = 0.6
SNACK_HANDOFF_HOLD = 1.5


class ExchangeState(enum.Enum):
    WAIT_FOR_BILL      = "wait_for_bill"
    ACCEPT_BILL        = "accept_bill"
    PLACE_BILL_ASIDE   = "place_bill_aside"
    PICK_SNACK         = "pick_snack"
    HAND_SNACK_TO_USER = "hand_snack_to_user"
    RETURN_HOME        = "return_home"


def wait_for_bill(camera: RealSenseInput, timeout: float) -> bool:
    """Poll until a bill is detected in the bill area, or timeout."""
    start = time()
    while time() - start < timeout:
        if camera.object_in_zone("bill_area"):
            return True
        sleep(0.1)
    return False


def run_exchange(motion: MotionClient, audio: AudioPrompt) -> None:
    state = ExchangeState.ACCEPT_BILL

    while state != ExchangeState.RETURN_HOME:
        print(f"State: {state.value}")

        if state == ExchangeState.ACCEPT_BILL:
            motion.safe_pose("bill_pickup")
            motion.set_hand_pose("right_hand", "gentle_close")
            sleep(BILL_HOLD_SECONDS)
            state = ExchangeState.PLACE_BILL_ASIDE

        elif state == ExchangeState.PLACE_BILL_ASIDE:
            motion.safe_pose("bill_side_drop")
            motion.set_hand_pose("right_hand", "open")
            sleep(0.3)
            state = ExchangeState.PICK_SNACK

        elif state == ExchangeState.PICK_SNACK:
            motion.safe_pose("snack_pickup")
            sleep(0.4)
            state = ExchangeState.HAND_SNACK_TO_USER

        elif state == ExchangeState.HAND_SNACK_TO_USER:
            motion.safe_pose("snack_handoff")
            audio.say("Here you go.")
            sleep(SNACK_HANDOFF_HOLD)
            state = ExchangeState.RETURN_HOME

    motion.safe_pose("idle")


def main() -> None:
    motion = MotionClient()
    camera = RealSenseInput()
    audio  = AudioPrompt()

    motion.safe_pose("idle")
    audio.say("Ready. Place your bill on the table.")

    bill_detected = wait_for_bill(camera, BILL_WAIT_TIMEOUT)

    if not bill_detected:
        audio.say("No bill detected. Returning to idle.")
        motion.safe_pose("idle")
        return

    try:
        motion.lock_behavior("dollar_snack_exchange")
        run_exchange(motion, audio)
    finally:
        motion.unlock_behavior("dollar_snack_exchange")
        motion.safe_pose("idle")


if __name__ == "__main__":
    main()

Code walkthrough

Try changing this

• Change the snack position.
• Add a thank-you sound.
• Add a timeout if no bill is detected.
• Make the robot wave after completing the exchange.

Demo 06: Follow the Face

Demo 07: Classroom Attendance Greeting

Demo 08: Object Sorting Starter

Demo 09: Voice Prompt Motion

Demo 10: Custom Student Demo

Student Labs

Student labs are guided activities where students edit code, run the robot, observe the result, and answer a short reflection question. Labs are more structured than demos, but still focused on real robot behavior.

Ready labs

These labs are ready to use as classroom or robotics club activities.

Coming soon

These slots are reserved for future SwayForm curriculum material.

Lab 01: Hello Robot Motion

Goal: Run your first safe robot motion and understand that code sends target positions to robot joints.

What students edit: Students change a small motion value or timing value after running the starter version.

Concepts

• Motion commands
• Neutral pose
• Safe movement
• Terminal command
• Observation before editing

Starter command

Steps

1. Connect to the robot through VS Code and SSH.
2. Open the lab file.
3. Run the starter command without editing anything.
4. Observe which part of the robot moves.
5. Change one allowed value.
6. Run the lab again.
7. Return the robot to idle.

Expected result

The robot performs a small safe motion, such as moving an arm or head, then returns to a neutral pose.

Reflection question

What changed physically when you changed the code value?

Extension challenge

Add a second safe motion after the first one, then return the robot to idle.

Lab 02: Servo Angles and Safe Limits

Goal: Understand that each joint has safe angle limits and that robot motion should stay inside tested ranges.

What students edit: Students adjust allowed servo target values inside a provided safe range.

Concepts

• Servo range
• Joint limits
• Mechanical safety
• Angle values
• Safe testing

Starter command

Steps

1. Open the lab file and find the safe angle range.
2. Run the starter motion.
3. Change the angle slightly within the allowed range.
4. Run the motion again.
5. Compare small changes to larger changes.
6. Return the joint to neutral.
7. Write down why random angles are unsafe.

Expected result

Students see that small code changes can create visible joint movement, but only within safe mechanical limits.

Reflection question

Why should a robot program use safe limits instead of sending any angle directly to a servo?

Extension challenge

Create a helper function that rejects values outside the safe range.

Lab 03: Build a Gesture Sequence

Goal: Create a small gesture by combining multiple safe poses with timing delays.

What students edit: Students reorder poses, adjust delays, and add one extra gesture step.

Concepts

• Sequences
• Timing
• Poses
• Reusable functions
• Human-readable robot behavior

Starter command

Steps

1. Run the starter gesture.
2. Identify each pose in the sequence.
3. Change one delay value.
4. Add one new pose from the provided safe pose list.
5. Run the new sequence.
6. Check whether the gesture still looks smooth.
7. Return the robot to idle.

Expected result

The robot performs a short custom gesture using multiple poses.

Reflection question

How does timing change the way a robot gesture feels to a person watching it?

Extension challenge

Create two versions of the same gesture: one that looks calm and one that looks excited.

Lab 04: Head Tracking Basics

Goal: Move the robot head left, center, or right based on a simple target position.

What students edit: Students adjust zone thresholds and head yaw values.

Concepts

• Neck yaw
• Neck pitch
• Camera target position
• Mapping input to motion
• Simple tracking behavior

Starter command

Steps

1. Run the starter head tracking script.
2. Move the target between left, center, and right zones.
3. Observe how the head responds.
4. Change one threshold value.
5. Change one head yaw value within the safe range.
6. Run the script again.
7. Return the head to center.

Reflection question

What is the difference between detecting where something is and deciding how far the robot should move?

Extension challenge

Add a small delay so the head movement feels smoother and less twitchy.

Lab 05: Button-to-Motion Control

Goal: Connect a keyboard input or simple button event to a robot motion.

What students edit: Students map different inputs to different safe robot actions.

Concepts

• Events
• Input handling
• Calling robot actions
• Safety stop
• Simple control interface

Starter command

Steps

1. Run the starter input script.
2. Press the provided key to trigger a motion.
3. Find where the input is checked in the code.
4. Add a second input option.
5. Map the second input to a different safe pose.
6. Test both inputs.
7. Use the stop key before ending the lab.

Reflection question

Why is it useful to separate input handling from the actual robot motion function?

Extension challenge

Add a simple menu that shows which keys trigger which motions.

Lab 06: RealSense Detection Basics

Goal: Use RealSense camera data as a trigger for a simple robot behavior.

What students edit: Students adjust a detection zone or distance threshold.

Concepts

• Camera input
• Detection zones
• Depth and distance
• Perception-triggered motion
• False positives

Starter command

Steps

1. Start the camera-based lab.
2. Place a target or user inside the detection area.
3. Observe when the robot triggers a response.
4. Adjust the detection distance or zone.
5. Run the test again.
6. Compare reliable and unreliable trigger conditions.
7. Return the robot to idle.

Reflection question

Why should camera-based triggers be conservative when the robot is near people?

Extension challenge

Add a timeout so the robot returns to idle if the target disappears.

Lab 07: Hand Pose Timing

Goal: Adjust hand and finger timing to understand how small delays affect robot gestures.

What students edit: Students change finger pose timing, open/close delays, or gesture order.

Concepts

• Finger servo poses
• Timing
• Grip and release
• Gesture realism
• Small motion changes

Starter command

Steps

1. Run the starter hand pose.
2. Observe how quickly the fingers move.
3. Change one timing delay.
4. Run the gesture again.
5. Change the order of two finger movements.
6. Compare which version looks more natural.
7. Return the hand to relaxed pose.

Reflection question

Why can timing make a robot motion feel more natural even if the final pose is the same?

Extension challenge

Create a small hand gesture that looks like a count-in or signal.

Lab 08: Base Rotation Basics

Goal: Command the robot's rotating base to turn left or right safely.

What students edit: Students adjust direction, duration, or speed values inside safe limits.

Concepts

• Base yaw
• Motor control
• Direction
• Speed
• Stop command

Starter command

Steps

1. Make sure the robot base area is clear.
2. Run the starter base rotation command.
3. Observe direction and stopping behavior.
4. Change the direction.
5. Change the duration slightly.
6. Run the test again.
7. Send the stop command.

Reflection question

Why should base motion always include a clear stop condition?

Extension challenge

Create a turn-left, pause, turn-right sequence.

Lab 09: Behavior Priority and Motion Locking

Goal: Understand why one robot behavior should not interrupt another motion at the wrong time.

What students edit: Students test simple behavior priority rules and see how a motion lock protects a running action.

Concepts

• Motion lock
• Behavior priority
• State control
• Safe cancellation
• Competing commands

Starter command

Steps

1. Run the starter behavior.
2. Trigger a second behavior while the first is active.
3. Observe whether the second behavior is blocked or delayed.
4. Find the motion lock in the code.
5. Change the priority of one behavior.
6. Run the test again.
7. Return the robot to idle.

Reflection question

What could go wrong if two scripts tried to control the same arm at the same time?

Extension challenge

Add a low-priority idle behavior that pauses when a higher-priority demo starts.

Lab 10: Mini Demo Challenge

Goal: Combine motion, timing, and optional perception into a small custom robot demo.

What students edit: Students create their own short behavior using safe poses and at least one idea from earlier labs.

Concepts

• Project planning
• Code reuse
• Debugging
• Demo presentation
• Behavior design

Starter command

Steps

1. Choose a simple demo idea.
2. Pick which robot parts will move.
3. Start from a provided safe template.
4. Add two or more motion steps.
5. Add timing between steps.
6. Test one part at a time.
7. Prepare a short explanation of how the demo works.

Expected result

Students build and run a short custom robot behavior that they can explain.

Reflection question

What part of your demo was easiest to control, and what part needed the most debugging?

Extension challenge

Add camera input or user input to trigger the demo.

Lab 11: Simple State Machines

Lab 12: Custom Motion Presets

Lab 13: Camera-Based User Greeting

Lab 14: Object Position Mapping

Lab 15: Two-Arm Coordination

Lab 16: Speaker Prompts and Timing

Lab 17: Classroom Challenge: Helpful Robot

Lab 18: Intro to Robot Debug Logs

Lab 19: Build Your Own Interaction

Lab 20: Final Showcase Demo

ROS 2 Concepts

The Learning Hub introduces ROS 2-style ideas through SwayForm examples. Students do not need to memorize every term immediately. They should understand how information moves through the robot system.

Node

A node is a program that does one part of the robot's work. A camera node might read vision data. A motion node might control joint movement. A demo script might decide what behavior to run.

Topic

A topic is a named stream of information. One part of the robot can publish information, and another part can listen to it.

Publisher

A publisher sends information onto a topic. For example, a camera node might publish target position data.

Subscriber

A subscriber listens for information from a topic. A behavior script might subscribe to vision data and react when a user is detected.

Service

A service is a request-and-response interaction. A script can ask for something specific, such as requesting a safe motion or checking a system status.

Launch file

A launch file starts multiple parts of the robot system together. Instead of opening many terminals manually, a launch file can start the needed nodes in one workflow.

Motion node

The motion node is the part of the system responsible for receiving movement requests and turning them into safe joint commands.

Behavior script

A behavior script decides what the robot should do. For example, the wave demo is a behavior script that sends a sequence of arm movements to the motion system.

Motion Node

The motion node is the part of the robot software that helps turn behavior requests into controlled movement.

A demo should not directly throw random values at every servo. Instead, a behavior should ask for safe poses, joint groups, or controlled movement sequences. The motion layer helps keep robot behavior predictable.

Why this matters

If two behaviors try to control the same arm at the same time, the robot can move in a confusing or unsafe way. The motion node and motion lock idea help organize which behavior is allowed to control the robot.

A wave script can request the right arm. A handshake script can request the same arm. The system should not allow both to command the arm at the same time.

Servo Mapping

Servo mapping connects human-readable joint names to the physical servo channels used by the robot.

Students should not need to memorize every channel number at the beginning. They should learn that a name like right_elbow_pitch points to a real actuator inside the robot.

Example idea

When a script says right_elbow_pitch, the robot software knows which servo controller and channel should receive that command.

RealSense Camera

The RealSense camera gives SwayForm visual input for classroom demos and labs.

Camera data can be used to detect that a user is nearby, estimate where a target appears in the frame, or trigger a robot behavior. Early labs should keep vision simple and reliable instead of pretending the robot understands everything it sees.

Learning Hub use cases

• Detecting that someone is in front of the robot.
• Checking whether an object is in a target zone.
• Turning the head toward a left, center, or right region.
• Starting a behavior when a condition is met.

Troubleshooting

Robotics debugging is part software, part hardware, and part workflow. Most beginner issues come from connection problems, workspace setup, wrong commands, or another process already running.

Glossary

Quick definitions for terms used throughout the Learning Hub.