On the state of MCUXpresso SDK documentation

cancel
Showing results for 
Show  only  | Search instead for 
Did you mean: 

On the state of MCUXpresso SDK documentation

1,377 Views
scottm
Senior Contributor II

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.

3 Replies

1,368 Views
xiangjun_rong
NXP TechSupport
NXP TechSupport

Mr Scott,

Thank you for pointing out the disadvantage of SDK and giving the recommendation.

I suppose that you use LPC55S69, the ADC converter of LPC55xx is different IP from that of the other LPC family, it is more complicated that that of 12 bits SAR ADC the other LPC processors integrate, so the description in both UM and SDK for LPC55xx is not perfect.

From customer perspective, pls download SDK package from the link:

https://www.nxp.com/design/software/development-software/mcuxpresso-software-and-tools-/mcuxpresso-s...

 

You can refer to the ADC example in SDK.

xiangjun_rong_0-1665733616073.png

 

Then you can test the ADC example.

If you have additional requirement for example hardware triggering mode or multiple channels sampling, pls update the ticket, we can provide support further.

Hope it can help you

BR

XiangJun Rong

0 Kudos

1,358 Views
scottm
Senior Contributor II

I'm not asking for support with a particular technical problem in this post. Another embedded developer just said something to me that I think really gets to the point - he said that he uses ST parts not because he particularly likes ST parts, but because he feels like ST respects his time.

That's what's lacking here. NXP doesn't seem to respect their customers enough to put in the effort to properly document the SDK. And rather than acknowledging the problem, you're just telling me "Pls calm down". 

The description of the LPC55S69 ADC isn't wrong because it's more complicated than other IP versions. It's wrong because someone just pasted the entire description in from something else. It never even states what LPADC stands for.

The specific example you gave is titled "lpadc_interrupt" but in its own description it switches to "lpdc_single_interrupt". There are at least five errors in that description paragraph that could have been caught just by using a spellcheck function.

To give another example of why the samples are frustrating to use, check i2s_dma_transfer. The description says "The I2S example project uses one I2S interface to continuously record input sound to a bufferand another I2S interface to playback the buffer to output - digital loopback."

That is not at all what the sample does. The sample does go through all of the setup for both a transmit and receive channel, but it only uses the TX channel and sends sine wave samples. This is a perfectly valid thing to do with I2S, but who does the sample serve when someone looking for a DDS example wouldn't know to look there, and someone wanting to implement a loopback would find an example that does something else? And because there is no narrative description in the SDK documentation on how to set up the driver we're forced to rely entirely on examples. In this case we need to be able to read it well enough to understand that it's wrong and to figure out which pieces are irrelevant.

And the demo projects never have any header indicating their purpose or overall theory of operation. Any programming instructor I ever had would immediately reject an assignment that was turned in without a descriptive header.

If NXP wants to show some respect to developers, do it by making corrections when problems are brought up. I've been complaining about the same problems for years and the most that ever comes of it is someone telling me "Pls calm down" and maybe making some excuses for why nothing will change.

So let's steer this thread back in a productive direction. When a customer like me finds an obvious problem in the documentation and examples, what is the proper procedure to get that fixed? How do I get these changes into the next version of the SDK? I will happily submit a ticket for every problem I find, with a suggested resolution if I have one, if someone will actually do something about it.

Thanks,

Scott

1,312 Views
xiangjun_rong
NXP TechSupport
NXP TechSupport

Hi,

I agree with you that the SDK documentation has space to improve.

If you have good suggestion and recommendation, you can post them on community for a specific technical problem, if it is proper, we will submit to SDK team so that they can fix it or modify the documentation.

Hope it can help you

BR

XiangJun Rong

 

0 Kudos