Fix example project doxygen hierarchy; Copy and modify a demo from Pa…

…rallax to demonstrate the helpfulness of PropWare

Examples/Examples.dox

@@ -0,0 +1,4 @@
+/**
+@defgroup _propware_examples Examples
+@brief    Example projects to demonstrate the capabilities and the simplicity of developing projects using PropWare
+*/

Examples/HD44780/HD44780_Demo.h

@@ -2,6 +2,8 @@
  * @file    HD44780_Demo.h
  */
 /**
+ * @brief   Display "Hello world" on LCD screen and demonstrate line-wrapping
+ *
  * @project HD44780_Demo
  *
  * @author  David Zemon
@@ -29,12 +31,9 @@
 #ifndef HD44780_DEMO_H_
 #define HD44780_DEMO_H_
 
-/** @addtogroup _propware_examples
- * @{
- */
-
 /**
- * @defgroup    _propware_examples_hd44780  HD44780     Character LCD Demo
+ * @defgroup _propware_examples_hd44780 Character LCD Demo
+ * @ingroup _propware_examples
  * @{
  */
 
@@ -69,6 +68,6 @@ void error (const uint8_t err);
 
 /**@}*/
 
-/**@}*/
+/*@}*/
 
 #endif /* HD44780_DEMO_H_ */

Examples/L3G/L3G_Demo.h

@@ -1,25 +1,61 @@
 /**
  * @file    L3G_Demo.h
- * 
- * @author  David Zemon
+ */
+/**
+ * @brief   Demonstration using various functions of the L3G gyroscope
+ *
  * @project L3G_Demo
+ *
+ * @author  David Zemon
+ *
+ * @copyright
+ * The MIT License (MIT)<br>
+ * <br>Copyright (c) 2013 David Zemon<br>
+ * <br>Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:<br>
+ * <br>The above copyright notice and this permission notice shall be included
+ * in all copies or substantial portions of the Software.<br>
+ * <br>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
 #ifndef L3G_DEMO_H_
 #define L3G_DEMO_H_
 
+/**
+ * @defgroup    _propware_example_l3g   L3G Gyroscope Demo
+ * @ingroup     _propware_examples
+ * @{
+ */
+
 #include <propeller.h>
 #include <PropWare.h>
 #include <l3g.h>
 
-#define MOSI        BIT_0
-#define MISO        BIT_1
-#define SCLK        BIT_2
-#define CS          BIT_4
-#define FREQ        10000
+/** Pin number for MOSI (master out - slave in) */
+#define MOSI                BIT_0
+/** Pin number for the clock signal */
+#define SCLK                BIT_1
+/** Pin number for MISO (master in - slave out) */
+#define MISO                BIT_2
+/** Pin number for chip select */
+#define CS                  BIT_4
+/** Frequency (in Hertz) to run the SPI protocol */
+#define FREQ                10000
 
 #define DEBUG_LEDS  BYTE_2
 
 void error (const int8_t err);
 
+/**@}*/
+
 #endif /* L3G_DEMO_H_ */

Examples/MAX6675/MAX6675_Demo.h

@@ -2,6 +2,8 @@
  * @file    MAX6675_Demo.h
  */
 /**
+ * @brief   Display the temperature on stdout and a character LCD
+ *
  * @project MAX6675_Demo
  *
  * @author  David Zemon
@@ -29,12 +31,9 @@
 #ifndef MAX6675_DEMO_H_
 #define MAX6675_DEMO_H_
 
-/** @addtogroup _propware_examples
- * @{
- */
-
 /**
- * @defgroup    _propware_examples_max6675  MAX6675 Demo
+ * @defgroup    _propware_example_max6675  MAX6675 Demo
+ * @ingroup     _propware_examples
  * @{
  */
 
@@ -77,6 +76,4 @@ void error (int8_t err);
 
 /**@}*/
 
-/**@}*/
-
 #endif /* MAX6675_DEMO_H_ */

Examples/MCP300x/MCP300x_Demo.h

@@ -2,6 +2,9 @@
  * @file    MCP300x_Demo.h
  */
 /**
+ * @brief   Display the value of an analog channel on stdout and as a bar graph
+ *          over the 8 LEDs of the QUICKSTART board
+ *
  * @project MCP300x_Demo
  *
  * @author  David Zemon
@@ -29,12 +32,9 @@
 #ifndef MCP300X_DEMO_H_
 #define MCP300X_DEMO_H_
 
-/** @addtogroup _propware_examples
- * @{
- */
-
 /**
- * @defgroup    _propware_examples_mcp300x  MCP300x Demo
+ * @defgroup    _propware_example_mcp300x   MCP300x Demo
+ * @ingroup     _propware_examples
  * @{
  */
 
@@ -70,6 +70,4 @@ void error (int8_t err);
 
 /**@}*/
 
-/**@}*/
-
 #endif /* MCP300X_DEMO_H_ */

Examples/Makefile

@@ -29,6 +29,9 @@ all:
 
 	$(shell mkdir $(MKDIR_FLAG) SPI$(DIR_DIV)Debug $(NULL))
 	$(MAKE) -C SPI/Debug -f ../Makefile
+
+	$(shell mkdir $(MKDIR_FLAG) PropWare$(DIR_DIV)Debug $(NULL))
+	$(MAKE) -C PropWare/Debug -f ../Makefile
 
 clean:
 	$(shell mkdir $(MKDIR_FLAG) HD44780$(DIR_DIV)Debug $(NULL))
@@ -48,3 +51,6 @@ clean:
 
 	$(shell mkdir $(MKDIR_FLAG) SPI$(DIR_DIV)Debug $(NULL))
 	$(MAKE) -C SPI/Debug -f ../Makefile clean
