From f31dda34ba7df68bb59eb69a5a368320188b8d90 Mon Sep 17 00:00:00 2001 From: Stephan Martin Date: Tue, 15 Aug 2023 10:07:13 +0200 Subject: [PATCH 1/3] Fixing spell check errors --- avr/cores/tiny/Arduino.h | 2 +- avr/extras/ATtiny_x5.md | 4 ++-- avr/extras/ATtiny_x7.md | 6 +++--- avr/extras/README.md | 4 ++-- avr/extras/Ref_ChangePWMFreq.md | 6 +++--- avr/extras/SpecificationConventions.md | 4 ++-- avr/extras/tinyNeoPixel.md | 10 +++++----- .../SoftwareSerialExample/SoftwareSerialExample.ino | 2 +- avr/libraries/Wire/Readme.md | 12 ++++++------ 9 files changed, 25 insertions(+), 25 deletions(-) diff --git a/avr/cores/tiny/Arduino.h b/avr/cores/tiny/Arduino.h index 4d7fd330..7f77284c 100644 --- a/avr/cores/tiny/Arduino.h +++ b/avr/cores/tiny/Arduino.h @@ -674,7 +674,7 @@ void loop() { #endif #endif -// Thcase where both SIGRD and RSIG is definded is unlikely to exist in the wild. +// Thcase where both SIGRD and RSIG is defined is unlikely to exist in the wild. /*--------------------------------------------------------------------------- * Aliases for the interrupt service routine vector numbers so the code diff --git a/avr/extras/ATtiny_x5.md b/avr/extras/ATtiny_x5.md index 448fb6a4..885fcca8 100644 --- a/avr/extras/ATtiny_x5.md +++ b/avr/extras/ATtiny_x5.md @@ -197,7 +197,7 @@ While assembled boards, even socketed ones, have not been reported as impacted, ### Despite having only 8 pins, there are 5 different packages used x5-family parts The manufacturer part numbers (ordering codes) indicate, in the final non-decimal characters, several properties of the part. -* If it ends in R, the part is being sold in tape and reel form, as opposed to tubes. This is not marked on the chip, ever. This is very important if you hope to feed it into your pick and place machine (some machines can deal with trays, some can even deal with SMT parts in tubes (utilizing vibration and a slight incline to nudge the parts down the tube and out, where it can pick them up), but some cannot, and all have constraints on these (either limited number of parts like that, or the physical impact of occupying a large amount of space that could be full of your boards with a tray of parts instead). If you do not have a pick and place machine, or are not planning to use it with these parts, the R just means that instead of a reusable tube, you will be removeing parts from non-reusable plastic tape. +* If it ends in R, the part is being sold in tape and reel form, as opposed to tubes. This is not marked on the chip, ever. This is very important if you hope to feed it into your pick and place machine (some machines can deal with trays, some can even deal with SMT parts in tubes (utilizing vibration and a slight incline to nudge the parts down the tube and out, where it can pick them up), but some cannot, and all have constraints on these (either limited number of parts like that, or the physical impact of occupying a large amount of space that could be full of your boards with a tray of parts instead). If you do not have a pick and place machine, or are not planning to use it with these parts, the R just means that instead of a reusable tube, you will be removing parts from non-reusable plastic tape. * After removing the R if present, what is left indicates three things: The package, the temperature range, and what treatment was applied to the pins. The termination treatment and temp range use the last letter (after removing the R): The Atmel lettering scheme may have a different letter to indicate NiPdAu and extended temperature ranges - these letters saw use throughout the non-automotive AVR parts (those used a different set of letters). As far as I can tell, the primary criteria for selecting the letters was to maximize the difficulty of clandestinly remarking the chips to convincingly appear to be a different (higher, of course) speed grade convincingly without grinding the markings off entirely like they do to tiny13's. Automotive parts used different letters, but they had the same properties w/regards to resistance to modification. You also couldn't change whether a chip was marked as an automotive temp grade without both erasing and adding lines. I think that in order to erase lines without their work being plainly obvious, they have no choice but to grind off the markings entirely and reinscribe, while it's plausible that someone could add lines quite easily. * U indicates -40 through 85 C operating range, and matte tin. * H indicates the same temperatures, but NiPdAu treatment (likely analogous to the PCB ENEPIG process) @@ -207,7 +207,7 @@ The manufacturer part numbers (ordering codes) indicate, in the final non-decima * P = PDIP-8 * S = Wide SOIC-8 - Was more common in the past, presumably when the same parts were made on older process technology and hence with a physically larger die. * SS = Narrow SOIC-8/SOP-8 - By far the most commonly seen today - * X = TSSOP-8 (not available for tiny85, only smaller parts - presumably for die size considerations - this package is actualy smaller than the QFN in one dimension, which was likely the determining factor of whether they could offer the t85 in that package - While surely it would be no problem now, few companies like to revisit old designs to add package variants, and Microchip is no exception. I know of [only one case](ATtiny_x7.md) where this happened for a classic AVR post Microchip acquisition. + * X = TSSOP-8 (not available for tiny85, only smaller parts - presumably for die size considerations - this package is actually smaller than the QFN in one dimension, which was likely the determining factor of whether they could offer the t85 in that package - While surely it would be no problem now, few companies like to revisit old designs to add package variants, and Microchip is no exception. I know of [only one case](ATtiny_x7.md) where this happened for a classic AVR post Microchip acquisition. * M = 4mm x 4mm QFN-20 0.5mm pitch. Only 8 of the contacts are electrically connected, the other 12 are just for decoration and to promote successful soldering via self-centering. If you ever, for some crazy reason, end up using these, and after-reflow inspection reveals visible solder bridge(s), only those that involve the 8 used pins must be corrected. ## Interrupt Vectors diff --git a/avr/extras/ATtiny_x7.md b/avr/extras/ATtiny_x7.md index 85685707..2cb57fef 100644 --- a/avr/extras/ATtiny_x7.md +++ b/avr/extras/ATtiny_x7.md @@ -184,11 +184,11 @@ I (Spence Konde / Dr. Azzy) sell ATtiny167 boards through my Tindie store - your The 87 and 167 are available in three package variations. Additionally, the 167 only can be had in a fourth package. * 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 belived 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 fromthe past, so I have to imagine 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. +* 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, so I have to imagine 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, aas 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. +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. Note: The shown addresses below are "byte addressed" as that has proven more readily recognizable. The vector number is the number you are shown in the event of a duplicate vector error, as well as the interrupt priority (lower number = higher priority), if, for example, several interrupt flags are set while interrupts are disabled, the lowest numbered one would run first. Notice that INT0 is (as always) the highest priority interrupt. diff --git a/avr/extras/README.md b/avr/extras/README.md index 33b376d1..941c74b7 100644 --- a/avr/extras/README.md +++ b/avr/extras/README.md @@ -232,9 +232,9 @@ There are several ways to refer to pins. 2. **Recommended: MISO, MOSI, SCK, SS, SCL, SDA** - Regardless of whether your device uses a USI, has hardware SPI, even hardware I2C, these defines are provided with the appropriate pins (though SS is the only one you need to know, since you need to keep it output) 3. **Deprecated: Numeric pin numbers** - these put a pin-mapping dependency on your code. ### Assembler Listing generation -Sketch -> Export compiled binary will generate an assembly listing in the sketch folder; this is particularly useful when attempting to reduce flash usage, as you can see how much flash is used by different functions. The file is named with abbreviations for all options selected from a tools menu, so you can export, change a tools submenu, export again, and then find two sets of listings waiting for you (if it's not added as an abbreviation, it does not change the binary output - or it shouldnt). +Sketch -> Export compiled binary will generate an assembly listing in the sketch folder; this is particularly useful when attempting to reduce flash usage, as you can see how much flash is used by different functions. The file is named with abbreviations for all options selected from a tools menu, so you can export, change a tools submenu, export again, and then find two sets of listings waiting for you (if it's not added as an abbreviation, it does not change the binary output - or it shouldn't). -You should also have two .map files - these are memory maps. They are fucking ugly to read, and it's very difficult to get them into excell, for example, when it really shouldn't be. That is because the format that the linker uses is so evil that it is surely the work of the devil or a minion of his (All of the formats it uses suck. The one I use sucks the worst, but it also is the one that displays the most complete information. I've been working on python scripts to clean them up to be more readable. It's over in [AVR Research: Maps and Listings](https://github.com/SpenceKonde/AVR_Research/MapsAndListings) +You should also have two .map files - these are memory maps. They are fucking ugly to read, and it's very difficult to get them into excel, for example, when it really shouldn't be. That is because the format that the linker uses is so evil that it is surely the work of the devil or a minion of his (All of the formats it uses suck. The one I use sucks the worst, but it also is the one that displays the most complete information. I've been working on python scripts to clean them up to be more readable. It's over in [AVR Research: Maps and Listings](https://github.com/SpenceKonde/AVR_Research/MapsAndListings) ### Link-time Optimization (LTO) support As of 2.0.0, we no longer support use without Link Time Optimization. It is required for some of the tricks I use to ensure that useful compile errors appear instead of mysterious broken behavior at runtime when we know at compile time that it won't work, and link time optimization is a stunning reduction in sketch size as well. diff --git a/avr/extras/Ref_ChangePWMFreq.md b/avr/extras/Ref_ChangePWMFreq.md index c8289782..9a374a3b 100644 --- a/avr/extras/Ref_ChangePWMFreq.md +++ b/avr/extras/Ref_ChangePWMFreq.md @@ -25,8 +25,8 @@ In a timer counter unit, when we're talking about PWM, we're talking about the s * Periodic interrupts with CTC (Clear Timer on Compare match) * Arbitrary TOP values, sometimes without the loss of an output * Higher resolution on Timer1 and Timer2 (where present) - those are both mostly standard 16-bit timers. - * Asynchronous low speed opperation from an external clock or watch crystal (x7, possibly a small number of others) - * Asynchronous high speed operration from a x8 PLL on the 8 MHz internal osc. (x5, x61 26 only) + * 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) ### What can I change without breaking analogWrite() or other core API functions? * TC0 cannot be reconfigured at all without breaking millis, and should only be used if millis is disabled from the tools submenu. @@ -47,7 +47,7 @@ tccr1b |= 0b00000001; // set the one low bit(s) we want - this sets the timer t TCCR1B = tccr1b; ``` -You can also change the Waveform Generation Mode (WGM)) - on a normal 16-bit timer this is 2 bits each in TCCR1A (0bxxxxxx10) and TCCR1B (0xbxxx43xxx) to another 8-bit mode (including the frequency and phase correct PWM option where TOP is specified by ICR1, if and only if ICR1 is set to exactly 255. You should probably at a minimum disable interrupts, and stop the timer, write TCCR1A, then TCCR1B, then reenable interrupts. . Depending on the application, you may also want to zero out TCNT1. +You can also change the Waveform Generation Mode (WGM)) - on a normal 16-bit timer this is 2 bits each in TCCR1A (0bxxxxxx10) and TCCR1B (0xbxxx43xxx) to another 8-bit mode (including the frequency and phase correct PWM option where TOP is specified by ICR1, if and only if ICR1 is set to exactly 255. You should probably at a minimum disable interrupts, and stop the timer, write TCCR1A, then TCCR1B, then re-enable interrupts. . Depending on the application, you may also want to zero out TCNT1. Consult the datasheet for the list of WGMs that your timer supports and the values corresponding to them. diff --git a/avr/extras/SpecificationConventions.md b/avr/extras/SpecificationConventions.md index 7e2c467e..f732f40f 100644 --- a/avr/extras/SpecificationConventions.md +++ b/avr/extras/SpecificationConventions.md @@ -39,10 +39,10 @@ External Clock | All Standard | All Standard | **16**,8,4,2,1 | All This core, being designed to handle almost every configuration, has a large number of tools submenus ### Tools -> Board -This control two things: Which microcontroller or family will be used (a "family" or "series" is 2 or more microcontrollers that differ only in memory sizes), and what bootloader, if any, will used to bootload and be assumed assumed when uploading. Possibilities here are no bootloader, "Optiboot", or "Micronucleus" "Urboot" may be added, in which case Optiboot would become deprecated, as it has one very serious bug. Parts with at least 4k of flash and which are available in a version with at least 8k of flash have an Optiboot bootloader available. Micronucleus bootloaders are provided for boards with atleast 8k of flash, with the exception of the 828 which is such a sorry piece of hardware it is not worth the time to make it wiork. If you do not know if a chip has been bootloaded, or know that it hasn't, you should select the definition with the bootloader you *want*, select the options you want, and connect an ISP programmer, and choose Tools -> Burn Bootloader. +This control two things: Which microcontroller or family will be used (a "family" or "series" is 2 or more microcontrollers that differ only in memory sizes), and what bootloader, if any, will used to bootload and be assumed assumed when uploading. Possibilities here are no bootloader, "Optiboot", or "Micronucleus" "Urboot" may be added, in which case Optiboot would become deprecated, as it has one very serious bug. Parts with at least 4k of flash and which are available in a version with at least 8k of flash have an Optiboot bootloader available. Micronucleus bootloaders are provided for boards with at least 8k of flash, with the exception of the 828 which is such a sorry piece of hardware it is not worth the time to make it wiork. If you do not know if a chip has been bootloaded, or know that it hasn't, you should select the definition with the bootloader you *want*, select the options you want, and connect an ISP programmer, and choose Tools -> Burn Bootloader. ### Tools -> Chip 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 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 expence 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 is ot needed, enable should be tied high, low, or allowed to float depeding on the device, refer to the datasheet). The other two opposite corners are Vdd and Gnd. It is imperitve that these never be powered baclwardsl they will burn out aslmost instantly. 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, 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. It is imperitve that these never be powered baclwardsl they will burn out aslmost instantly. 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". diff --git a/avr/extras/tinyNeoPixel.md b/avr/extras/tinyNeoPixel.md index 06533724..1dbf7114 100644 --- a/avr/extras/tinyNeoPixel.md +++ b/avr/extras/tinyNeoPixel.md @@ -174,7 +174,7 @@ Clones that are WS2811-like (that is, it is a standard IC which must be connecte These clones sometimes vary in thresholds of their timing (I have, for example, seen cases where a controller would only drive one of the two types, particularly if the oscillator is not exactly on the frequency target. I have never seen one that couldn't use the output of other "2812-alikes"). They also sometimes vary in the maximum voltage that can be seen at their outputs (12V units like the 2811 can be used to drive 3 LEDs of each color in series, at a lower current). However, with the exception of the SK6812/6805 and WS281x (as well as the APA102 and it's clones), none have achieved significant name recognition in the western world. I'm sure we're buying plenty of them - but not under their real names/part numbers. The WS2812 and SK6812 names are used almost interchangibly when finished devices are sold - regardless of which one is used (be it SK68xx, WS2812B, or some randome no-name clone). -One thing that is worh noting is that although competent people, over time, have debated whether SK6812 or WS2812B's (the B is rarely seen in marketing material now, and I don't think non-B WS2812's are made anymore) are better, there has been no consensus. The non-B's were clearly inferior, being failure prone and requiring additional connections, and the WS2813 and WS2815 are clearly superior, with the addiional backup data line and (on the '15s) 12v operation - but cost significantly more. While WorldSemi deserves some credit for originality, having been the first to make such a device, and have addressed the "old school christmas light problem" where one light goes out and the whole string after it does with the WS2813/15, the SK6812's have a much greater variety of LEDs available: They now come in in RGBW and RGBWW (warm white) 4-color versions, a WWA (Cool White, Warm White, Amber) version, and have been shrunken down to package sizes as small as 1.5mm square, and are available in side facing packages. Note that these are guesses based on the catalogs of vendors who openly sell both SK6812's and WS2812's in the same listing, which makes it unlikely that they'd be lying about the model of the IC. +One thing that is worh noting is that although competent people, over time, have debated whether SK6812 or WS2812B's (the B is rarely seen in marketing material now, and I don't think non-B WS2812's are made anymore) are better, there has been no consensus. The non-B's were clearly inferior, being failure prone and requiring additional connections, and the WS2813 and WS2815 are clearly superior, with the additional backup data line and (on the '15s) 12v operation - but cost significantly more. While WorldSemi deserves some credit for originality, having been the first to make such a device, and have addressed the "old school christmas light problem" where one light goes out and the whole string after it does with the WS2813/15, the SK6812's have a much greater variety of LEDs available: They now come in in RGBW and RGBWW (warm white) 4-color versions, a WWA (Cool White, Warm White, Amber) version, and have been shrunken down to package sizes as small as 1.5mm square, and are available in side facing packages. Note that these are guesses based on the catalogs of vendors who openly sell both SK6812's and WS2812's in the same listing, which makes it unlikely that they'd be lying about the model of the IC. I think the only way one could *really* find out would be to depot them and examine the die under a microscope, and even that isn't foolproof, because in the time that they've existed, there have most certainly been die-shrinks. In any event, mostly sold as SK6812's, they are available in nearly every plausible component package: 5050, 3535, at least two drastically different packages both called 2020 by the merchant selling them, 1515 (that's 1.5mm on a side), 2427 (these I am told are what are under the surface of COB led strip), 3216 (in english units, 1206 - the same size as the resistors), and more. In the other direction, there are 3mm and 5mm through-hole diffused ones (though they are less common - those strings of "christmas light" style lights are almost universally made with a little circuit board with a WS2811 or clone thereof and a standard 8mm RGB led, as opposed to an 8mm addressable through-hole LED. There are even a few PCBs that pair a WS2811 and a trio of beefy MOSFET drivers designed to drive *MONSTER* leds, in the 10-50 watt range. The intended use case remains unclear to me - and even at Direct-from-China prices, the costs would add up quickly. Plus LEDs of that size would need considerable heatsinks... @@ -192,7 +192,7 @@ There are a very small number of *significant* differences between the 2812-alik * A string of non-5050 size LEDs, but where the inputs are marked with abbreviations including "D" and "B" suggests a WS2813/WS2815-like scheme. ### No, we do not support APA 102's nor will we ever -The reason that this library exists is that a classic AVR WS2812-driver library (since the timing is critical and not all that many times the clock speed) will typically have the code that actually sends out the data written in assembly. That requires a separate implementation for each clock speed, and (in the original version) for every possible port. To reduce the size of the resulting code, only the most common ports were supported by adafruitNeoPixel; but within the heterogenous population that is the classic AVRs, that meant that only some pins worked on some of the parts. Particularly before we introduced the PIN_Pxn-notation to refer to pins, it caused great confusion. +The reason that this library exists is that a classic AVR WS2812-driver library (since the timing is critical and not all that many times the clock speed) will typically have the code that actually sends out the data written in assembly. That requires a separate implementation for each clock speed, and (in the original version) for every possible port. To reduce the size of the resulting code, only the most common ports were supported by adafruitNeoPixel; but within the heterogeneous population that is the classic AVRs, that meant that only some pins worked on some of the parts. Particularly before we introduced the PIN_Pxn-notation to refer to pins, it caused great confusion. Additionally, the adafruitNeoPixel library allows for changing the size of the LEDs at runtime. That sounds great, except that implementing that requires using malloc(). The problem with malloc() and free() (which it inevitably brings in) is that these take take 1k or so of flash, which the tinyAVRs can ill-afford. This has another more subtle problem too: When you 'verify' the sketch, you are told the amount of flash and RAM the sketch uses **but this does not include dynamically allocated RAM**. This can be the majority of the RAM usage on a LED controller. I have had people show me code which tried to control 250 LEDs on a tinyAVR with 512b of SRAM. Since the buffer to fit the pixel data would take 750 bytes, there was no hope of that working. But as far as the user could tell, there was tons of RAM available, because that almost-150%-of-total-RAM was not counted. @@ -214,7 +214,7 @@ The arrows for some speeds indicate that the higher speed pointed to is used ins Modern tinyAVRs are commonly run at 4, 5, 8, 10, 16 and 20 MHz (8 and up is supported), and can be overclocked through tuning as high as 30 MHz (0/1-series, some specimens only - others can only reach 24 or 25). The 2-series can reach speeds as high as 32 MHz (most specimens, but not all) again, just by tuning. Running at 5V, with a very solid power supply and an external **clock** will enable some (but not all) 0/1-series specimens to run at 32 as well. There's no analogy for that on the 2-series, since the internal oscillator there generally works at 32, and the next convenient frequency is 40 MHz, which a tinyAVR 2-series isn't going to hit even with an external clock. The modern tinyAVR series does not support using a crystal, relying upon a much better internal oscillator instead/ -The AVR Dx-series can be run at 4, 8, 10 (20/2), 12, 16, 20, or 24 MHz while remaining in spec, and the internal oscillator has "secret" 28 and 32 MHz settings. Additionally, with the exception of the DD, they support an external crystal. 40 MHz works on most specimens, and on some E-spec parts, even 48 MHz works! While the assembly starts to get a little silly at the high end of these speeds (a great deal of time is spent in space-optimized "no-op" instructions), even in the absence of other tricks for outputting WS2812 data (we belive a background method is possible by abusing the SPI and CCL subsystems) raising the clock speed allows allows longer LED strings or faster frame rates by making it possible to calculate more pixel colors between sending the buffer. +The AVR Dx-series can be run at 4, 8, 10 (20/2), 12, 16, 20, or 24 MHz while remaining in spec, and the internal oscillator has "secret" 28 and 32 MHz settings. Additionally, with the exception of the DD, they support an external crystal. 40 MHz works on most specimens, and on some E-spec parts, even 48 MHz works! While the assembly starts to get a little silly at the high end of these speeds (a great deal of time is spent in space-optimized "no-op" instructions), even in the absence of other tricks for outputting WS2812 data (we believe a background method is possible by abusing the SPI and CCL subsystems) raising the clock speed allows allows longer LED strings or faster frame rates by making it possible to calculate more pixel colors between sending the buffer. ### Common types of Light Strip This section lists the types of light strip that I have seen marketed. They @@ -245,7 +245,7 @@ Pre-populated PCBs full of addressable LEDs are readily available. They are comm Name in quotes because I don't think this is an official name; I don't know that they have one, but I have to call them something. These are the only type that is essentially always based on the WS2811: Each module has a single large RGB LED with the fogged plastic for light diffusion, connected to the '2811 driver IC (this is in spite of the existence of LEDs of the same size with 2812-alike controllers inside - I guess it's cheaper to do it this way, and the folks going . Each of those LED assemblies, with 6 wires from one the end opposite the LED, then has plastic surrounding it (it looks to me like they got pushed into a housing that fit tightly around the bulb and epoxy was then poured in). You should inject power at the start (or end) of each string of 50. You should use the additional power wires they provide for this; JST-SM connectors like they use can **barely** handle 3A (the maximum current from 50 LEDs), and you never want to push something right to it's limit. So should have power coming into one or both of the pairs of power wires on every section. #### "Cursed" String Lights - mystery has been solved -I was recently made aware of (as in was wondering what the heck was wrong with my lights) a type of light string which to all outward appearances, looks almost identical to normal string lights. Side-by-side, tiny differences like the exact tint of the potting compound may be visible. However, even though the data rate coming out is correct, many LEDs will not work when down-stream from them. It is nearly impossible to confirm this behavior without a 'scope - but on the 'scope it was very clear that something was up: the signal was only going up to like 3.somethign volts! These apparently use a different controller which also comes in a SOIC8 package... but this one outputs 3V logic levels? I didn't think it makes much sense either... +I was recently made aware of (as in was wondering what the heck was wrong with my lights) a type of light string which to all outward appearances, looks almost identical to normal string lights. Side-by-side, tiny differences like the exact tint of the potting compound may be visible. However, even though the data rate coming out is correct, many LEDs will not work when down-stream from them. It is nearly impossible to confirm this behavior without a 'scope - but on the 'scope it was very clear that something was up: the signal was only going up to like 3.something volts! These apparently use a different controller which also comes in a SOIC8 package... but this one outputs 3V logic levels? I didn't think it makes much sense either... Several weeks later, I was checking light strips and came upon them again - only this time the LED that was in my hand happened to have a smoother surface to the epoxy-filled case near the bottom, so I cold read the silkscreen inside. Gnd. Dat. **12v**. This was twelve volt LED string! Likely the logic voltage was going through an internal regulator. If it was expecting 7 volts of headroom, they wouldn't think twice about using cheaper regulator technology, resulting in 7805-like minimum dropouts, which from 5v would yield right around 3.3v. So these are not actually cursed, but are likely better. The only thing that gives me pause is that the brightness wasn't obviously "way too dim". There are no inductors inside for buck or boost conversion, implying *linear voltage regulation*, so they'd be dissipating considerably more power as heat. #### Diffused "String Lights" @@ -287,7 +287,7 @@ In addition to following all the usual safety guidelines, pay particular attenti * PVC wire is almost universally afflicted with this. It is rare to purchase PVC wire from chinese suppliersand get what was advertised; I have found in the wild that the wire is typically 4 AWG thinner, but it may be as little as 1 AWG undersized to as much as 8. This does not apply western wire makers who subcontract manufacture to China - they weren't born yesterday, and are keenly aware of this trick, and keep their manufacturing partners in line. I try to avoid PVC insulated wire from China entirely. * This is particularly troublesome when you were planning to crimp on connectors, as the insulation thickness no longer matches what the crimper and terminals expect. You can think "Okay, I need 24 AWG wire, so I'll order 20 AWG wire" to maximize your chance of getting 24 AWG wire". But to conceal their fraud, they made the insulation as thick as it would be on to 20 AWG wire: Your terminals won't fit over it! * You know those "christmas light" style WS2811 strings? You know how you need to inject power stupidly often? The wire says 20 AWG on the side, so you really shouldn't need to inject power that often... So is it really 20 AWG? I counted 19 wires, measured each strand as 0.08mm, so it's 19/0.08, or in AWG... around 27 AWG. *No wonder we have to feed power in every 50 LEDs!* That wire is the second least honestly spec'ed wire I have encountered, being beaten by less than 1 AWG by a particularly horrible batch of prewired JST-SM connectors (the ones I mentioned above where red wire was cooked black) - * FEP (Flourinated ethylene-propylene, a copolymer of perflouroethylene and perflouropropylene) is a much tougher, stronger, more heat resistant material used as insulation. It is considerably harder to manufacture, but can be made thinner while having superior mechanical properties. Like PVC, however, it can still be removed with thermal wire strippers, and is not terribly hard to remove with hand strippers wither. It is, unsurprisingly, more expensive. What **is** surprising is that it doesn't seem to have the undersizing problem that PVC insulated wire does. I don't know if this is just because it's harder to make and that keeps the riff-raff out of the market, or if they consider people who would buy FEP wire to be more likely to notice their bogus wire, or what the full reason is, but I've never had PVC-insulated wire arrive from China that wasn't at least 1 AWG undersized, while no FEP insulated wire has been undersized by even 1 AWG. The thinner insulation ensures that crimp connnectors will fit over the wire, even when you're pushing the upper limits of the size of wire that can fit a given type of terminal. This wire is often mis-sold as PTFE (teflon) insulated wire. Luckily they are lying about this: you don't want *actual* PTFE insulated wire. That stuff is tough as nails. It laughs at a normal thermal wire stripper, and is very challenging to strip with hand strippers as well. Stripping it easily needs a *fancy* thermal-wirestripper (and my chemical background struggles to come up with potential compounds which might make up odd-smelling fumes which wouldn't be noxious). Thankfully, little if any of the "PTFE" wire you would get buying from China is PTFE - it's all FEP. + * FEP (Flourinated ethylene-propylene, a copolymer of perflouroethylene and perflouropropylene) is a much tougher, stronger, more heat resistant material used as insulation. It is considerably harder to manufacture, but can be made thinner while having superior mechanical properties. Like PVC, however, it can still be removed with thermal wire strippers, and is not terribly hard to remove with hand strippers either. It is, unsurprisingly, more expensive. What **is** surprising is that it doesn't seem to have the undersizing problem that PVC insulated wire does. I don't know if this is just because it's harder to make and that keeps the riff-raff out of the market, or if they consider people who would buy FEP wire to be more likely to notice their bogus wire, or what the full reason is, but I've never had PVC-insulated wire arrive from China that wasn't at least 1 AWG undersized, while no FEP insulated wire has been undersized by even 1 AWG. The thinner insulation ensures that crimp connnectors will fit over the wire, even when you're pushing the upper limits of the size of wire that can fit a given type of terminal. This wire is often mis-sold as PTFE (teflon) insulated wire. Luckily they are lying about this: you don't want *actual* PTFE insulated wire. That stuff is tough as nails. It laughs at a normal thermal wire stripper, and is very challenging to strip with hand strippers as well. Stripping it easily needs a *fancy* thermal-wirestripper (and my chemical background struggles to come up with potential compounds which might make up odd-smelling fumes which wouldn't be noxious). Thankfully, little if any of the "PTFE" wire you would get buying from China is PTFE - it's all FEP. * Always pull-test a few samples from a batch of prewired connectors (most commercial dupont line fails the pull test, and even some JST-SM prewired connector fails. Hopefully if you crimp your own, you're already pull testing them). * When using pre-wired connectors, use a pin extractor to pull out a male and female pin from a given batch and compare them to a pin on the "same" connectors you already have. Proceed only with great caution and testing if you discover that the existing connectors and the ones you just got do not look identical - some terminals are made in several versions with different mating force or for different wire gauges. These both matter, but are generally designed to be compatible. On the other hand there are horror stories of incompatible male and female pins from different suppliers that would fail over time when used together, or male pins that were ever so slightly too large and would damage female terminals from other manufacturers - both could result in a poor (high resistance) connection which might get hot without causing visible symptoms until you start a fire, or notice that the wires have been discolored from heat.. * Make sure that any power supply you use will turn itself off in the event of overcurrent, instead of changing to constant current mode. Folding back to constant current mode is great for a benchtop supply in your workshop, but in the field, all it does is waste power while generating a bunch of heat wherever the fault is, until either someone notices, something burns out, or it starts a fire. diff --git a/avr/libraries/SoftwareSerial/examples/SoftwareSerialExample/SoftwareSerialExample.ino b/avr/libraries/SoftwareSerial/examples/SoftwareSerialExample/SoftwareSerialExample.ino index b61fb103..eade4bb1 100644 --- a/avr/libraries/SoftwareSerial/examples/SoftwareSerialExample/SoftwareSerialExample.ino +++ b/avr/libraries/SoftwareSerial/examples/SoftwareSerialExample/SoftwareSerialExample.ino @@ -51,7 +51,7 @@ void setup() { // Open serial communications on either the "fake" hardware serial port // which is actually another implementation of software serial (if there - // is no harware serial) or the actual hardware serial port (if any) + // is no hardware serial) or the actual hardware serial port (if any) Serial.begin(9600); Serial.println("Goodnight moon!"); diff --git a/avr/libraries/Wire/Readme.md b/avr/libraries/Wire/Readme.md index 239d52b8..82b9bbad 100644 --- a/avr/libraries/Wire/Readme.md +++ b/avr/libraries/Wire/Readme.md @@ -1,5 +1,5 @@ # UniversalWire library -Should provide a mediocre rendition ofthe standard API for most use cases. There is a reason it's not better than this, and it's not exclusively a list of my deficiencies. +Should provide a mediocre rendition of the standard API for most use cases. There is a reason it's not better than this, and it's not exclusively a list of my deficiencies. ## Background: Heterogeneous hardware The root of most problems with the Universal Wire library is that there are a total of 6 implementations in here - USI master, USI slave, Real TWI master (direct copy from Uno library, I think), Real TWI slave (definitely direct copy from uno version), and for two unfortunate parts, Software I2C master only - though they have slave only hardware implementations too. @@ -11,7 +11,7 @@ Only on the Tiny88. Here, as long as you're able to fit in overall resource limi ### Useless Serial Interface (USI) Some resources refer to this as "Universal". Others refer to it as what you get if you strip out every feature and nicety that we expect from hardware SPI or hardware TWI, and instead of branding it as "crippled SPI/TWI" which doesn't have much of a ring to it, they called it a universal serial interface. It also happens to do very little for you. Essentially, what you get is an 8-bit SPI-like shift register, that is triggered, by USCK/scl, a way to see when 8 bits have been clocked through it, and a data register that that gets copied to at that time. You do get a start condition detector that works to wake from all sleep cycles at least. -You may have noticed that I didn't mention clock generation. That's cause there is none. You have to stobe the pin from software or monopolize a timer to generate a clock, and you cant use timer0 cause that's millis, and if you use timer1, you have only 1 PWM pin left. Hence we do software strobing on the master side, +You may have noticed that I didn't mention clock generation. That's cause there is none. You have to stobe the pin from software or monopolize a timer to generate a clock, and you can't use timer0 cause that's millis, and if you use timer1, you have only 1 PWM pin left. Hence we do software strobing on the master side, We are also not allowed to use the internal pullups: To quote the datasheet: @@ -19,7 +19,7 @@ To quote the datasheet: (emphasis mine) -Now, the internal pullups are NEVER strong enough for reliable opperation except under the most favorable conditions, but those conditions are common enough that people will be dissappointed to find that configurations that worked without external pullups require them here. They should not be upset at that, they should be upset with the stock API which hid the critical defect (lack of external pullups) from them. The pullups should be like 4.7-10k at 5V normal speed, and lower values (stronger pullups) at 3.3v and/or higher clock speeds. +Now, the internal pullups are NEVER strong enough for reliable operation except under the most favorable conditions, but those conditions are common enough that people will be disappointed to find that configurations that worked without external pullups require them here. They should not be upset at that, they should be upset with the stock API which hid the critical defect (lack of external pullups) from them. The pullups should be like 4.7-10k at 5V normal speed, and lower values (stronger pullups) at 3.3v and/or higher clock speeds. ### Slave Only TWI The exiting quartet - 841, 441, 1634 and 828 have a slave only TWI. The 1634 also has a USI, though. So that uses USI TWI master and HW slave TWI as slave. @@ -28,7 +28,7 @@ So 3 of those have only HW slave TWI. Most people consider TWI master to be non- So on these devices, we have the worst I2C master of all: Software I2C. Not only is there no clock generation, since there's no dedicated hardware, bits are clocked out through the Wire.EndTransaction and Wire.request() purely by software manipulation of pins, and we also can't guarantee that it will read correctly in the absence of sufficient setup and hold time. It does not deal very well with clock stretching, and bus errors are not well reported. -It might be possible to achive modest improvements on the master behavior in these cases, but I do not expect to be able to work on that. +It might be possible to achieve modest improvements on the master behavior in these cases, but I do not expect to be able to work on that. On the 828, due to an erratum that will never get corrected, you must have the WDT running (interrupt mode with the interrupt being declared as an empty ISR is recommended). If the WDT oscillator is not running one of the TWI lines will be continually pulled low, rendering the bus unusable. @@ -37,7 +37,7 @@ All 6 of these implementations do the best they can to provide the same API. The Caveats: * On 841, 441, and 828, errors are not always properly recognized. -* On 828, the ULP (hence WDT) must be on if slave mode is used, otherwise one of the I2C pins is pulled low with greater strength thatn the pullups can counteract. +* On 828, the ULP (hence WDT) must be on if slave mode is used, otherwise one of the I2C pins is pulled low with greater strength that the pullups can counteract. * Wire.setClock() has no effect on 841, 441, and 828. * 828 Wire Master pins are different from normal to get away from the bugged pin. @@ -83,4 +83,4 @@ For a read, the master would first perform the first 4 steps above setting the l ### Yeah, they don't line up so good. It's like the API designer read the protocol spec and designed to that and had never actually used an I2C device. You cannot have a register-model, because you don't know how many bytes the master will read (the protocol never tells you this), nor can you find out how many are read after the fact, nor can you put the slave to sleep because it might be silently servicing an interrupt for a read that hasn't finished yet. This will generally make you "that device" that when misused, becomes non-responsive with one or both being held low. You don't want to be that device. -The API has been extended for DxCore and mTC, as the problem was far more tractable there (not only is it a single implementation covering a much more cooperative peripheral, the same library works unmodified and likely will continue to do so for the forseeable future. +The API has been extended for DxCore and mTC, as the problem was far more tractable there (not only is it a single implementation covering a much more cooperative peripheral, the same library works unmodified and likely will continue to do so for the foreseeable future. From d0412e666d5a6218efa93b09530745005e79d7f3 Mon Sep 17 00:00:00 2001 From: Stephan Martin Date: Tue, 15 Aug 2023 11:08:50 +0200 Subject: [PATCH 2/3] Fix blank-first-line and trailing blanks --- avr/extras/README.md | 8 ++++---- avr/extras/development/_Removed_from_wiring.c | 1 - 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/avr/extras/README.md b/avr/extras/README.md index 941c74b7..7863aafe 100644 --- a/avr/extras/README.md +++ b/avr/extras/README.md @@ -226,13 +226,13 @@ In version 1.3.3 and later, the clock source is also made available via the CLOC ### How to refer to pins -There are several ways to refer to pins. +There are several ways to refer to pins. 1. **Recommended: `PIN_PA0` - PIN_Pxn notation** - the Pxn constants are defined in the headers a. For all Pxn that corresponds to a pin, the headers define as n, eg, #define PA0 0, #define PA1 1 ... #define PB7 7). As it is unprecedented and generally agreed to be a mortal sin, we do not undefine anything that the Microchip IO headers supply - that road leads to hell (or at least, to users thinking they're in hell) - and that in turn is why there are so many programmers down there. We add to them (when they change the spelling of things, which they've been doing lately to newer parts, we add compatibility #defines with the name of the old constant), but we don't take away. -2. **Recommended: MISO, MOSI, SCK, SS, SCL, SDA** - Regardless of whether your device uses a USI, has hardware SPI, even hardware I2C, these defines are provided with the appropriate pins (though SS is the only one you need to know, since you need to keep it output) -3. **Deprecated: Numeric pin numbers** - these put a pin-mapping dependency on your code. +2. **Recommended: MISO, MOSI, SCK, SS, SCL, SDA** - Regardless of whether your device uses a USI, has hardware SPI, even hardware I2C, these defines are provided with the appropriate pins (though SS is the only one you need to know, since you need to keep it output) +3. **Deprecated: Numeric pin numbers** - these put a pin-mapping dependency on your code. ### Assembler Listing generation -Sketch -> Export compiled binary will generate an assembly listing in the sketch folder; this is particularly useful when attempting to reduce flash usage, as you can see how much flash is used by different functions. The file is named with abbreviations for all options selected from a tools menu, so you can export, change a tools submenu, export again, and then find two sets of listings waiting for you (if it's not added as an abbreviation, it does not change the binary output - or it shouldn't). +Sketch -> Export compiled binary will generate an assembly listing in the sketch folder; this is particularly useful when attempting to reduce flash usage, as you can see how much flash is used by different functions. The file is named with abbreviations for all options selected from a tools menu, so you can export, change a tools submenu, export again, and then find two sets of listings waiting for you (if it's not added as an abbreviation, it does not change the binary output - or it shouldn't). You should also have two .map files - these are memory maps. They are fucking ugly to read, and it's very difficult to get them into excel, for example, when it really shouldn't be. That is because the format that the linker uses is so evil that it is surely the work of the devil or a minion of his (All of the formats it uses suck. The one I use sucks the worst, but it also is the one that displays the most complete information. I've been working on python scripts to clean them up to be more readable. It's over in [AVR Research: Maps and Listings](https://github.com/SpenceKonde/AVR_Research/MapsAndListings) diff --git a/avr/extras/development/_Removed_from_wiring.c b/avr/extras/development/_Removed_from_wiring.c index 7685b048..d5b33757 100644 --- a/avr/extras/development/_Removed_from_wiring.c +++ b/avr/extras/development/_Removed_from_wiring.c @@ -1,4 +1,3 @@ - /* Delay for the given number of microseconds. Assumes a 1, 8, 12, 16, 20 or 24 MHz clock. */ //Not used anymore, we have the version we stole from nerdralph's picocore! From ddebb4ad39db78ca4dba4c3a387235a12f8a226a Mon Sep 17 00:00:00 2001 From: Stephan Martin Date: Tue, 15 Aug 2023 11:11:55 +0200 Subject: [PATCH 3/3] missed this blank_first_line --- avr/extras/development/removed_from_wiring.c | 1 - 1 file changed, 1 deletion(-) diff --git a/avr/extras/development/removed_from_wiring.c b/avr/extras/development/removed_from_wiring.c index 7685b048..d5b33757 100644 --- a/avr/extras/development/removed_from_wiring.c +++ b/avr/extras/development/removed_from_wiring.c @@ -1,4 +1,3 @@ - /* Delay for the given number of microseconds. Assumes a 1, 8, 12, 16, 20 or 24 MHz clock. */ //Not used anymore, we have the version we stole from nerdralph's picocore!