This codelab provides a suggested delivery plan and resources for instructors interested in delivering a hands-on workshop. Take these resources, and make it your own!

Workshop Overview

• Goal: Introduce components and services as concepts and operate a rover base using an SDK
• Audience: Beginner developers with basic programming and hardware skills
• Duration: ~2-3 hours

What You'll Teach

• How to build a TypeScript application to control a machine in Viam.

Watch the Video

See a demonstration of controlling the rover using a TypeScript app in this video.

Review the list of required components (hardware, software), and determine which materials are provided or required for participants to bring on their own. Provide instructions to participants, giving them ample time to prepare and complete prerequisites.

Hardware and supplies requirements

• 1 - Viam rover
• 1 - Raspberry Pi 4
• 1 - USB flash drive or microSD card to use with the Pi on the rover, along with an adapter or reader
• 4 - 18650 batteries (with charger) or an RC type battery with dimensions no greater than 142mm x 47mm x 60mm (LxWxH) (with charger)

Software and other device requirements

• A Linux, macOS or Windows computer that can run SDK code
• Preferred IDE, such as VS Code
• Node.js installed
• Sign up for a free Viam account, and then sign in to the Viam app

Learning Objectives

Review the suggested learning objectives, and adjust it according to your goals and audience.

• How to use environment variables with your Viam machine
• How to implement reusable configuration fragments
• How to use the Viam TypeScript SDK to control your machine

Agenda

Review the suggested agenda, and adjust it according to your goals and audience.

• Introduction (10 mins)
• Hardware Assembly (30 mins)
• Software Setup (30 mins)
• Hands-On Experiment (40 mins)
• Q&A/Wrap-Up (10 mins)

Pre-workshop checklist ✅

Review these setup steps as you're planning the workshop to help prepare for it.

1. Planning and Logistics
   • Verify equipment inventory: Decide which materials are provided or required for participants to bring on their own. Order any materials and supplies that are provided to participants.
   • Determine rover allocation for individuals, groups, or virtual access: Determine whether rovers are provided for each participant, group of participant, or accessed virtually through Viam's Try Viam experience or at another external location.
   • Confirm workstation setup: Verify the workshop room layout supports hardware work, such as tables, and space to drive the rovers. Ensure participants have power outlets and internet access. Have spare supplies, such as Raspberry Pis, adapters/readers, and cables, in case of failures. For virtual workshops, confirm logistics for breakout sessions, providing support, and checkpoints.
   • Communicate prerequisites: Share a participant guide prior to the workshop with learning objectives and instructions for installing software and preparing laptops. Provide a checklist for participants to confirm readiness.
   • Establish support channels: Determine how participants can get support for real-time troubleshooting (e.g. Slack or Discord channel for virtual workshops, additional helpers in the room for on-site workshops)
   • Request Viam stickers: Don't forget to request Viam stickers for the workshop.
2. Content Preparation
   • Prepare workshop teaching materials: Review the Delivery Plan, sample slide deck, and provided resources. Tailor these materials to suit your participants' needs. Decide whether to present them to the group or provide them for independent reference, such as through a web browser or printed handouts.
   • Determine extensibility: During the Hands-on Experiment portion of the delivery plan, there are many options to guide the workshop on a different learning path. Determine if this section will be self-guided exploration, a group exercise, or self-paced learning for participants to explore on their own after the workshop.
   • Prepare code and documentation: Review the provided code and add comments as necessary.
   • Review discussion topics: Review the suggested group discussion topics and adjust for your participants.
   • Review quiz questions: Review the suggested quiz questions and adjust for your participants. Determine if knowledge assessment will be completed throughout the workshop or afterwards.
3. Dry Run and Testing
   • Test the workshop project: Run through the build following the prepared documentation to ensure it works as expected. Simulate common issues and prepare troubleshooting tips for these scenarios. If physical space is limited, consider sharing a rover or setting up the rover in a remote location to be viewed through a webcam.
   • Bring backups: In addition to the backup supplies mentioned earlier during planning, make sure batteries are charged.

Feel free to make a copy of this sample slide deck, customize it, and make it your own.

During the workshop, instructors can present this customizable slide deck (see above) tailored to your specific workshop needs. Alternatively, learners can follow step-by-step instructions and checkpoints independently by referencing the pages linked below in a web browser.

1. Hardware Assembly
   • Set up your Raspberry Pi
   • Set up your Viam rover
2. Software Setup
   • Configure your machine
   • Configure your Viam rover with a fragment
   • Test drive your rover
3. Hands-On Experiment
   • Control your rover with TypeScript
   • Customize your TypeScript web application

Set up your Raspberry Pi

