Add to system documentation

little-red-rover · Nov 5, 2024 · b465fed · b465fed
1 parent ee952b0
commit b465fed
Show file tree

Hide file tree

Showing 8 changed files with 2,045 additions and 62 deletions.
diff --git a/_images/lrr_schematic.pdf b/_images/lrr_schematic.pdf
diff --git a/_images/system_overview/little_red_rover_system_diagram.svg b/_images/system_overview/little_red_rover_system_diagram.svg
diff --git a/_scripts/kicanvas.js b/_scripts/kicanvas.js
diff --git a/_sidebar.md b/_sidebar.md
@@ -2,13 +2,14 @@
     - [Assembly](assembly.md "Assembly | Little Red Rover")
     - [Software Installation](software_installation.md "Quickstart | Little Red Rover")
 * Tutorials
-    - [Comming soon...](tutorials.md)
+    - [Coming soon...](tutorials.md)
 * System Documentation
     - [Overview](system_overview.md)
-    - [Hardware - Coming soon...](hardware.md)
-    - [Firmware - Coming soon...](firmware.md)
-    - [ROS Drivers - Coming soon...](ros_drivers.md)
-    - [Hardware Sourcing Guide - Coming soon...](hardware_sourcing.md)
+    - [Hardware](hardware.md)
+    - [Firmware](firmware.md)
+    - [ROS Drivers](ros_drivers.md)
+    - [Tooling](tooling.md)
+    - [Hardware Sourcing Guide](hardware_sourcing.md)
 * Contributing
     - [Coming soon...](contributing.md)
 * Troubleshooting

diff --git a/hardware.md b/hardware.md
@@ -1,5 +1,61 @@
 # Hardware Documentation
 
-Coming soon...
+[Find the open source hardware project on GitHub](https://github.com/little-red-rover/lrr-hardware)
+
+Little Red Rover's hardware design is influenced by the same core priorities as the rest of the project:
+
+1. Make it affordable (under $150)
+2. Make it reliable (so it can be used in a large class without issues)
+3. Make it capable (enough to be worth teaching a college course with)
+
+These priorities, especially #1, played a major role in the design process.
+
+## Off the Shelf Parts
+
+Little Red Rover is a two wheel, differential drive mobile robot.
+It consists of the following off the shelf parts:
+
+
+## Electrical Design
+
+### The circuit board
+
+In recent years, custom printed circuit boards (PCBs) have become affordable enough for small batch production.
+Little Red Rover's PCB is designed to be manufactured and assembled affordably, arriving fully functional on your doorstep, no soldering required.
+
+Circuit boards can also be ordered with arbitrary outlines, making it possible to use them as mechanical parts.
+LRR uses its circuit board as the main body of the robot, saving on parts count and helping with strength.
+
+### Schematic
+
+<kicanvas-embed src="https://raw.githubusercontent.com/little-red-rover/lrr-hardware/refs/heads/main/little_red_rover/little_red_rover.kicad_sch" controls="full" theme="kicad"> </kicanvas-embed>
+
+### Layout
+
+<kicanvas-embed src="https://raw.githubusercontent.com/little-red-rover/lrr-hardware/refs/heads/main/little_red_rover/little_red_rover.kicad_pcb" controls="full" theme="kicad"> </kicanvas-embed>
+
+### Microcontroller
+
+Little Red Rover is based around the ESP32-S3-MINI system on a chip from EspressIf.
+The S3 was chosen because it has wireless capability (Wi-Fi and BLE) out of the box, plenty of IO, and an extensively documented SDK. 
+
+### Sensors
+
+The rover includes the following sensors:
+
+### Power system
+
+Little Red Rover is powered by a single cell Lithium-ion battery.
+Lithium batteries can be extremely dangerous if used improperly, so great care must be taken to ensure safety.
+
+The first set of protections are built into the battery itself.
+The rover uses a protected 18650 battery, which means the battery includes a circuit in its housing that provides under voltage, over voltage, and short circuit protection.
+
+The second set of protections are provided by the BQ24072RGT IC.
+This battery charger chip manages safely charging and discharging the battery.
+
+## Mechanical Design
+
+Holding all the parts together are 7 3D printed components, designed to be printed on a low-end hobby grade machine.
+
 
-This page will document Little Red Rover's hardware design.
diff --git a/index.html b/index.html
@@ -107,12 +107,17 @@
             --table-row-odd-background: none;
 
             --docsifytabs-border-color: #707070;
+
+            --heading-font-weight: 500;
         }
     </style>
 </head>
 
 <body>
     <div id="app"></div>
