diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index e147608..a1db9b8 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -1,6 +1,7 @@ # Summary - [Introduction](./intro.md) + - [Why TinyKart](./why.md) - [Hardware BOM and Overview](./bom.md) - [Chapter 1: Installation](./installation.md) - [PlatformIO](./installation_pio.md) diff --git a/book/src/assets/tinykart-misc.jpg b/book/src/assets/tinykart-misc.jpg new file mode 100644 index 0000000..e50b68e Binary files /dev/null and b/book/src/assets/tinykart-misc.jpg differ diff --git a/book/src/auton_intro.md b/book/src/auton_intro.md index 2d3d9af..3646673 100644 --- a/book/src/auton_intro.md +++ b/book/src/auton_intro.md @@ -1,5 +1,7 @@ # The Part Where we Make it Move + + Ladies, gentleman, baby lidar - it's finally time to make TinyKart autonomous! This is going to be a multipart process, and be quite a bit more involved than the prior sections. This is why we're diff --git a/book/src/bom.md b/book/src/bom.md index cffc378..afb8237 100644 --- a/book/src/bom.md +++ b/book/src/bom.md @@ -1,3 +1,43 @@ -# Hardware +# Hardware BOM -TODO cover what hardware is required, and explain its role \ No newline at end of file +> Note: If you are doing this with ISC, we already have this hardware available. + +## Kart + +> est. cost: $200 + + + +We use the Traxxas Slash as our platform. Unfortunately, it seems like it may no longer be available, so any brushed +Traxxas RC car should also work. The slash was chosen for its size, but other RC cars should also be reasonable. +The only part of the codebase that depends on the RC car is the ESC control, which we've found to not be portable to +some other brand ESCs in the past. It may be portable with some work, however. + +Note that you will also need a 2s LiPO. + +## LiDAR + +> est. cost: $100 + + + +We use the [LD06](https://www.inno-maker.com/product/lidar-ld06/) for our LiDAR. The driver will only work with this. + +## Nucleo + +> est. cost: $30 + + + +We use the [STM32 H723ZG nucleo](https://www.st.com/en/evaluation-tools/nucleo-h723zg.html) as our microcontroller. +Pretty much any H7 should work, although pins may need to be reassigned. + +Because we use the HAL in the background, some headers would need to be changed to use other series boards, like +F4 or something. Porting to non-ST boards will require re-writing the logger.hpp and dma files. + +# Misc. + +You should also have: +- A breadboard or something similar +- Some male to male jumper wires +- A micro usb cable \ No newline at end of file diff --git a/book/src/intro.md b/book/src/intro.md index a64e735..b107f8b 100644 --- a/book/src/intro.md +++ b/book/src/intro.md @@ -1,3 +1,45 @@ # Introduction to _The TinyKart ™️_ -TODO introduce the idea of the project, its goals, and audience \ No newline at end of file + + +TinyKart is the [Intelligent System Club's](http://iscumd.com) entry level project to introduce new members to +several areas of robotics, while having a strong supporting codebase to ensure it does not become overwhelming. + +This book serves both as a reference and course for anyone looking to make their own TinyKart, or just curious on how +any part of it works. + +**Some topics covered by this book:** +- Setting up an Arduino environment in PlatformIO +- LiDARs, and processing their data +- UART communication +- Interacting with motors +- Ackermann kinematic models +- A basic autonomy stack built around sense-think-act: + - Basic reactionary planners + - Pure Pursuit + +By the end of this book, you will have created your own implementation of a reference TinyKart. Armed with your newfound +knowledge, you will then expand on what you've made, and race against other students! + +## Prerequisites + +While this book assumes little of the reader outside a desire to learn, there are a few things we have to require: +- A Windows or Linux computer + - Mac may work, but is not tested +- Basic working knowledge of C++ + - This book is about robotics, not C++. The C++ used is not very complex, but may require some googling if syntax is + new to you. Additionally, the codebase makes use of modern C++ features like std::optional. When relevant, links to + external resources are provided for your reference. +- Very basic electrical knowledge + - If you know what 5V and ground are, you're good. + +## Notable topics not covered + +TinyKart is deliberately left basic, to fill the gap between something like E100 and F1/10. Because of this, a few major +topics in mobile robotics are not covered, and are best learned through other media: +- Odometry + - Localisation + - SLAM and VSLAM +- Computer vision +- Control theory +- DSP \ No newline at end of file diff --git a/book/src/onwards.md b/book/src/onwards.md index 9da2891..d0eb193 100644 --- a/book/src/onwards.md +++ b/book/src/onwards.md @@ -1,3 +1,28 @@ # Onwards -TODO cover the competition and some ideas \ No newline at end of file +Well done! By this point you should have a complete, workable TinyKart. + +From here, how you improve TinyKart is up to you. You could add sensors, improve algorithms, and more. + +## Competition + +If you are a part of ISC, we plan to have a competition at year-end, where TinyKart teams can race each other to find +the one true TinyKart. + +This competition will be based around time trials. The goal is for each team to make their TinyKart as fast as possible, +while still avoiding hitting walls. + +More information on this event will be given on a semester by semester basis. + +## Ideas + +Some ideas for areas to improve TinyKart, if I was doing it: +- Adding an encoder + - Encoders would allow for measuring the karts speed. This allows for much more advanced control over speed, allowing + the creation of true speed control. +- Adding sensors that can be polled faster than the LiDAR + - You may be able to use things like sonar to get faster readings than the LiDAR, as a secondary perception source +- New algorithms + - The path solutions provided are far from optimal. As you try tuning these, think about how our specific TinyKart + track setup could be exploited. + diff --git a/book/src/why.md b/book/src/why.md new file mode 100644 index 0000000..9557c9b --- /dev/null +++ b/book/src/why.md @@ -0,0 +1,96 @@ +# Why TinyKart + +> Note: this page is mostly for those more experienced, and are curious why TinyKart exists. If you're a student +> just looking to work on a TinyKart, disregard this page. + +TinyKart may appear to be a bit redundant at first, so I want to justify why ISC created this program, and it's larger +goals. + +## The Background + +Before TinyKart, being onboarded into ISC was a rough process. New members were essentially just thrown unto a project +and left to fend for themselves. While this did yield a few generational talents that ended up leading the team through +each of its generations through their sheer motivation, this model ultimately limited the clubs scope. + +Because of the classes at UofM Dearborn, it is functionally impossible for students under senior year to participate in +robotics purely off knowledge from courses. In the case of CS majors, _it is literally impossible_, as all robotics +courses are in a different department. This is why, if the club has no program, talent in ISC largely originates from +pure tenacity and the loyal efforts of generally about 3 or so current members acting as mentors. This leads to teams +around 8-10 in size. + +## The Problem + +So why is this a problem? After all, ISC existed for years as essentially just a small group and did pretty well. +While there are a few perspectives on this, I'll give mine as the software lead. + +### Bus factor, or program stability + +> _Bus factor (noun): the number of people that need to get hit by a bus before your project is completely doomed._ + +I'm stealing this term from the wonderful [Google SWE book](https://abseil.io/resources/swe-book/html/toc.html). Bus +factor refers to, rather crudely, the number of people on +a project that can be hit by a bus before the project collapses. This is really just another way of calling someone a +single point of failure, weather that be in their knowledge of some problem, or their organisational knowledge and +rapport. + +ISC's tendency to have a small, highly capable, ingroup leads it to be highly vulnerable to SPOF. This is rather +self-explanatory, as with a small team it simply isn't feasible to distribute work among members, while the project is +so challenging that its basically luck to find people capable of understanding everything. + +While one can trivially expect this to cause issues when the bus hits, like missing deadlines, it causes a more +existential issue. + +#### Time is a bus + +Every four years or so, people graduate. This means that, however careful you are, your SPOF _will happen_ eventually. +When your SPOF leaves, it's up to luck that someone puts in the time to take their place, only to become a new SPOF. + +The answer to this issue is simple, of course - just train members. + +In reality though, it's far more difficult. This is because the SPOF _is the only one who can train members_. This SPOF +is also the one who is making the project possible however, so it's unreasonable to expect them to both mentor a ton +of people and fulfill their work. This leads to a hideous cycle, where every four years the SPOF graduates, everyone +who doesn't have the ability to take their spot leaves, a new SPOF is created, the club finally seems to get traction, +they graduate, and the cycle continues. Indeed, this is the cycle the team has been in for the last four years. + +**TL;DR, a small team means you cannot train members, which means you cannot do cool things.** + +## The Solution + +TinyKart is our answer to the above problem. + +In its simplest form, TinyKart is a course designed to bring a ton of people into the labspace, and get them to at least +a base level understanding of robotics. From there, those that remain, for there will always be attrition, will have the +chance to work in a team and experiment with software on a project far simpler and less daunting than large projects. + +The goal of this is to break the cycle by iteratively growing the club body year by year. Critically, this doesn't mean +that we want TinyKart to teach all that the team needs. Rather, it's just an interesting problem to get people in the +labspace and up to a certain level of knowledge. Once they go to learn the big projects, they should be able to avoid the +SPOF by means of numbers. Will this avoid a SPOF entirely? Probably not. But by virtue of pure numbers, it should be +easier to, at least, train up the next year of TinyKart members, to avoid the team completely falling apart when the SPOF +leaves. + +With this in mind, TinyKart has a few major choices: +- It should have minimal prerequisites +- It should have fallbacks, so if someone fails they don't get left behind +- It should be doable _without meetings at all if required_ + - Hence, this book +- It should focus on getting people to work together at ISC first, before critically challenging people + - This is why we don't cover localisation +- It should allow for more exploratory work later, after people are more committed to the club socially, and thus more + willing to stick through hard parts + +### Why not F1/10? + +I want to briefly address why we didn't just use F1/10, since this question comes up a lot. While F1/10 is great, +it doesn't really meet the program needs above. For two main reasons. + +First, It's just very expensive. The f1/10 platform is like $1500 all included, which is just crazy. TinyKart is around +$350 all things included, which is far more scalable for us. + +Second, because we don't want to get too deep into robotics for sake of accessibility, we want to avoid ROS. I love ROS, +but it has a crazy learning curve, especially because you need to learn quite a lot of C++ to use it. Most of our new +members barely even know C++, and often have only had one programming course. Conveniently, they have also almost all +at least heard of Arduino, so it makes sense for us to exploit that. Because of this we also have to run with microcontrollers, +which conveniently also simplifies the hardware considerably. +