apps: Added comments to the top of every app explaining what it does.…

… For the apps available in the Pololu Wixel User's Guide, added a link to the user's guide.

This should improve the experiences of people who are browsing through the github repository to look at the apps.

apps/example_blink_led/example_blink_led.c

@@ -1,3 +1,11 @@
+/** example_blink_led app:
+This app blinks the red LED.
+
+For a precompiled version of this app and a tutorial on how to load this app
+onto your Wixel, see the Pololu Wixel User's Guide:
+http://www.pololu.com/docs/0J46
+*/
+
 #include <wixel.h>
 #include <usb.h>
 #include <usb_com.h>

apps/example_usb_com/example_usb_com.c

@@ -1,9 +1,11 @@
-#include <wixel.h>
-#include <usb.h>
-#include <usb_com.h>
-#include <stdio.h>
+/** example_usb_com app:
+
+This example app shows how to process and respond to commands received from
+a USB virtual COM port.  The command protocol is documented below.
+
+
+== Serial Command Protocol ==
 
-/* Serial Command Protocol *****************************************************
 Command Name: Toggle Yellow LED
 Protocol:
   Computer sends 0x81 OR the ASCII encoding of character 'y' (0x79).
@@ -29,6 +31,11 @@ Command Name: Get Time
   milliseconds that the Wixel has been running for.
 */
 
+#include <wixel.h>
+#include <usb.h>
+#include <usb_com.h>
+#include <stdio.h>
+
 #define COMMAND_TOGGLE_YELLOW_LED   0x81
 #define COMMAND_GET_X               0x82
 #define COMMAND_SET_X               0x83
@@ -179,7 +186,7 @@ void processByte(uint8 byteReceived)
         case 't':
             time = getMs();
             // SDCC's default sprintf doesn't seem to support 32-bit ints, so we will
-            // split getMs in to two parts and print it in hex.
+            // split getMs into two parts and print it in hex.
             responseLength = sprintf(response, "time=0x%04x%04x\r\n", (uint16)(time >> 16), (uint16)time);
             usbComTxSend(response, responseLength);
             break;

apps/io_repeater/io_repeater.c

@@ -1,3 +1,13 @@
+/** io_repeater app:
+
+This app allows you to wirelessly extend the reach of your microcontroller's
+I/O lines using two or more Wixels.
+
+For complete documentation and a precompiled version of this app, see the
+"I/O Repeater App" section of the Pololu Wixel User's Guide:
+http://www.pololu.com/docs/0J46
+*/
+
 /** Dependencies **************************************************************/
 #include <cc2511_map.h>
 #include <board.h>

apps/radio_sniffer/radio_sniffer.c

