doc sync

Author: SpenceKonde

megaavr/extras/PowerSave.md

@@ -91,7 +91,7 @@ sleep_cpu();
 This can be in your loop() section of your sketch.
 Now the device will enter sleep mode and you will notice (depending on your sleep mode setting) the power consumption is less than 1μA (very difficult to measure). Waking it up with the real time counter is described next.
 
-### Unused pins and sleep modes
+### Unused pins and Sleep modes
 **IMPORTANT** In order to minimize power consumption, you *must* eliminate or disable all floating pins. A floating pin is any pin which is not being driven high or low (by this or another device) nor held in a specific state (for example by pullup resistors). Because these pins transition randomly in response to ambient noise, those digital input buffers are consuming power with every transition. To minimize power consumption, one or more of the following must apply to every pin:
 * It is set as an OUTPUT
 * It is set INPUT_PULLUP or the internal pullups are otherwise enabled

megaavr/extras/Ref_Analog.md

@@ -29,7 +29,7 @@ Notes:
 3. No external reference on 0-series and 1-series below 16k.
 4. 16k (1+series) parts are blessed with a number a boons. One of them is a second ADC. I think the intent was to provide a way to approximate having a differential ADC by triggering both at once (well, one of the intents, another one was because the ADC0 is taken over by the PTC if that is in use.
 5. The Dx-series differential ADC is a bad joke. First: The maximum absolute value both voltages is V<sub>ref</sub>, above that, wrong results are returned. And there's no amplification other than what you can press the opamps into service as.
-  **Unsubstantiated and slanderous speculation** My theory is this: The dual ADC on the 1+ series was to get dual ADC field tested because even then they could see that the new ADC was going to be an ordeal. They figured they can get away with 1 generation of chips without explicit differential ADC, but they still needed a way for some friendly customers to be able to do something like a differential ADC reading - and they were going to have to dothat in the DX - I think the Dx-series parts's "differential mode" is equivalent to two single ended measurements and some simple math)
+  **Unsubstantiated and slanderous speculation** My theory is this: The dual ADC on the 1+ series was to get dual ADC field tested because even then they could see that the new ADC was going to be an ordeal. They figured they can get away with 1 generation of chips without explicit differential ADC, but they still needed a way to get the same effect for some major customer application
 6. This is a REAL differential ADC. Max V<sub>Ain</sub> = Vdd + .1 or .2V and for useful readings their difference must be smaller than VREF. The tiny2 has some mysterious tunables, proper tuning of which is unclear. Offset error is disappointingly high, which Microchip noticed and introduced sign chopping (and removed a mysterious tunable or two) in the EA series, which should help significantly.
 
 The differential ADC on the Dx-series is disappointing.
@@ -109,27 +109,27 @@ analogReference() as you know takes only a single argument, and the overhead of
 ## Internal Sources
 In addition to reading from pins, you can read from a number of internal sources - this is done just like reading a pin, except the constant listed in the table below is used instead of the pin number:
 
-
-| AVR DA           | AVR DB            | AVR DD            | AVR EA
-|------------------|-------------------|-------------------|------------------
-| `ADC_TEMPERATURE`| `ADC_VDDDIV10`    | `ADC_VDDDIV10`    | `ADC_VDDDIV10`
-| `ADC_GROUND` *   | `ADC_TEMPERATURE` | `ADC_TEMPERATURE` | `ADC_TEMPERATURE`
-| `ADC_DACREF0` *  | `ADC_GROUND` *    | `ADC_GROUND`      | `ADC_GROUND`
-| `ADC_DACREF1` *  | `ADC_DACREF0` *   | `ADC_DACREF0`     | `ADC_DACREF0`
-| `ADC_DACREF2` *  | `ADC_DACREF1` *   | `ADC_DAC0`        | `ADC_DACREF1`
-| `ADC_DAC0`       | `ADC_DACREF2` *   | `ADC_VDDIO2DIV10` | `ADC_DAC0`
-|                  | `ADC_DAC0` *      |                   |
-|                  | `ADC_VDDIO2DIV10` |                   |
-
-| tinyAVR 0/1-series                     | tinyAVR 2-series
-|----------------------------------------|-------------------------------------
-| `ADC_INTREF`                           | `ADC_VDDDIV10`
-| `ADC_TEMPERATURE`                      | `ADC_TEMPERATURE`
-| `ADC_DAC0` (1-series only)             | `ADC_GROUND` (offset calibration?)
-| `ADC_GROUND` (offset calibration?)     | `ADC_DACREF0`
-| `ADC_DACREF0` (alias of ADC_DAC0)      | `ADC_DAC0` (alias of `ADC_DACREF0`)
-| `ADC_PTC` (not particularly useful)    | *see note*
-| `ADC1_DACREF1` (16/32k 1-series only)† |
+| AVR DA           | AVR DB            | AVR DD            | AVR EA           |
+|------------------|-------------------|-------------------|------------------|
+| `ADC_TEMPERATURE`| `ADC_VDDDIV10`    | `ADC_VDDDIV10`    | `ADC_VDDDIV10`   |
+| `ADC_GROUND` *   | `ADC_TEMPERATURE` | `ADC_TEMPERATURE` | `ADC_TEMPERATURE`|
+| `ADC_DACREF0` *  | `ADC_GROUND` *    | `ADC_GROUND`      | `ADC_GROUND`     |
+| `ADC_DACREF1` *  | `ADC_DACREF0` *   | `ADC_DACREF0`     | `ADC_DACREF0`    |
+| `ADC_DACREF2` *  | `ADC_DACREF1` *   | `ADC_DAC0`        | `ADC_DACREF1`    |
+| `ADC_DAC0`       | `ADC_DACREF2` *   | `ADC_VDDIO2DIV10` | `ADC_DAC0`       |
+|                  | `ADC_DAC0` *      |                   |                  |
+|                  | `ADC_VDDIO2DIV10` |                   |                  |
+
+
+| tinyAVR 0/1-series                     | tinyAVR 2-series                    |
+|----------------------------------------|-------------------------------------|
+| `ADC_INTREF`                           | `ADC_VDDDIV10`                      |
+| `ADC_TEMPERATURE`                      | `ADC_TEMPERATURE`                   |
+| `ADC_DAC0` (1-series only)             | `ADC_GROUND` (offset calibration?)  |
+| `ADC_GROUND` (offset calibration?)     | `ADC_DACREF0`                       |
+| `ADC_DACREF0` (alias of ADC_DAC0)      | `ADC_DAC0` (alias of `ADC_DACREF0`) |
+| `ADC_PTC` (not particularly useful)    | *see note*                          |
+| `ADC1_DACREF1` (16/32k 1-series only)† |                                     |
 
 The Ground internal sources are presumably meant to help correct for offset error. On Classic AVRs they made a point of talking about offset cal for differential channels. They are thus far silent on this, despite a great number of tech briefs related to the new ADC has been coming out, greatly improving the quality of the available information
 DACREF0 is the the reference voltage for the analog comparator, AC0. On the 1-series, this is the same as the `DAC0` voltage (yup, the analog voltage is shared). Analog comparators AC1 and AC2 on 1-series parts with at least 16k of flash also have a DAC1 and DAC2 to generate a reference voltage for them (though it does not have an output buffer). On the 2-series, this is only used as the AC0 reference voltage; it cannot be output to a pin.
@@ -457,8 +457,6 @@ As of 2.5.12 (1.6.8) we will always disable and re-enable the ADC if touching LO
 
 **Disabling the ADC is REQUIRED for acceptable sleep power consumption on the 2-series!**
 
-**No word either way on the EA-series!**
-
 Lowlat mode is enabled by default for this reason, as well as to generally improve performance. Disabling the ADC will end the power consumption associated with it.
 
 On 0/1-series parts, this function supports functions that are far more limited, since there are few power options.

megaavr/extras/Ref_Export.md

@@ -59,7 +59,7 @@ You will quickly notice that assembly is non-linear it will often jump off to so
 * The argument is in decimal, not hexadecimal, the comment will contain the address of the target in hexadecimal.
 * Jump - the `jmp` and much more commonly, `rjmp` instructions move execution to a different address. `rjmp` is smaller and faster, but can only jump a limited distance. `jmp` can jump to anywhere in the flash - this is a 4-byte instruction, and the two second bytes are the address it's jumping to.
   * Addresses are word addresses in the opcodes, but byte addressed in the assembly (and the comment) after them will convert it to a byte address.
-  * `jmp`'s third and fourth byte are the address i's jumping to. On the small number of AVR parts with flash larger than 128k bytes (64k words, 2^16), some of the bits of the first two bytes of jump are used `*`, since this can reach the whole address space.
+  * `jmp`'s third and fourth byte are the address it's jumping to. On the small number of AVR parts with flash larger than 128k bytes (64k words, 2^16), some of the bits of the first two bytes of jump are used `*`, since this can reach the whole address space.
   * `rjmp` will have an argument of `.+number` or `.-number`, which represents the position as measured from the the *next* instruction. so `.+42` means that that the next instruction it executes (if it branches) will have an address 42+2 higher than the current instruction.
   * That means that `rjmp .-2` is an infinite loop with no test. It is normal for avr-gcc to emit one of these in every program; if `main()` were ever to return, this is where it would go (C was designed for systems where it was meaningful for a program to "exit", which is not the case on embedded systems)
   * That also means that `rjmp .+0` does nothing. This is very common in timing critical hand-written code: it's a 2-clock-cycle `nop`(no operation), and never seen in compiler generated code (if it is, it's because some assembly macro is being used)