The Raspberry Pi boots from a USB flash drive (or microSD card). You need to install Raspberry Pi OS on a USB flash drive that you will use with your Pi. For more details about alternative methods of setting up your Raspberry Pi, refer to the Viam docs.

Install Raspberry Pi OS

1. Connect the USB flash drive (or microSD card) to your computer.
2. Download the Raspberry Pi Imager and launch it.
3. Click CHOOSE DEVICE. Select your model of Pi, which is Raspberry Pi 4.
4. Click CHOOSE OS. Select Raspberry Pi OS (64-bit) from the menu.
5. Click CHOOSE STORAGE. From the list of devices, select the USB flash drive you intend to use in your Raspberry Pi.
6. Configure your Raspberry Pi for remote access. Click Next. When prompted to apply OS customization settings, select EDIT SETTINGS.
7. Check Set hostname and enter the name you would like to access the Pi by in that field, for example, rover.
8. Select the checkbox for Set username and password and set a username (for example, your first name) that you will use to log into the Pi. If you skip this step, the default username will be pi (not recommended for security reasons). And specify a password.
9. Connect your Pi to Wi-Fi so that you can run viam-server wirelessly. Check Configure wireless LAN and enter your wireless network credentials. SSID (short for Service Set Identifier) is your Wi-Fi network name, and password is the network password. Change the section Wireless LAN country to where your router is currently being operated.
10. Select the SERVICES tab, check Enable SSH, and select Use password authentication.
11. Save your updates, and confirm YES to apply OS customization settings. Confirm YES to erase data on the USB flash drive. You may also be prompted by your operating system to enter an administrator password. After granting permissions to the Imager, it will begin writing and then verifying the Linux installation to the USB flash drive.
12. Remove the USB flash drive from your computer when the installation is complete.

Connect with SSH

1. Place the USB flash drive into your Raspberry Pi and boot the Pi by plugging it in to an outlet. A red LED will turn on to indicate that the Pi is connected to power.
2. Once the Pi is started, connect to it with SSH. From a command line terminal window, enter the following command. The text in <> should be replaced (including the < and > symbols themselves) with the user and hostname you configured when you set up your Pi.

   ssh <USERNAME>@<HOSTNAME>.local
   

3. If you are prompted "Are you sure you want to continue connecting?", type "yes" and hit enter. Then, enter the password for your username. You should be greeted by a login message and a command prompt.
4. Update your Raspberry Pi to ensure all the latest packages are installed

   sudo apt update
   sudo apt upgrade
   

Enable communication protocols

1. Launch the Pi configuration tool by running the following command

   sudo raspi-config
   

2. Use your keyboard to select "Interface Options", and press return.
3. Enable the relevant protocols to support our hardware. Enable the I2C protocol on your Pi to get readings from the power sensor anc accelerometer when controlling your rover. Select I2C enabled.
4. Confirm the options to enable the serial login shell and serial interface. And reboot the Pi when you're finished.

   sudo reboot
   

Set up your Viam rover

Follow these steps to assemble your Viam rover.

1. Add the power supply: Turn the rover over so that you can see the battery housing. Place four 18650 batteries (taking care to ensure correct polarity orientation) inside the battery pack to provide power to the rover, which can be turned on and off through the power switch.
2. To be able to attach the Raspberry Pi, unscrew the top of the rover with the biggest Allen key.
3. Use the smallest Allen key and the provided M2.5 screws to attach the Raspberry Pi to your rover through the standoffs on the motherboard. The Raspberry Pi 4 should be mounted such that the USB ports are to the right, as viewed from above.
4. Use the ribbon cable to connect the Raspberry Pi 4 to the motherboard.
5. Connect the webcam's USB lead to any USB port on your Pi.
6. Screw the top plate back on with the biggest Allen key.
7. Use the power switch to turn the rover on. Wait a second the rover motherboard to power on. If the Pi has power, the lights on the Raspberry Pi will light up.

Configure your machine

1. In the Viam app under the LOCATIONS tab, create a machine by typing in a name and clicking Add machine.
2. Click View setup instructions.
3. Install viam-server on the Raspberry Pi device that you want to use to communicate with and control your rover. Select the Linux / Aarch64 platform for the Raspberry Pi to control the rover, and leave your installation method as viam-agent.
4. Use the viam-agent to download and install viam-server on your Raspberry Pi. Follow the instructions to run the command provided in the setup instructions from the SSH prompt of your Raspberry Pi. The setup page will indicate when the machine is successfully connected.

Configure your Viam rover with a fragment

