2.12/2.120 Intro to Robotics
Spring 2024¹

• Lab 1: DC Motor Basics
  • Table of Contents
  • 1 Software Set Up
    • 1.1 Visual Studio Code (VSCode)
    • 1.2 PlatformIO Extension
    • 1.3 C/C++ Extension
    • 1.4 Git
  • 2 Hardware Set up
  • 3 Validating the Microcontroller
    • 3.1 Git Clone
    • 3.2 Uploading Code on the Microcontroller
  • 4 Validating the Motor
    • 4.1 Motor Driver Actuation
    • 4.2 Wiring up the Motor and Microcontroller
    • 4.3 Microcontroller Actuation
  • 5 Validating the Encoder
    • 5.1 Wiring up the Encoder and Microcontroller
    • 5.2 Testing the Encoder
  • 6 Feedback Form
  • X Optional
    • X.1 Controlling the Motor via Joystick
      • X.1.1 Motor Position Control
      • X.1.2 Wiring up the Joystick
      • X.1.3 Printing Joystick Input
      • X.1.4 Put It All Together!

Please install the following software. Although you are working in pairs today, both of your machines should have all of these software.

1. Download VSCode here: https://code.visualstudio.com/Download.
2. Follow installation instructions. When prompted for which extensions you want to install, refer to the next two sections.

PlatformIO is an open-source ecosystem for IoT development with support for various microcontroller platforms. The PlatformIO extension in VSCode provides a seamless environment for embedded systems programming. We will be using the Arduino ecosystem in PlatformIO, so if you are familiar with programming microcontrollers using the Arduino IDE, the code will look familiar.

1. Open the VSCode application.
2. Go to the Extensions tab by clicking on the Extensions icon in the Activity Bar on the left side of the window (5th from the top).
3. Search for "PlatformIO IDE" by PlatformIO and click "Install".

Since the code we need for the microcontroller is based on C++, we also need a C++ extension in VSCode for context-aware code completion. This helps speed up the coding process and reduce bugs.

1. Repeat the process in the previous section to navigate to the Extensions tab.

2. Search for "C/C++" by Microsoft and click "Install". We want the extension that only says "C/C++".

   Can't find "Install"?

   If you don't see "Install" and instead only see "Uninstall", you must already have this extension!

Git is a distributed version control system that allows for efficient collaboration and tracking changes in code. We will use Git to manage our code repositories.

1. Download Git here: https://git-scm.com/downloads.
2. Follow installation instructions.

For today's lab, you should have the following parts:

