doc update

CODE_OF_CONDUCT.md

@@ -44,6 +44,6 @@ Instances of abusive, harassing, or otherwise unacceptable behavior may
 be reported by emailing `spencekonde@gmail. com>` which only goes to to
 Spence Konde.
 
-This Code of Conduct is adapted from the `Contributor
+This Code of Conduct is adapted from the examples cited by GitHub, which was adapted from the `Contributor
 Covenant <http://contributor-covenant.org>` version 1.0.0, available at
-http://contributor-covenant.org/version/1/0/0/
+[http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/).

README.md

@@ -18,9 +18,14 @@ The most significant changes are:
 6. For various historical reasons, some parts have up to 3 pin mappings. These are now named consistently, and listed and described in the part specific documentation - All parts have a recommended pin mapping, some of them have a second one for a specific VUSB board (digispark pro, MH-ET) with the pins numbered differently, and some of them have a "legacy" pin mapping with the pins in an order that makes less sense, and which makes converting between analog and digital pins harder (as in, if there is stuff determined at runtime, it uses more flash and is slower), but which has been widely used in the past and is what existing code may have been written for. A number of inconsistencies between these pin mappings (where information was missing from one or the other) have been fixed, and they are now formatted and commented consistently.
 7. The ATtiny1634 and ATtiny861 are now supported for Micronucleus. Test and demonstration boards will be available from my Tindie store. New versions of bootloader for all existing Micronucleus boards. Users should use the bootloader upgrade functionality to ensure that they have the latest version of the bootloader, and that it has their desired entry conditions (on reset pin, power on reset, power-on with pin held down, reset/power on w/reset held high (in case of disabled reset, holding the reset pin high during power on will make it enter bootloader - takes advantage of the fact that reset PIN bit always reads 0 when reset is not disabled... Actually, one wonders if it would work if you did PORTx |= 1 << RESETBIT; then test if that bit is set - does disabling reset actually make registers not store the value? If so, that would be even better - no dependence on hardware, clear the bit if could set it and run app, otherwise run bootloader. )
 
+## Main Documentation
+The documentation, broadly, falls into two categories. The General Documentation applies to all parts.
 
+Additionally, there are parameters that are specific to one or several families of parts. These cover the specifics of the peripherals on the parts (how Serial, I2C, and SPI are implemented on that hardware), the PWM frequencies that will be used at specific system clock frequencies, any additional options relating to the ADC such as differential inputs, and particularly notable or problematic errata, if any, applicable to this part. These are linked below.
 
+You should **always review that part-specific documentation** before making any choice of parts. The time it takes to read them is far less than the time it takes to redesign with a different part when you're nearly done and then trip over some unexpected limitation... I try to catch the differences that might pose this hazard and describe them in these documents.
 
+### [General Documentation](https://github.com/SpenceKonde/ATTinyCore/blob/v2.0.0-devThis-is-the-head-submit-PRs-against-this/avr/extras/README.md) -
 ### [Installation](Installation.md)
 ### [Wiring and required external components](https://github.com/SpenceKonde/ATTinyCore/blob/v2.0.0-devThis-is-the-head-submit-PRs-against-this/avr/extras/Ref_Wiring.md)
 ### [Using with Micronucleus boards](https://github.com/SpenceKonde/ATTinyCore/blob/v2.0.0-devThis-is-the-head-submit-PRs-against-this/avr/extras/Ref_Micronucleus.md)
@@ -30,7 +35,7 @@ The most significant changes are:
 
 
 ## Supported devices
-This core supports the following processors - essentially every "classic" tinyAVR processor that makes sense to use with Arduino. The modern (post-2016 release) tinyAVR parts have [their own core](https://github.com/SpenceKonde/megaTinyCore), as there is practically zero code at the core level that can be shared with classic parts (porting application code (sketches) typically poses fewer challenges - code that did not stray from the Arduino API functions can be ported easily, while code that interacts with registers directly does need to be modified). Porting application code between different parts supported by this core is generally a matter of pin adapting to the different arrangement of peripherals among the pins on the two parts
+This core supports the following processors - essentially every "classic" tinyAVR processor that makes sense to use with Arduino. The modern (post-2016 release) tinyAVR parts have [their own core](https://github.com/SpenceKonde/megaTinyCore), as there is practically zero code at the core level that can be shared with classic parts (porting application code (sketches) typically poses fewer challenges - code that did not stray from the Arduino API functions can be ported easily, while code that interacts with registers directly does need to be modified). Porting application code between different parts supported by this core is generally a matter of pin selection adapting to the different arrangement of peripherals among the pins on the two parts. Atmel seems to have picked their pin mappings with a dart board, so there's a lot of variation.
 
 * [ATtiny441, 841](https://github.com/SpenceKonde/ATTinyCore/blob/v2.0.0-devThis-is-the-head-submit-PRs-against-this/avr/extras/ATtiny_x41.md) (With or without Optiboot or Micronucleus bootloader) - One of the last classic tinyAVR parts released, and probably the single best of them. This has a second 16-bit timer (like Timer1) giving it a total of 6 PWM channels, two hardware serial ports, analog input on every pin with differential capability with programmable gain. On top of that, if you tune the internal oscillator to nearly the maximum, 90+% of these will run at 16 MHz.
 * [ATtiny1634](https://github.com/SpenceKonde/ATTinyCore/blob/v2.0.0-devThis-is-the-head-submit-PRs-against-this/avr/extras/ATtiny_1634.md)  (With or without Optiboot bootloader - Micronucleus probably coming soon) - One of the last classic tinyAVR parts released. Sporting 16k of flash, 1k of RAM, and dual hardware serial ports spread across it's 18 I/O pins, this is one of the stars of the classic AVR line, though it would have really benefited if it got the same featureset that the 841 did.

avr/bootloaders/optiboot/source/README.md

@@ -20,26 +20,25 @@ This is being maintained as part of ATTinyCore, so issues be reported to:
 Arduino-specific issues are tracked as part of the Arduino project
 at [http://github.com/arduino/Arduino](http://github.com/arduino/Arduino)
 
-
-There is additional information in the wiki - however, the wiki does not reflect the changes specific to Optiboot X for megaTinyCore
+There is additional information in the wiki - however, the wiki does not reflect the changes specific to Optiboot for ATTinyCore
 [https://github.com/Optiboot/optiboot/wiki](https://github.com/Optiboot/optiboot/wiki)
 
 
 ## To set up this environment in windows
-This is how the files megaTinyCore ships with are built. I can provide no guarantee that any other method will still work after what I've done to the makefile.
+This is how the files ATTinyCore ships with are built. I can provide no guarantee that any other method will still work after what I've done to the makefile.
 1. Download and extract the Arduino 1.0.6 .zip package.
 * Make sure it is not in a "protected" location. I normally put them in the root of C:.
 * Rename the folder so you remember what it's for; I have it in `C:\arduino-1.0.6-5.4.0compiler` (this location will be used in the examples below)
 * You may delete everything except the hardware and tools subdirectories
 2. Download the 5.4.0 toolchain - or use the latest 7.3.0 one if brave.
-* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-armhf-pc-linux-gnu.tar.bz2 ](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-armhf-pc-linux-gnu.tar.bz2 )
-* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-aarch64-pc-linux-gnu.tar.bz2 ](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-aarch64-pc-linux-gnu.tar.bz2 )
-* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i386-apple-darwin11.tar.bz2 ](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i386-apple-darwin11.tar.bz2 )
-* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-w64-mingw32.zip ](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-w64-mingw32.zip )
-* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-pc-linux-gnu.tar.bz2 ](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-pc-linux-gnu.tar.bz2 )
-* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-x86_64-pc-linux-gnu.tar.bz2 ](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-x86_64-pc-linux-gnu.tar.bz2 )
+* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-armhf-pc-linux-gnu.tar.bz2](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-armhf-pc-linux-gnu.tar.bz2)
+* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-aarch64-pc-linux-gnu.tar.bz2](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-aarch64-pc-linux-gnu.tar.bz2)
+* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i386-apple-darwin11.tar.bz2](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i386-apple-darwin11.tar.bz2)
+* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-w64-mingw32.zip](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-w64-mingw32.zip)
+* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-pc-linux-gnu.tar.bz2](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-i686-pc-linux-gnu.tar.bz2)
+* [http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-x86_64-pc-linux-gnu.tar.bz2](http://downloads.arduino.cc/tools/avr-gcc-5.4.0-atmel3.6.1-arduino2-x86_64-pc-linux-gnu.tar.bz2)
 * For the brave:
-* [https://spencekondetoolchains.s3.amazonaws.com/avr-gcc-7.3.0-atmel3.6.1-azduino7-i686-w64-mingw32.tar.bz2 ](https://spencekondetoolchains.s3.amazonaws.com/avr-gcc-7.3.0-atmel3.6.1-azduino7-i686-w64-mingw32.tar.bz2)
+* [https://spencekondetoolchains.s3.amazonaws.com/avr-gcc-7.3.0-atmel3.6.1-azduino7-i686-w64-mingw32.tar.bz2](https://spencekondetoolchains.s3.amazonaws.com/avr-gcc-7.3.0-atmel3.6.1-azduino7-i686-w64-mingw32.tar.bz2)
 3. Extract the toolchain, and locate the top level 'avr' folder inside.
 4. Copy the AVR folder to the `C:\arduino-1.0.6-5.4.0compiler\hardware\tools` directory in the 1.0.6 install. Be careful not to put it inside the avr folder that is already there (if you make a mistake, delete the mess and go back to step 1 - trying to unpick the mess is hopeless, because there are like 4 nested folders named avr, 2 folders in different locations named bin, and several 'include' folders. Don't look at me, I didn't choose that directory structure!
 5. Copy the `optiboot` folder from `(core install location)/megaavr/bootloaders` to `C:\arduino-1.0.6-5.4.0compiler\hardware\arduino\bootloaders`.
@@ -52,7 +51,6 @@ This can be done the same way in linux except that you would download the versio
 These may or may not work. I am not versed in the ways of makefiles and am not competent to fix any issues that may be encountered. Thus, if you want to use one of these methods, you'll have to fix the makefile yourself (sorry - my brain uses 16-bit addressing. You'll notice I never talk about working with an ATmega2560 - that would require an extra bit, ya see? So figuring out how to wrangle a makefile on a 64-bit desktop computer is well beyond my ability). I will gladly accept pull requests that fix these things - as long as they do not break the method detailed above, as that would leave me unable to build DxCore bootloaders without toolchain wrangling, which as I said, is outside my zone of competence. If you find that these do in fact work as written, please let me know so I can update this file.
 
 ### Building optiboot for Arduino
-
 Production builds of optiboot for Arduino are done on a Mac in "unix mode"
 using CrossPack-AVR-20100115.  CrossPack tracks WINAVR (for windows), which
 is just a package of avr-gcc and related utilities, so similar builds should
@@ -67,7 +65,6 @@ the Arduino IDE.)
 
 
 ### Building Optiboot in the Arduino IDE Install
-
 Work in the .../hardware/arduino/bootloaders/optiboot/ and use the
 `omake <targets>` command, which just generates a command that uses
 the arduino-included "make" utility with a command like:
@@ -85,7 +82,6 @@ directory (or something created at the same "level") for it to work.
 
 
 ### Building Optiboot in the Arduino Source Development Install
-
 In this case, there is no special shell script, and you're assumed to
 have "make" installed somewhere in your path.
 Build the Arduino source ("ant build") to unpack the tools into the

avr/extras/ATtiny_1634.md

@@ -47,9 +47,10 @@ New in 2.0.0. D+ is on PC4, D- is on PC5, and it tries to blink an LED on PC2. T
 ### Two pin mapping options
 When I first merged in support for the tiny1634, I lacked the background to assess the pin mapping that the original author (TC-world as I recall) had chosen. With greater experience, it is evident that it is markedly worse than it could have been I think it was designed with it's prime directive to make 0 and 1 be the serial pins, which was very common practice in those days - and to try to have the SPI be on the same numbered pins as the '328p. As the market has become less of a monoculture, that convention has become less ubiquitous, which is good, because it's destructive . 2.0.0 introduces a more rational pin mapping with the pins numbered in clockwise order instead of counterclockwise. The desired pin mapping can be chosen from the Tools -> Pin Mapping submenu. Be very sure that you have selected the one that you wrote your sketch for, as debugging these issues can be surprisingly timeconsuming. Your sketch can check for PINMAPPING_CCW or PINMAPPING_CW macro (eg, `#ifdef PINMAPPING_CCW` - I would recommend checking for the incompatible one, and immediately #error'ing if you find it). Remember also that you can always refer to pins by their port and number within that port, using the `PIN_Pxn` syntax - where x is the port letter, and n is the pin number, eg PIN_PA7 is PIN A7, which is pin 7 in the clockwise mapping and pin 1 in the counterclockwise mapping. The clockwise mapping is strictly better than the counterclockwise one - the macros are more efficient (hence smaller binary sizes)
 Example of a "guard" against wrong pin mapping:
-```
+
+```c
 #ifdef PINMAPPING_CCW
-#error "Sketch was written for clockwise pin mapping!"
+  #error "Sketch was written for clockwise pin mapping!"
 #endif
 ```
 
@@ -97,9 +98,9 @@ There is no hardware SPI peripheral. SPI functionality can be achieved with the
 There are two hardware serial ports, Serial and Serial1. It works the same as Serial on any normal Arduino - it is not a software implementation.
 
 To use only TX or only RX channel, after Serial.begin(), one of the following commands will disable the TX or RX channels (for Serial1, use UCSR1B instead)
-```
-UCSR0B&=~(1<<TXEN0); // disable TX
-UCSR0B&=~(1<<RXEN0); // disable RX
+```c
+UCSR0B &= ~(1<<TXEN0); // disable TX
+UCSR0B &= ~(1<<RXEN0); // disable RX
 ```
 
 ### ADC Reference options
@@ -128,20 +129,20 @@ I (Spence Konde / Dr. Azzy) sell ATtiny1634 boards through my Tindie store - you
 If you have no need to use the WDT, but do have a need to use PB3 as an input, you can keep the WDT running by putting it into interrupt mode, with an empty interrupt, at the cost of just 10b of flash, an ISR that executes in 11 clock cycles every 8 seconds, and an extra 1-4uA of power consumption (negligible compared to what the chip consumes when not sleeping, and you'll turn it off while sleeping anyway - see below) - so the real impact of this issue is in fact very low, assuming you know about it and don't waste hours or days trying to figure out what is going on.
 
 ```c
-//put these lines in setup
-CCP=0xD8; //write key to configuration change protection register
-WDTCSR=(1<<WDP3)|(1<<WDP0)|(1<<WDIE); //enable WDT interrupt with longest prescale option (8 seconds)
-//put this empty WDT ISR outside of all functions
-EMPTY_INTERRUPT(WDT_vect) //empty ISR to work around bug with PB3. EMPTY_INTERRUPT uses 26 bytes less than ISR(WDT_vect){;}
+// put these lines in setup
+CCP = 0xD8; //write key to configuration change protection register
+WDTCSR = (1 << WDP3) | (1 << WDP0) | (1 << WDIE); //enable WDT interrupt with longest prescale option (8 seconds)
+// put this empty WDT ISR outside of all functions
+EMPTY_INTERRUPT(WDT_vect) // empty ISR to work around bug with PB3. EMPTY_INTERRUPT uses 26 bytes less than ISR(WDT_vect){;}
 ```
 If you are using sleep modes, you also need to turn the WDT off while sleeping (both because the interrupts would wake it, and because the WDT is consuming power, and presumably that's what you're trying to avoid by sleeping). Doing so as shown below only uses an extra 12-16 bytes if you call it from a single place, 20 if called from two places, and 2 bytes when you call it thereafter, compared to calling sleep_cpu() directly in those places, as you would on a part that didn't need this workaround.
 ```c
 void startSleep() { //call instead of sleep_cpu()
-  CCP=0xD8; //write key to configuration change protection register
-  WDTCSR=0; //disable WDT interrupt
+  CCP = 0xD8; //write key to configuration change protection register
+  WDTCSR = 0; //disable WDT interrupt
   sleep_cpu();
-  CCP=0xD8; //write key to configuration change protection register
-  WDTCSR=(1<<WDP3)|(1<<WDP0)|(1<<WDIE); //enable WDT interrupt
+  CCP = 0xD8; // write key to configuration change protection register
+  WDTCSR = (1 << WDP3) | (1 << WDP0) | (1 << WDIE); // enable WDT interrupt
 }
 ```
 

avr/extras/ATtiny_828.md

@@ -45,7 +45,7 @@ We do still provide a >4.5v clock option in order to improve behavior of the run
 
 The internal oscillator is factory calibrated to +/- 10% or +/- 2% for the slightly more expensive 828R. +/- 2% is good enough for serial communication. However, this spec is only valid below 4v - above 4v, the oscillator runs significantly faster; enough so that serial communication does not work absent the above-described countermeasures.
 
-### PWM frequency:
+### PWM frequency
 TC0 is always run in Fast PWM mode: We use TC0 for millis, and phase correct mode can't be used on the millis timer - you need to read the count to get micros, but that doesn't tell you the time in phase correct mode because you don't know if it's upcounting or downcounting in phase correct mode.
 
 | F_CPU  | F_PWM<sub>TC0</sub> | F_PWM<sub>TC1</sub>   | Notes                        |

avr/extras/ATtiny_x4.md

@@ -63,7 +63,7 @@ Example of a "guard" against wrong pin mapping:
 
 All pin mapping options assume that PB2 has the LED (bootloaders will blink that pin, and LED_BUILTIN is defined as PIN_PB2), unless it's a micronucleus configuration with D+ on PB2, in which case it will instead use PB0.
 
-### PWM frequency:
+### PWM frequency
 TC0 is always run in Fast PWM mode: We use TC0 for millis, and phase correct mode can't be used on the millis timer - you need to read the count to get micros, but that doesn't tell you the time in phase correct mode because you don't know if it's upcounting or downcounting in phase correct mode.
 
 | F_CPU  | F_PWM<sub>TC0</sub> | F_PWM<sub>TC1</sub>   | Notes                        |