CDC Console

[tmk]

WIP:

I'm working on CDC console with this branch.
https://github.com/tmk/tmk_keyboard/tree/cdc_console

Its discussion was also found in this issue #660.

Build options

• CONSOLE_ENABLE = [yes|no] (for backward compatibility)
• CONSOLE_DRIVER = [HID|CDC|UART|SUART] (if not set HID is used by default)

CDC Console

CONSOLE_ENABLE = yes
CONSOLE_DRIVER = CDC

HID Console

It is existent default console which requires PJRC's hid_listen tool to see debug outputs.

CONSOLE_ENABLE = yes
CONSOLE_DRIVER = HID

<stdio.h> API

Console driver offers stdin, stdout and <stdio.h> functions are available now, hopefully. Not tested closely yet, you can use getchar() or similar to get input from terminal app. And to send message to terminal xprintf() or <stdio.h> printf() can be used. (Using xprintf() is prefered at this point.)

AVR libc <stdio.h>

https://www.nongnu.org/avr-libc/user-manual/group__avr__stdio.html

xprintf

http://elm-chan.org/fsw/strf/xprintf.html

https://github.com/tmk/tmk_keyboard/blob/1a02ebcc612e9a9c0d87e02295c7258de3a70ccc/tmk_core/common/avr/xprintf.h

TODO

• Cosole driver interface
• <stdio.h> support(printf, getchar)
• Windows 10 support(Interface Association Descriptor)
• Test on older Windows(INF file)
• Test on Mac
• Test UART and SUART
• Refactor print.h, sendchar.h
• Blocking problem
• Port close problem
• Update xprintf

Command Interface

Console can be used to communicate with user.
#660 (comment)

Command

Blocking Problem

As for the blocking problem I found this note on LUFA CDC documenation.

Another major oversight is that there is no mechanism for the host to notify the device that there is a data sink on the host side ready to accept data. This means that the device may try to send data while the host isn't listening, causing lengthy blocking timeouts in the transmission routines. It is thus highly recommended that the virtual serial line DTR (Data Terminal Ready) signal be used where possible to determine if a host application is ready for data.

I confirmed that checking DTR on ControlLineStates before using SendByte() and Flush() is needed and musthave. These checks makes the blocking very rare but there is still very slight chance of block. Setting USB_STREAM_TIMEOUT_MS to 0 would minimizes the blocking time in Endpoint_WaitUntilReady() in the case.

This is related issue and pull request of LUFA which not merged yet.
abcminiuser/lufa#106
abcminiuser/lufa#120

DTR usage

Most of terminal softwares seems to control DTR properly to indicate it is ready. But there will be exceptions like 'hterm' which doesn't assert DTR by default when connected. You can still make 'hterm' use DTR by configuration. This won't be problem.

Also other softwares may use DTR for other purpose. For example ESP-IDF uses DTR to reset microcontroller. But this is beyond scope of CDC console.

hathach/tinyusb#506
hathach/tinyusb#482
hathach/tinyusb#401
hathach/tinyusb#492

CDC Device Recognition

Note on LUFA CDC documenation:

One major issue with CDC-ACM is that it requires two Interface descriptors, which will upset most hosts when part of a multi-function "Composite" USB device. This is because each interface will be loaded into a separate driver instance, causing the two interfaces be become unlinked. To prevent this, you should use the "Interface Association Descriptor" addendum to the USB 2.0 standard which is available on most OSes when creating Composite devices.

This is not problem on Linux 5.4.0 but Windows 10 fails to recognize CDC device.(without Interface Association Descriptor)

[tmk]

USB Interface Association Descriptor

https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/usb-interface-association-descriptor

Port close problem

Serial terminal cannot close port properly when CDC device retrieve data from endpoint bank. After that terminal app fail to send data and some like jerm even don't receive any data from CDC device after that.

This code throws away received data.

if (Endpoint_IsOUTReceive())
    Endpoint_ClearOUT();

INF file

Windows 10 doesn't need INF file while other versions need to setup CDC ACM device.

Infterface number of CDC device should be fixed to indicate device id in INF file?

%DESCRIPTION%=DriverInstall, USB\VID_FEED&PID_CAFE&MI_01

https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-inf-files

https://www.lufa-lib.org/files/LUFA/Doc/170418/html/_page__o_s_drivers.html

https://www.kernel.org/doc/Documentation/usb/linux-cdc-acm.inf