• DC motor set up (which we have already assembled for you)
• Motor driver
• Power supply
• ESP32-S3 microcontroller (https://esp32s3.com/)
• Breadboard
• Jumper cables
• USB-C cable

Before connecting the microcontroller to the rest of the system, we want to make sure it works on its own.

This GitHub repository contains all the code you need for this lab. In order to make a local copy of this repository, you need to clone it. For all Git operations in this class, we will use VSCode's built-in Source Control. Both of you must do this section.

1. Open the VSCode application.
2. Go to the Source Control tab by clicking on the Source Control icon in the Activity Bar on the left side of the window (3rd from the top).
3. Click "Clone Repository".
4. Enter "https://github.com/mit212/lab1_2024" on the bar that appears at the top of the window.
5. Select "Clone from URL" from the dropdown.
6. Navigate to the directory where you want your lab code files to be saved. Git will create a new folder called lab1_2024 within that directory to contain all files in this repository. Click "Select as Repository Destination".
7. In the pop-up window asking whether you would like to open the cloned repository, click "Open".
8. In the succeeding pop-up window asking whether you trust the authors of the files in the folder, click "Yes, I trust the authors".

Note: In the future, if you need to view or edit a repository you have already cloned, just click "Open Folder" when you first launch the VSCode application and select the cloned folder, e.g. lab1_2024 folder.

Now that you have the code on your machine, you can upload it on the microcontroller. This is a process we will repeat not only in this lab but throughout the semester, so try to remember the steps! We will first upload a simple test that changes the color of the onboard LED.

1. To verify that the code compiles, first build the code by clicking the check mark at the bottom of the screen. A terminal window will open to report progress as your code builds. Once done, it should say SUCCESS.

   What does compiling code mean?

   Compiling converts source code (human readable) into machine code (machine executable). The process verifies that the code is written correctly.

2. Connect the microcontroller to your machine using a USB-C cable.

3. Put the microcontroller into download mode by holding down the onboard BOOT button, clicking the adjacent RST button, and then releasing BOOT. Depending on your machine, you may have to do you this every time you want to upload code on your microcontroller.

   Upload failed? COM port doesn't exist?

   Delete the .pio folder and put the microcontroller into download mode again. The onboard LED on the microcontroller should be off when it is in download mode. Make sure you clicked RST while you are still holding down BOOT. You should only let go of BOOT after you have let go of RST.

   You can also try manually selecting the upload port. Click the plug icon next to "Auto" at the bottom of the screen and try the options that appear at the top of the screen.

   

4. Click the right arrow at the bottom of the screen to upload the code on the microcontroller. The upload process also includes compiling so if you only make small changes in the future, you don't need to build before uploading.

5. Run the code by clicking RST. You should see the onboard LED change colors!

6. For the lab partner who did not get to use their machine to upload code on the microcontroller yet, open src/robot/blink_test.cpp.

7. Modify the code in line 20 to increase the delay to 60.

8. Save the file and repeat steps 1 to 5. You should notice that the speed at which the onboard LED changes colors is much slower!

Note: In this lab, we configured PlatformIO to compile and upload only the files within the src/robot/ directory. Since all the other .cpp files are outside this directory, only blink_test.cpp was ran. This means that if you want to run a different .cpp file, you will have to rearrange the files by taking out blink_test.cpp and adding in that .cpp file to the src/robot/ directory.

Now that we have confirmed the microcontroller is working, we want to test the motor and motor driver. From this section onwards, you may choose to only work on one of your machines.

We will start by actuating the motors using only the motor driver.

1. Connect the motor power cables to the motor driver cables (black to black and red to orange).
2. Plug in the power supply output to the motor driver input.
3. Push and hold either of the M1A and M1B buttons on the motor driver to see the wheel spin! Each button should spin the wheel in opposite directions.
4. The power supply has a knob to vary its output voltage. Try changing this to about 10V, 7V, then 3V. Notice that the wheel spins slower at lower voltages, and doesn't spin at all below certain voltages! This is because the motor driver has a lower limit it needs to surpass in order to function.
5. Change the output voltage back to about 12V.

We will then wire the motor driver to the microcontroller so that we can use code to command the motors.

1. Open include/pinout.h and find the assigned motor DIR1 and PWM1 pin numbers.

2. Use the jumper cables to connect the following:

   motor driver	microcontroller	suggested cable color
   DIR1	from pinout.h	orange
   PWM1	from pinout.h	white
   GND	- or GND	black or brown

   Note: We have suggested jumper cable colors for convention, but remember that the colors alone don't mean anything! If you see a black jumper cable in the future, don't automatically assume that it must be ground.

   Nothing is happening?

   Make sure you wired up the motor driver and not the encoder! The motor driver is the PCB you connected to the power supply output, while the encoder is the black cylinder attached to the end of the motor.

   How do I use a breadboard?

   Please refer to this online guide or approach a TA or LA for a crash course!

3. Examine the schematic diagram below and confirm that it corresponds to the wiring you just did. Make sure you completely understand the correspondence as you will only be provided with a schematic for the next wiring task! Feel free to clarify with a TA or LA if needed.

Finally, we will upload the provided motor test code on the microcontroller! Repeat the process outlined in the previous section to run motor_drive_test.cpp instead of blink_test.cpp. The wheel should spin in different directions with varied speeds.

We can now test our entire system consisting of the microcontroller, motor, motor driver, and encoder.

Using what you learned about reading schematics in the previous section, wire up the encoder to the microcontroller based on the schematics below!

Hint: You only need to connect the 4 encoder wires to the microcontroller through the breadboard. Remember to refer to include/pinout.h to confirm pin numbers.

To see the encoder in action, we will upload the provided encoder test code on the microcontroller.

1. Ensure that the motor driver is powered off by unplugging the power supply cable connection.
2. Upload and run encoder_basic_test.cpp.
3. Open the Serial Monitor by clicking the plug icon at the bottom of the screen.
4. By looking at the counts printed in the Serial Monitor, estimate how many encoder counts it takes per revolution. Observe that counter-clockwise motion increases the encoder count, while clockwise motion decreases it!
5. Upload and run encoder_test.cpp.
6. Rotate the wheel. Confirm that the position and velocity readings make sense!

Before you leave, please fill out https://tinyurl.com/212-feedback.

If you finished lab early, here's a few optional challenges you can try!

The goal for this challenge is to use a joystick to dictate the position of the motor.

We have provided code that performs basic motor position control with PID. We first want you to get familiar with this code.

1. Open motor_position_control.cpp and read its contents.
2. Plug in the power supply output to the motor driver input.
3. Upload and run motor_position_control.cpp. You should see the wheel cycle back and forth.

Please ask a TA or LA for a joystick. Refer to the schematic below to wire it to the rest of the system.

We will now write some code to collect and print input from the joystick.

1. Right-click on the robot subfolder and click "New File...".
2. Name the file motor_joystick_control.cpp. It is important that you include .cpp in the filename.
3. Copy down the code written on the whiteboard.
4. Upload and run motor_joystick_control.cpp. You should see the positions of the two potentiometers of the joystick print on the Serial Monitor!

Combine motor_joystick_control.cpp and motor_position_control.cpp so that the setpoint in motor_position_control.cpp is dictated by either x or y in motor_joystick_control.cpp.