@@ -1,42 +1,45 @@
-/* radio_sniffer app:
- *
- * == Overview ==
- * This app shows the radio packets being transmitted by other Wixels on the
- * same channel.
- *
- * == Technical Description ==
- * A Wixel running this app appears to the USB host as a Virtual COM Port,
- * with USB product ID 0x2200.  To view the output of this app, connect to
- * the Wixel's virtual COM port using a terminal program.  Be sure to set your
- * terminal's line width to 120 characters or more to avoid line wrapping.
- *
- * The app uses the radio_queue libray to receive packets.  It does not
- * transmit any packets.
- *
- * The output from this app takes the following format:
- *
- * 147> "hello world!"       ! R: -50 L: 104 s:0 PING  p:0 0D0068656C6C6F20776F726C64212A68
- *  (1)      (2)            (3)  (4)    (5)  (6)  (7)  (8)    (9)
- *
- * (1) index (line number)
- * (2) ASCII representation of packet contents (unprintable bytes are replaced with '?')
- * (3) '!' indicates packet failed CRC check
- * (4) RSSI
- * (5) LQI
- * (6) sequence bit (only applies to RF communications using radio_link)
- * (7) packet type (only applies to RF communications using radio_link)
- * (8) payload type (only applies to RF communications using radio_link)
- * (9) hexadecimal representation of raw packet contents, including length byte
- *     and any header bytes at beginning
- *
- * The red LED indicates activity on the radio channel (packets being received).
- * Since every radio packet has a chance of being lost, there is no guarantee
- * that this app will pick up all the packets being sent, and some of
- * what it does pick up will be corrupted (indicated by a failed CRC check).
- *
- * == Parameters ==
- *   radio_channel : See description in radio_link.h.
- */
+/** radio_sniffer app:
+
+This app shows the radio packets being transmitted by other Wixels on the
+same channel.
+
+
+== Description ==
+
+A Wixel running this app appears to the USB host as a Virtual COM Port,
+with USB product ID 0x2200.  To view the output of this app, connect to
+the Wixel's virtual COM port using a terminal program.  Be sure to set your
+terminal's line width to 120 characters or more to avoid line wrapping.
+ 
+The app uses the radio_queue libray to receive packets.  It does not
+transmit any packets.
+
+The output from this app takes the following format:
+
+147> "hello world!"       ! R: -50 L: 104 s:0 PING  p:0 0D0068656C6C6F20776F726C64212A68
+ (1)      (2)            (3)  (4)    (5)  (6)  (7)  (8)    (9)
+
+(1) index (line number)
+(2) ASCII representation of packet contents (unprintable bytes are replaced with '?')
+(3) '!' indicates packet failed CRC check
+(4) RSSI
+(5) LQI
+(6) sequence bit (only applies to RF communications using radio_link)
+(7) packet type (only applies to RF communications using radio_link)
+(8) payload type (only applies to RF communications using radio_link)
+(9) hexadecimal representation of raw packet contents, including length byte
+    and any header bytes at beginning
+
+The red LED indicates activity on the radio channel (packets being received).
+Since every radio packet has a chance of being lost, there is no guarantee
+that this app will pick up all the packets being sent, and some of
+what it does pick up will be corrupted (indicated by a failed CRC check).
+
+
+== Parameters ==
+
+radio_channel: See description in radio_link.h.
+*/
 
 /** Dependencies **************************************************************/
 #include <cc2511_map.h>

apps/serial_i2c/serial_i2c.c

@@ -1,14 +1,22 @@
-/* serial_i2c app:
- *
- * Default pinout:
- * P1_0 = I2C SCL
- * P1_1 = I2C SDA
- * P0_3 = UART TX
- * P0_2 = UART RX
- *
- * This app allows you use a Wixel as an I2C bus master, controlled by a
- * wireless, UART, or USB interface.
- */
+/** serial_i2c app:
+
+This app turns a Wixel into a serial-to-I2C bridge, acting as a master
+controller on a single-master I2C bus. To perform I2C operations, another
+device can issue serial ASCII commands to the Wixel on its radio, UART, or USB
+interface.
+
+For complete documentation and a precompiled version of this app, see the
+"Serial-to-I2C App" section of the Pololu Wixel User's Guide:
+http://www.pololu.com/docs/0J46
+ 
+
+== Default pinout ==
+
+P1_0 = I2C SCL
+P1_1 = I2C SDA
+P0_3 = UART TX
+P0_2 = UART RX
+*/
 
 /** Dependencies **************************************************************/
 #include <cc2511_map.h>

apps/shiftbrite/shiftbrite.c

@@ -1,3 +1,13 @@
+/** shiftbrite app:
+
+This app allows you to wirelessly control a chain of one more ShiftBrite RGB LED
+modules.
+
+For complete documentation and a precompiled version of this app, see the
+"Shiftbrite App" section of the Pololu Wixel User's Guide:
+http://www.pololu.com/docs/0J46
+*/
+
 #include <cc2511_map.h>
 #include <board.h>
 #include <random.h>

apps/test_adc/test_adc.c

