Document recent 1.1.6 updates

README.md

@@ -45,7 +45,7 @@ There is a solution to the lack of a hardware reset pin when you need to keep UP
 
 If you were to set up a "low level" interrupt on a pin, and put that in the ISR, that pin would act as an ersatz reset pin (note that it wouldn't "stay" in reset like a real reset pin - it will reset the chip, and then the sketch (or bootloader) will start running again from the start until the interrupt was enabled, then reset again).
 
-megaTinyCore supports configurations with this pin fused to act as reset with programming over UART serial. See the Optiboot section below for more information
+megaTinyCore supports configurations with this pin fused to act as reset with programming over UART serial, as well as with the UPDI pin used as GPIO, on Optiboot boards only. See the Optiboot section below for more information
 
 # Features
 
@@ -136,19 +136,23 @@ PORTMUX.CTRLB&=~(1<<TWI0);
 The core provides hardware PWM (analogWrite) support. On the 8-pin parts (412, 212, 402, 204), 4 PWM pins are available (1.0.5 and later - 1.0.4 and earlier only have 1). On all other parts except the x16 and x17 series, 6 PWM pins are available, driven by Timer A. The type B timers cannot be used for additional PWM pins - their output pins are the same as those available with Timer A - however you can take them over if you need to generate PWM at different frequencies. See the pinout charts for a list of which pins support PWM.
 The 3216,1616,816,416,3217,1617 and 817 have two additional PWM pins driven by Timer D (pins 10 and 11 on x16, 12 and 13 on x17). Timer D is an async timer, and the outputs can't be enabled or disabled without briefly stopping the timer. This results in a brief glitch on the other PWM pin (if it is currently outputting PWM), and doing so requires slightly longer (in 1.0.0, this delay is 1ms, in 1.0.1 and later, it is around 1us). This applies to digitalWrite() or analogWrite of 0 or 255 while it is currently outputting PWM, and analogWrite of 1~254 while the pin is not currently outputting PWM. This is a hardware limitation and cannot be further improved.
 
-**Note that TCA0 (the type A timer) on all parts is configured in split mode to support the most PWM pins possible with analogWrite(). This timer is also used for millis() (all parts on 1.1.2 and earlier, 8 and 14-pin 1-series parts on 1.1.3 and later), so reconfiguring it for different PWM frequencies will break millis(). Use a type B timer if you need to take over a timer if possible, or change millis() to use a different timer - see the section on that below**
+**Note that TCA0 (the type A timer) on all parts is configured in split mode to support the most PWM pins possible with analogWrite(). This timer is also used for millis() (all parts on 1.1.2 and earlier, and all parts except 8 and 14-pin 1-series parts on 1.1.3 and later), so reconfiguring it for different PWM frequencies will break millis(). Use a type B timer if you need to take over a timer if possible, or change millis() to use a different timer - see the section on that below**
+
+If you wish to change the PWM frequency, on versions prior to 1.1.6, it will break tone, as well as millis/micros with TCA0, TCB0, or TCB1 as a clock source, and the Servo library. On 1.1.6 and later, only TCA0 as millis/micros source and the Servo library will be broken by changing the TCA0 prescaler. 
 
 ### NeoPixel (WS2812) support (new in 1.0.3)
 The usual NeoPixel (WS2812) libraries have problems on these parts. This core includes two libraries for this, both of which are tightly based on the Adafruit_NeoPixel library. See the [tinyNeoPixel documentation](megaavr/extras/tinyNeoPixel.md) and included examples for more information.
 
 ### Tone Support
-Support for tone() is provided on all parts using Timer B 0. This is like the standard tone() function; it does not support use of the hardware output compare to generate tones (yet). See caveats below if using specific millis()/micros() settings.
+Support for tone() is provided on all parts using TCB0, unless TCB1 is present and TCB0 is set as millis source. This is like the standard tone() function; it does not support use of the hardware output compare to generate tones. See caveats below if using TCB0 or TCB1 for millis/micros settings.
 
 ### millis/micros options and timer use
-By default, as of 1.1.3, TCD0 will be used by default for millis() on parts without PWM pins that can be driven by TCD0 and not TCA0, otherwise TCA0 will be used (on previous versions, TCA0 is used on all parts). A tools submenu, millis()/micros() provides options to enable with default settings for the part, disable millis and micros entirely (to save flash), or to force it onto a specific timer - as of 1.1.5, TCA0 and TCD0 (1-series parts only, breaks PWM on the two timer D pins on 20 and 24 pin parts), TCB0, TCB1 (where present) and the RTC (no micros, only millis, clocked from internal ULP or external 32,768khz watch crystal) are supported for timekeeping. When using TCB0 (breaks tone and servo on parts with only one type b timer, and tone on all parts); using TCB1 (parts with two type b timers only - 1-series parts with 16k or more of flash - on those parts servo and tone cannot be used simultaneously if this is selected). Support for millis() with the RTC using external watch crystal or internal ULP are planned for a future version (this will only support millis, not micros - the 32kHz clock is not fast enough for microsecond timing). The timer selection menu provides a way to ensure that if you need to take over a specific timer completely, you can move millis()/micros() to a different timer, accepting the consequences outlined above.
+By default, as of 1.1.3, TCD0 will be used by default for millis() on parts without PWM pins that can be driven by TCD0 and not TCA0, otherwise TCA0 will be used (on previous versions, TCA0 is used on all parts). A tools submenu, millis()/micros() provides options to enable with default settings for the part, disable millis and micros entirely (to save flash), or to force it onto a specific timer - as of 1.1.5, TCA0 and TCD0 (1-series parts only, breaks PWM on the two timer D pins on 20 and 24 pin parts), TCB0, TCB1 (where present) and the RTC (no micros, only millis, clocked from internal ULP or external 32,768khz watch crystal) are supported for timekeeping. When using TCB0 as millis() source, tone and the Servo library will be unavailable on parts with only one type b timer. Using either TCB0 or TCB1 on parts with both will prevent simultaneous use of tone and the Servo library. Support for millis() with the RTC using external watch crystal or internal ULP are planned for a future version (this will only support millis, not micros - the 32kHz clock is not fast enough for microsecond timing). The timer selection menu provides a way to ensure that if you need to take over a specific timer completely, you can move millis()/micros() to a different timer, accepting the consequences outlined above.
 
 When 20/10/5MHz system clock is used, the micros() count will not increase exactly 1000 times faster than millis() count - it is close, but not exact. This was required for performance and flash usage optimization.
 
+In versions prior to 1.1.6, TCB0 and TCB1 as the millis/micros source, as well as tone and the Servo library depend on the prescaler of TCA0 not being changed - this prescaled clock source is used (type B timers do not have a separate prescaler). On 1.1.6, this dependence is removed for millis/micros and tone, so that the TCA0 prescaler can be freely changed. However, the Servo library still requires the TCA0 prescaler to be unchanged.
+
 #### RTC timer for millis
 If the RTC is selected as the timer for millis timekeeping, micros will not be available. Additionally, this timer is configured to run while in STANDBY sleep mode. This has two important consequences: First, it will keep time while in sleep. Secondly, every 64 seconds, the RTC overflow interrupt will fire, waking the chip - thus, if you are using the RTC for millis and putting the part into sleep, you should declare a volatile global variable that you set in the ISR that is supposed to wake the part, eg 'volatile boolean ShouldWakeUp=0;' - set it to 1 in the ISR, and when you put the ATtiny to sleep, have it check this immediately after waking, going back to sleep if it's not set, and clearing it if it is, e.g.:
 ```cpp
@@ -175,7 +179,7 @@ These parts all have ADC channels available on most pins (11 pins on 24 and 20 p
 The 1-series parts have an 8-bit DAC which can generate a real analog voltage (note that this provides very low current and can only be used as a voltage reference, it cannot be used to power other devices). This generates voltages between 0 and the selected VREF (which cannot be VCC, unfortunately) - select the DAC VREF voltage from the Tools -> DAC Voltage Reference submenu. This voltage must be lower than Vcc to get the correct voltages. Call analogWrite() on the DAC pin to set the voltage to be output by the DAC. To turn off the DAC output, call digitalWrite() on that pin. The Tools -> DAC Voltage menu contains an additional option to disable the DAC output, as this saves a fair bit of flash.
 
 ### Servo Support
-This core provides a version of the Servo library which will select an appropriate timer (Timer B 0, except on the 3216, 3217, 1617, 1616 and 1614, where there is a Timer B 1 available; except on the aforementioned parts, tone cannot be used at the same time as the Servo library. If millis/micros is set to use TCB1 on those parts, servo will use TCB0 instead, making it incompatible with tone there as well). Servo output is better the higher the clock speed - when using servos, it is recommended to run at the highest frequency permitted by the operating voltage to minimize jitter.
+This core provides a version of the Servo library which will select an appropriate timer (TCB0, except on the 3216, 3217, 1617, 1616 and 1614, where there is a Timer B 1 available; except on the aforementioned parts, tone cannot be used at the same time as the Servo library. If millis/micros is set to use TCB1 on those parts, servo will use TCB0 instead, making it incompatible with tone there as well). Servo output is better the higher the clock speed - when using servos, it is recommended to run at the highest frequency permitted by the operating voltage to minimize jitter.
 
 **Warning** If you have installed a version of the Servo library to your <sketchbook>/libraries folder (including via library manager), the IDE will use that version of the library (which is not compatible with these parts) instead of the one supplied with megaTinyCore. As a workaround, a duplicate of the Servo library is included with a different name - to use it, `#include <Servo_megaTinyCore.h>` instead of `#include <Servo.h>`
 
@@ -218,12 +222,12 @@ A new version of Optiboot (Optiboot-x) now runs on the Tiny0 and Tiny1 chips.  I
 To use the serial bootloader, select a board definition with (optiboot) after it (note - this might be cut off due to the width of the menu; the second set of board definitions are the optiboot ones).
 
 If the chip you will be programming has not been bootloaded, connect your UPDI programmer, and the desired options for clock rate (20/10/5MHz vs 16/8/4/1MHz is all that matters here. The fuses set the base clock to 20MHz or 16MHz, but the prescaler is set at startup by the sketch - so if you "burn bootloader" with 20MHz selected, but upload sketch compiled for 10MHz, that's fine and will work), Brown Out Detect (BOD), Serial port pins for the bootloader, and whether to leave the UPDI pin configured as such, or reconfigure it as a reset pin, and select Tools -> "Burn Bootloader"
-**WARNING: After doing "Burn Bootloader", if you set the UPDI pin to act as reset, the chip cannot be reprogrammed except via the serial bootloader or using an HV UPDI programmer - it is strongly suggested to first burn the bootloader with the UPDI/Reset pin left as UPDI, verify that sketches can be uploaded, and only then "Burn Bootloader" with the UPDI/Reset pin set to act as Reset**
+**WARNING: After doing "Burn Bootloader", if you set the UPDI pin to act as reset or IO, the chip cannot be reprogrammed except via the serial bootloader or using an HV UPDI programmer - it is strongly suggested to first burn the bootloader with the UPDI/Reset pin left as UPDI, verify that sketches can be uploaded, and only then "Burn Bootloader" with the UPDI/Reset pin set to act as Reset**
 
 After this, connect a serial adapter to the serial pins (as well as ground and Vcc). On the megaavr ATtiny breakout boards which I sell on Tindie, a standard 6-pin "FTDI" header is provided for this that can be connected directly to many serial adapters.
 
 
-If the UPDI/Reset pin option was set to UPDI when bootloading, you must unplug/replug the board (or use a software reset - see note near start of readme; you can make an ersatz reset button this way) to enter the bootloader - after this the bootloader will be active for 8 seconds.
+If the UPDI/Reset pin option was set to UPDI or IO when bootloading, you must unplug/replug the board (or use a software reset - see note near start of readme; you can make an ersatz reset button this way) to enter the bootloader - after this the bootloader will be active for 8 seconds.
 
 If the UPDI/Reset pin option was set to reset, you must reset the chip via the reset pin (or software reset to enter the bootloader, and the bootloader will run for 1 second before jumping to the application). This is the same as how optiboot works on classic AVR boards. The standard DTR-autoreset circuit is recommended (this is how boards I sell on Tindie with Optiboot preloaded are configured).