diff --git a/Arduino/README.md b/Arduino/README.md index 4aaed924..c48f04a5 100644 --- a/Arduino/README.md +++ b/Arduino/README.md @@ -7,26 +7,26 @@ This folder is not a part of the ROS package structure. It contains the code tha This section describes the internals of communication between the Raspberry Pi and the Arduino. You don't need to understand these if you just want to get your rover running. -### Initilization Packet -There is an initilization exchange between the Raspberry Pi and Arduino which is used to let each device know the other +### Initialization Packet +There is an initialization exchange between the Raspberry Pi and Arduino which is used to let each device know the other one is ready to send/receive data. Until each device has correctly agreed upon them they will both be in an IDLE state. -The Raspberry Pi will continually send its initilization command at a 2Hz frequency until it recieves the Arduino's -initilization command. The Arduino sits and listens constantly until it hears this command, and then transistions into -a RUNNING state, and sends its' initilization command. While in IDLE the RPi listens for this command, and will also -transistion to RUNNING upon receiving it. +The Raspberry Pi will continually send its initialization command at a 2Hz frequency until it receives the Arduino's +initialization command. The Arduino sits and listens constantly until it hears this command, and then transitions into +a RUNNING state, and sends its' initialization command. While in IDLE the RPi listens for this command, and will also +transition to RUNNING upon receiving it. | `Name` | `Value` | |---------------|------------------| | RPi Init | 0xA | | Arduino Init | 0xCD | -Once both of them have agreed upon recieving each other's initilization command they will both be in a RUNNING state +Once both of them have agreed upon receiving each other's initialization command they will both be in a RUNNING state sending the normal telemetry packet. If either system hits the timeout constant on listening for the telemetry packet -they will be transistioned back to the IDLE state, in which initilization must occur again. +they will be transitioned back to the IDLE state, in which initialization must occur again. ### Preamble -The preamble (or syncword) is used to do bit-level syncronization of the data frames between the two system. +The preamble (or syncword) is used to do bit-level synchronization of the data frames between the two systems. It is the first 2 bytes of every single message. | | | | | | @@ -41,7 +41,7 @@ re-calculated on both sides of the data stream. It is calculated as the uint16_t or the SUM of all bytes in the data packet except for the preamble (and itself of course) ### Data Frames -The data frame is a total of 16 bytes sent, and will have the following structure +The data frame is a total of 16 bytes sent and will have the following structure. | `PREAMBLE` | `CONN` | `BATTERY` | `ERROR` | `TEMP` | `DRIVE_CURRENT` | `STEERING_CURRENT` | `FACE` | `CHECKSUM` | |------------|--------|-----------|----------|-----------|-----------------|--------------------|---------|------------| @@ -55,10 +55,10 @@ Connected Status of the remote controller to the Robot. 1 Byte length |---------|---------------------------------------------------------| | 0x01 | Remote connected | | 0x00 | Remote disconnected | -| 0xFF | Overloaded to transistion the arduino back to IDLE state| +| 0xFF | Overloaded to transition the arduino back to IDLE state| ##### BATTERY -Battery value read in by the motor controllers. 1 Byte length. The value ranges from 0x00 to 0x1F, based on battery % +Battery value is read by the motor controllers. 1 Byte length. The value ranges from 0x00 to 0x1F, based on battery % | `Value` | `Battery % ` | |---------|--------------| @@ -71,7 +71,7 @@ Battery value read in by the motor controllers. 1 Byte length. The value ranges #### Status Error status of each individual motor controller. 1 Byte length. Each motor controller error status is x << i bits, -where x indicates an error, is 1 if error and 0 otherwise +where x indicates an error, is 1 if error, and 0 otherwise | Motor Controler Address | Binary (if error) | |-------------------------|-------------------| @@ -87,7 +87,7 @@ had errors the error message would be `0000 1010` #### TEMP Temperature reading coming off of each RoboClaw. 3 Bytes length, where each nibble corresponds to a motor controller, with possible nibble values from 0x0 to 0x4, which ranges from temperatures 28-40 C. The TEMP values are binned into -every 20% of the total range, which are also shown below +every 20% of the total range, which is also shown below | `NIBBLE NUM`| 0 | 1 | 2 | 3 | 4 | 5 | |-------------|-------|-------|-------|-------|-------|-------| @@ -103,9 +103,9 @@ every 20% of the total range, which are also shown below #### DRIVE_CURRENT -Driving motors current reading coming off of each RoboClaw. 3 Bytes length, where each nibble corresponds to a motor +Driving motors current reading coming off of each RoboClaw. 3 Bytes in length, where each nibble corresponds to a motor controller, with possible nibble values from 0x0 to 0x4, which ranges from current 0-1 amps. -The current values are binned into every 20% of the total range, which are also shown below +The current values are binned into every 20% of the total range, which is also shown below. | `NIBBLE NUM`| 0 | 1 | 2 | 3 | 4 | 5 | |-------------|-------|-------|-------|-------|-------|-------| @@ -136,7 +136,7 @@ controller, with possible nibble values from 0x0 to 0x4, which ranges from curre |0.8 < A | 0x4 | #### FACE -Command for the face. __TO DO: ADD THIS FUNCTIONALITY IN STILL, FOR NOW FACE IS STATIC__ +The command for the face. __TO DO: ADD THIS FUNCTIONALITY IN STILL, FOR NOW, FACE IS STATIC__ ### Example @@ -153,12 +153,12 @@ The following data is in the format which is passed from the ROS topic `/status` | STEER_CURRENT| [9,5,9,6] | | FACE | 1 | -First each of these values must be converted into its' respective values, and then inserted into the correct spot into +First, each of these values must be converted into its' respective values, and then inserted into the correct spot into the data frame. -The Battery is full, and will be 0x1F +The Battery is full and will be 0x1F -Motor controllers 129, 130, 131 have errors, which means that the STATUS binary code generated should be: `0000 1110` +Motor controllers 129, 130, and 131 have errors, which means that the STATUS binary code generated should be: `0000 1110` Using the above information in the TEMP description we can see the TEMP should bytes should be 0x01, 0x12, 0x10 diff --git a/Emulation/README.md b/Emulation/README.md index 561c5b59..60b12a72 100644 --- a/Emulation/README.md +++ b/Emulation/README.md @@ -2,7 +2,7 @@ This project provides a Docker-based emulation environment for a rover control system using ROS 2 Foxy. -We currently have command and control emulation +We currently have command and control emulation. Possible things we can add: diff --git a/README.md b/README.md index 82ed2234..4568c5a4 100644 --- a/README.md +++ b/README.md @@ -9,17 +9,17 @@ The rover runs on ROS2 (tested on Foxy), mostly using Python 3. ## Internals & structure -Please refer to README files associated with each folder for insight in how components work and what they do. +Please refer to the README files associated with each folder for insight into how components work and what they do. This is also the place to look when you have modifications on your rover that require the code or parameters to be changed. * The [ROS overview](ROS/README.md) gives an overview of the setup related to ROS and links to specific implementations such as how the drive and corner commands are being calculated -* The [Arduino readme](Arduino/README.md) details the code that runs on the Arduino, used to control the LED screen. +* The [Arduino readme](Arduino/README.md) details the code that runs on the Arduino, which is used to control the LED screen. ## Setup -The setup directory contains tutorial files for getting everything setup and configured for running the rover code. You should proceed through them in the following order: +The setup directory contains tutorial files for getting everything set up and configured for running the rover code. You should proceed through them in the following order: - [Arduino setup](setup/arduino.md) - [Raspberry Pi setup with Ubuntu 20.04](setup/rpi.md) - [Rover code bringup](setup/rover_bringup.md) diff --git a/ROS/README.md b/ROS/README.md index 3c47f347..7b33ff1b 100644 --- a/ROS/README.md +++ b/ROS/README.md @@ -10,14 +10,14 @@ structure, which are covered below * `osr_bringup`: configuration and launch files for starting the rover * `led_screen`: code to communicate to the Arduino Uno to run the LED screen -Please refer to the docstrings wihin each file to gain understanding of the internals as that is the most +Please refer to the docstrings within each file to gain an understanding of the internals as that is the most up-to-date and complete source of information. ### osr * `roboclaw.py`: copy of the roboclaw python library, API to the roboclaw controllers. ROS agnostic * `roboclaw_wrapper.py`: ROS node that wraps around and abstracts the roboclaw library. Takes in commands and reports - state of each motor + the state of each motor * `rover.py`: ROS node that controls the rover, taking in high-level commands and calculating motor commands which are sent to `roboclaw_wrapper.py` @@ -30,8 +30,7 @@ and units. ### osr_bringup -The osr_bringup package contains the launch file necessary to start all the ROS nodes, -as well as the operating parameters for the robot. +The osr_bringup package contains the launch file necessary to start all the ROS nodes, as well as the robot's operating parameters. ### led_screen