1. In the Viam app, find the CONFIGURE tab. It's time to configure your hardware.
2. Click the + icon in the left-hand menu and select Insert Fragment to browse the available configuration fragments.
3. Select ViamRover2-2024-rpi4-a.
4. Click Insert fragment again to add the fragment to your machine.
5. Notice adding this fragment adds several hardware components to your machine's JSON configuration. Each component is listed in the left sidebar, along with a corresponding panel on the right with more details.
6. Click Save in the top right to save and apply your configuration changes.

Test drive your rover

1. Under the CONFIGURE tab of the Viam app, some resources have a TEST section on the bottom half of their configuration pane which you can expand and interact with to test out controlling the component. When you configure a component on the CONFIGURE tab, it will also appear on the CONTROL tab which gives you an interface to interact with it.
2. Find the CONTROL tab. This is where you can control your Viam rover. Find the viam_base in the left sidebar, and click on it. Notice the components in the left sidebar correspond to a more detailed view on the right side of the page.
3. Within the viam_base card, toggle on the Keyboard control so that you can control the rover using keyboard keys WASD.
4. Continue exploring the different components of your rover.

Control your rover with TypeScript

Now that you know how to manually control the rover using the Viam app, let's control the rover programmatically with code using one of Viam's SDKs. You can run control code from anywhere; it does not necessarily have to be run on the same machine that runs viam-server.

