Merge pull request #581 from iRobotEducation/shamlian/add_lessons

Add lessons to docs from learning library

docs/lessons/getting-started.md

@@ -0,0 +1,6 @@
+# Getting Started with the Create® 3 Robot
+## Details
+Use these resources to get started with Create® 3 Educational Robot, the next generation of iRobot’s affordable, trusted, all-in-one mobile robot development platform. Grasp the fundamentals of robotics, computer science, and engineering by programming the Create® 3 robot to perform simple behaviors, sounds, and movements, or tap into advanced applications including multi-robot exploration, navigation & mapping, and telepresence capabilities.
+
+* [Create 3 Getting Started Manual](./Create3-Welcome-Guide.pdf)
+* [Create 3 Discussion Forum](https://github.com/iRobotEducation/create3_docs/discussions)

docs/lessons/pwp/c3-phone-home.md

@@ -0,0 +1,33 @@
+# C3, Phone Home
+## Details
+Use a coordinate system to command your robot to return to its starting position.
+### Downloads and Resources
+* [PDF: C3, Phone Home Activity Sheet](./Create3-C3_Phone_Home.pdf)
+
+## The Main Idea
+The Create® 3 robot keeps track of its position on an invisible coordinate grid as it moves around. This feature can be particularly handy when you’d like to tell your robot to drive to a specific set of coordinates, landmark, etc. Here we will use the invisible coordinate system to tell your robot to return to its starting position after roaming around a room.
+
+## Project Steps
+1. Remove your robot from the Home Base™ Charging Dock and place it on an empty space on the floor. This starting position will be registered as (0, 0) by the robot when you press “Play” on your program.
+
+2. Create a program that drives the robot forward until it bumps into an obstacle. With a bump event, back up a few centimeters and then use await robot.navigate_to(0 , 0) to send your robot back to its original starting point. See the example below for help:
+```
+@event(robot.when_play)
+async def play(robot):
+    await robot.set_wheel_speeds(25, 25)
+
+@event(robot.when_bumped, [True, True])
+async def when_bumper(robot):
+    await robot.move(-15)
+    await robot.navigate_to(0, 0)
+
+robot.play()
+```
+3. Press play to watch your robot drive forward until it bumps into an obstacle. Once it bumps, it should reverse, turn around and drive back to its original starting position.
+
+## Going Further
+Can you use the command await robot.get_position() to program your robot to list the coordinates of the obstacles it bumps into? How might you turn that list into a basic map?
+
+Try combining the navigate_to() commands with the Create® 3 Light Painting Activity to create precise drawings from a coordinate grid.
+
+Try measuring out your robot’s arena in centimeters and placing stickers or other flat landmarks down on specific coordinates. Program your robot to drive to each of the coordinates. How similar are you measurements?

docs/lessons/pwp/cheat-sheets.md

@@ -0,0 +1,93 @@
+# Python Cheat Sheets
+## Details
+Reference resources to support coding in the iRobot Education Python[^1] Web Playground.
+
+### Downloads and Resources
+* [PDF: Syntax Cheat Sheets](./pwp-sdk_commands.pdf)
+
+## Get Started
+1. Visit python.irobot.com in a Bluetooth®-supported web browser, such as Google Chrome.
+1. Explore the pre-loaded example code file. If you have a robot, turn it on and ensure your computers Bluetooth is activated. Press the connect button and select your robot from the browser's Bluetooth devices menu. Press 'Pair' and close the window.
+1. Press the play button in the top-left section of the Python Playground window to run the example code.
+1. Press the stop button to stop the code project.
+1. Explore our menu of example projects to the right of the screen.
+1. Explore the Learning Library for other exciting projects compatible with the Python Playground.
+
+## Python Explanation
+Since the python syntax may be a bit different than what you're used to (asyncio), there are some notes on some common points of confusion surrounding this event loop structure. This framework executes each function, but it does so out of order to become more efficient
+### Events
+If a function is "decorated" by @event, then once the "event" is triggered, all of those functions will occur simultaneously. For example, if multiple functions are decorated as "@event(robot.when_play)," then whenever "robot.play()" is written in the script, it will trigger all functions with that event tag. In functions used with events, you must use "async" due to the nonparallel nature. This is telling the script that we don't necessarily want to run that function right now. We want to call it when we want all the events to happen together, not in a partiuclar order. In other words, it is "asyncronous." Because of this, we don't use return values with event functions. Since all the event functions happen at the same time, we would never care to use the return value of one of them.
+
+Whenever you want a function to be decorated by @event, you must use async in front of def. Since we want to run these functions when the event tag is called, it is an asynchronous function, thus never running when we get to it in the script. For example:
+```
+@event(robot.when_play)
+    async def move(robot):
+
+@event(robot.when_play)
+    async def color(robot):
+
+robot.play()
+```
+The `robot.play()` line starts the robot's event system. It triggers all the functions decorated with @event(robot.when_play). Additionally, it will listen for other events like the ones associated with sensors. See max_obstacles.py, instrument.py, or bumper_control.py for full example. Each function that is triggered will run "in parallel," meaning they will all run at the same time. Normally, python scripts will run each function in the order that it reads. The events allow us to run functions at the same time or out of order, instead of one by one.
+
+Since the robot uses a few different sensors, now we can take advantage of all of them at once. We don't have to wait to run the bumpers if we are using the IR sensors.
+
+We can use the normal "def" format if we want to run that function to access its return value later. See max_obstacles.py as an example.
+
+### Async
+Async functions can suspend their execution before reaching return, and move to run a different function in that time. You can use async with or without an event decorator. This is when you have a function that you don't want to run immediately in the script (such as the normal "def" function) or if you want to run when the event is called. Async is used with a function that is called later, usually in an event function. Async functions can have return values. If you want to run a function where it is in the script, use def. If you want it to run asynchronously and run when you call it, used async def. If you use methods, put an "await" in front. "Await" can only be used in an async def function. For example:
+```
+async def forward(robot):
+  await robot.set_wheel_speeds(speed, speed)
+
+async def sensors(robot):
+  sensors = (await robot.get_ir_proximity()).sensors
+  avg = sum(sensors)/len(sensors)
+  return avg
+
+@event(robot.when_play)
+async def play(robot):
+  await forward(robot)
+
+robot.play()
+```
+
+### Class
+Class:
+A function in a class is called a method. Each method receives the 'self' parameter. In the example below, the parameter "name" is stored in the property "self.name". You can have multiple classes in a script. They can be used to organize the functions in your code. For example:
+
+```
+class my_robot:
+  def __init__(self, name):
+    self.name = name
+
+  def message(self, color):
+    print('I am ' + str(color))
+```
+
+Methods:
+The robot's methods are all called with await. Methods are lines that tell the robot to do specific actions. It basically just means wait for this to occur until called. Examples of what methods look like:
+
+```
+robot.set_wheel_speeds(speed, speed)
+# or
+robot.set_lights_rgb(255, 0, 0)
+# or
+robot.arc(Robot.DIR_LEFT, large_angle, arc_speed)
+```
+
+Methods should follow the await term such as:
+
+```
+await robot.set_wheel_speeds(speed, speed)
+```
+
+## TL/DR:
+* async is used with events
+* When methods are in async functions, use await
+* def and async def can have return values, but not when tagged by an event
+* events happen simultaneously
+* event functions don't use return values
+
+[^1]: Python is governed by the Python Software Foundation.
+[^2]: All trademarks mentioned are the property of their respective owners.

docs/lessons/pwp/integrating-airtable.md

@@ -0,0 +1,91 @@
+# Integrating AirTable with the Python Web Playground
+## Details
+Reference resources to support coding in the iRobot Education Python[^1] Web Playground.
+
+### Downloads and Resources
+* [Link: Python Web Playground](http://python.irobot.com/)
+* [Link: Airtable](http://airtable.com/)
+
+## Integrating Airtable into the Python Web Playground
+### Setting Up Your Airtable
+1. Visit airtable.com and make an account.
+1. Create a new Airtable base named "Python Playground Controller"
+![AddBase](./airtable/add-a-base.png)
+![NameBase](./airtable/name-base.png)
+1. Name the new base's first table "PlaygroundInfo"
+![PlaygroundInfo](./airtable/playground-info.png)
+1. In cell 1, Type the word "Forward"
+![Forward](./airtable/forward.png)
+1. Navigate to the top-left corner of the page and click "Help"
+![Help](./airtable/help.png)
+1. At the bottom, click "API Documentation." This page shows the details for connecting your Airtable base to other connected apps using the REST API. Here, we will gather some unique identifiers for your base so that we can identify it with the Python Playground.
+![API Documentation](./airtable/api-documentation.png)
+1. Next, navigate to the top-left corner and activate the "Show Your API" option. This will show your account's API Key in the links on the page. Make sure to keep this key private, as it carries the same access as your username/password!
+![OpenBase](./airtable/open-base.png)
+1. Scroll to find your API Key and the curl URL. Save both strings for later.
+![Auth](./airtable/auth.png)
+
+### Building Your Python Playground Project
+1. Open python.irobot.com.
+1. Highlight and delete the starter code so you are left with an empty code screen.
+1. Copy and paste the below code snippet into the Python Playground. NOTE: The indent formatting may be incorrect on this website. Update your copy & pasted code with the indent spacing shown in the screenshot below in Editing Your Python Playground Project.
+```
+#
+# Licensed under 3-Clause BSD license available in the License file. Copyright (c) 2021 iRobot Corporation. All rights reserved.
+#
+
+from irobot_edu_sdk.backend.bluetooth import Bluetooth
+from irobot_edu_sdk.robots import event, hand_over, Color, Robot, Root, Create3
+from irobot_edu_sdk.music import Note
+from pyodide.http import pyfetch
+
+robot = Root(Bluetooth()) # Will connect to the first Root Robot found.
+#robot = Create3(Bluetooth()) # Will connect to the first Create Robot found.
+
+@event(robot.when_play)
+async def play(robot):
+    i = 0 # Debug: just to be sure that the program is iterating properly.
+    while True:
+    print(i)
+    i += 1
+  response = await pyfetch('INSERT CURL URL HERE')
+  j = await response.json()
+  # print(j['records'])
+  for record in j['records']:
+  print(record) # Debug.
+  if record and record['fields']:
+  if record['fields']['Name'] == 'Forward':
+  print('Forward!')
+  await robot.set_wheel_speeds(10, 10)
+  elif record['fields']['Name'] == 'Spin':
+  print('Spin!')
+  await robot.set_wheel_speeds(5, -5)
+  elif record['fields']['Name'] == 'Stop':
+  print('Stop!')
+  await robot.set_wheel_speeds(0, 0)
+robot.play()
+```
+
+### Editing Your Python Playground Project
+1. If you are using the Root Coding Robot, you can leave the template as-is. However, if you are using the Create® 3 Educational Robot, change lines 14 and 15 to the following code snippet:
+```
+#robot = Root(Bluetooth()) # Will connect to the first Root Robot found.
+robot = Create3(Bluetooth()) # Will connect to the first Create Robot found.
+```
+1. Next, copy your Airtable's curl URL and use it to replace the URL inside the single-quotation marks in line 24.
+![PWP Screenshot](./airtable/pwp-screenshot.png)
+
+### Playing Your Program
+1. Open the Python Playground and your Airtable base side-by-side.
+1. Now that your project and database are set up, click "Connect" to pair with your robot. Make sure that your robot is powered on!
+1. Press Play to start your project. Because your Airtable entry says "forward," the robot should begin to drive forward.
+1. Try controlling your robot by typing Forward, Stop, and Spin into cell 1 in your Airtable!
+    * Forward drives the robot forward at 10 cm/s
+    * Stop stops your robot's wheels
+    * Spin rotates your robot clockwise at 5 cm/s
+
+### Going Further
+You can take this project further by integrating your Airtable with other internet-connected tools. For example, on Thunkable.com, you can use drag-and-drop block code to create a mobile app that updates the values in your Airtable. From there, you can turn your phone into a remote control for your robot!
+
+[^1]: Python is governed by the Python Software Foundation.
+[^2]: All trademarks mentioned are the property of their respective owners.

docs/lessons/pwp/light-painting.md

@@ -0,0 +1,6 @@
+# Light Paint with the Create® 3 Robot
+## Details
+Use long-exposure light photography, paired with the Create® 3 Robot, to create EPIC robot-infused light paintings.
+
+### Downloads and Resources
+* [PDF: Light Paint with Create® Robot Lesson Plan](./Create3-Rainbow_Light_Painting.pdf)

docs/lessons/pwp/robot-dance-recital.md

@@ -0,0 +1,9 @@
+# Create® 3 Robot Dance Recital
+## Details
+Use the Create® 3 and the iRobot Education Python[^1] Web Playground to code your robot to dance the Hokey Pokey. Looking for more? Take your new choreography skills to new heights and code a dance to your own song!
+
+### Downloads and Resources
+* [PDF: Robot Dance Recital](./Create3-Robot_Dance_Recital.pdf)
+
+[^1]: Python is governed by the Python Software Foundation.
+[^2]: All trademarks mentioned are the property of their respective owners.

docs/lessons/pwp/sound-off-1-2.md

@@ -0,0 +1,43 @@
+# Sound Off, 1-2
+## Details
+Code your Create® 3 Robot to play musical tones and respond to button presses and other sensor input.
+### Downloads and Resources
+* [PDF: Sound Off, 1-2 Activity Sheet](./Create3-Sound_Off.pdf)
+
+## The Main Idea
+Robots can play musical notes by emitting sounds of different frequencies and durations. These notes can be strung together in a sequence to play simple melodies, which are used to help the robot communicate its status. A “Happy Sound” can communicate “I am ready to run,” while an “Angry Sound” can mean “I am experiencing a problem.” Explore programming different notes and melodies to give your robot its own voice!
+
+## Project Steps
+1. Locate Button 1 and Button 2 in the Create® 3 button suite. In the code, trigger an event for Button 1 and 2 press with these commands:
+```
+@event(robot.when_touched, [True, False]
+async def when_touch_fl(robot):
+    pass
+
+@event(robot.when_touched, [False, True]
+async def when_touch_fr(robot):
+    pass
+```
+
+2. Use the command await robot.play_note(440, 0.25) to play an A4 quarter note. The first parameter determines the note frequency and the second parameter determines note duration (in seconds). Explore playing different notes with our Python[^1] Note Frequencies Guide.
+
+3. Under a Button 1 event, list at least three notes together in a sequence to create a “happy sound” melody. Our example snippet is below:
+```
+@event(robot.when_touched, [True, False])
+async def when_touch_fl(robot):
+    await robot.play_note(F4, .125)
+    await robot.play_note(G4, .125)
+    await robot.play_note(A4, .125)
+```
+
+4. Under a Button 2 event, list at least three notes together in a sequence to create an “angry sound.” When finished, you have the beginnings of a robot personality!
+
+## Going Further
+Take your robot’s personality to new heights by programming it to “grumble” and “shout” via angry melodies when it bumps into obstacles as it drives around the room.
+
+OR
+
+Transform your robot into a random guess machine! Create a program that will randomly play a happy or angry sound when a button is pressed. Use the robot to answer Yes or No questions randomly.
+
+[^1]: Python is governed by the Python Software Foundation.
+[^2]: All trademarks mentioned are the property of their respective owners.

docs/lessons/pwp/web-playground.md

@@ -0,0 +1,41 @@
+# Create® 3 Robot + Web Playground for Python
+## Details
+You can connect to the Create® 3 Educational Robot via Bluetooth[^1] and run your first program in a browser through the Python[^2] Web Playground. Follow the instructions to connect, run and explore!
+
+### Downloads and Resources
+* [PDF: Python Web Playground First Project](./Python-Web-Playground_First-Project.pdf)
+* [Video: Run Your First Python Web Playground Project with Create 3](https://bcove.video/3wY40IC)
+* [Link: Python Web Playground](https://python.irobot.com/)
+
+## Coding The First Project - Python Web Playground
+Important Note: If running multiple Create® robots, complete all of the steps below for one robot at a time to avoid connection errors.
+### You’ll Need:
+* Home Base® Charging Dock
+* Charging Dock Cable
+* Create® 3 Educational Robot
+* Computer with Bluetooth™ Compatibility (i.e. [Google Chrome Browser](https://www.google.com/chrome/))
+
+### Step 1
+Confirm that your computer’s Bluetooth™ setting is [“on.”](https://support.microsoft.com/en-us/windows/turn-bluetooth-on-or-off-in-windows-9e92fddd-4e12-e32b-9132-5e36bdb2f75a)
+
+### Step 2
+Power on your robot. Wait for your robot to fully boot up and play its “Happy Sound” before proceeding.
+
+### Step 3
+Confirm that your robot is in Bluetooth Mode. You can check this by looking for a blue light glowing through the faceplate on the back-right side of your robot. If no blue light is glowing, remove the faceplate and manually set the switch on the Adaptor Board to the Bluetooth logo on the right.
+
+### Step 4
+Open Google Chrome in a new window and navigate to [python.irobot.com](http://python.irobot.com/).
+
+### Step 5
+Click on the Connect button to open the Google Chrome Bluetooth manager. Your robot should appear in the device menu after ~30 seconds under its default device name, or as “Unsupported Device.” Select the robot’s name and click the Pair button.
+
+### Step 6
+Press play to run the example code project. Try pressing your robot’s bumpers. When you press on the right side of the bumper, your robot’s Ring Light should glow yellow and the robot should begin to spin clockwise. What happens when you press on the left side?
+
+### Step 7
+Congratulations, you have run your first python web program! To go further, explore our example code snippets and the Python Web Playground glossary to learn more about all of the available commands. Happy Coding!
+
+[^1]: The Bluetooth® word mark and logos are registered trademarks owned by Bluetooth SIG, Inc. and any use of such marks by iRobot is under license.
+[^2]: Python is governed by the Python Software Foundation.
+[^3]: All trademarks mentioned are the property of their respective owners.

docs/lessons/ros2/intro/creating-packages.md

@@ -0,0 +1,9 @@
+# Intro to ROS 2: Creating Packages
+## Details
+In this tutorial, Maddie and Kate walk you through the basics of creating a custom ROS 2[^1] package.
+
+### Downloads and Resources
+* [Video: Creating a ROS 2 Package](https://bcove.video/3FZoaq3)
+
+[^1]: ROS 2 is governed by Open Robotics
+[^2]: All trademarks mentioned are the property of their respective owners.

docs/lessons/ros2/intro/serial-communication.md

@@ -0,0 +1,9 @@
+# Intro to ROS 2: Serial Communication with the Create® 3 Robot
+## Details
+In this tutorial video, review the basics of communicating over a serial port with the Create® 3 robot in order to connect external hardware and other attachments!
+
+### Downloads and Resources
+* [Video: Serial Communication Tutorial](https://bcove.video/3TyfQ3K)
+
+[^1]: ROS 2 is governed by Open Robotics
+[^2]: All trademarks mentioned are the property of their respective owners.