megaavr/extras/Ref_Reset.md

@@ -175,7 +175,7 @@ void resetViaWDT() {
 void resetViaWDTFaster() {
   _PROTECTED_WRITE(WDT.CTRLA,WDT_WINDOW_8CLK_gc | WDT_PERIOD_8CLK_gc); //enable the WDT, minimum timeout, minimum window.
   while (1) __asm__ __volatile__ ("wdr"::);
-  // execute WDR's until reset. The loop should in total take 3 clocks (the compiler will implement it as wdr, rjmp .-4)
+  // execute WDRs until reset. The loop should in total take 3 clocks (the compiler will implement it as wdr, rjmp .-4)
   // but because of the sync delay described above, it will run thousands of times before the first premature (from the
   // WDT's perspective) wdr finally makes it to the WDT domain and slams into the closed window.
 }
@@ -286,6 +286,7 @@ void setup() {
 
 ```
 
+
 ## The WRONG way to reset from software
 I have seen people throw around `asm volatile("jmp 0");` as a solution to a need to reset from software. **Don't do that** - all compiled C code makes assumptions about the state from which it is run. Jumping to 0 from a running application violates several of them unless you take care to avoid those pitfalls (if I were to add a comment after that line, it would read something like `// Reset chip uncleanly to produce unpredictable results`. Resetting with a jump to 0 was always risky business and should never be done on any part, ever (certainly not without taking a bunch of precautions and knowing exactly what you're getting into (which nobody who did this ever seemed to). Now that we have a right way to do software reset, there is absolutely no excuse for intentionally triggering a dirty reset like this.
 

megaavr/extras/Ref_Robust.md

@@ -9,7 +9,7 @@ This is a work in progress, and is not exhaustive. It is however a starting poin
 These parts have multiple features for enhanced robustness. You should like, use themm..... (hardly anyone does)
 
 ### Use BOD if you can spare the power for sampled mode, at least while the chip is awake
-See the datasheet for your part to check the exact power consumption and compare to your power budget. If you can - use it! Without BOD, there is nothing to keep the chip from operating incorrectly in amost arbitrary manners, as the symptoms (above VPOR)of insufficient voltage for a given clock speed is that *instructions will get the wrong answers to basic math, often with 1 bits coming out as 0's.* This includes pointers, indirect jumps, probably function return addresses pushed onto the stack, in short, for predictable behavior in undervoltage, use the BOD, that's what it's there for.
+See the datasheet for your part to check the exact power consumption and compare to your power budget. If you can - use it! Without BOD, there is nothing to keep the chip from continuing to try (and fail) to operate despite insufficient power supply voltage to do so.
 
 BOD will keep the chip in reset when you it knows the voltage is too low to keep the chip running.
 
@@ -60,7 +60,7 @@ The Dx-series parts overclock fantastically well. That should not be an invitati
 ### Check the thickness of the wire you're using
 I don't mean reading the number on the insulation anyone can print "22 AWG" on wire, but that doesn't make it 22 AWG. Strip it, measure the bundle of wire,  separate it to strands, count them, and measure one strand as accurately as you can (need to measure to at least 0.01 mm) and calculate what gauge it actually is. Some dishonest Chinese manufacturers (and probably some in other countries, but China is by far the most prolific producer of everything) frequently use wire 2-6 AWG smaller than the number they print on the insulation.  In order to keep people from immediately noticing (because it's too thin) they make up the difference with extra thick insulation. Cheap hookup wire (UL1007) on AliExpress, for example, is usually 3-4 AWG too thin. Some pre-wired JST-SM connectors I've gotten had what appears to be 32-gauge wire marked 24. I didn't discover this until heat from the load through the too-small wires had resulted in it heating up and turning the red insulation black; when investigating the subsequent failure, I was mystefied as to why there were two black wires instead of a black and a red...
 
-Apparently it's not just wire being exported that's like this - I hear stories of assembled equipment also made with the undersized wire, and failing as a result. The impression I get is that some of the manufacturers using it don't realize it's undersized (likely they are aware that undersized wire exists, were asserted that the stuff they were getting was not, and maybe even measured it back when they started buying from that supplier...)
+Apparently it's not just wire being exported that's like this - I hear stories of assembled equipment also made with the undersized wire, and failing as a result. The impression I get is that some of the manufacturers using it don't realize it's undersized (likely they are aware that undersized wire exists, were assured that the stuff they were getting was not, and maybe even measured it back when they started buying from that supplier...)
 
 ### Do not use dupont line in production devices
 At least not the cheap crap normally sold as that. The cheao dupont line is for prototyping only, and barely suitable for that. Real DuPont line with real DuPont terminals is fine (that division is now run by Amphenol, the line is called MiniPV), as long as you make sure you get ones made by Amphenol obtained through a reputable western supply house. They should cost a minimum of 10 cents each in quantiy for no-frills terminals, and typically more like 20-30 for decent gold plated ones. Use the highest spring tension ones unless you have more than 20 pins ins a connector, and make sure that you or your manufacturing partner is doing a good job crimping them on (go try the pull test on some cheap dupont line - most of it doesn't even pass the pull test) If you look at the terminal of real dupont connectors, they are obviously not the same design as the cheap ones.
@@ -73,7 +73,7 @@ Any connector that can be plugged in backwards will be. Try to design the pinout
 Or my 3-pin UPDI header. Ground in the middle, Vcc and UPDI on the sides. Plugging it in backwards connects power to UPDI and UPDI to power. There's almost always a current limiting resistor somewhere on the UPDI line (there should be!), and the modern devices are much more forgiving of current through the clamp diodes than classic AVRs are, often being rated for max of 15-20mA, and on the tinyAVRs, it's also the HV pin (otherwise, it has protection/clamp diodes, but that's what the resistor limits the current through).
 Don't use two connectors of the same type, same gender, and same number of pins on one device if they're not interchangible. It is worth using a larger connector and leaving one slot empty. You can cut the pin off the socket and fill the eopty hole in the housing with glue (the plastic polarizing pins, if you can find them, are a lot more graceful, but they seem to be scarcer than hens teeth).
 
-If you can't keep people from reversing a connector, and you can't make it harmless if they do so through pinout choice, or don't want to because it wiould require too many other compromises, how about a diode in series with the problem wire (likely power)?
+If you can't keep people from reversing a connector, and you can't make it harmless if they do so through pinout choice, or don't want to because it would require too many other compromises, how about a diode in series with the problem wire (likely power)?
 
 ### The Second law of Connectors
 You will have one or more connectors that carry power. Connectors get abused over time, and foreign objects can get into them. You do not want them to cause a short when thety do. There are many connectors that manage to keep both inacessable (for example, USB). With other connectors, generally **The side which supplies power should always be the female** - it is almost always easier for the male terminals to be shorted by contact with the environment than female terminals. Also, the convention is that the negative side is ground, and is considered less hazsrdous. That is whty barrrel jacks are almost always center positive.