# Bad documentation: Engineers can’t write, and Marketing folks are full of crap

No, really.

For the past week or so I’ve been configuring my STM32F37x series microcontroller. Specifically one from the chip-tray STmicro custom-fabbed and hand-delivered to me (all I wanted was fedex ground!). This adventure has been one with fortune, and failure.

Delightfully this microcontroller was engineered proper, unlike the TMF320′s which gave me so much woe last month. That is to say, it responded to my initial st-link JTAG requests immediately and without issue, and hasn’t given any connection troubles thereafter. “Bricking it” does not appear to be a possibility given that all fuse bits are write-protected during its user-flash sequence, as well as its bootloader and other really important things. TI, please take a lesson from ST and write protect your non-program pages!

ST unfortunately does not maintain an IDE for their microcontrollers. Instead users are forced to use one of four commercial IDEs, the most notable of which are MDK-ARM (keil) and IAR workbench. I assume that this course of action is what allows [legally] for them to provide *so many* freeware peripheral drivers (many are in fact, developed by those who make these IDEs), but still, it’s a bit awkward having a 32k code limit on the freeware versions of such workbenches.

That’s where the fun appears to end, however. ST needs a librarian. Really. Or a new webmaster. After much struggle and somewhat-of an implicit “go to hell, plebeian” response from IAR support, I settled on Keil/MDK-ARM. While it’s UI leaves a lot to be desired, overall I’m quite impressed with its capabilities. Its compiler (not GCC!) compresses code like a champ, it has built-in core config files for nearly every ARM available, and its debugger is nothing short of amazing. I can snoop on local variables, even!

Although the company has many examples, datasheets and programming guides for their microcontrollers, it took communication with an engineer to find any of it. As one would have it, the collection of STM32F37x peripheral drivers was buried in a folder, inside a folder, inside a zip file, inside a lonely webpage, itself linked to only by one non-emphasized link in the “design resources” tab on the STM32F373RB’s  product page. I kid you not.

It gets better though; as it turns out, while much documentation exists on the microcontroller’s busses, core, peripherals and their registers, there’s absolutely nothing about their C drivers.  That is, nothing but the little /* @brief statements */ contained within them.

While inconvenient, this wasn’t a showstopper. Fortunately many of these helper functions directly correlate with the configuration registers documented in their big book, and every peripheral has several C examples to give the designer an idea of how to use them. That said, some functions do not work unless others are called beforehand, and it’s often a mystery as to what their proper order is.

• Enable your clocks! Every peripheral has an RCC_blah clock command which must be run before the device will work, and some others also have a PWR_blah command that must be set before even that. Nothing throws an error if these aren’t turned on,  and quite frankly it took me 4 hours to debug timers because of it!

• Disable your watchdog. There’s an unconfigured watchdog timer enabled by default in the option bytes, that will repeatedly kill your program unless it’s turned off. This took another 4 hours to debug.

• Use this tool to write your sys config file (for the stm32f37x only). The microcontroller won’t throw any errors if the sysclock is misconfigured, and again, this was a real bitch to debug.

• Be forewarned; despite what some of ST’s configuration programs (cubeMX, microXplorer) might imply, that you cannot arbitrarily define analog pins as differential pairs. Rather, the pins must be labeled in the form SDADCx_AIN#P, SDADCx_AIN#N, where # is some channel number. I’m going to need to fab new boards because of this.  ಠ_ಠ

• This powerpoint has been the most useful piece of documentation I’ve found yet.

Some 30 hours after first contact I eventually did get things configured. As of now I have clocks running, timers counting and ΔΣADCs sampling. There’s still an ADC, USART peripheral, DMA and interrupt table to configure before I can *actually* start crunching vectors in $$\mathbb{R}^3$$, and given the pace of current progress I expect that to take at least another week. Oh well.

However, I did run into an unexpected problem last night around 2. Evidently, marketing engineers lie.

As one would have it, all of TI/BB’s micro-tiny “rail to rail” amplifiers are in fact, not “rail to rail”. Rather, the ones I chose to buffer my current shunts (OPA244) bottom out at 100mV, and are nonlinear for a good 50mV thereafter! This means that my nice getcurrent_float() function bottoms out at 0.9A, and doesn’t start properly working until we pass 2.5A or so through the phase in question.

Good job Burr-Brown, you get a medal. Also included is one angry customer, who now has to redesign their board to include a negative-rail charge pump that should not been needed.

Oh well, such goes “progress”. Despite their idiosyncrasies I’m happy with the STM32 product line, and will do my best to master the machine.

## 4 thoughts on “Bad documentation: Engineers can’t write, and Marketing folks are full of crap”

1. You don’t need a negative supply rail, the OPA365 can get within 20mV of the rails (I haven’t noticed non-linearity but that may happen).

If you need to go down to 0V, you can rework your amp to have a small bias that will occur, then 0A of current would in the linear region of the op-amp. Post your schematic and I can give you some pointers (I’m guessing you already have a diff-amp configuration, all you should have to do is modify some resistor values).

The lesson you should have gotten from this is: read your datasheets twice before building boards.

Also I’ve been using C2000 micros for 5 years now, never have I locked the flash, what the hell were you doing?

Alex,

Rather than introducing unpredictable offsets (who can guarantee a 1% tolerance resistor is actually 1% tolerance?) I’ve decided to just go with the negative rail plan, using an sot-23 inverting charge pump. I’ve switched also to chopper-stabilized op amps for less input offset voltage.

Re datasheets: STmicro has conflicting documentation. Their datasheets don’t necessarily line up with comments in their driver libraries, which ultimately leads me to connecting differential lines to useless pins. This has been fixed.

Every C2000 I tried would lock its flash if there were JTAG connection issues. The STM32′s haven’t done this, and I’ll stick with them considering I’d be a *really unhappy person* if the DSP on a \$1500 segue-kit bricked during chip erase (which would be a good possibility, given hackers and their improvised solutions).