@@ -1,26 +1,37 @@
+/** test_adc app:
+
+This app uses the CC2511's analog-to-digital converter (ADC) to read the
+voltages on all 6 analog inputs and measure the voltage of the Wixel's VDD (3V3)
+line.  The results are reported to the computer either in CSV format or
+as a bar graph.
+
+
+== Parameters ==
+
+input_mode:  Specifies whether to enable internal pull-down resistors, 
+    enable internal pull-up resistors, or just let the analog lines float.
+     1 = Pull-ups
+     0 = Float (default)
+    -1 = Pull-downs
+
+bar_graph:  Specifies whether to print out a bar graph or not.
+    1 = Print a bar graph (default, requires you to use a terminal program that
+        supports VT100 commands)
+    0 = Print the 7 readings on a single line, separated by commas.
+
+report_period_ms: Specifies the number of milliseconds to wait between
+    reports to the computer.  The default is 40.
+*/
+
 #include <wixel.h>
 #include <usb.h>
 #include <usb_com.h>
 #include <stdio.h>
 
 /* PARAMETERS *****************************************************************/
 
-/*! Specifies whether to use pull-down resistors, pull-up resistors, or just
- * let the analog lines float.
- *  1 = Pull-ups
- *  0 = Float
- * -1 = Pull-downs */
 int32 CODE param_input_mode = 0;
-
-/*! Specifies whether to print out a fancy bargraph or not.
- * 1 = Print a bar graph (requires you to use a terminal program that supports VT100 commands)
- * 0 = Print the 7 readings on a single line, separated by commas.
- */
 int32 CODE param_bar_graph = 1;
-
-/*! Specifies the number of milliseconds to wait between reports
- * to the computer.
- */
 int32 CODE param_report_period_ms = 40;
 
 /* VARIABLES ******************************************************************/

apps/test_board/test_board.c

@@ -1,19 +1,21 @@
-/* test_board: This is a simple test application that test the basic
- * features of board.h and time.h.
- * 
- * It blinks the green LED, but that is only visible if the USB
- * is connected because the green LED is powered from USB.
- * 
- * It turns on the yellow LED if and only if self power is present.
- * 
- * It turns on the red LED if and only if USB power is present.
- * 
- * Note that this app does NOT implement a USB interface, so it will
- * not be recognized by the Wixel Configuration Utility and you can
- * not get it in to bootloader mode using a USB command.  However, it
- * does call boardService(), so you can get it in to bootloader mode
- * by shorting P2_2 to 3V3 (3.3 V) as long as the yellow LED is off.
- */
+/** test_board app:
+
+This is a simple test application that tests the basic
+features of board.h and time.h.
+
+It blinks the green LED, but that is only visible if the USB
+is connected because the green LED is powered from USB.
+
+It turns on the yellow LED if and only if self power is present.
+
+It turns on the red LED if and only if USB power is present.
+
+Note that this app does NOT implement a USB interface, so it will
+not be recognized by the Wixel Configuration Utility and you can
+not get it into bootloader mode using a USB command.  However, it
+does call boardService(), so you can get it into bootloader mode
+by shorting P2_2 to 3V3 (3.3 V) as long as the yellow LED is off.
+*/
 
 #include <board.h>
 #include <time.h>

apps/test_hid/test_hid.c

@@ -1,9 +1,33 @@
-/* pinout:
- *
- * P0_0 = Left Mouse Button input
- * P0_1 = Right Mouse Button input
- * P0_2 = Button to trigger keyboard input
- */
+/** test_hid_app:
+
+This is app tests the USB Human Interface Device (HID) library that allows
+the Wixel to emulate a mouse, keyboard, and joystick simultaneously.
+
+The yellow LED shows whether Caps Lock is turned on.  This might not work if
+the USB host is a Linux or Mac OS machine.
+
+The code in keyboardService() demonstrates how to send a sequence of characters
+to the computer as fast as possible.
+
+
+== Default Pinout ==
+
+P0_0 = Left Mouse Button input (active low, pulled up internally)
+P0_1 = Right Mouse Button input (active low, pulled up internally)
+P0_2 = Button to trigger keyboard input (active low, pulled up internally)
+
+
+== Parameters ==
+
+move_cursor: Setting this to 1 will make the app move the cursor in a square
+    path.
+  
+move_mouse_wheel: Setting this to 1 will make the app move the virtual mouse
+    wheel up and down.
+
+move_joystick:  Settings this to 1 will make the app move the virtual joystick
+    and press all the joystick buttons in sequence.
+*/
 
 #include <wixel.h>
 #include <usb.h>

