1 /* 2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 #ifndef _PICO_STDIO_USB_H 8 #define _PICO_STDIO_USB_H 9 10 #include "pico/stdio.h" 11 12 /** \brief Support for stdin/stdout over USB serial (CDC) 13 * \defgroup pico_stdio_usb pico_stdio_usb 14 * \ingroup pico_stdio 15 * 16 * Linking this library or calling `pico_enable_stdio_usb(TARGET ENABLED)` in the CMake (which 17 * achieves the same thing) will add USB CDC to the drivers used for standard input/output 18 * 19 * Note this library is a developer convenience. It is not applicable in all cases; for one it takes full control of the USB device precluding your 20 * use of the USB in device or host mode. For this reason, this library will automatically disengage if you try to using it alongside \ref tinyusb_device or 21 * \ref tinyusb_host. It also takes control of a lower level IRQ and sets up a periodic background task. 22 * 23 * This library also includes (by default) functionality to enable the RP-series microcontroller to be reset over the USB interface. 24 */ 25 26 // PICO_CONFIG: PICO_STDIO_USB_DEFAULT_CRLF, Default state of CR/LF translation for USB output, type=bool, default=PICO_STDIO_DEFAULT_CRLF, group=pico_stdio_usb 27 #ifndef PICO_STDIO_USB_DEFAULT_CRLF 28 #define PICO_STDIO_USB_DEFAULT_CRLF PICO_STDIO_DEFAULT_CRLF 29 #endif 30 31 // PICO_CONFIG: PICO_STDIO_USB_STDOUT_TIMEOUT_US, Number of microseconds to be blocked trying to write USB output before assuming the host has disappeared and discarding data, default=500000, group=pico_stdio_usb 32 #ifndef PICO_STDIO_USB_STDOUT_TIMEOUT_US 33 #define PICO_STDIO_USB_STDOUT_TIMEOUT_US 500000 34 #endif 35 36 // todo perhaps unnecessarily frequent? 37 // PICO_CONFIG: PICO_STDIO_USB_TASK_INTERVAL_US, Period of microseconds between calling tud_task in the background, default=1000, advanced=true, group=pico_stdio_usb 38 #ifndef PICO_STDIO_USB_TASK_INTERVAL_US 39 #define PICO_STDIO_USB_TASK_INTERVAL_US 1000 40 #endif 41 42 // PICO_CONFIG: PICO_STDIO_USB_LOW_PRIORITY_IRQ, Explicit User IRQ number to claim for tud_task() background execution instead of letting the implementation pick a free one dynamically (deprecated), advanced=true, group=pico_stdio_usb 43 #ifndef PICO_STDIO_USB_LOW_PRIORITY_IRQ 44 // this variable is no longer set by default (one is claimed dynamically), but will be respected if specified 45 #endif 46 47 // PICO_CONFIG: PICO_STDIO_USB_ENABLE_RESET_VIA_BAUD_RATE, Enable/disable resetting into BOOTSEL mode if the host sets the baud rate to a magic value (PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE), type=bool, default=1 if application is not using TinyUSB directly, group=pico_stdio_usb 48 #ifndef PICO_STDIO_USB_ENABLE_RESET_VIA_BAUD_RATE 49 #if !defined(LIB_TINYUSB_HOST) && !defined(LIB_TINYUSB_DEVICE) 50 #define PICO_STDIO_USB_ENABLE_RESET_VIA_BAUD_RATE 1 51 #endif 52 #endif 53 54 // PICO_CONFIG: PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE, Baud rate that if selected causes a reset into BOOTSEL mode (if PICO_STDIO_USB_ENABLE_RESET_VIA_BAUD_RATE is set), default=1200, group=pico_stdio_usb 55 #ifndef PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE 56 #define PICO_STDIO_USB_RESET_MAGIC_BAUD_RATE 1200 57 #endif 58 59 // PICO_CONFIG: PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS, Maximum number of milliseconds to wait during initialization for a CDC connection from the host (negative means indefinite) during initialization, default=0, group=pico_stdio_usb 60 #ifndef PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS 61 #define PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS 0 62 #endif 63 64 // PICO_CONFIG: PICO_STDIO_USB_POST_CONNECT_WAIT_DELAY_MS, Number of extra milliseconds to wait when using PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS after a host CDC connection is detected (some host terminals seem to sometimes lose transmissions sent right after connection), default=50, group=pico_stdio_usb 65 #ifndef PICO_STDIO_USB_POST_CONNECT_WAIT_DELAY_MS 66 #define PICO_STDIO_USB_POST_CONNECT_WAIT_DELAY_MS 50 67 #endif 68 69 // PICO_CONFIG: PICO_STDIO_USB_DEINIT_DELAY_MS, Number of milliseconds to wait before deinitializing stdio_usb, default=110, group=pico_stdio_usb 70 #ifndef PICO_STDIO_USB_DEINIT_DELAY_MS 71 #define PICO_STDIO_USB_DEINIT_DELAY_MS 110 72 #endif 73 74 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED, Optionally define a pin to use as bootloader activity LED when BOOTSEL mode is entered via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE), type=int, min=0, max=47 on RP2350B, 29 otherwise, group=pico_stdio_usb 75 76 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW, Whether pin to use as bootloader activity LED when BOOTSEL mode is entered via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE) is active low, type=bool, default=0, group=pico_stdio_usb 77 #ifndef PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED_ACTIVE_LOW 78 #define PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED_ACTIVE_LOW 0 79 #endif 80 81 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED, Whether the pin specified by PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED is fixed or can be modified by picotool over the VENDOR USB interface, type=bool, default=0, group=pico_stdio_usb 82 #ifndef PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED 83 #define PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED 0 84 #endif 85 86 // Any modes disabled here can't be re-enabled by picotool via VENDOR_INTERFACE. 87 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK, Optionally disable either the mass storage interface (bit 0) or the PICOBOOT interface (bit 1) when entering BOOTSEL mode via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE), type=int, min=0, max=3, default=0, group=pico_stdio_usb 88 #ifndef PICO_STDIO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK 89 #define PICO_STDIO_USB_RESET_BOOTSEL_INTERFACE_DISABLE_MASK 0u 90 #endif 91 92 // PICO_CONFIG: PICO_STDIO_USB_ENABLE_RESET_VIA_VENDOR_INTERFACE, Enable/disable resetting into BOOTSEL mode via an additional VENDOR USB interface - enables picotool based reset, type=bool, default=1 if application is not using TinyUSB directly, group=pico_stdio_usb 93 #ifndef PICO_STDIO_USB_ENABLE_RESET_VIA_VENDOR_INTERFACE 94 #if !defined(LIB_TINYUSB_HOST) && !defined(LIB_TINYUSB_DEVICE) 95 #define PICO_STDIO_USB_ENABLE_RESET_VIA_VENDOR_INTERFACE 1 96 #endif 97 #endif 98 99 // PICO_CONFIG: PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL, If vendor reset interface is included allow rebooting to BOOTSEL mode, type=bool, default=1, group=pico_stdio_usb 100 #ifndef PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL 101 #define PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_BOOTSEL 1 102 #endif 103 104 // PICO_CONFIG: PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT, If vendor reset interface is included allow rebooting with regular flash boot, type=bool, default=1, group=pico_stdio_usb 105 #ifndef PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT 106 #define PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_RESET_TO_FLASH_BOOT 1 107 #endif 108 109 // PICO_CONFIG: PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR, If vendor reset interface is included add support for Microsoft OS 2.0 Descriptor, type=bool, default=1, group=pico_stdio_usb 110 #ifndef PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR 111 #define PICO_STDIO_USB_RESET_INTERFACE_SUPPORT_MS_OS_20_DESCRIPTOR 1 112 #endif 113 114 // PICO_CONFIG: PICO_STDIO_USB_RESET_RESET_TO_FLASH_DELAY_MS, Delay in ms before rebooting via regular flash boot, default=100, group=pico_stdio_usb 115 #ifndef PICO_STDIO_USB_RESET_RESET_TO_FLASH_DELAY_MS 116 #define PICO_STDIO_USB_RESET_RESET_TO_FLASH_DELAY_MS 100 117 #endif 118 119 // PICO_CONFIG: PICO_STDIO_USB_CONNECTION_WITHOUT_DTR, Disable use of DTR for connection checking meaning connection is assumed to be valid, type=bool, default=0, group=pico_stdio_usb 120 #ifndef PICO_STDIO_USB_CONNECTION_WITHOUT_DTR 121 #define PICO_STDIO_USB_CONNECTION_WITHOUT_DTR 0 122 #endif 123 124 // PICO_CONFIG: PICO_STDIO_USB_DEVICE_SELF_POWERED, Set USB device as self powered device, type=bool, default=0, group=pico_stdio_usb 125 #ifndef PICO_STDIO_USB_DEVICE_SELF_POWERED 126 #define PICO_STDIO_USB_DEVICE_SELF_POWERED 0 127 #endif 128 129 // PICO_CONFIG: PICO_STDIO_USB_SUPPORT_CHARS_AVAILABLE_CALLBACK, Enable USB STDIO support for stdio_set_chars_available_callback. Can be disabled to make use of USB CDC RX callback elsewhere, type=bool, default=1, group=pico_stdio_usb 130 #ifndef PICO_STDIO_USB_SUPPORT_CHARS_AVAILABLE_CALLBACK 131 #define PICO_STDIO_USB_SUPPORT_CHARS_AVAILABLE_CALLBACK 1 132 #endif 133 134 #ifdef __cplusplus 135 extern "C" { 136 #endif 137 138 extern stdio_driver_t stdio_usb; 139 140 /*! \brief Explicitly initialize USB stdio and add it to the current set of stdin drivers 141 * \ingroup pico_stdio_usb 142 * 143 * \ref PICO_STDIO_USB_CONNECT_WAIT_TIMEOUT_MS can be set to cause this method to wait for a CDC connection 144 * from the host before returning, which is useful if you don't want any initial stdout output to be discarded 145 * before the connection is established. 146 * 147 * \return true if the USB CDC was initialized, false if an error occurred 148 */ 149 bool stdio_usb_init(void); 150 151 /*! \brief Explicitly deinitialize USB stdio and remove it from the current set of stdin drivers 152 * \ingroup pico_stdio_usb 153 * 154 * \return true if the USB CDC was deinitialized, false if an error occurred 155 */ 156 bool stdio_usb_deinit(void); 157 158 /*! \brief Check if there is an active stdio CDC connection to a host 159 * \ingroup pico_stdio_usb 160 * 161 * \return true if stdio is connected over CDC 162 */ 163 bool stdio_usb_connected(void); 164 #ifdef __cplusplus 165 } 166 #endif 167 168 #endif 169