adds documentation for console in

docs/feature_console_in.md

@@ -0,0 +1,26 @@
+# Console In
+
+The "Console" in QMK refers to PJRC's vendor page of `0xFF31` and usage page of `0x74` - this is mainly used for sending debug statements to the computer that can be read via the QMK Toolbox (recommended), or HID listen.
+
+When `#define CONSOLE_IN_ENABLE` is placed in the `config.h` file, the keyboard will also listen to messages sent to the keyboard, will be able to respond in a custom way, defined at the `quantum`, `kb`, or `user` level. A keymap's example might look like this:
+
+```c
+void process_console_data_user(uint8_t * data, uint8_t length) {
+  switch (data[0]) {
+    case 0x05:
+      print("Sending back a message to the computer\n");
+      break;
+  }
+}
+```
+
+Which will execute when a report is sent to the keyboard when the first byte is `0x05`.
+
+## Default actions (defined at the `quantum` level)
+
+When the first byte is:
+
+* `0x01`: Print "Saying hello\n" via the console, and play the audio on song
+* `0xFE`: Enter the bootloader - only works when `CONSOLE_IN_BOOTLOADER` is defined in the `config.h`
+
+This needs to be fleshed out a bit more with some sort of versioning.

keyboards/planck/config.h

@@ -44,6 +44,8 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #define AUDIO_VOICES
 #define C6_AUDIO
 
+#define CONSOLE_IN_ENABLE
+
 #define BACKLIGHT_PIN B7
 
 /* COL2ROW or ROW2COL */

keyboards/planck/rules.mk

@@ -65,7 +65,7 @@ CONSOLE_ENABLE = yes         # Console for debug(+400)
 COMMAND_ENABLE = no        # Commands for debug and configuration
 NKRO_ENABLE = yes            # Nkey Rollover - if this doesn't work, see here: https://github.com/tmk/tmk_keyboard/wiki/FAQ#nkro-doesnt-work
 BACKLIGHT_ENABLE = no      # Enable keyboard backlight functionality
-MIDI_ENABLE = yes            # MIDI controls
+MIDI_ENABLE = no            # MIDI controls
 AUDIO_ENABLE = yes           # Audio output on port C6
 UNICODE_ENABLE = no         # Unicode
 BLUETOOTH_ENABLE = no       # Enable Bluetooth with the Adafruit EZ-Key HID

quantum/quantum.c

@@ -1296,3 +1296,42 @@ __attribute__ ((weak))
 void shutdown_user() {}
 
 //------------------------------------------------------------------------------
+
+#ifdef CONSOLE_IN_ENABLE
+
+__attribute__ ((weak))
+void process_console_data_user(uint8_t * data, uint8_t length) {
+}
+
+__attribute__ ((weak))
+void process_console_data_kb(uint8_t * data, uint8_t length) {
+  process_console_data_user(data, length);
+}
+
+void process_console_data_quantum(uint8_t * data, uint8_t length) {
+  // This can be used for testing - it echos back the information received
+  // print("Received message:\n  ");
+  // while (*data) {
+  //   sendchar(*data);
+  //   data++;
+  // }
+  switch (data[0]) {
+    case 0x01:
+      print("Saying hello\n");
+      #ifdef AUDIO_ENABLE
+        audio_on();
+      #endif
+      break;
+    case 0xFE:
+    #ifdef CONSOLE_IN_BOOTLOADER
+      print("Entering bootloader\n");
+      reset_keyboard();
+    #else
+      print("Unable to enter bootloader\n");
+    #endif
+      break;
+  }
+  process_console_data_kb(data, length);
+}
+
+#endif

quantum/quantum.h

@@ -193,4 +193,10 @@ void led_set_kb(uint8_t usb_led);
 
 void api_send_unicode(uint32_t unicode);
 
+#ifdef CONSOLE_IN_ENABLE
+void process_console_data_user(uint8_t * data, uint8_t length);
+void process_console_data_kb(uint8_t * data, uint8_t length);
+void process_console_data_quantum(uint8_t * data, uint8_t length);
+#endif
+
 #endif

tmk_core/protocol/lufa/descriptor.h

@@ -208,8 +208,11 @@ typedef struct
 
 #ifdef CONSOLE_ENABLE
 #   define CONSOLE_IN_EPNUM         (RAW_OUT_EPNUM + 1)
-//#   define CONSOLE_OUT_EPNUM        (RAW_OUT_EPNUM + 2)
-#   define CONSOLE_OUT_EPNUM        (RAW_OUT_EPNUM + 1)
+#   ifdef CONSOLE_IN_ENABLE
+#       define CONSOLE_OUT_EPNUM        (RAW_OUT_EPNUM + 2)
+#   else
+#       define CONSOLE_OUT_EPNUM        (RAW_OUT_EPNUM + 1)
+#   endif
 #else
 #   define CONSOLE_OUT_EPNUM        RAW_OUT_EPNUM
 #endif

tmk_core/protocol/lufa/lufa.c

@@ -264,6 +264,14 @@ static void raw_hid_task(void)
  * Console
  ******************************************************************************/
 #ifdef CONSOLE_ENABLE
