I doubt this rant will make any difference, but I'm throwing this out there in case someone in a position to do something about it doesn't realize just what a huge mess the SDK documentation is and how totally infuriating it is to try to use.
One of my tasks for today is to set up an ADC on an LPC55S69 to take a simple voltage measurement. I'm going to walk through the process.
The first mistake you might make is googling "mcuxpresso sdk documentation". This is a mistake because it will take you to something that looks like the right document, but it's for one specific chip's version of the SDK. Which chip? There's no telling, because the machine-compiled manuals don't specify which parts they're for.
You have to log on to your SDK dashboard account and generate the documentation. Since the docs are specific to a particular part, you'd think this would give the creators the opportunity to customize the docs to have the chip-specific information designers need. They could have done that, but they didn't.
So you go to look up the ADC module. In the user's manual it's called "16-bit ADC controller (ADC)". There's nothing with that name in the SDK docs. It's actually listed under "LPADC: 12-bit SAR Analog-to-Digital Converter Driver". An "lp" prefix usually denotes a special low-power peripheral. There's no indication of what it means here. As is the case for most SDK files, there's nothing but a boilerplate license in the header comments - not a single word about what the file is for. Like most things, the description has been copied and pasted from something else without review.
To set up the ADC, you need to select the appropriate VREF input pin. From the example project you glean that the parameter is "referenceVoltageSource" and it's part of the ADC config struct. Following up on that in the SDK manual gives you this:
"For detail information, need to check the SoC's specification."
It lists kLPADC_ReferenceVoltageAlt1 as "Option 1 setting." and so on. This is where the per-chip documentation should come in to play - it ought to tell us here what those mean for this particular chip, since the SDK was specifically generated for this chip.
So where do you go in the manual to find it? If you browse the ADC section in the user's manual you find table 724, which says Vrefh2 is VDDA and Vrefh3 is VREFP. All well and good, but that doesn't tell you if Vref2 is the same as kLPADC_ReferenceVoltageAlt2. No, you have to search through the whole register description section. That brings you eventually to CFG:REFSEL, which tells you that 2 = VREFP.
Which option is that? There's no way to tell from the SDK documentation. You have to look up the enum definition to find that 2 is kLPADC_ReferenceVoltageAlt3.
In no way is this better than just starting with the datasheet and writing the initialization code from scratch. It's actually more effort to figure out how to do it properly with the SDK. It's easily a 10 minute task just to hunt down which option you needed to select, and setting up a peripheral can involve dozens of selections like that.
Back in 2016 I was more forgiving of this stuff because NXP had just merged with Freescale and there were bound to be growing pains as everything was consolidated. It's been more than 6 years now and it's simply not any better.
For an $11 billion/year company it's just disgraceful. It's insulting to the customers who are asked to accept this state of affairs. There's no quality control. There's no proofreading. There's not even any automated spellchecking to catch the mangled language found everywhere in the comments, when you can find any comments at all.
You're asked to refer to the example code to figure out most things, and the example code is usually more minimum-effort junk. Take the I2S examples for the LPC55S69. They all have exactly the same description - they're all supposedly loopbacks. At least one of them is not. It still sets up a receive channel, because again it's been copied and pasted from something else without review. The receive channel is never used and the example instead plays a simple sine wave. So even with an example to work from, there's no guarantee the example makes any sense.
NXP as a company is capable of putting out quality work. The sensor fusion documentation is really quite good, especially for such a complex topic. But the meat of the SDK has the feel of something farmed out to entry-level developers with poor English language skills, and there's no one to review their work.
Please, please NXP - hire at least one person who speaks English fluently and knows enough about embedded systems to know what they're looking at. Set some reasonable documentation standards. Do a tiny bit of quality control.