+
+	$(shell mkdir $(MKDIR_FLAG) PropWare$(DIR_DIV)Debug $(NULL))
+	$(MAKE) -C PropWare/Debug -f ../Makefile clean

Examples/PropWare/Makefile

@@ -0,0 +1,27 @@
+# @file     Makefile
+#
+# @author   David Zemon
+# @project  PropWare_Demo
+
+PRJ = PropWare_Demo
+
+NAME = $(PRJ)
+OBJS = $(PRJ).o
+BOARD = QUICKSTART
+MODEL = lmm
+CFLAGS = -Os
+
+# Insert your own path here - it should be the same directory that contains "common.mk"
+ifndef PROPWARE_PATH
+	PROPWARE_PATH = ../../..
+endif
+
+# Optionally, specify where your compiler is installed
+ifndef PROPGCC_PREFIX
+	# Default = /opt/parallax
+	PROPGCC_PREFIX = /path/to/compiler/directory
+endif
+
+all: $(NAME).elf
+
+include $(PROPWARE_PATH)/common.mk

Examples/PropWare/PropWare_Demo.c

@@ -26,13 +26,60 @@
  * SOFTWARE.
  */
 
-
 #include "PropWare_Demo.h"
 
-/**
- * @brief   Demonstrate various aspects of the top-level PropWare functions and
- *          preprocessor macros
- */
-void main (void) {
-	// TODO: Coming soon!!!
+static int cog_stack[STACK_SIZE][8];
+static _thread_state_t thread_data;
+
+volatile unsigned int wait_time;
+volatile unsigned int startcnt;
+volatile unsigned int pins;
+volatile int syncstart;
+
+int main (int argc, char* argv[]) {
+    int n;
+    int cog;
+    int pin[] = {
+            BIT_16,
+            BIT_17,
+            BIT_18,
+            BIT_19,
+            BIT_20,
+            BIT_21,
+            BIT_22,
+            BIT_23 };
+    unsigned int nextcnt;
+
+    wait_time = 50 * MILLISECOND;
+
+    syncstart = 0;
+
+    for (n = 1; n < COGS; n++) {
+        cog = _start_cog_thread(cog_stack[n] + STACK_SIZE, do_toggle,
+                (void*) pin[n], &thread_data);
+        printf("Toggle COG %d Started\n", cog);
+    }
+
+    startcnt = CNT;
+    syncstart = 1;
+    nextcnt = wait_time + startcnt;
+    while (1) {
+        GPIOPinToggle(pin[0]);
+        nextcnt = waitcnt2(nextcnt, wait_time);
+    }
+    return 0;
+}
+
+void do_toggle (void *arg) {
+    int pin = (int) arg;
+    unsigned int nextcnt;
+
+    while (syncstart == 0)
+        ;  // wait for start signal from main cog
+
+    nextcnt = wait_time + startcnt;
+    while (1) {
+        GPIOPinToggle(pin);
+        nextcnt = waitcnt2(nextcnt, wait_time);
+    }
 }

Examples/PropWare/PropWare_Demo.h

@@ -1,15 +1,22 @@
 /**
- * @file    PropWare_Demo.h
+ * @file        PropWare_Demo.h
  */
 /**
- * @brief   Examples demonstrating PropWare capabilities
+ * @brief       Blink an LED on each of the 8 Propeller cogs
  *
- * @note    Coming soon! I will demonstrate the capabilities of some of the
- *          basics in PropWare along with some multi-core programming!
+ * @detailed    This file is nearly a direct copy of SimpleIDE's blinkcogs.c.
+ *              Some changes were made to highlight the helpfulness of PropWare.
  *
- * @project PropWare_Demo
+ *              Make all propeller cogs blink assigned pins at exactly the same
+ *              rate and time to demonstrate the precision of the
+ *              _start_cog_thread method. This program and method uses 8 LMM C
+ *              program COG "threads" of execution simultaneously.
  *
- * @author  David Zemon
+ *              This program should be compiled with the LMM memory model.
+ *
+ * @project     PropWare_Demo
+ *
+ * @author      Modified by David Zemon
  *
  * @copyright
  * The MIT License (MIT)<br>
@@ -35,18 +42,23 @@
 #define PROPWARE_DEMO_H_
 
 /**
- * @defgroup _propware_examples  Examples
+ * @defgroup    _propware_example_propware  PropWare Basics
+ * @ingroup     _propware_examples
  * @{
  */
 
-/**
- * @defgroup _propware_example_propware PropWare Functions & Macros
- */
-
 #include <stdio.h>
 #include <PropWare.h>
 
-/*@}*/
+#define COGS            8
+#define STACK_SIZE      16
+
+/**
+ * @brief       Toggle thread function gets started in an LMM COG.
+ *
+ * @param[in]   *arg    pin number to toggle
+ */
+void do_toggle (void *arg);
 
 /*@}*/
 

Examples/SD/SD_Demo.h

@@ -2,6 +2,9 @@
  * @file    SD_Demo.h
  */
 /**
+ * @brief   Demonstrate various functions including writing to files and the
+ *          Shell
+ *
  * @project SD_Demo
  *
  * @author  David Zemon
@@ -30,12 +33,8 @@
 #define SD_DEMO_H_
 
 /**
- * @addtogroup _propware_examples
- * @{
- */
-
-/**
- * @defgroup _propware_examples_sd  SD Card Demo
+ * @defgroup    _propware_example_sd    SD Card Demo
+ * @ingroup     _propware_examples
  * @{
  */
 
@@ -73,6 +72,4 @@ void error (const uint8_t err);
 
 /**@}*/
 
-/**@}*/
-
 #endif /* SD_DEMO_H_ */