1. From the command line within your terminal window of your laptop (not SSH'd into your Pi), let's use a command line utility to quickly set up a new TypeScript project. Input the following command:

   $ npm create robot-app
   

2. At the command-line prompt, input your project name. Or hit Enter to accept the default project name, my-viam-project.
3. Select the project template controlRover, and hit Enter.
4. Once the project setup is completed, follow the command-line instructions. Navigate into your new project directory. In the example shown below, we are using the default project name my-viam-project.

   $ cd my-viam-project
   

5. In the Viam app, find the CONNECT page, select the TypeScript SDK, and turn on Include API key to reveal your machine credentials within the code sample. Use these machine credentials to update the .env file in your new project directory, and save your changes.
6. Start the application server. Your web app should be running at http://localhost:5173/

   $ npm start
   

7. Open your browser's devtools, for example, by right-clicking and selecting Inspect, to see the browser's console logs. Make sure there is adequate space surrounding your rover. And then press the Click me button in the web application to see what happens to your rover.

Customize your TypeScript web application

Now it's time to customize the TypeScript web application and make it your own. In your preferred IDE, consider the following suggestions for adding more functionality to your web application:

• Program the business logic: Edit src/main.ts to change the logic being run.
  • Consider moving the rover along a different route using the Viam base API, for example, spin the rover.
  • Use the Viam SLAM service for mapping or the Viam Navigation service for GPS
  • Integrate with third-party cloud services and APIs to enhance the functionality of your robot, such as voice control, data logging, or GPS tracking.
• Program the frontend: Edit index.html to change the layout of the web application.
  • Add descriptive text to display each action directly on the webpage, instead of logging it to the console.
  • Display a camera feed within your web application using the Viam camera API

Additional resources

• The website pinout.xyz is a helpful resource with the exact layout and role of each pin for Raspberry Pi. When working with Viam, make sure to reference the physical pin numbers, and not the GPIO numbers listed on pinout.xyz.
• The demo video provides a brief overview of the project.
• Viam APIs provide consistent methods of working with components, such as a base, camera, and services, such as computer vision. Refer to the Viam documentation for API reference for all components and services.
• Besides TypeScript, Viam provides SDKs in various programming languages to write control code for the backend, frontend, and mobile applications.

Common pitfalls and troubleshooting guidance

1. Safety
   • Lithium-ion batteries may pose a flammable hazard. This product requires four 18650 lithium-ion batteries OR an RC-type battery. DO NOT connect multiple power sources simultaneously. Refer to the battery manufacturer's operating instructions to ensure safe operation of the Viam Rover. Dispose of lithium-ion batteries per manufacturer instructions.
   • Pay attention to the orientation of the ribbon cable while connecting the Raspberry Pi to the rover, as it can damage the Pi if connected incorrectly.
2. Security
   • Do not share your API credentials publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.
3. Flashing firmware
   • Make sure you are using a 5V 5A (25W) power supply.
   • Participants must remember the hostname and username they set while flashing their Raspberry Pi, as they will need this when they SSH into the Pi.
   • To save time, instructors can flash all the Pis ahead of time with pre-determined credentials and share the credentials with participants during the workshop. Each Pi should have a unique hostname to avoid conflicts on the shared local network, such as <student-name>-rover or <group-name>-rover if they are working in groups.
     • If you're using SD cards, verify that you have a way to write data onto them before providing them to participants.
4. Alternative setups
   • If you're not using a Raspberry Pi 4, you can use different boards with your Viam Rover 2 with some alternative board configurations while attaching the boards.
   • If you're not using a Viam rover, you can use other wheeled-base robots, like SCUTTLE and Yahboom
5. Configuring machine and peripherals
   • If any problems occur while setting up the machine and peripherals in the Viam app, check under the LOGS tab to see what might be going wrong.
   • Check that all wires are securely attached to the correct pins.
   • If you are using a battery to power the base, check that it is adequately charged. If the motors are drawing more power than the battery can supply, the single-board computer may be power cycling. Consider using a wall power supply for testing purposes to rule out this issue.
   • If you are using a battery to power the base, ensure that the batteries are making contact with the terminals inside the battery pack. Some shorter batteries might need to be pushed along to ensure that contact is being made.
   • Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the base there.
   • Also refer to the overall Viam troubleshooting guide.

Logistics for continued learning

Participants have several options for continuing their projects beyond the workshop environment:

• Take-home projects: For participants allowed to take their rover home after the workshop, the viam-agent on the Raspberry Pi can simplify the setup process:
  • Provisioning mode: Upon rebooting the Raspberry Pi in a new environment like at home, the viam-agent automatically creates a Wi-Fi hotspot if it cannot connect to a known network.
  • Connect to the hotspot: Look for a network named viam-setup-HOSTNAME in your list of available Wi-Fi networks, where HOSTNAME is the custom hostname you set during the workshop, and viamsetup is the default password. Connect your laptop to this network.
  • Provide network information for the machine: Go to the provisioning portal at http://viam.setup/ in a browser to follow the on-screen instructions to configure the Raspberry Pi for your home Wi-Fi.
• Remote control: If participants cannot take their rover home but want to continue their projects, they can access their rover remotely:
  • Access the workshop rover: Participants can control the workshop rover remotely from anywhere in the world. A webcam can be set up for participants to view the rover's movements in real time.
  • Code from home: Without SSH access to the Raspberry Pi, participants can still write and test code on their laptops and integrate changes during their next in-person session or via workshop-provided tools.
• Try Viam virtual experience: For participants without access to a physical rover, Viam provides an online learning experience called Try Viam in the web browser to remotely control a rover pre-configured with components in the NYC Viam robotics lab.

Group discussion topics 🗣️

Review suggested topics for discussion at key points during the workshop.

• What were the biggest challenges participants faced during the workshop (e.g., assembly, coding, debugging)?
• Share troubleshooting experiences and how participants resolved issues.
• What components are included in the configuration fragment, and how could we use them?
• What additional features could improve the system (e.g. sensors, cloud services, mobile app)?
• How can rovers be used in homes, schools, or offices?
• Discuss different ways rovers can interact with the environment in industrial settings and outdoor spaces.
• Discuss the feasibility of deploying a network of rovers for a citywide project.
• How can the design of the rover be improved for better accessibility, performance, or durability?
• What are some ethical considerations when deploying rovers in shared or public spaces?

Quiz questions ❓

Review the suggested quiz questions below to evaluate participants' understanding of key concepts. These questions can be used to assess knowledge either during (see multiple choice answers in the delivery plan) or after the workshop.

1. Hardware Assembly
   • What is the purpose of setting a custom hostname during the Raspberry Pi OS configuration?
   • Which protocol must be enabled on the Raspberry Pi to allow it to communicate with the power sensor and accelerometer?
2. Software Setup
   • Why is it important to connect your machine to the Viam app during setup?
   • What is a benefit to using a Viam configuration fragment?
   • What does it mean that viam-server enables remote access to the rover?
   • How does the Viam app simplify the process of testing and controlling hardware components like the base and camera?
3. Hands-on Experiment
   • What is the primary role of viam-server in the system architecture of your rover setup?
   • What is the purpose of the .env file in your TypeScript project?

Next-level projects

Here are some ideas for expanding and enhancing the current project to create autonomous behaviors.

• Detect color with a webcam guide: to add this capability to your rover to respond to the environment
• Navigate with a rover base tutorial: to set up user-defined waypoints for your rover to move to in the order that you specify or dynamically adapt using inputs like GPS or vision
• Train a custom ML model guide: to enable object detection or classification and program the rover to act accordingly, such as moving toward or avoiding detected objects
• Add sensors and other components to extend the functionality of your rover
• Use the Viam mobile SDK to build an iOS or Android application to control the machine's components

Post-workshop resources for participants

• Viam documentation for reference
• Viam Discord community for inspiration and support
• Viam how-to guides for task-based learning, codelabs for hands-on learning, and tutorials for project-based learning.

Contribute your own workshop

This workshop and other educational codelabs are part of this Viam open-source project. You are invited to document your own workshop(s) to share with the Viam community. Be sure to follow these contributing guidelines, and let us know about it in the Viam Discord community!