Correction Request: Inconsistent usage of terms in AN2867 (Oscillator Design Guidelines)

[BarryWhit]

It is vital to use language and terms with great care and  precision in technical writing. Whenever you don't, you create confusion.

Newcomers often make the mistake of conflating the terms "crystal", and "oscillator". For example, see @Andrew_Neil   's multiple comments on this thread, where he does his utmost to banish this common error.

Quite recently, I made the same mistake when asking for help finding a low-power clock source.

We can forgive newcomers and ourselves our trespasses (I personally have, grudgingly), but shouldn't we expect more from official ST documentation?

AN2867: Guidelines for oscillator design on STM8AF/AL/S and STM32 MCUs/MPUs

mixes and shifts between related terms multiple times in its 59 pages. The resulting confusion is enormous. Instead of working to remove confusion, ST's documentation contributes to it:

==

==

==

==

==

which is followed immediately by

==

Dear ST,  please flag this AN for review and urge the documentation team to be absolute tyrants about correct usage.

[Andrew Neil]

Another recent one here:

https://community.st.com/t5/stm32-mcus-products/external-oscillator-issue-stm-not-booting/m-p/691287/highlight/true#M253674

[BarryWhit]

From [EPSON] Crystal Fundamentals & State of the Industry :

If ST writers lack a catch-all term, perhaps "Frequency Source" would do, instead of randomly selecting one of the three (crystal, oscillator, resonator) on each occasion. Including a glossary placed at the start of the appnote would enhance clarity as well.

[STOne-32]

Dear @BarryWhit @Andrew Neil ,

Thank you for the feedback. I concur your message and Will be taken into account in our next Release . Indeed nowadays “resonators” are rarely used IMHO as most of modern MCUs have very nice RC / HSI / MSI precision low cost internal oscillators , this was not the case 20 years ago where they are very famous and especially from Murata. As we work with many crystal partners we have close contact with all of them and major breakthrough the last decade was : Ultra low power and very small PCB footprint to reach 1016 and even lower size while keeping very high precision including Wireless communications and asynchronous clocking : Ethernet, USB etc.

well received for the AN2867 ! 

Cheers,

STOne-32

[BarryWhit]

So... no internal ticket for this?

This term confusion is an engineering epidemic. ST should make an effort to stop this confusion by explicitly calling this common error out in documentation, and should also avoid making it themselves in their literature.

From SE:

[STOne-32]

Dear @BarryWhit ,

>>So... no internal ticket for this? >>

The door is already open ;-).  let's close it with AN2867 Update on next release and may be also a Knowledge Article on the topic that covers crystals, oscillators.  For follow-up the internal number is #185375.

Wish you a great sunday.

Ciao

STOne-32.

[BarryWhit]

Thank you, @STOne-32 . Fingers crossed.

[Andrew Neil]

---

@BarryWhit wrote:

crystal, oscillator, resonator

---

I'd say that "resonator" is a generic term which includes both crystal resonators and ceramic resonators - maybe even RC and LC ...

But, whatever, the document should give a clear definition of the terms it's going to use, and then stick consistently to those terms as defined.

[BarryWhit]

STOne-32 wrote:

> Indeed nowadays “resonators” are rarely used

So clearly the word "resonator" is not universally understood in this way.

I completely agree with the rest. Define your terms, Spinoza.