From effbdea477b1260ae33654965e10aa8c208fc9e9 Mon Sep 17 00:00:00 2001
From: Asbelos <asbelos@btinternet.com>
Date: Fri, 19 Jun 2020 10:45:08 +0100
Subject: [PATCH] Improved comments and <#> diagnostic

---
 CVReader.ino | 57 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 17 deletions(-)

diff --git a/CVReader.ino b/CVReader.ino
index 1dda384..e76d7f8 100644
--- a/CVReader.ino
+++ b/CVReader.ino
@@ -3,40 +3,61 @@
 #include "DCCEXParser.h"
 #include "WifiInterface.h"
 
-/* this code is here to test the waveform generator and reveal the issues involved in programming track operations.
-
-    It tests the Waveform genartor and demonstrates how a DCC  API function can be simply written
-    to transmit and receive DCC data on the programming track.
-
-    Once started, it continues to operate as a DCC++ compaitible command parser
-    Important... Config.h contains hardware specific confioguration settings
-    that you will need to check.
+/* this code is here to demonstrate use of the DCC APi
 
 */
 
+// myFilter is an example of an OPTIONAL command filter used to intercept < > commands from
+// the usb or wifi streamm.  It demonstrates how a command may be intercepted
+//  or even a new command created without having to bfreak open the API library code.
+// The filgter is permitted to use or modify the parameter list before passing it on to 
+// the standard parser. By setting the opcode to ZERO, the standard parser will 
+// just ignore the command on the assumption that you have already handled it.
+//
+// The filter must be enabled by calling the DCC EXParser::setFilter method, see use in setup().
+ 
+void myFilter(Stream & stream, byte & opcode, byte & paramCount, int p[]) {
+    switch (opcode) {
+      case 'T':  // Intercept turnout functions because I have special hardware
+              DIAG(F("\nStop messing with Turnouts!"));
+              opcode=0; // tell parssr to ignore ithis command
+              break;   
+       case '#':   // Diagnose parser <#....>
+            DIAG(F("# paramCount=%d\n"),paramCount);
+            for (int i=0;i<paramCount;i++) DIAG(F("p[%d]=%d (0x%x)\n"),i,p[i],p[i]);
+            opcode=0; // Normal parser wont understand #, 
+            break;
+       default:  // drop through and parser will use the command unaltered.   
+            break;  
+    }
+}
+
+// Callback functions are necessary if you call any API that must wait for a response from the 
+// programming track. The API must return immediately otherwise other loop() functions would be blocked.
+// Your callback function will be invoked when the data arrives from the prog track.
+
 void myCallback(int result) {
   DIAG(F("\n getting Loco Id callback result=%d"),result); 
 }
 
 
-void myFilter(Stream & stream, byte & opcode, byte & paramCount, int p[]) {
-    if (opcode=='T') {
-      DIAG(F("\nStop messing with Turnouts!"));
-      opcode=0; // tell parssr to ignore it   
-    }
-}
-
+// Create a serkial command parser... This is OPTIONAL if you don't need to handle JMRI type commands
+// from the Serial port.
 DCCEXParser  serialParser;
 
 void setup() {
-  Serial.begin(SERIAL_BAUD_RATE);
+   Serial.begin(SERIAL_BAUD_RATE);
    DCC::begin();
    if (WIFI_PORT>0) WifiInterface::setup();
    DIAG(F("\n===== CVReader demonstrating DCC::getLocoId() call ==========\n"));
    DCC::getLocoId(myCallback); // myCallback will be called with the result 
    DIAG(F("\n===== DCC::getLocoId has returned, but wont be executed until we are in loop() ======\n"));
-   DIAG(F("\nReady for JMRI commands\n"));
+   
+   // Optionally tell parser to use my example filter 
    DCCEXParser::setFilter(myFilter);
+
+   DIAG(F("\nReady for JMRI commands\n"));
+
 }
 
 void loop() {      
@@ -44,5 +65,7 @@ void loop() {
 
   // This line passes input on Serial to the DCCEXParser
   serialParser.loop(Serial);
+
+  // This line passes input on Wifi to another DCCEXParser
   if (WIFI_PORT>0) WifiInterface::loop();
 }