From 5da0898b7eb9068c6e1767c05691f9f963903590 Mon Sep 17 00:00:00 2001 From: Toby Nguyen Date: Sun, 15 Sep 2024 13:57:29 -0500 Subject: [PATCH] Updated introductory sections, removed checkpoints, updated 'getting started' section, added some content to 'sensors and actuators' section --- docs/_sections/_guide-general/forms.md | 2 +- docs/_sections/_guide-general/schedule.md | 4 +- docs/_sections/_guide-general/welcome.md | 10 ++-- .../checkpoints/checkpoints.md | 9 --- .../checkpoints/color-checkpoint.md | 7 --- .../checkpoints/line-checkpoint.md | 7 --- .../checkpoints/mechanical-checkpoint.md | 57 ------------------- .../checkpoints/wall-checkpoint.md | 32 ----------- .../getting-started/environment-setup.md | 28 ++++++++- .../microcontroller-interface.md | 26 ++++----- .../sensors-and-actuators/actuators.md | 10 ++-- .../sensors-and-actuators/color-sensors.md | 29 +++++----- .../sensors-and-actuators/ir-sensors.md | 18 +++++- .../sensors-and-actuators/line-sensors.md | 13 +++-- 14 files changed, 89 insertions(+), 163 deletions(-) delete mode 100644 docs/_sections/_guide-primaries/checkpoints/checkpoints.md delete mode 100644 docs/_sections/_guide-primaries/checkpoints/color-checkpoint.md delete mode 100644 docs/_sections/_guide-primaries/checkpoints/line-checkpoint.md delete mode 100644 docs/_sections/_guide-primaries/checkpoints/mechanical-checkpoint.md delete mode 100644 docs/_sections/_guide-primaries/checkpoints/wall-checkpoint.md diff --git a/docs/_sections/_guide-general/forms.md b/docs/_sections/_guide-general/forms.md index c718595e..f1ac96bd 100644 --- a/docs/_sections/_guide-general/forms.md +++ b/docs/_sections/_guide-general/forms.md @@ -5,7 +5,7 @@ nav_include: true nav_order: 4 --- -# Forms TODO: add actual links +# Forms and Links This page contains direct links and forms that you might need for Robotathon! diff --git a/docs/_sections/_guide-general/schedule.md b/docs/_sections/_guide-general/schedule.md index a0c1e318..26d96de3 100644 --- a/docs/_sections/_guide-general/schedule.md +++ b/docs/_sections/_guide-general/schedule.md @@ -6,6 +6,8 @@ nav_order: 2 --- # Competition Schedule + +This calendar will have the most up to date version of the competition timeline! {: .highlight} @@ -26,7 +28,7 @@ Tip: You can add this calendar to your personal Google calendar by clicking the **Breadboarding Workshop** - Oct 14
**Line/Wall/Color Checkpoint** - Oct 20
**Color Sensor Workshop** - Oct 21
-**Line/Wall Follow Workshop** - Oct 28
+**Line/Wall/Color Follow Workshop** - Oct 28
**Mechanical Design Checkpoint** - Nov 3
**Line/Wall/Color Checkpoint** - Nov 10
**Competition Day** - Nov 16
diff --git a/docs/_sections/_guide-general/welcome.md b/docs/_sections/_guide-general/welcome.md index 9bdad36c..16b7d1f0 100644 --- a/docs/_sections/_guide-general/welcome.md +++ b/docs/_sections/_guide-general/welcome.md @@ -10,16 +10,16 @@ nav_order: 1 ## Hello! -This guide aims to provide you with helpful information and direction throughout your robot building process. While this guide is broad, it stays mostly within the realm of setup and basic tips since we want you to discover your own solutions. +This guide aims to provide you with helpful information and direction throughout your robot building process. While this guide is broad, it stays mostly within the realm of setup and basic tips since we encourage you to discover your own solutions. -Finally, if you have any technical questions or don’t understand a topic, ask the mentors or during office hours, which can be found [here (todo)](link)! We can help to resolve your problems, or point you to the right person who can. Mentors, office hours, and other teammates are valuable resources to turn to if you are stuck. +Finally, if you have any technical questions or don’t understand a topic, ask the mentors or during office hours, which can be found [here (soon™️)](link)! We can help to resolve your problems, or point you to the right person who can. Mentors, office hours, and other teammates are valuable resources to turn to if you are stuck. ## Overview -The first section, Getting Started, sets you up for success in regards to getting familiar with the ESP32 microcontroller, the software build process, and embedded systems development in general. We highly recommend that you at least take a look at Environment Setup, as this page will streamline your development process and prevent a lot of environment errors you may get in the future. +The first section, Getting Started, is about getting familiar with the ESP32 microcontroller, the software build process, and embedded systems development in general. We highly recommend that you at least take a look at Environment Setup, as this page will streamline your development process and prevent a lot of environment errors you may get in the future. -The second section, Sensors and Actuators, goes into detail about the wiring and programming for various peripherals you will be using in the competition, which include motors, distance sensors, line sensors, and color sensors. +The second section, Sensors and Actuators, goes into detail about the various peripherals you will be using in the competition, which include motors, distance sensors, line sensors, and color sensors. -The third section, Designing a Robot, covers the computer aided design (CAD) software - SOLIDWORKS - that Mechanical Engineers will use in their courses here. We’ll also discuss the physical construction of a robot, as well as the resources Texas Inventionworks (TIW) provides to students. +The third section, Designing a Robot, covers the physical construction of a robot, as well as the resources Texas Inventionworks (TIW) provides to students. Finally, the Robotathon steering committee appreciates your feedback! If you have questions that you think should be clarified here, or topics that you think should be covered in the next revision of this guide, please fill out our [google form!](https://forms.gle/6UpwaETAtQpkvoMa8) \ No newline at end of file diff --git a/docs/_sections/_guide-primaries/checkpoints/checkpoints.md b/docs/_sections/_guide-primaries/checkpoints/checkpoints.md deleted file mode 100644 index 54388499..00000000 --- a/docs/_sections/_guide-primaries/checkpoints/checkpoints.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: default -title: Checkpoints -nav_include: true -has_children: true -nav_order: 5 ---- - - \ No newline at end of file diff --git a/docs/_sections/_guide-primaries/checkpoints/color-checkpoint.md b/docs/_sections/_guide-primaries/checkpoints/color-checkpoint.md deleted file mode 100644 index cf445eb6..00000000 --- a/docs/_sections/_guide-primaries/checkpoints/color-checkpoint.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Color Checkpoint -nav_include: true -parent: Checkpoints -nav_order: 3 ---- \ No newline at end of file diff --git a/docs/_sections/_guide-primaries/checkpoints/line-checkpoint.md b/docs/_sections/_guide-primaries/checkpoints/line-checkpoint.md deleted file mode 100644 index 7b90db21..00000000 --- a/docs/_sections/_guide-primaries/checkpoints/line-checkpoint.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: default -title: Line Checkpoint -nav_include: true -parent: Checkpoints -nav_order: 1 ---- \ No newline at end of file diff --git a/docs/_sections/_guide-primaries/checkpoints/mechanical-checkpoint.md b/docs/_sections/_guide-primaries/checkpoints/mechanical-checkpoint.md deleted file mode 100644 index 5112d8b5..00000000 --- a/docs/_sections/_guide-primaries/checkpoints/mechanical-checkpoint.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -layout: default -title: Mechanical Checkpoint -nav_include: true -parent: Checkpoints -nav_order: 4 ---- -# Mechanical Checkpoint (content unedited) -Your team has to come up with a mechanical design that translates individual robot components into how you envision your robot completing particular tasks. -A lil intro to engineering projects! Along with your team, these are the bare bones of what it takes to create a project (ahem ahem like a robot?? ahem ahem) from start to finish. For more elaboration on these key steps, I recommend checking out our tutorial on the Engineering Design Process here. - -1- Identify the tasks/functions needed for the challenge -It would be wise to take a look at the RAScade competition rules, my dear. In particular, start thinking about your team’s game plan for each match. -2- Identify how parts can be used -Take a look at the provided parts list. Look up things like what a servo motor is used for or how to operate different sensors! -3- Brainstorm how you can combine parts to achieve that goal; no wrong ideas! -4- Build/Test/Improve a Prototype - -Your robot is faced with the challenge of throwing an object. Here are some “template” designs that might be appealing to look more into! Here’s a separate link that might help with your research. - -A Few Robot Arm Designs - -Basic Claw Bot -It gets the job done. - -- Up up down down left right left right- I mean use motors to move wheels, lift your bot’s arm(s), and grip or release something. -- Usually done for controlled robots rather than autonomous. - -Conveyor Belt Lift/Drop -Going up? Or down? - -- Using flaps, chains, gears, etc, guide stuff from point A to B. -- Can be used to transfer something front to back or vice versa as well. --Make sure the objects are supported by the system! - -Flywheel Shooter -There is a need for speed in order to fly. - --With a wheel (or two!) and a fast enough motor and friction, your bot can send stuff flying! --Whatever is holding the wheel and axle that spins needs to be held steady! Don’t need your whole bot shaking now do we? - -Fling/Catapult -An oldie but a goodie. - --A strong enough flick of the wrist can project an object away from the bot. -- Rubber bands could be used like a slingshot. --Be careful to balance the weights of the bot and what the lever arm is flinging! - -Pusher/Intake -To hold objects or let them go. - -- Get creative for how your bot wrangles objects closer to or away from itself near to the ground. -- Can be passive or active with motors. -- Avoid scenarios where objects could get stuck! - -The engineering design process is just that- a process! Designs don’t always work they way you planned, so be prepared to do a lot (and I mean a lot) of revising to end up achieving the goal you originally intended. Keep an open mind and think outside of the box! :) - diff --git a/docs/_sections/_guide-primaries/checkpoints/wall-checkpoint.md b/docs/_sections/_guide-primaries/checkpoints/wall-checkpoint.md deleted file mode 100644 index 75ce63b9..00000000 --- a/docs/_sections/_guide-primaries/checkpoints/wall-checkpoint.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: default -title: Wall Checkpoint -nav_include: true -parent: Checkpoints -nav_order: 2 ---- - -# Wall Checkpoint/Challenge UNEDITED - -Below is the premise for this checkpoint: -Checkpoint 4: I’m Dumb, Not Stupid (Wall Following) - -Some things you should look out for: -IR sensor placement -There is a previous page in this guide that discusses sensor placement so be sure to take a look at this when working on the checkpoint -You can always experiment with different IR sensor placement since you will be given 2! -Touch Sensor Use -It is up to your group whether or not you would like to utilize the touch sensor for this challenge as well. It could serve to help change direction if your robot were to run into a wall (hint hint) -Your code (dun dun dun) -This is of course a very important aspects of this checkpoint!! I know this part is one of the hardest and most time consuming so try to get a head start and come to office hours if you need help! - -Once you have completed this checkpoint you will have a better idea of what to expect from the Pacman Maze. -Below is a sneak peak of the design for the maze… - - -Your robot will have to traverse this area and reach the end accordingly. This challenge will specifically test your ability to validate the IR sensors and either error correct or have good control loops to remain in range of good data. The maximum amount of points you can obtain by completing this challenge is 24. If your robot gets stuck or cannot complete the maze then you can still receive partial points for the amount of pellets you cross. - - - - -One thing that helps is making sure that your robot can execute accurate 90 degree turns. Try to think of some ways that you could experiment with wheel direction and speed. Maybe one motor going slower than the other or rotating the opposite direction o_o diff --git a/docs/_sections/_guide-primaries/getting-started/environment-setup.md b/docs/_sections/_guide-primaries/getting-started/environment-setup.md index d9d2f3ba..a4539490 100644 --- a/docs/_sections/_guide-primaries/getting-started/environment-setup.md +++ b/docs/_sections/_guide-primaries/getting-started/environment-setup.md @@ -6,6 +6,32 @@ parent: Getting Started nav_order: 5 --- +Please reference the setup guide found in the [Robotathon Repo's readme!](https://github.com/ut-ras/RobotathonESP32) + +## Programming goal +For this tutorial, we will control the onboard microcontroller by toggling it on and off periodically. This will serve as the goal for the Blink Checkpoint and demonstrates that you can flash your own program to the ESP32. If you are having trouble configuring your development environment, reference the setup guide on our [Github (scroll down)](https://github.com/ut-ras/RobotathonESP32) or ask a mentor for help! + +The following program will blink the onboard LED (pin 2) on the ESP32 every second: + +{: .highlight} +Note: While it is good coding practice to leave comments in your code to make it more understandable, they should be used sparingly to explain complex code — the below example has a ton of comments for the sake of explanation. +{: .callout-toby} + +```cpp +int LED_BUILTIN = 2; // defines the word "LED_BUILTIN" as the number 2 for ease of use when defining and using the pin later + +void setup() { +pinMode (LED_BUILTIN, OUTPUT); // configures pin 2 to be a GPIO output pin +} + +void loop() { +digitalWrite(LED_BUILTIN, HIGH); // writes a digital high to pin 2 +delay(1000); // waits for 1000 milliseconds (1 second) +digitalWrite(LED_BUILTIN, LOW); // writes a digital low to pin 2 +delay(1000); +} + +``` + -ermm uhh ummm \ No newline at end of file diff --git a/docs/_sections/_guide-primaries/getting-started/microcontroller-interface.md b/docs/_sections/_guide-primaries/getting-started/microcontroller-interface.md index a3986458..2fca1582 100644 --- a/docs/_sections/_guide-primaries/getting-started/microcontroller-interface.md +++ b/docs/_sections/_guide-primaries/getting-started/microcontroller-interface.md @@ -6,29 +6,25 @@ parent: Getting Started nav_order: 4 --- -# Microcontroller Interfacing KINDA OUTDATED, images need formatting -Microcontrollers are cool and all, but they’re a lot more interesting when you can do stuff in the real world! +# Microcontroller Interfacing +Microcontrollers are cool and all, but they’re a lot more interesting when you can use them to do stuff in the real world! You can connect all sorts of devices to the ESP32 microcontroller to do whatever your heart desires. Below is a picture of that describes what kinds of connections can be made with each pin: -## Programming goal -For this tutorial, we want to turn on the LED by setting PA2 to output high (to power the LED) and the switch (button) is closed (pressed). +wroom_pinout.jpg + +We are only concerned with pins that are power, ground, GPIO, and ADC enabled, so don't worry about all the extra abilities. -## Interfacing example -For this example, we’ll use an LED and a switch. You will need six components - a red LED, switch, 470 ohm resistor, TM4C, breadboard, and some wires. +* Power - 3V3 and 5V pins labeled with red. These pins will always be outputting their respective voltage levels (3.3V and 5V) as long as the ESP32 is powered +* Ground - pins labeled as GND. These pins are 0V and serve as the return path in your circuits. +* GPIO (General Purpose Input/Output) - virtually every pin. These pins can be configured to read or output digital high and low signals. +* ADC (Analog to Digital Converter) - only some pins. These pins can read analog values instead of just high or low. {: .highlight} -Our microcontroller pin outputs way too much current for our LED to handle, so we need to put a resistor in series with the microcontroller output pin and LED. The exact resistance depends on the current rating of the diode. +Note: Do NOT short (connect) a power pin directly to a ground pin. This will likely fry your ESP32 by causing a huge surge of current. {: .callout-toby} -1. Connect a wire to a GPIO pin (let’s choose PA2 for this example). The other end goes to one of the switch legs. -1. Stick the long side of the LED on another switch leg. Use the continuity mode on the multimeter to make sure the leg is disconnected by putting each of the probes at each end of the switch (see below). Pressing the switch should short the legs. -1. Put the resistor in series with the short end of the LED (-), and connect the GND pin to the other end of the resistor. +If you want to know more about any features, feel free to ask a mentor or Google for more information :) -led interface -outdated-circuit-diagram -button-diagram.png -continuity-test.png -wroom_pinout.jpg diff --git a/docs/_sections/_guide-primaries/sensors-and-actuators/actuators.md b/docs/_sections/_guide-primaries/sensors-and-actuators/actuators.md index a49f4397..2e515453 100644 --- a/docs/_sections/_guide-primaries/sensors-and-actuators/actuators.md +++ b/docs/_sections/_guide-primaries/sensors-and-actuators/actuators.md @@ -8,9 +8,7 @@ nav_order: 5 # Actuators -Actuators in our case is just a fancy word for motors, and they will be the key to your robot's motion! You will deal with two types of motors in this competition: DC motors and servo motors. - - +The word "actuators" is just a fancy word for "devices that create motion," which can include anything ranging from hydraulic pistons to motors. In our case, electric motors will be the key to your robot's motion! You will deal with two types electrical actuators in this competition: DC motors and servo motors. # DC Motors dc_motor.jpg @@ -39,7 +37,7 @@ Control Pins: Connect the control pins (e.g., IN1, IN2, ENA) on the motor contro | Red | OUT1 | | Black | OUT2 | -| Motor Controller Terminal | ESP32 Pin | +| Motor Controller Terminal | ESP32 Pin | |:-------------|:------------------| | +5V | 5V | | IN1 | GPIO | @@ -47,7 +45,7 @@ Control Pins: Connect the control pins (e.g., IN1, IN2, ENA) on the motor contro | ENA | GPIO | The following is an example of configuring and running the motor in software: -```c +```cpp #define IN1 27 // Control pin 1 #define IN2 26 // Control pin 2 #define ENA 25 // PWM pin @@ -100,7 +98,7 @@ If you're not sure which ESP32 pins are PWM capable, then check out the diagram In this competition, we will be using the Arduino servo library to control the servos. The following is an example of how to configure the servo: -```c +```cpp #include Servo myservo; diff --git a/docs/_sections/_guide-primaries/sensors-and-actuators/color-sensors.md b/docs/_sections/_guide-primaries/sensors-and-actuators/color-sensors.md index dffa7aea..1cd1e0ad 100644 --- a/docs/_sections/_guide-primaries/sensors-and-actuators/color-sensors.md +++ b/docs/_sections/_guide-primaries/sensors-and-actuators/color-sensors.md @@ -6,29 +6,32 @@ parent: Sensors and Actuators nav_order: 1 --- -# Color Sensor UNEDITED -The TCS34725 ordered from Adafruit will allow you to navigate the Dance Challenge. By sensing the color of the tile you are on, your robot can waltz across the dance floor to victory, racking up those sweet combos! +# Color Sensor +The TCS34725 from Adafruit will allow you to complete the Color Challenge. + +color_sensor.jpg + ## How it Works -The RGB sensor uses the RGB color space to represent the color that it sees. In our case, it provides the data in integer values of 0-255, represented in 8 binary bits. We will grab that data using a communication protocol called I2C, which is used in many electrical devices. The specific I2C implementation is found in RASware, but we’ve abstracted the hard logic for you already. +The RGB sensor uses the RGB color space to represent the color that it sees through photodiodes. It provides the data in integer values of 0-255, represented in 8 binary bits. We will grab that data using a communication protocol called I2C, which is used in many electrical devices. Implementing I2C is out of the scope of this competition, but you can find more information about it [here.](https://learn.sparkfun.com/tutorials/i2c/all) -# INSERT DIAGRAM OF WIRED EXAMPLE HERE +If you want more details on how the color sensor works, check out [this link!](https://www.utmel.com/components/everything-you-know-about-tcs34725-color-sensors-faq?id=1986) + +| Color Sensor Pin | ESP32 Pin | +|:-------------|:------------------| +| VIN | 3.3V | +| GND | GND | +| SDA | GPIO21 | +| SCL | GPIO22 | ## Programming For this tutorial, we’re only going to be reading the RGB sensor values from the TCS34725. Make sure that your pins are correctly connected or otherwise you won’t receive the data! -Build and flash the program, and watch the output change as you hold the sensor to different colored objects! -# Extensions -Extensions -Now that you’ve completed this tutorial, let’s move to more advanced stuff! -For the checkpoint I’m Sorry, You May Be Color Blind, you need to classify various colors. Try to output a specific message on CLI when you read Red or Blue or other colors. +# Tips +For the color checkpoint, you need to classify various colors. Try to output the sensor readings on the serial monitior for debugging. Try to threshold a level of error for your sensor and think about the following questions. * Do the values change under different lighting? * Different distances? * What about various shades of red? Is red one specific RGB value? If you have a moving base, try to drive in a certain direction based on color. How about going right on a red tile? -color_sensor_wiring.png -color_sensor.jpg - -todo make the color sensor picture a lot smaller lol \ No newline at end of file diff --git a/docs/_sections/_guide-primaries/sensors-and-actuators/ir-sensors.md b/docs/_sections/_guide-primaries/sensors-and-actuators/ir-sensors.md index 4a9d2f0f..6008bf43 100644 --- a/docs/_sections/_guide-primaries/sensors-and-actuators/ir-sensors.md +++ b/docs/_sections/_guide-primaries/sensors-and-actuators/ir-sensors.md @@ -13,15 +13,27 @@ nav_order: 1 A necessary component for any challenge that utilizes walls, analog IR sensors are a staple of Robotathon. This particular sensor is the GP2Y0A21, and detects distances from 10 to 80 cm. ## How it Works -IR distance sensors emit long wavelength (700 nm - 1 mm) light towards a surface. The light bounces off objects it hits, and then enters a proximity sensor. The output is then transformed into a voltage that can be fed into the ESP32 and read. +IR distance sensors emit long wavelength (700 nm - 1 mm) light towards a surface. The light bounces off objects it hits, and then enters a proximity sensor. The output is then transformed into a voltage that can be read by the ESP32. ir-sensor-functionality.png ir-sensor-graph.png ## Interfacing -There are 3 pins (red, black, white) to the device as seen in the top right picture, associated to Power, Ground, and Output Signal, respectively. For testing the distance sensor, let’s use the analog pin, pin 27, as the signal pin. Hook up the circuit as follows. +There are 3 pins (red, black, white) to the device as seen in the picture, associated to Power, Ground, and Output Signal, respectively. For testing the distance sensor, let’s use the analog pin, pin 27, as the signal pin. Hook up the circuit as follows: -ir-sensor-wiring-diagram.png +{: .highlight} +Note that some of our IR sensors may have preattached cables with incorrect color coding. Be sure to follow the colors shown in the first picture! +{: .callout-toby} + +| IR Sensor Pin | ESP32 Pin | +|:-------------|:------------------| +| VIN (red) | 3.3V | +| GND (black) | GND | +| Signal (white) | Any ADC Capable Pin | + +{: .highlight} +If you're not sure which ESP32 pins are ADC (Analog to Digital Converter) capable, then check out the diagram in [this page!](https://ut-ras.github.io/RobotathonESP32/getting-started/microcontroller-interface) +{: .callout-toby} ## Programming The following program will allow you to read values from the IR sensor in a loop. After you build and flash the program, you should see the values in the UART change as you move it towards and away from an object. diff --git a/docs/_sections/_guide-primaries/sensors-and-actuators/line-sensors.md b/docs/_sections/_guide-primaries/sensors-and-actuators/line-sensors.md index 30c5a5b7..548b6a96 100644 --- a/docs/_sections/_guide-primaries/sensors-and-actuators/line-sensors.md +++ b/docs/_sections/_guide-primaries/sensors-and-actuators/line-sensors.md @@ -15,7 +15,7 @@ The line sensor is made up of an array of 8 IR LED/phototransistor pairs, each t line_sensor_diodes.png {: .highlight} -Note that you do NOT have to use all 8 of the LED/phototransistor pairs — You can leave the ones you do not want to use disconnected from the MCU. +Note: you do NOT have to use all of the LED/phototransistor pairs — You can leave the ones you do not want to use disconnected from the ESP32. {: .callout-toby} ## Programming @@ -25,11 +25,12 @@ different sensors. TIP: always run the calibrate function (i.e. hold a line of the color you’re sensing under all the sensors during set up) to ensure consistent and accurate results. ## Extensions -You received values from the sensor, but do they mean anything? -How does the position value change as you place your line beneath different sensors, and how can you control that? -Is there an easier way to quantify the “change” when the car is veering off the line? -What do you do with your robot when that happens? I.e. adjusting movement -Consistency in data collection is key for calibration +* You received values from the sensor, but what do they mean? +* How does the position value change as you place your line beneath different sensors, and how can you control that? +* Is there an easier way to quantify the “change” when the car is veering off the line? +* What do you do with your robot when that happens? I.e. adjusting movement +* Consistency in data collection is key for calibration + * Can you automate the calibration process? line_sensor_wiring.png