Add project documentation

Author: twilco

README.md

@@ -1,2 +1,15 @@
 # AVR RF Transmitter
 
+Here lies the code powering my 433mhz RF transmitter.  This transmitter supports 11 buttons and an analog stick, providing lots of potential inputs for any use case I might have for the receiving end circuit.  I utilized a cheap superheterodyne transmitter for this circuit which communicates via USART.  After some experimentation balancing between transmitter range and data able to be transferred per second, I've landed at a 2400 baud rate.  A complete data packet is transmitted roughly every 35 milliseconds.  I've also added in an easily configurable sleep mode when there are periods of inactivity in the name of battery preservation.
+
+### What's in a data packet?
+
+A packet is comprised of seven different bytes:
+
+1. `U` - This, and the following char, are our training bytes.  The binary value of `U` is `01010101`, which gives any receivers' data slicers a nice square wave to sync up with.  This makes them more receptive to the rest of our packet, which is important because that's where our actual data is.
+2. `U` - Another literal `U` training character.
+3. `button_byte` - Each bit in this byte corresponds to the status of our 8 non-special buttons that are on the top face of the transmitter.  If a bit in this byte is `1`, it means the associated button is currently pressed.
+4. `misc_byte` - A byte containing a conglomerate of bits that didn't fit anywhere else.  Here we have three bits corresponding to the pressed status of our left shoulder button, right shoulder button, and the button on the analog stick.  We also have the two most significant bits of both the x-axis and y-axis analog stick values.  The analog values of each axis are of 10-bit resolution, so rather than allocating two whole bytes for each one we instead put these MSBs here.
+5. `lsb_analog_stick_x_byte` - A byte containing the 8 least significant bits of the x-analog stick value.
+6. `lsb_analog_stick_y_byte` - A byte containing the 8 least significant bits of the y-analog stick values.
+7. `checksum` - Finally, we have our checksum byte.  The checksum is calculated by adding up all our data bytes (so no training characters).  Any overflow is ignored.  This gives the receiver a simple (and admittedly not perfect) way to ensure that the data they've received is valid.  

src/main.c

@@ -24,7 +24,7 @@ enum Buffer_Status construct_and_store_packet(struct Ring_Buffer* buffer, const
 #define DEFAULT_MISC_BYTE 0b01010000
 
 /* Number of seconds of user inactivity before the AVR should go to sleep. */
-#define SECONDS_BEFORE_SLEEP (uint16_t) 600
+#define SECONDS_BEFORE_SLEEP (uint16_t) 300
 
 /* Number of times Timer 2 needs to overflow before the AVR should go to sleep. */
 #define EIGHT_BIT_TIMER_MAX 255
@@ -186,17 +186,19 @@ ISR(PCINT2_vect)
 
 ISR(TIMER2_OVF_vect)
 {
+    // Send a packet every other timer overflow, and alternate analog-to-digital conversions between our two analog stick axes.
     if(timer2_overflows == 0) {
-         selected_adc_channel = ANALOG_STICK_Y;
-         timer2_overflows++;
+        selected_adc_channel = ANALOG_STICK_Y;
+        timer2_overflows++;
     } else if(timer2_overflows == 1) {
         selected_adc_channel = ANALOG_STICK_X;
         timer2_overflows = 0;
         should_construct_packet = true;
     }
     start_adc(selected_adc_channel);
 
-    // active high button first (analog stick button), then all active low buttons
+    // If the button value matches that of the last value from the last overflow, we know (almost certainly) that
+    // the value we're seeing is not a button bounce.  Let's set it in our data bytes.
     if(digital_input_status.analog_stick_btn_pressed == BIT_CHECK(ANALOG_STICK_BTN_PIN_REG, ANALOG_STICK_BTN_PIN)) {
         set_or_clear(BIT_CHECK(ANALOG_STICK_BTN_PIN_REG, ANALOG_STICK_BTN_PIN), &misc_byte, ANALOG_STICK_BTN_BYTE_POS);
     }

src/util/avr_util.c

@@ -65,6 +65,7 @@ void enable_pcint(enum Pcint_Group group)
     }
 }
 
+// Performs the necessary pre-sleep housekeeing items, and then puts the uC to sleep to preserver power.
 void enter_sleep()
 {
     sei();
@@ -81,6 +82,7 @@ void enter_sleep()
     disable_pcint(ALL_GROUPS);
 }
 
+// This function handles post-sleep house keeping items to get our uC back up and ready to go.
 void exit_sleep()
 {
     power_adc_enable();