ready for review (please get me out)

docs/_sections/_guide-general/forms.md

@@ -15,7 +15,6 @@ This page contains direct links and forms that you might need for Robotathon!
 [RAS Dues Form](https://utdirect.utexas.edu/nlogon/txshop/item_details.WBX?application_name=ENENGALU&component=0&dept_prefix=E2&item_id=199&cat_seq_chosen=02&subcategory_seq_chosen=000){: .btn .btn-green }
 <br>
 [RAS Safety Waiver](https://docs.google.com/forms/d/e/1FAIpQLSdRvNc2R3vnG0AXu4k7bypacyeB2jgF_D1nDPq76kE8WIIBmQ/viewform){: .btn .btn-green }
-[Robotathon Sign Up Form](https://docs.google.com/forms/d/e/1FAIpQLScSTcmRPuThAxm5Y_3yomNF6AkQEQ5HVp_gJdVz3lGVPYHTgw/viewform){: .btn .btn-green }
 
 Here are some more general links for RAS:
 

docs/_sections/_guide-general/schedule.md

@@ -14,4 +14,4 @@ This calendar will have the most up to date version of the competition timeline!
 Tip: You can add this calendar to your personal Google calendar by clicking the plus button above^^
 {: .callout-toby}
 
-Here is the (RAS office hours schedule.)[https://docs.google.com/spreadsheets/d/1MNuk1WAB5ZmVcOo-_wdnVN3yREhI9oH90169OuW2QAc/edit?gid=1317822740#gid=1317822740] You may go to any of the office hours that you please, but note that office hours are subject to change throughout the semester.
+Here is the [RAS office hours schedule](https://docs.google.com/spreadsheets/d/1MNuk1WAB5ZmVcOo-_wdnVN3yREhI9oH90169OuW2QAc/edit?gid=1317822740#gid=1317822740) You may go to any of the office hours that you please, but note that office hours are subject to change throughout the semester.

docs/_sections/_guide-general/welcome.md

@@ -12,7 +12,7 @@ nav_order: 1
 
 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.
 
-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.
+If you have any technical questions or don’t understand a topic, ask the mentors or during [office hours here](https://docs.google.com/spreadsheets/d/1MNuk1WAB5ZmVcOo-_wdnVN3yREhI9oH90169OuW2QAc/edit?gid=1317822740#gid=1317822740)! 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
 

docs/_sections/_guide-primaries/getting-started/microcontroller-interface.md

@@ -21,29 +21,24 @@ We are only concerned with pins that are power, ground, GPIO, and ADC enabled, s
 * ADC (Analog to Digital Converter) - only some pins. These pins can read analog values instead of just high or low. 
 
 {: .highlight}
-Note: Do NOT short (connect) a power pin directly to a ground pin. This will likely fry your ESP32 and more by causing a huge surge of current. 
+Warning: Be careful to not short (connect) a power pin directly to a ground pin. This will fry your ESP32 and more by causing a huge surge of current. 
 {: .callout-toby}
 
-You can power your ESP32 by 2 methods: USB connection to laptop or external battery pack.
+## Powering the ESP32
+You can power your ESP32 by 2 methods: USB connection or external battery pack.
+
+The USB connection to your computer is necessary for uploading and debugging your code through the serial monitor. It would be easiest to keep using the USB connection until later in the competition when testing the entire system.
 
 {: .highlight}
-Note: Do NOT power your ESP32 through its 5V pin using the battery pack while simultaneously connecting it to your computer!! This may damage your devices (please only do one at a time).
+Note: Do NOT power your ESP32 through its 5V pin with the battery pack while simultaneously connecting it to your computer! This may irreversibly damage your devices (only do one at a time).
 {: .callout-toby}
 
-The USB connection is necessary for uploading and debugging your code through the serial monitor. 
-
-For this competition, you will be able to control your robot with a wireless game controller to navigate around the field (sensor challenges should be completed autonomously). It would be impractical to power your ESP32 through your laptop with a super long cable all the time, so you will use an external battery pack feeding through a buck converter to power the 5V pin of the ESP32.
-
-<img src="{{ '/_assets/images/buck_converter.png' | prepend: site.baseurl }}" alt="buck_converter.png" width=400 height=400>
-
-You will use this buck converter to reduce the voltage of the battery pack down to a level the ESP32 can safely use (5V). Here are the steps to interface the battery pack to the ESP32 (assumes ESP32 is seated in breadboard):
-
- (((insert picture of wire diagram here)))
-
+Using the external battery pack is detailed in the [Actuators page](https://ut-ras.github.io/RobotathonESP32/sensors-and-actuators/actuators) because we will be using the motor driver's 5V output to power the ESP32.
 
 If you want to know more about any features, feel free to ask a mentor or Google for more information :) 
 
 
 
 
 
+

docs/_sections/_guide-primaries/getting-started/reading-datasheets.md

@@ -44,7 +44,6 @@ Typically, the first page is pretty meta. Areas of interest include:
 Note: manufacturers might use different wording to describe what was mentioned above (i.e. pinout = connection diagram). 
 {: .callout-toby}
 
-
 Just like a Wikipedia page, datasheets tell you a lot of information that may or may not pertain to what you’re looking for. By knowing generally where to look and what you’re interested in, it’s faster for you to find the details you need!
 
 

docs/_sections/_guide-primaries/sensors-and-actuators/actuators.md

@@ -3,7 +3,7 @@ layout: default
 title: Actuators
 nav_include: true
 parent: Sensors and Actuators
-nav_order: 5
+nav_order: 4
 ---
 
 # Actuators
@@ -17,45 +17,59 @@ You will be using DC (direct current) motors as the primary means of moving your
 
 ## Motor Controllers
 <img src="{{ '/_assets/images/l298n_motor_driver.jpg' | prepend: site.baseurl }}" alt="l298n_motor_driver.jpg" width="200" height="300">
+<img src="{{ '/_assets/images/l298n_driver_pinout.png' | prepend: site.baseurl }}" alt="l298n_driver_pinout.png" width="300" height="400">
 
-A motor controller, such as the L298N, acts as an intermediary between the microcontroller and the DC motor. It allows the microcontroller to control the motor's speed and direction without directly handling the high current. The motor controller typically has the following key components:
-* H-Bridge Circuit: This allows the motor to be driven in both forward and reverse directions.
-* PWM (Pulse Width Modulation) Control: This enables speed control by varying the duty cycle of the PWM signal.
+A motor controller, such as the L298N, acts as an intermediary between the microcontroller and the DC motor. It allows the microcontroller to control the motor's speed and direction without directly handling the high current. The motor controller has the following key components:
+* H-Bridge Circuit: This allows the motor to be driven in both forward and reverse directions. Different combinations of IN1 and IN2 will determine the spin direction. 
+* PWM (Pulse Width Modulation) Control: This allows speed control by varying the duty cycle of the PWM signal.
 * Power Supply Terminals: These provide the necessary power to the motor.
+* 5V Voltage Regulator: This allows the motor controller to act as a 5V output power supply. This functionality can be disabled by removing the corresponding jumper (see below)
 
 The following information is an adapted version of [this guide.](https://lastminuteengineers.com/l298n-dc-stepper-driver-arduino-tutorial/)
 
-# How to Use Motor and Controller?
-To control a DC motor using an ESP32 and a motor controller, you need to directly connect the power source and ESP32 to the motor controller as shown below:
-<br>
-<img src="{{ '/_assets/images/l298n_driver_pinout.png' | prepend: site.baseurl }}" alt="l298n_driver_pinout.png" width="300" height="400">
+# How to Use Motor and Motor Controller?
+First we will go over using an external power source for the ESP32. For this competition, you will be able to control your robot with a wireless game controller to navigate around the field (sensor challenges should be completed autonomously). It would be impractical to power your ESP32 through USB on the field, so you will use a battery pack. We need to reduce the voltage of the battery pack down to a level the ESP32 can safely use through the motor controller's 5V voltage regulator.
 
-Motor Controller Power: Connect the motor controller's 12V terminal to a power source less than 12V
-Motor Power: Connect the motor leads into the terminals with 2 slots. Polarity (order of red and black wires) do not matter because DC motors are designed to run either direction based on the current direction running through them.
-Control Pins: Connect the control pins (e.g., IN1, IN2, ENA) on the motor controller to the GPIO pins on the ESP32.
-<br>
+Here is a diagram of how your circuit should look when using the battery pack (voltage regulator jumper needs to be in place to enable the motor controller's 5V output to the ESP32):
 
-| Motor Wire        | Motor Controller Terminal          |
-|:-------------|:------------------|
-| Red           | OUT1                      |
-| Black          | OUT2       |
+<img src="{{ '/_assets/images/external_ESP32_power.png' | prepend: site.baseurl }}" alt="external_ESP32_power.png">
+<img src="{{ '/_assets/images/motor_controller_jumper.png' | prepend: site.baseurl }}" alt="motor_controller_jumper.png" width=400 height=400>
+
+If you want to power your ESP32 and motors while using a USB connection, simply remove one battery from the battery pack (creates open circuit) and take out the voltage regulator jumper on the motor controller (will make 5V terminal receive input). You should now be able use your USB connection safely!
+
+{: .highlight}
+Do NOT power your ESP32 through its 5V pin with the battery pack while simultaneously connecting it to your computer through USB! This may irreversibly damage your devices (only do one at a time).
+{: .callout-toby}
+
+To control a DC motor using the ESP32, a motor controller, and AA battery pack, you can connect them together as shown below:
+
+<img src="{{ '/_assets/images/motor_with_external_power.png' | prepend: site.baseurl }}" alt="motor_with_external_power.png">
+
+* You will need to remove the jumper shorting the ENA pin to 5V
+* You will need to use a screwdriver to clamp the power wires in place (all the wires connecting to the blue screw terminals) into place. Make sure these are secure because wires coming loose and causing a short circuit could be catastrophic!
+* Note that the wire polarity on the motor does not matter because DC motors' spin direction is based on the direction of current flowing through them.
+
+<br>
 
 |  Motor Controller Terminal   | ESP32 Pin          |
 |:-------------|:------------------|
-| +5V           | 5V                      |
+| 5V           | 5V                      |
 | IN1          | Any GPIO      |
 | IN2          | Any GPIO     |
 | ENA          | Any PWM enabled pin      |
 
+If you're not sure about the ESP32 pinout, then check out [this page!](https://ut-ras.github.io/RobotathonESP32/getting-started/microcontroller-interface)
+
+
 The following is an example of configuring and running the motor in software:
 ```cpp
 
 #include "sdkconfig.h"
 #include <Arduino.h>
 
 #define IN1  27  // Control pin 1
-#define IN2  26  // Control pin 2
-#define ENA  25  // PWM pin
+#define IN2  14  // Control pin 2
+#define ENA  12  // PWM pin
 
 void setup() {
   Serial.begin(115200);
@@ -79,7 +93,7 @@ void loop() {
   delay(1000); // Stop for 1 second
 }
 ```
-More detailed information about the L298N motor controllers can be [found here!](https://lastminuteengineers.com/l298n-dc-stepper-driver-arduino-tutorial/)
+Again, more detailed information about the L298N motor controllers can be [found here!](https://lastminuteengineers.com/l298n-dc-stepper-driver-arduino-tutorial/)
 
 # Servo Motors
 
@@ -93,15 +107,16 @@ Servos are motors that are designed for precise position control. Instead of fre
 
 For the servos in our competition, you can use it to precisely control your mechanism for the Mechanical Challenge. To interface it with your ESP32, you will connect the wires as follows:
 
+<img src="{{ '/_assets/images/servo_wiring.png' | prepend: site.baseurl }}" alt="servo_wiring.png">
+
 | Servo Wire        | ESP32 Pin          |
 |:-------------|:------------------|
 | Red           | 5V                      |
 | Black          | GND      |
 | White        |  Any PWM capable pin          |
 
-{: .highlight}
-If you're not sure which ESP32 pins are hardware PWM capable, then check out the diagram in [this page!](https://ut-ras.github.io/RobotathonESP32/getting-started/microcontroller-interface)
-{: .callout-toby}
+If you're not sure about the ESP32 pinout, then check out [this page!](https://ut-ras.github.io/RobotathonESP32/getting-started/microcontroller-interface)
+
 
 In this competition, we will be using the Arduino servo library to control the servos. The following is an example of how to spin a servo using the ESP32's pin 2 as the PWM output.
 

docs/_sections/_guide-primaries/sensors-and-actuators/color-sensors.md

@@ -16,6 +16,10 @@ The RGB sensor uses the RGB color space to represent the color that it receives
 
 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)
 
+Here is a wiring diagram:
+
+<img src="{{ '/_assets/images/color_sensor_wiring.png' | prepend: site.baseurl }}" alt="color_sensor_wiring.png">
+
 |  Color Sensor Pin   | ESP32 Pin          |
 |:-------------|:------------------|
 | VIN          | 3.3V                      |
@@ -27,7 +31,7 @@ If you want more details on how the color sensor works, check out [this link!](h
 Make sure to connect the color sensor's power pin to 3.3V! A 5V connection will fry the sensor.
 {: .callout-toby}
 
-insert wiring diagram here
+The SDA and SCL on the color sensor MUST be connected to the specified GPIO pins on the ESP32. This is because they are the dedicated pins for I2C commmunication.
 
 ## 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!

docs/_sections/_guide-primaries/sensors-and-actuators/ir-sensors.md

@@ -3,37 +3,41 @@ layout: default
 title: IR Sensor
 nav_include: true
 parent: Sensors and Actuators
-nav_order: 1
+nav_order: 2
 ---
 
 # IR Sensor
 
 <img src="{{ '/_assets/images/ir_sensor.png' | prepend: site.baseurl }}" alt="ir_sensor.png" width=200 height=300>
 
-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.
+A necessary component for any challenge that utilizes walls, analog IR sensors are a staple of Robotathon. This particular sensor is the GP2Y0A21YK0F model.
 
 ## How it Works
 IR distance sensors emit bursts of infrared 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 (see graph below) that can be read by the ESP32. See [this link for more information.](https://www.pololu.com/product/136)
 
 <img src="{{ '/_assets/images/ir-sensor-functionality.png' | prepend: site.baseurl }}" alt="ir-sensor-functionality.png">
 <img src="{{ '/_assets/images/ir-sensor-graph.png' | prepend: site.baseurl }}" alt="IR-sensor-graph.png">
 
+Notice that the sensor will output garbage if the sensor is too close to an object.
+
 ## Interfacing
-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:
+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 pin 12, as the signal pin. Hook up the circuit as follows:
+
+<!-- <img src="{{ '/_assets/images/ir_sensor_wiring.png' | prepend: site.baseurl }}" alt="ir_sensor_wiring.png"> -->
+<!-- decided not to include the above picture because it might be confusing with the adapter being the wrong colors lol -->
+
 
 {: .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!
+Note that some of our IR sensors may have preattached cables with incorrect color coding (Red and Black got switched). Be sure to follow the order 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    |
+| VIN  (Red)| 5V                      |
+| 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}
+If you're not sure about the ESP32 pinout then check out the diagram in [this page!](https://ut-ras.github.io/RobotathonESP32/getting-started/microcontroller-interface)
 
 ## 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 your terminal change as you move it towards and away from an object.
@@ -44,7 +48,7 @@ The following program will allow you to read values from the IR sensor in a loop
 
 #include <ESP32SharpIR.h>
 
-ESP32SharpIR IRSensorName(ESP32SharpIR::GP2Y0A21YK0F, 27);
+ESP32SharpIR IRSensorName(ESP32SharpIR::GP2Y0A21YK0F, 12);
 
 void setup() {
     Serial.begin(115200);
@@ -57,8 +61,7 @@ void loop() {
 }
 ```
 
-
 ## Extensions
-You received values from the sensor, but do they mean anything? The next step for the IR sensor is translating and thresholding it. Take a look at the above graph. There is a strong linear relationship between your signal value and the inverse of the distance away from the object. It’s your job now to code a function that returns an accurate distance given a voltage input value. After that, your team needs to threshold the data. When do the values become inconsistent (too close or too far)? What do you do with your robot when that happens?
+You received values from the sensor, but do they mean anything? The next step for the IR sensor is translating and thresholding it. Take a look at the above graph. There is a strong linear relationship between your signal value and the distance away from the object. It’s your job now to code a function that returns an accurate distance given a voltage input value. After that, your team needs to threshold the data. When do the values become inconsistent (too close or too far)? What do you do with your robot when that happens?