apps/test_radio_link/test_radio_link.c

@@ -1,4 +1,8 @@
-// test_radio_link.c: A little program that lets you test the radio_link library.
+/** test_radio_link app:
+
+This app lets you test the radio_link library.  This app is mainly intended for
+people who are debugging the library.
+*/
 
 #include <wixel.h>
 #include <usb.h>

apps/test_radio_signal_rx/test_radio_signal_rx.c

@@ -1,32 +1,32 @@
-/* test_radio_signal_rx:
- *
- * You can load test_radio_signal_rx onto one Wixel and load test_radio_signal_tx on
- * to another Wixel in order to test the quality of your radio signal.
- *
- * The transmitter (the Wixel loaded with test_radio_signal_tx) will transmit a
- * burst of 100 packets every second.
- *
- * The receivers(s) (the Wixel(s) loaded with test_radio_signal_rx) will listen for
- * the bursts.  Every time a burst is received, the receiver will send a report to
- * the USB virtual COM port with three statistics in it:
- * 1) The number of packets successfully received.  This is your packet success
- *    percentage.  Bigger values are better, and a value of 100 is perfect.
- *    This is the most important statistic because it determines the amount of
- *    data that the radios can transfer per second.
- *
- * 2) Average signal strength of the packets received in dBm.  This will be a number
- *    typically between -100 and -10 that indicates how strong the signal is.  A
- *    higher number (closer to zero if negative) is better.
- *
- * 3) The average Link Quality Indicator (LQI) of the packets received.  According to
- *    the CC2511F32 datasheet, the LQI is a metric of the quality of the received signal.
- *    "LQI is best used as a relative measurement of link quality (a high value indicates
- *    a better link than what a low value does), since the value is dependent on the
- *    modulation format."
- *
- * The radio_channel parameter determines what frequency will be used, and should be the
- * same in both the transmitter and receiver.
- */
+/** test_radio_signal_rx app:
+
+You can load test_radio_signal_rx onto one Wixel and load test_radio_signal_tx
+onto another Wixel in order to test the quality of your radio signal.
+
+The transmitter (the Wixel loaded with test_radio_signal_tx) will transmit a
+burst of 100 packets every second.
+
+The receivers(s) (the Wixel(s) loaded with test_radio_signal_rx) will listen for
+the bursts.  Every time a burst is received, the receiver will send a report to
+the USB virtual COM port with three statistics in it:
+1) The number of packets successfully received.  This is your packet success
+   percentage.  Bigger values are better, and a value of 100 is perfect.
+   This is the most important statistic because it determines the amount of
+   data that the radios can transfer per second.
+
+2) Average signal strength of the packets received in dBm.  This will be a number
+   typically between -100 and -10 that indicates how strong the signal is.  A
+   higher number (closer to zero if negative) is better.
+
+3) The average Link Quality Indicator (LQI) of the packets received.  According to
+   the CC2511F32 datasheet, the LQI is a metric of the quality of the received signal.
+   "LQI is best used as a relative measurement of link quality (a high value indicates
+   a better link than what a low value does), since the value is dependent on the
+   modulation format."
+
+The radio_channel parameter determines what frequency will be used, and should be the
+same in both the transmitter and receiver.
+*/
 
 #include <wixel.h>
 #include <radio_registers.h>