+
+    <script type="module" src="/_scripts/kicanvas.js"></script>
+
     <script>
         window.$docsify = {
             name: 'Little Red Docs',
@@ -133,6 +138,7 @@
     <!-- Required -->
     <script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/js/docsify-themeable.min.js"></script>
 
+
     <!-- Recommended -->
     <!-- TODO: Remove CDN dependencies -->
     <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>

diff --git a/system_overview.md b/system_overview.md
@@ -1,76 +1,86 @@
 # System Overview
 
-Little Red Rover consists of four major components:
-1. Hardware
-    * The physical components that make up the rover.
-2. Firmware
-    * The software the runs on the microcontroller onboard the rover.
-3. ROS Drivers
-    * ROS code that facilitates communication between the host computer and the rover. 
-4. Tooling
-    * Tools support cross platform support for the Rover.
+## Design motivation
+
+ROS enabled robots are expensive. Like $800 just to dip your toes in the water expensive. This prevents many aspiring engineers from ever working with ROS. It doesn't have to be this way.
+
+Little Red Rover is designed to be the first truly affordable ROS enabled robot for education.
+In order of priority, Little Red Rover's goal is to be:
 
-This page gives a high level overview of each component and how they interconnect.
-Each of these components are descibed in detail on their own page.
+1. Less expensive than a textbook (nominally $100 - $150).
+2. Reliable enough to use in classrooms of 200+ students.
+3. Capable enough to use in interesting assignments for a college level robotics course.
 
-## System Diagram
+Some non-goals of the project are:
 
-**TODO**
+1. Using high end, research grade components (conflicts with priority #1)
+2. Be highly extensible (conflicts with priority #2, and in some ways #1)
 
-Everyone loves a good diagram.
+In other words, Little Red Rover is your starter car for ROS.
+It not as fast as other cars, but its affordable, safe, and reliable.
+Once you've learned enough to know what you want in your next robot, you'll be prepared and educated enough to go and buy it.
 
-## Hardware to Firmware Interconnect
+These core priorities impacted every design decision that went into the rover.
 
-An ESP32-S3 microcontroller is used to orchestrate the rover's functionality.
-Heres what it controls, and how:
+## Comparison to other systems
 
-* Planar LiDAR scanner
-    * Communicates over UART
-* 6 degree of freedom IMU
-    * Communicates over I2C
-* Two DC motors
-    * Controlled using PWM
-* Wheel encoders
-    * Pulses counted using the [ESP32 PCNT peripheral](https://docs.espressif.com/projects/esp-idf/en/v5.3.1/esp32/api-reference/peripherals/pcnt.html)
-* Status LEDs
-    * Controlled using the [ESP32 RMT peripheral](https://docs.espressif.com/projects/esp-idf/en/v5.3.1/esp32/api-reference/peripherals/rmt.html)
+How is Little Red Rover different from other ROS enabled systems?
+Little Red Rover focuses on doing more with less.
 
-Commands and sensor data are exchanged over wifi, as descibed in the following section.
+### The status quo
 
-## Firmware to ROS Interconnect
+Existing robots are build around single board computers (SBCs) like the Raspberry Pi series or NVIDA Jetson.
+These SBCs run Linux and ROS onboard the robot.
+This is great if you want a fully self-contained robot, but it does come with some downsides.
 
-The ESP32 onboard the rover is wifi capable.
-To communicate with the host computer, the ESP32 starts an wifi access point (think hotspot).
-When the host computer connects to the rover access point, the firmware logs the relevant IP and opens a UDP socket with that IP on port 8001.
+The first is cost.
+Getting a Raspberry Pi this isn't so bad, costing just $35 at the time of writing.
+But if you want something with more kick, you'll have to open your checkbook.
+The Jetson lineup will run you anywhere from $250 all the way up to $2000 depending on your requirements.
 
-Sensor data from the robot is serialized (turned a language neuteral binary format) using [Protocol Buffers](https://protobuf.dev/).
-Specifically, the firmware side serialization uses [nanopb](https://github.com/nanopb/nanopb) to serialize it's c data structures.
-The serialized data is sent over the UDP port, where it is unpacked in Python using the `protobuf` package.
-Commands from ROS are communicated the same way, just in the inverse direction.
+The second is performance.
+SBCs are fundamentally limited by their size, and further kneecapped by the low power requirements of a small mobile robot.
+You're not going to be seeing anything close to a laptop or desktop computers' performance without seriously breaking the bank.
 
-Within ROS, messages are interpreted by the hardware abstraction layer (HAL).
-The HAL is a node that serves as a translator between ROS messages and Protocal Buffer messages.
-For outgoing messages, it subscribes to all topics relevant to the robot, repackages any incoming data into a buffer, then sends the message over UDP.
-For incoming data it listens on the UDP port for messages from the rover, then unpacks the data and publishes it as a ROS message on the relevant topic.
+### What Little Red Rover does differently
 
-> [!NOTE]
-> The hardware abstraction layer is currently implemented as a python ROS node.
-> The idiomatic, ROS-y way to handle this problem is implementing a hardware controller using [ros_control](https://wiki.ros.org/ros_control).
-> This improvement is tracked in an issue on the [ros driver's github](https://github.com/little-red-rover/lrr-ros/issues/2).
+Unlike existing robots, LRR does not include a single board computer.
+Instead, it uses a low-cost microcontroller to communicate wirelessly with a base station.
+This base station can be any computer you already own, running any operating system.
 
-## ROS to User Interconnect
+The flow looks like this:
+1. The rover sends sensor information to the base station.
+2. The base station uses the data to compute commands.
+3. Commands are sent back to the rover.
+4. The rover executes the commands.
+5. Repeat
 
-The offical advice for getting started with ROS is to first install Linux. This is where many people's ROS journey started and ended.
+### Pros and cons
 
-Little Red Rover is built for begginers, so this was an unacceptably obtuse solution.
-Instead, the project provideds a containerized development environment through [Docker](https://www.docker.com/) and [DevContainers](https://containers.dev/).
+When compared to other robots, Little Red Rover lack the ability to operate independently of the base station.
+In return, it gains computational performance and saves on cost.
+In an educational setting, we feel this trade off is a no-brainer.
+Educational robots are meant to be worked with interactively and observed, not to operate unsupervised.
+
+## System breakdown
+
+Little Red Rover consists of four subsystems:
+1. Hardware
+    * The physical components that make up the rover.
+2. Firmware
+    * The software the runs on the microcontroller onboard the rover.
+3. ROS Drivers
+    * ROS code that facilitates communication between the host computer and the rover. 
+4. Tooling
+    * Tools supporting cross-platform usage of the Rover.
 
-Docker provides a container runtime - a piece of software that allows you to run portable and self contained software applications.
-Portable means they will run on any host OS, and self contained means they contain all dependencies of the software (including the OS!).
+How the hardware, firmware, and ROS communicate is described by their interconnects:
+1. Hardware to firmware interconnect
+    * How firmware reads data from the hardware and sends commands to the actuators.
+2. Firmware to ROS interconnect
+    * How data from the robot gets transmitted to the host computer's ROS instance.
 
-DevContainers provide utilities for using containers not only to run software, but also to develop it.
-Notably, DevContainers are integrated into VSCode to provide a one button solution for launching a containerized developement environment.
+The following system diagram gives a high level overview of the system.
+For further details, consult each subsystem's page.
 
-It is difficult to run graphical apps from within a Docker container, so we leverage web based visualization tools.
-The best of which is, in my opinion, [Foxglove](https://foxglove.dev).
-Foxglove communicates with ROS using a websocket connection, allowing the user to visualize the robot and its data in real time.
+![System Overview Diagram](./_images/system_overview/little_red_rover_system_diagram.svg)
diff --git a/tooling.md b/tooling.md
@@ -0,0 +1,5 @@
+# Tooling
+
+Coming soon…
+
+This page will document Little Red Rover’s tooling.