+
+static bool console_flush = false;
+#define CONSOLE_FLUSH_SET(b)   do { \
+  ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {\
+    console_flush = b; \
+  } \
+} while (0)
+
 static void Console_Task(void)
 {
     /* Device must be connected and configured for the task to run */
@@ -272,49 +280,62 @@ static void Console_Task(void)
 
     uint8_t ep = Endpoint_GetCurrentEndpoint();
 
-#if 0
-    // TODO: impl receivechar()/recvchar()
-    Endpoint_SelectEndpoint(CONSOLE_OUT_EPNUM);
+    #ifdef CONSOLE_IN_ENABLE
+      /* Create a temporary buffer to hold the read in report from the host */
+      uint8_t ConsoleData[CONSOLE_EPSIZE];
+      bool data_read = false;
 
-    /* Check to see if a packet has been sent from the host */
-    if (Endpoint_IsOUTReceived())
-    {
-        /* Check to see if the packet contains data */
-        if (Endpoint_IsReadWriteAllowed())
-        {
-            /* Create a temporary buffer to hold the read in report from the host */
-            uint8_t ConsoleData[CONSOLE_EPSIZE];
+      // TODO: impl receivechar()/recvchar()
+      Endpoint_SelectEndpoint(CONSOLE_OUT_EPNUM);
 
-            /* Read Console Report Data */
-            Endpoint_Read_Stream_LE(&ConsoleData, sizeof(ConsoleData), NULL);
+      /* Check to see if a packet has been sent from the host */
+      if (Endpoint_IsOUTReceived())
+      {
+          /* Check to see if the packet contains data */
+          if (Endpoint_IsReadWriteAllowed())
+          {
 
+              /* Read Console Report Data */
+              Endpoint_Read_Stream_LE(&ConsoleData, sizeof(ConsoleData), NULL);
+              data_read = true;
+          }
+
+          /* Finalize the stream transfer to send the last packet */
+          Endpoint_ClearOUT();
+
+          if (data_read) {
             /* Process Console Report Data */
-            //ProcessConsoleHIDReport(ConsoleData);
-        }
+            process_console_data_quantum(ConsoleData, sizeof(ConsoleData));
+          }
 
-        /* Finalize the stream transfer to send the last packet */
-        Endpoint_ClearOUT();
-    }
-#endif
+      }
 
-    /* IN packet */
-    Endpoint_SelectEndpoint(CONSOLE_IN_EPNUM);
-    if (!Endpoint_IsEnabled() || !Endpoint_IsConfigured()) {
-        Endpoint_SelectEndpoint(ep);
-        return;
-    }
+    #endif
+
+    if (console_flush) {
+      /* IN packet */
+      Endpoint_SelectEndpoint(CONSOLE_IN_EPNUM);
+      if (!Endpoint_IsEnabled() || !Endpoint_IsConfigured()) {
+          Endpoint_SelectEndpoint(ep);
+          return;
+      }
 
-    // fill empty bank
-    while (Endpoint_IsReadWriteAllowed())
-        Endpoint_Write_8(0);
+      // fill empty bank
+      while (Endpoint_IsReadWriteAllowed())
+          Endpoint_Write_8(0);
 
-    // flash senchar packet
-    if (Endpoint_IsINReady()) {
-        Endpoint_ClearIN();
+      // flash senchar packet
+      if (Endpoint_IsINReady()) {
+          Endpoint_ClearIN();
+      }
+      // CONSOLE_FLUSH_SET(false);
+      console_flush = false;
     }
 
     Endpoint_SelectEndpoint(ep);
+
 }
+
 #endif
 
 
@@ -380,13 +401,8 @@ void EVENT_USB_Device_WakeUp()
 
 
 
-#ifdef CONSOLE_ENABLE
-static bool console_flush = false;
-#define CONSOLE_FLUSH_SET(b)   do { \
-  ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {\
-    console_flush = b; \
-  } \
-} while (0)
+// #ifdef CONSOLE_ENABLE
+#if 0
 
 // called every 1ms
 void EVENT_USB_Device_StartOfFrame(void)
@@ -395,9 +411,9 @@ void EVENT_USB_Device_StartOfFrame(void)
     if (++count % 50) return;
     count = 0;
 
-    if (!console_flush) return;
+    //if (!console_flush) return;
     Console_Task();
-    console_flush = false;
+    //console_flush = false;
 }
 
 #endif
@@ -440,10 +456,10 @@ void EVENT_USB_Device_ConfigurationChanged(void)
     /* Setup Console HID Report Endpoints */
     ConfigSuccess &= ENDPOINT_CONFIG(CONSOLE_IN_EPNUM, EP_TYPE_INTERRUPT, ENDPOINT_DIR_IN,
                                      CONSOLE_EPSIZE, ENDPOINT_BANK_SINGLE);
-#if 0
+  #ifdef CONSOLE_IN_ENABLE
     ConfigSuccess &= ENDPOINT_CONFIG(CONSOLE_OUT_EPNUM, EP_TYPE_INTERRUPT, ENDPOINT_DIR_OUT,
                                      CONSOLE_EPSIZE, ENDPOINT_BANK_SINGLE);
-#endif
+  #endif
 #endif
 
 #ifdef NKRO_ENABLE
@@ -1101,7 +1117,7 @@ static void setup_usb(void)
     USB_Init();
 
     // for Console_Task
-    USB_Device_EnableSOFEvents();
+    //USB_Device_EnableSOFEvents();
     print_set_sendchar(sendchar);
 }
 
@@ -1216,6 +1232,10 @@ int main(void)
         raw_hid_task();
 #endif
 
+#ifdef CONSOLE_ENABLE
+        Console_Task();
+#endif
+
 #if !defined(INTERRUPT_CONTROL_ENDPOINT)
         USB_USBTask();
 #endif