Merge branch 'pr/798' into v2.0.0-devThis-is-the-head-submit-PRs-agai…

…nst-this

avr/extras/ATtiny_x7.md

@@ -184,7 +184,6 @@ The 87 and 167 are available in three package variations. Additionally, the 167
 * SOIC-20 (wide) - bigger than the side of a house, but easy to hand solder
 * TSSOP-20 - Slightly more demanding to solder. While it is hard to imagine being able to read this text and miss a bridge between adjacent pins on a SOIC-20, the same cannot be said for a SSOP-20 - depending on your eyesight, you may need magnification or more attention to lighting in order to spot bridges visually
 * VQFN32 - with 12 unused pins - Atmel seemed to REALLY like this package - a lot of 20-pin tinyAVR parts got this as their QFN instead of a proper QFN20-type. It's an annoying package, though - it's very fine pitch, large for a QFN (5mm x 5mm), and the unused pins don't appear to have been arranged with consideration of the layout. They're in the same order as the pins up and down the two sides of the SOIC/SSOP parts (probably a technical constraint I've never seen a chip with what was believed to have the same die, *not* have the same pin order, so I think bond wires have to make straight lines that don't cross each other from the die to the pin), but the decisons for where those dummy pins would go appears to have been based only on their convenience.
-* WQFN20 (167 only) - the only time, to my knowledge, that a new package option has been added for a classic AVR after the Microchip buyout. That this has only happened once, despite many examples of disappointing packages from the past, leads me to believe that one or more very large customers (they're automotive parts, so the main buyers tend to be small in number but make up for it in volume) was giving them holy hell over that 32-pin package. The 87 did not get the same blessing (nor did the 861, which was also a 20-pin tiny stuck in a 32-pin VQFN), nor did any other part they have made. They have also not added any packages to a post-revolutionary part either, even when we can show that the die size would would work fine based on what they've already fit it into, and it is plain to see the that the product is held back by it's current package options.
 
 ## Interrupt Vectors
 This table lists all of the interrupt vectors available on the ATtiny x7-family, as well as the name you refer to them as when using the `ISR()` macro. Be aware that a non-existent vector is just a "warning" not an "error" (for example, if you misspell a vector name) - however, when that interrupt is triggered, the device will (at best) immediately reset (and not clearly - I refer to this as a "dirty reset") The catastrophic nature of the failure often makes debugging challenging.

avr/extras/Ref_ChangePWMFreq.md

@@ -23,8 +23,14 @@ In a timer counter unit, when we're talking about PWM, we're talking about the s
     * On Timer 1 (which is not used for millis), you can optionally get an additional /2 prescaling by using phase correct mode. Many cores copy the official core and always use this mode, but this can slow the PWM down to speeds we might prefer it avoid - or slow them down **from** speeds we'd like to avoid. by being willing to change this mode, it becomes much easier to stay within the target PWM frequency of 490-980 Hz, or at absolute most 1960 Hz (chosen for a number of reasons - it's fast enough that you can blink an LED and it won't appear to flicker, but slow enough that you can PWM most power MOSFETs with just a small gate resistor while staying in spec. At higher frequencies, microcontrollers begin to have trouble driving the pins fast and hard enough to switch the pin without the use of a gate driver), since on most parts the prescaling options are  0 (timer off) 1, 8, 64, 256, and 1024. On the x5 and x61, Timer1 has prescale options of 0, 1, and 2^n where n can be any integer up to 14 (ie, divide by 16384). On parts where timer1 doesn't have that crazy prescaler, which easily gets us into our target range for any frequency, we will choose fastPWM or phase correct PWM if it gets us closer to the target range.
 * When full control of the timer is taken the additional functionality might include (briefly - these features are beyond the scope of this document):
   * Periodic interrupts with CTC (Clear Timer on Compare match)
-  * Arbitrary TOP values, sometimes without the loss of an output, other times only at the cost of an output channel
-  * Higher resolution on Timer1 and Timer2 (where present), at least on most parts, which have a 16-bit timer1 (and the x61's with a 10-bit one, though using that 10-bit one is tricky)
+  * Arbitrary TOP values, sometimes without the loss of an output, other times only at the cost of an output channel.
+    * 16-bit timers which have an input capture feature (I belive all of the classic AVR "standard" timer1s plus higher timers that are a copy of the standard timer1) have a PWM mode where you set the ICR register to the TOP value without losing either of the output compares.
+    * On 8-bit timers, typically the only option is to set it so output compare channel A sets top, losing a channel.
+  * Higher resolution on Timer1, except:
+    * On the 43 - it's 8-bit there, copy of timer0.
+    * On the x5 or 26, where timer1 is instead a high speed 8 bit async timer.
+    * Limited benefit is seen on the x61 - it's the souped up version of the 26, and timer1 is again a high speed timer - but a 10-bit one. The 10-bit register behavior is nonstandard.
+  * Higher resolution on Timer2, on the single family of parts that has one, the x41. Timer2 there is a copy of Timer1, not the Timer2 that the ATmegas got.
   * Asynchronous low speed operation from an external clock or watch crystal (x7, possibly a small number of others)
   * Asynchronous high speed operation from a x8 PLL on the 8 MHz internal osc. (x5, x61 26 only)
 

avr/extras/SpecificationConventions.md

@@ -45,4 +45,8 @@ This control two things: Which microcontroller or family will be used (a "family
 Very simple. When a family (as opposed to single chip) is selected, this is where you choose which one you are using.
 
 ### Clock Source and Speed
-Often a VERY long menu, this lists all supported combinations of clock source and clock speed for the system clock. The options are listed in approximately descending order of popularity/usefulness. Internmal and PLL speeds (if present) are at the top. Then come Crystal speeds, starting with common ones, then USART-crystals (the speeds that provide perfect UART baud rates, at the expense of making timekeeping slower and worse). After that are the rarely used "tuned" bootloader options that allow a chip which has been "tuned" by running the tuning sketch. These speeds are generally 8 MHz (user calibration at operating temperature and voltage beats factory cal significantly), 12.0 MHz, and on most parts, 12.8 (12.8 is mathematically favorable since 64 divides evenly into it, vastly simplifying the math. All of these speeds can almost always be reached with the internal oscillator and tuning. On the ATtiny841 and 441, the oscillator is much fancier, and an additional 16 MHz tuning is attempted. Most chips can do it (as long as they're running at around 5v) a few have unusually slow oscillators and cannot. Finally, we end on the external CLOCK options. An external clock is a component that looks near identical to a square, golden crystal package most of the time, but the pins are typically Out and Enable in place of the two crystal pins (if enable control pin is present, consult the datasheet to see if the enable is active high or low, or if it turns itself on automatically when alowed to float, and connect that pin appropriately. It is only extremely unusual use cases that will do something other than tie the pin high, low, or leave floating, whenever turns it on. The other two opposite corners are Vdd and Gnd. It is imperitve that these never be powered backwards (for example, by the easy mistake of the orientation being rotated 180 degrees) - the oscillators will destoy themselves essentially immediately if power is applied like that (this is almost always true of IC's, and though it looks like a crystal the active  I've seen that's harder to see the orientation marks on. External clocks also cost a lot more money than crystals, and the "china discount" for buying parts direct from china is much smaller than with crystals".
+Often a VERY long menu, this lists all supported combinations of clock source and clock speed for the system clock. The options are listed in descending order of popularity/usefulness. Internmal and PLL speeds (if present) are at the top. Then come Crystal speeds, starting with common ones, then USART-crystals (the speeds that provide perfect UART baud rates, at the expense of making timekeeping slower and worse). After that are the rarely used "tuned" bootloader options that allow a chip which has been "tuned" by running the tuning sketch. These speeds are generally 8 MHz (user calibration at operating temperature and voltage beats factory cal significantly), 12.0 MHz, and on most parts, 12.8 (12.8 is mathematically favorable since 64 divides evenly into it, vastly simplifying the math. All of these speeds can almost always be reached with the internal oscillator and tuning. On the ATtiny841 and 441, the oscillator is much fancier, and an additional 16 MHz tuning is attempted. Most chips can do it (as long as they're running at around 5v) a few have unusually slow oscillators and cannot.
+
+Finally, we end on the external CLOCK options. An external clock is a component that looks near identical to a square, golden crystal package most of the time (though IC-shaped ones are not unusual), but the pins are typically Out and Enable in place of the two crystal pins (if enable control is needed, enable should be tied high, low, or allowed to float depending on the device, refer to the datasheet). The other two opposite corners are Vdd and Gnd. As the most commomn, crystal-looking package is a rectangle, it can easily be installed rotated 180 degrees. It is imperitve that this be avoided! This will power them backwards and they will burn out instantly (symptom - high current, no clock, component hot). Fortunately manufacturers put highly visible orientation-marks... wait... no they don't. They mark the outside with text so tiny that you need a magnifying glass and made of nothing but a tiny groove made by a laser; smudges and dirt can easily fill this in. Some chinese external clocks (which did give the specified output clock!) had no markings on top whatsoever, and only the one notched-pad to orient it. They're also frequently horrifying power hogs. I have seen clocks spec'ed for 10, 20mA input *from Western Companies*, plus the load! Oh - and the only external clock that was rated for operation between 1.8 and 5.5 V VCC was discontinued in 2020. External clocks also cost a lot more money than crystals, and the "china discount" for buying parts direct from china is much smaller than with crystals. Besides, the chinese vendors seem to generally know neither part numbers nor voltage spec when asked. They also don't know crystal load capacitance, but on classic AVRs that's rarely a problem, they have a very tenacious crystal drive circuit.
+
+Try to avoid having to use external clocks, and if you do have to use them, buy them from the West (eg digikey/mouser, as opposed to aliexpress).