Jcirce/getting started

docs/book.toml

@@ -4,3 +4,5 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Carrie Documentation"
+[preprocessor.katex]
+after = ["links"]

docs/src/SUMMARY.md

@@ -2,7 +2,11 @@
 
 [Introduction](./introduction.md)
 
-# hey does this work?
-- [Where to Start](./where-to-start.md)
-- [Building Her](./building-her.md)
-- [Tools](./tools.md)
+# Background
+- [Overview](./background/overview.md)
+- [Kinematics](./background/kinematics.md)
+
+# Operating Carrie
+- [Where to Start](./operation/where-to-start.md)
+<!-- - [Building Her](./building-her.md) -->
+<!-- - [Tools](./tools.md) -->

docs/src/background/kinematics.md

@@ -0,0 +1,12 @@
+# Kinematic Model
+<img src="../images/model.png"
+     alt="Kinematic Model"
+     style="max-height:300px;" />
+
+While writing the model and controls for Carrie, we specify the curvature of the path. To calculate the required steering angle, we use the bicycle model for front wheel steering vehicles. Because the vehicle is a rigid body, we can assume the entire vehicle has the same angular velocity around a a point of rotation with a radius $R$. The curvature $\kappa$ is calculated using equation below based on based on the steering angle $\delta$ and the wheel base $L$. Rearranging this equation yields the steering angle based on the desired curvature.
+
+$\kappa = \frac{1}{R} = \frac{tan(\delta)}{L}$
+
+Since we cannot directly measure the steering angle of the vehicle, we can use the same model to calculate the curvature the vehicle is traveling at based on the measured velocities of the rear wheels. The radius of curvature is calculated based on the velocities and half the track width $t$.
+
+$R = \frac{t}{2} \left ( \frac{v_{R}+v_{L}}{v_{R}-v_{L}} \right )$

docs/src/background/overview.md

@@ -0,0 +1,30 @@
+# Overview 
+In the Spring of 2023, under the supervision of Professor Shlayan, Cat and Jeannette undertook the task of bringing Carrie to life. Our research goal was to create a vehicle capable of parallel parking, no easy feat. When Carrie first came to us, she was an elegant mechanical design, but required a brain and power distribution to all of her components. 
+
+## Research Background
+When designing vehicle controls for parallel parking, there are two problems to solve: creating the trajectory and calculating the steering angle. 
+
+First, the trajectory of the parallel parking manuever. Since the typical manuever involves steering at the maximum angle both ways while moving backwards, the simplest trajectory is the combination of two circular paths [[1]]. Due to the sudden change in steering angle, the vehicle must stop midway through the manuever so that it is not thrown off the path [[2]]. This stop may be avoided if instead a more continuous path is chosen as the trajectory [[3]]. 
+
+Continuous paths for parallel parking include polynomials [[4]], b-spline curves [[5]], and clothoid curves [[3],[6]]. Clothoid curves [[7]] are curves with linearly changing curvature. They are used to design railways [[8]] and for vehicle trajectories because their curvature changes continuously, allowing the vehicle to follow said trajectory without stopping. Some have claimed clothoid curves are too computationally intensive [[9]] but they are still one of the most desireable trajectories for this type of vehicle, especially in parallel parking.
+
+The second problem is designing the controller for steering angle based on the desired trajectory of the vehicle. For parallel parking specifically, many have employed fuzzy controllers [[10], [11], [12]]. Many path following controllers have been developed for autonomous vehicles [[13]]. For geometric controllers, once the path is generated, the error (and eventual control signal) is based on the closest point along the path and the vehicles position and orientation relative to the path. 
+
+For parallel parking, various geometric techniques have been used: a look-ahead yaw error [[14]], and pure pursuit [[15]]. To our knowledge, Stanley control [[16]] has not been tested for parallel parking. Stanley geometric control is based on a combination of the heading (yaw) error and the cross track error (the distance the vehicle is from the path tangential to the path).
+
+[1]:(https://www.researchgate.net/publication/328798507_Automatic_Parallel_Parking_Algorithm_for_a_Carlike_Robot_using_Fuzzy_PDI_Control)
+[2]:(https://ieeexplore.ieee.org/document/620143)
+[3]:(https://ieeexplore.ieee.org/document/6548775)
+[4]:(https://ieeexplore.ieee.org/document/6395363)
+[5]:(https://journals.sagepub.com/doi/full/10.1177/0020294020944961)
+[6]:(https://ieeexplore.ieee.org/document/7962257)
+[7]:(https://pwayblog.com/2016/07/03/the-clothoid/)
+[8]:(https://archive.org/details/railwaytransiti02talbgoog/)
+[9]:(https://ieeexplore.ieee.org/document/9669069)
+[10]:(https://ieeexplore.ieee.org/document/5945221)
+[11]:(https://ieeexplore.ieee.org/document/1548645)
+[12]:(https://www.researchgate.net/publication/224350298_Development_of_an_automatic_parking_system_for_vehicle)
+[13]:(https://ieeexplore.ieee.org/document/8191998)
+[14]:(https://ieeexplore.ieee.org/document/6704211)
+[15]:(https://ieeexplore.ieee.org/document/4677655)
+[16]:(https://ieeexplore.ieee.org/document/4282788)

docs/src/images/.gitattributes

@@ -0,0 +1,2 @@
+carrie-cover.JPG filter=lfs diff=lfs merge=lfs -text
+model.png filter=lfs diff=lfs merge=lfs -text

docs/src/introduction.md

@@ -1 +1,12 @@
-# Introduction
+# Meet Carrie
+<img src="images/carrie-cover.JPG"
+     alt="Carrie in her former glory in 2023"
+     style="max-height:300px;" />
+
+Carrie is the vehicle originally designed for a study on geometric control for parallel parking by Catherine Van West and Jeannette Circe. 
+
+We designed Carrie to have a computer (a Raspberry Pi) and microcontroller (a Pico) on board, and a custom PCB for power conversion from a power supply or a battery, which provides the necessary voltages for all systems. The PCB contains two motor drivers, one connecting to two motors with a differential so that the rear wheels can follow any path without slipping. The second motor driver controls the steering motor. The steering is an Ackermann configuration for stability and so that the vehicle can drive without slipping, with the same kinematics as any car on the road. We control the steering angle by a motor on a set of gears that attach to one side of the front axle. Each of the rear wheels has a quadrature encoder attached so that we can measure both position and direction of the each wheel. The vehicle has a large power supply so that it can operate for long periods of time without needing to recharge or replace the battery. Impact attenuators (pool noodles) are attached so that in the case of a crash, the components will not break. 
+
+The high level geometric control signals are calculated based on the current position and calculated path based on the desired end position and orientation sent by the user. The required steering angle at any point on the path is calculated by the Raspberry Pi and sent to the Pico microcontroller. The Pico contains the low-level control firmware with a PID controller on both the rear motor speed and the front motor steering actuation based on the encoder readings. Carrie is able to travel anywhere in the room along a calculated clothoid trajectory.  
+
+Inside this documentation, you'll find everything we know about Carrie and how you can use her to explore trajectory following controls for steering vehicles! 

docs/src/operation/where-to-start.md

@@ -0,0 +1,2 @@
+# Where to Start
+Operations guide is currently in progress, check back soon!