EEVblog #1264 - uSupply Software Development Setup

[EEVblog]

Dave & David installing the software required for the uSupply development.
Yep, one whole hour of installing software, for all you software installation aficionados.
Microsoft Visual Studio Code, cMake, Ninja, OpenOCD, and ST ARM programmers.
Doxygen and how to do automatically documenting code.

[nctnico]

Oh no, not Doxygen.  I fire anyone on the spot if they suggest using Doxygen for 'documentation'. It may fool some idiot manager into thinking a project is documented properly but not me.

Doxygen doesn't produce documentation; it just list the functions and some remarks which any good IDE can do in realtime (and usually even better!). Good documentation tells you how the software is put together, what the ideas behind it are, the layers and building blocks, information flows and state diagrams. All this is information Doxygen can't provide because code is (in programmer's speak) compiled output from our brains. However for maintaining and extending software you need to understand it's structure and for that you need the initial 'for-the-brain' input. Otherwise you are back to guessing and reverse engineering.

[johnkeates]

I find Doxygen a perfectly suitable code documentation generator, it works everywhere, for many languages, for many systems and all that using standard technologies. Of course there is going to be some more restricted yet more targeted option that produces 'more' or 'better' code documentation, but that is hardly suitable for an open source project. Internally we don't use it either because at that point you are just creating useless dependencies; if code cannot be run through an open CI/CD pipeline it's a significant indicator that something is coming to bite you in the ass, and often that means highly proprietary stuff being the ass-biting variant. While this is not always an option, it most certainly is the preferred option over here.

Regarding this specific project (the repo isn't public so I couldn't verify it); it might be worth simply adding a shell script for sh-compatible environments and a ps1 script for modern windows environments for automated setup, and just document it for whoever wants something that falls outside of that so they can still do it manually. For the classical autotools/gmake based projects it's often an autogen.sh or something like that to setup and configure the project, toolchain and build scripts for the compiler and linker, but for CMake that can be done just as well. Even better; having such a script allows to install CMake programmatically and then execute an actual CMake task to install the rest. I was going to see if that can be done for this project as well, but no repo yet.

[chickenHeadKnob]

For those of us that are not sup-po-tah's can someone give us a brief run-down on uSupply features, and what will make it a unique   product we will be compelled to lust after?

[tomlut]

https://www.eevblog.com/projects/usupply/

[JohnnyBerg]

A recap at the end, and conclusions / opinions would have been nice. Now it is a kind of chaos of what to do when someone wants to replicate ..

[sdim]

What OS do you use? If you use Windows, there is no reason to set up Visual Studio code for small ARM projects.

You can user Keil MDK Lite. Is is free. The only limitation is that it compiles code up to 32KB but it is OK for the uSupply.

https://www2.keil.com/mdk5/editions/lite

[Bud]

A recap at the end, and conclusions / opinions would have been nice. Now it is a kind of chaos of what to do when someone wants to replicate ..

I agree. The same rule applies as the one for public speaking:

1. Tell em what you'll tell em
2. Tell em
3. Tell em what you told em

Presentations done in this manner are much more effective to absorb and remember.

[German_EE]

I sometimes watch presentations and lectures that are way above my level as it's nice to stretch the brain cells once in a while, this was one of these moments. I'm a hardware guy and there's no way on Earth that I could do something like this.

A couple of questions therefore for David. I have at home one of the original Apple Mac computers and it has 128K of ROM. In that space is a complete operating system for the 68000 CPU plus a load of other stuff so why is your code for the uSupply so big? Has code creation got so inefficient that we need thousands of times more memory to achieve a similar task?

[chickenHeadKnob]

https://www.eevblog.com/projects/usupply/

That link points to the old and abandoned project, not the new hotness

[pgvoorhees]

What OS do you use? If you use Windows, there is no reason to set up Visual Studio code for small ARM projects.

You can user Keil MDK Lite. Is is free. The only limitation is that it compiles code up to 32KB but it is OK for the uSupply.

https://www2.keil.com/mdk5/editions/lite

There are, of course, many free compilers and development environments. The point of going through all this is that the build system is separated from the IDE. There are at least two good reasons for doing this:

• You can control which version of the compiler you are using, which includes using a newer compiler than the IDE vendor has.
• IDEs (and especially the eclipse-based ones) tend to have difficult to manipulate configuration files. If your IDE blows up your configuration file (which has happened to me), you're in for a bad day.

[nctnico]

I find Doxygen a perfectly suitable code documentation generator, it works everywhere, for many languages, for many systems and all that using standard technologies.

You are missing the point: you can't generate documentation from source code just as you can't get the original code back through 'decompiling' code. Too much details get lost in translation.

[hans]

An API listing is not full software documentation. There always needs to be supplementary documentation, which could be arranged with dedicated pages (e.g. a README and more) that are placed somewhere in the source directory.

Also, watching this video reminds me that Windows really could use a package manager.
I watched through the whole thing last night. Having gained experience with the combination of  CMake, Make, GCC and  OpenOCD, yes.. setting up these tools can be overwhelming at first, but after doing so is well worth it. Especially being able to choose your own GCC version and architecture, plus not being dependent on GUI tools, for example if you want to do CI (Continuous Integration).

What OS do you use? If you use Windows, there is no reason to set up Visual Studio code for small ARM projects.

You can user Keil MDK Lite. Is is free. The only limitation is that it compiles code up to 32KB but it is OK for the uSupply.

https://www2.keil.com/mdk5/editions/lite

They need to update their compilers or website: http://www2.keil.com/mdk5/compiler/5/
Not even C++11? I see David is using lots of template stuff, such as PackedTuple using variadic templates, introduced in C++11.

Also I think the USB micro is 32K, but was too small for the USB side project, implying that the final binary will be bigger than that to support all the USB C and communication features. Also I'm sure that the supply-side microcontroller will slowly grow out of 32K. For example, controlling half a dozen peripherals with/without DMA, add some protocol sauce on top (e.g. for computer control via string commands), and have a comprehensive UI will grow out of hand.

Templates are great for embedded due to their speed, but can grow the codesize out of control, especially if you let it to be on optimization level O2 or O3.

[EEVblog]

Has code creation got so inefficient that we need thousands of times more memory to achieve a similar task?

Basically, yes. Generally speaking no thought is given top code size optimisation by companies writing libraries for things, like the USB_PD used here.

Here is a video of what I did in 1K of memory once:

[gmb42]

Also, watching this video reminds me that Windows really could use a package manager.

There are a few, but I've used Chocolatey for quite a few years for my Windows dev environments.

There are choco packages for all the items listed, e.g.

Code: [Select]

cinst -y cmake make gcc-arm-embedded openocd vscode
chocolatey also allows you to upgrade and "pin" versions as required.

[Howardlong]

I wonder what the half life of this recipe is before it breaks?

Q. "This is all so obvious. How does anyone learn how to do this shit?"

A. They don't, it's the result of hours of random button pushing, some of it from experience, but most of it luck. And I doubt it'll work anymore after a week or two.

[lukasz.kostka]

Do you have any link to a git repo

[Mr. Scram]

A recap at the end, and conclusions / opinions would have been nice. Now it is a kind of chaos of what to do when someone wants to replicate ..

I agree. The same rule applies as the one for public speaking:

1. Tell em what you'll tell em
2. Tell em
3. Tell em what you told em

Presentations done in this manner are much more effective to absorb and remember.

It's a decent guideline. Unfortunately a lack of imagination or communication skills and overuse lead to people rattling off completely superfluous lists at the start and finish of presentations which make an already boring presentation worse.

[splin]

The only good use of Doxygen is to mix it with sufficient Dhydrogen and a smidge of Dspark to hopefully release some of the day's tension built up attempting to discover any worthwhile crumbs of mis-information from Doxydegenerated f**king 'documentation' whilst attempting to suppress some of the most extreme internalized hate crimes against the b***ards who ever dreamt up such an ill-conceived scheme.

[santiall]

Has code creation got so inefficient that we need thousands of times more memory to achieve a similar task?

Basically, yes. Generally speaking no thought is given top code size optimisation by companies writing libraries for things, like the USB_PD used here.

Here is a video of what I did in 1K of memory once:

not only that but in many cases, specially when dealing with USB, the libraries tend to be incomplete and be more what I call a 'collection of intentions' than proper usable libraries. The standard out there seems to be a library that supports a basic USB class, with a single fixed endpoint and so on. Once you need something more general you need to hack the library yourself...
USB-PD is actually the perfect example of how uber-complicated they made all this (usually under the excuse of making it super-flexible). You'd need something like 76kB of Flash for a "simple" task like asking 12V from a battery, running everything in RTOS.

On the coding side, for us who haven't spent the last 10 years dealing with compilers, line commands, unix and so on, I'd suggest checking VisualGDB. It installs in Visual Studio and allows to develop embedded code for many micros and do all the debugging under VS. Pretty inexpensive too.

[German_EE]

This is crazy.  Somewhere on the PC side of things are two registers and two DACs, one to set the maximum current and one to set the maximum voltage for a USB3 port. All a USB negotiation needs to do is set these registers so why does this take kilobytes of flash and an hour of software downloads?

Or as a software novice have I got things totally wrong here?

[jklasdf]

USB has never been simple specification, and the hardest part about using it with embedded systems has always been the massive software stack required. USB Power Delivery is no exception...it's a 40MB download https://www.usb.org/document-library/usb-power-delivery and the actual standard itself is more than 600 pages.

[ebclr]

"Doxygen a perfectly suitable code documentation"

I totally disagree, Doxygen documentation and nothing is the same thing, Doxygen trap the developer to believe that he made documentation,  but in reality, is a waste of processor time because the supposed to be documentation, just shows the obvious parameters that any header file can do, Without any real comments and tips/configs option created by the developer. This kind of documentation is userless, Is used by lazy developers not real ones

[Bud]

Oh-oh...

Visual Studio Code collects usage data and sends it to Microsoft, although this telemetry reporting can be disabled. The data is shared among Microsoft-controlled affiliates and subsidiaries and with law enforcement, per the privacy statement

[Howardlong]

USB has never been simple specification, and the hardest part about using it with embedded systems has always been the massive software stack required. USB Power Delivery is no exception...it's a 40MB download https://www.usb.org/document-library/usb-power-delivery and the actual standard itself is more than 600 pages.

I agree. I also believe it was a design requirement mistake to try to combine a high current interface with high speed data over such a fragile connector.

The biggest hardware failure mode in laptops nowadays is the USB Type C receptacle, either the physical connector or the electrical interface.

The physical aspect is a particular problem because if a mated connection is subject to excessive force, while the cable might be an acceptable sacrifice, the receptacle, often soldered directly to the main logic board, is also sacrificed. This is a far more expensive problem in terms of both time and money, especially bearing in mind the increasing trend towards soldering SSDs directly to the logic board.

The electrical failure mode is more to do with the data mux switching between Displayport, USB and optionally Thunderbolt than PD.

Finally, USB Type C is a horrific consumer experience. For example, apparently identical cables won't work for all usages, quite the opposite in fact. Consumers should not be expected to understand the nuances of PD, USB HS, USB SS and Thunderbolt and how it affects seemingly identical looking cables.