• AVR Freaks

Hot!EXPERIMENT: Is the Harmony documentation helpful in developing a project?

Author
BillP
Super Member
  • Total Posts : 414
  • Reward points : 0
  • Joined: 2014/09/28 07:53:35
  • Location: CA
  • Status: offline
2020/05/19 08:52:16 (permalink)
5 (3)

EXPERIMENT: Is the Harmony documentation helpful in developing a project?

Using the Harmony documentation is like playing a game of “Clue”.  You need to go to different repos help files for clues, you have to run MHC and try its various configuration options (many of which are not documented), and finally you have to decide on which Harmony APIs to call.  

Here is an example of how the Harmony documentation can help (or not) to solve one task in a project.

Task: Use the Harmony documentation as a guide to set up a hardware timer to interrupt every I millisecond.
1.    Go to the Harmony v3 folder where the basic repos (core, csp, mhc) are located.  
2.    Search for “timer”.  This gives too many entries to be useful.
3.    Search for “hardware timer”.  This gives multiple references to sys_time.h which points to the SYS_Time functions in the core repo.
4.    Go to the core repo, doc folder.  There is only a chm file (no pdf).  I am on a Mac, so that is not useful
5.    Go to the docs folder (containing many html files).  Try the index.html file which brings up the core help documentation.  Try the search feature.  It only works on files, so you have to know which file you want to search.  Not useful.
6.    Wade through the high level folders to find the System Service Library that contains a reference to hardware timers, but there is no explanation about the hardware timers.  False alarm. Nothing useful in the core documentation.  
7.    Dead end.
8.    Post a message on the Harmony forum.  Wait for someone to tell you to look for TMR in the csp repo.
9.    Go to the csp repo.  The doc folder only has a chm file (no pdf)
10.    Go to the docs folder, open the index.html file.  Open the Peripheral Libraries Help folder and scroll down to the Timer Peripheral Library Help folder.  There are two identical folders, so choose one of them (why are there 2?).  Click on the Introduction.   There is a short description of the hardware timers  (see the following)

"2. Timer2, 3, 4, etc…
This peripheral library covers this timer. Each timer has its own 16-bit counter and period registers. A 32-bit timer can be created by combining two timers (e.g. Timer2 & Timer3). In this case, the 32-bit timer is controlled by the even number timer control registers (e.g. Timer2). When an interrupt event occurs, the odd number timer generates the event (e.g. Timer3). The timer supports the following features…"

 
11.    So we are in the right repo.  Click on the Library Interface/TMRx_Initialize Function.
“This function initializes (sic) given instance of timer with the options configured in MHC GUI.”

 
12.    Go to the TMRx_PeriodSet Function.  The description shows:
 
“This function writes the period value. When timer counter matches period value counter is reset and interrupt can be generated.”

 
The description also tells us to use a 16 bit or a 32 bit number, but fails to provide what value/units to use.  No help there.
13.    Try configuring MHC to find the proper values.  Go to the Project Graph and add a TMR2 component and configure it.    But with what configuration options?  No information on which options to use.
14.    At this point the documentation path goes off the rails and the exercise fails.


What actually works for this task:
The value for the PeriodSet function should be in units of the PBCLK3 (for my 200 MHz MZ EF chip the PBCLK3 is running at 100MHz), should be in increments of 100,000,000.  So for a 1 millisecond interrupt, the period set value should be 100,000.  Oops…too big for a 16-bit word.  We need a 32-bit timer.

The only indication in the documentation on how to setup a 32-bit timer is the short statement above about combining 2 timers.  I could find no other instructions on how to configure the 2 timers and how to use them in the application.  So the trial-and-error method is used to configure the timers (TMR2 and TMR3).  The attached figures show the setup for the 2 timers.

In the source code, define a callback when the timer interrupt occurs.  In this example it sets a state in a state machine.

Void TMR_CallbackFn (uint32_t status,uintptr_t context );
void TMR_CallbackFn (uint32_t status,uintptr_t context )
{
    /* this will only happen after the timer is started */
    clkData.clkstate = CLKS_STATE_EVENT;
}


            TMR2_CallbackRegister(TMR_CallbackFn, NULL);
            TMR2_PeriodSet(100000); // Set the period (ms)
            TMR2_Start(); // Start the timer

 
CONCLUSION:  The Harmony documentation may not be sufficient to develop a project with Harmony.  It is a resource that can be used as a reference if needed.

So, what can be done about the Harmony documentation? Microchip asks for feedback on this important issues, so here are some ideas.  I'm sure others in this forum can add many more...
  • Who are the readers of the documentation and how does the documentation focus on their needs?
  • Is quantity better than quality?  
  • Are there any quality standards that can be applied?
  • Should the demos fit with the reference documentation?
  • Should there be auto-generated documents?
  • Should there be hyperlinks to help amalgamate the various related issues?
 

Attached Image(s)

#1

12 Replies Related Threads

    NKurzman
    A Guy on the Net
    • Total Posts : 18854
    • Reward points : 0
    • Joined: 2008/01/16 19:33:48
    • Location: 0
    • Status: online
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/05/19 09:20:30 (permalink)
    5 (1)
    Step 15 Go to the data sheet.
    Code it the old fashion way?
    #2
    realexander
    Super Member
    • Total Posts : 235
    • Reward points : 0
    • Joined: 2006/04/08 09:50:42
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/05/19 09:55:46 (permalink)
    5 (1)
    NKurzman
    Step 15 Go to the data sheet.
    Code it the old fashion way?



    Sort of defeats the purpose of Harmony, eh?
     
    #3
    NKurzman
    A Guy on the Net
    • Total Posts : 18854
    • Reward points : 0
    • Joined: 2008/01/16 19:33:48
    • Location: 0
    • Status: online
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/05/19 10:24:51 (permalink)
    5 (1)
    realexander
    Sort of defeats the purpose of Harmony, eh?



    Partially.  Harmony OK for Clock Setup, Stacks, and maybe pin setup.
    Documentation for V1.XX and V2.XX was an engineering challenge, Not a Tech Writer one.  It appears to be designed by engineers to minimize their workload.  Is 3 Better?
     
    Years ago I use Franklin C (for the 8051).  it was always hard to find anything in it.  One Release came with a New Manual.  It was well organized and well Indexed.  Comparing it to the Old Manual it had had the same info.  A tech Writer had reorganized it.  Never Under estimate what a good Tech writer can do.  Or how bad Engineers can be at documenting, especially when they would rater just code.
     
    The Goal is to Complete Our Project, Not to use Harmony.  Even if Microchip wants to Force us to use it.
    At this Point Harmony maybe losing them Customers.
    It is Good For Certain types of Projects. It is not a complete waste.  But they have had Years to clean it up and never seem to.  My greatest fear is that Harmony 4 will make all my Harmony 3 code useless.  Like the V1.XX and V2.XX Code I have.  Someone could Write a Harmony 3 Book, But how long would it be valid? ( A Comment I made for V1.XX and V2.XX
    #4
    Paul PortSol
    Super Member
    • Total Posts : 630
    • Reward points : 0
    • Joined: 2015/07/03 11:52:03
    • Location: Newfoundland, Canada
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/05/20 08:26:06 (permalink)
    5 (1)
    Agreed on all the previous. 
    Too time consuming using Harmony.
    #5
    glamprecht
    Starting Member
    • Total Posts : 10
    • Reward points : 0
    • Joined: 2010/09/27 22:45:46
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/06/27 13:35:23 (permalink)
    5 (2)
    We have used MLA for many years with great success. It worked really well. We have done a couple of projects on Harmony now and all my developers agree they dont see the point in using Harmony really. It is supposed to make things quicker and easier, but it doesn't. I think many Microchip users will over the next 5 years try out other manufacturers to see if it is any better. The downfall of Harmony are
    (1) Try to be everything for every architecture, every chip, every project, every size company, every project
    (2) Documentation is practically non-existent. If you think source is documentation: Going through really millions of lines of code to be able to use 1% of those code does not make sense. In that case you can rather start writing the 1% from scratch.
    (3) Many forums posts with legitimate questions, like how to properly save TCP/IP settings, are never responded/resolved, or a link provided where it was solved in other forum. Microchip example of 2010 had this working. The Microchip example of 2020 does not have this even coded - yet. Many people asked the question, but without answers.
     
    I hope the documentation can be sorted out.
    #6
    realexander
    Super Member
    • Total Posts : 235
    • Reward points : 0
    • Joined: 2006/04/08 09:50:42
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/06/27 13:51:33 (permalink)
    0
    For many peripherals, you're right: Harmony doesn't make sense.
     
    For some software stacks (USB, TCP-IP, etc) it does.
     
    glamprecht
    (1) Try to be everything for every architecture, every chip, every project, every size company, every project

     
    That's also true of libraries from other manufacturers.
     
    I very briefly tried the STM32 development environment a few weeks ago. My impression was it has its problems too. Different problems, of course, but still maddening. One thing I noticed right off was that while Harmony's USB device stack lets you implement multiple devices (e.g. COM and MSD simultaneously), STM32Cube's code generator is apparently limited to one USB device (e.g. COM or MSD, but not both). That would be a big deal for me.
     
    - Bob
     
    #7
    rjc101
    Super Member
    • Total Posts : 133
    • Reward points : 0
    • Joined: 2016/07/08 14:56:34
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/06/28 04:01:45 (permalink)
    5 (1)
    I found a fairly decent, free, .chm viewer for the Mac on the App Store called "ChmPages".  
     
     
    #8
    Paul PortSol
    Super Member
    • Total Posts : 630
    • Reward points : 0
    • Joined: 2015/07/03 11:52:03
    • Location: Newfoundland, Canada
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/06/29 05:39:27 (permalink)
    5 (2)
    Support:
    - Harmony answers to tickets dreadfully slow. Too often I got a reply "its been a long time since you posted, is this still an issue", which tells of the real issue of slow response.
    - Microchip answers on XC32 and MPLABX nice and fast
    - Why the difference? I suspect Insufficient support staff for the product given its state.
     
    Examples:
    - I like the MHC Code Generator under app for creating examples, didn't see same in Harmony3.
    - Competitors just seem to have way more working examples
     
    Doc:
    - Harmony2 help seemed to be help for the writers of Harmony, not the users. The language of the help is just tilted to the wrong level, not the target user. 
    - Harmony3 doc/help is broken, there is no easy way to browse through the total available help. You have to know where to find files. That is useless for beginners, or even begineers of new modules. There needs to be a help you can search through all installed modules. 
     
    Forum:
    - The mixed Harmony1/2/3 forum continues to be a mess. Solutions for one version aren't applicable to the others and so shouldn't be in same forum.
    - This shows that Microchip is doing what makes life easy for themselves, not what makes life easier for the customers.
    - The forum is obsolete tool. Customers have been complaining for many many years. Replace the forum engine! Not fixing it says Microchip just doesn't care about its customers. The same issues with forum have recurred many many times. I've only been using this a few years and even I am sick of seeing same complaints - just fix/replace it!
     
    Paul
    #9
    rjc101
    Super Member
    • Total Posts : 133
    • Reward points : 0
    • Joined: 2016/07/08 14:56:34
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/06/29 05:46:00 (permalink)
    0
    There is a new Harmony package called 'quick_docs' available now, this is a collection of pointers to the various documentation sets.  In itself it isn't a searchable lump of items, but does make an attempt to create an overall view of the documentation available.  It appears as a series of webpages, with an index.html file in a _START_HERE directory.
     
    After a quick glance, I think it links to a number of examples too.
     
    It's on the Harmony github and available in the Harmony3 content manager.  Might be worth a look.
    #10
    hungChun
    New Member
    • Total Posts : 5
    • Reward points : 0
    • Joined: 2016/05/31 02:08:06
    • Location: Taipei
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/08/04 00:44:20 (permalink)
    5 (1)
    - This shows that Microchip is doing what makes life easy for themselves, not what makes life easier for the customers.
     
    Can't agree with it more!!!
     
    I tried harmony v1 form its very early version, it is buggy(both harmony and mplab x) and introduce new bugs in every new release. When I attend the MASTERs Conference , The teaching assistant almost failed to run the lab just because the buggy environment.
     
    I have a project at that time ,finally I gave up and use other chip to make it work
     
    years later, I try it again with harmony v3 with atmel SAME chip, I can't even find an official API document for generated files, every time when I click "generate code", I should dig into the .c files to see what I can use in this file.
     
    Every time I compile the project and got error message, I should think "am I wrong?" or "oh the buggy framework again!". We are not students!, we can't just open the example, click run to see LED blinks and go home. We should provide reliable and complex service to our customers!
     
    The IDE, as many people said, is too huge and slow, I strongly suggest change the IDE to visual studio code.
     
    I think the MCUs of microchip is stable and reliable, but the developing environment is not. It seems you make the framework just for yourself, but not for other developers. Write code once and run in multi-MCUs? No! we don't need that, we don't want to change the MCU every time after we finish a project (in general case)
     
    finally, the harmony use state machine to run tasks, but in the generated plib code, I got the code like:(plib_qspi.c)
     
    bool QSPI_CommandWrite( qspi_command_xfer_t *qspi_command_xfer, uint32_t address )
    {
        uint32_t mask = 0;

        /* Configure address */
        if(qspi_command_xfer->addr_en){  ...  }

        /* Configure instruction */
        QSPI_REGS->QSPI_INSTRCTRL = (QSPI_INSTRCTRL_INSTR(qspi_command_xfer->instruction));

        /* Configure instruction frame */
        ...

        while((QSPI_REGS->QSPI_INTFLAG & QSPI_INTFLAG_INSTREND_Msk) != QSPI_INTFLAG_INSTREND_Msk)
        {
                /* Poll Status register to know status if instruction has end */
        }

        QSPI_REGS->QSPI_INTFLAG |= QSPI_INTFLAG_INSTREND_Msk;

        return true;
    }

     
    why you use a while loop the poll status register??? (in harmony project)
    where is the timeout handler?
    No description for each function (in generated plib_qspi.c), how do I use the input parameters, return values?
     
     
    Who are target users of harmony framework?
     
     
     
    #11
    dobrosoft
    Starting Member
    • Total Posts : 89
    • Reward points : 0
    • Joined: 2019/05/20 04:44:55
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/08/04 05:43:50 (permalink)
    5 (1)
    I start to use harmony year ago.  I has been very frustrated of lot of trying to develop software banality problems. Horrible documentation. I go step by step througth GPIO, SPI, ... CAN, memory and other peripheral. It's like big puzzle. For some problems (communication for i2c EEPROM) there was easier to create own communication, not use Harmony. It is fine to use serial communication with buffer, command line interpreter, but with using SPI, I2C and other I lost months of work. 
    I'm active developer of iOS too, but different in support from Apple and Microchip is very big. Microchip docs are bad, ambigious, Apple has perfect tutorials, examples.
    With Harmony, sometime you can use PLIB, sometime DRV, sometime both. When I want to create professional working code, I must go througth harmony function, and look what it does, othervise I risk some disfunctions of code.
    Harmony helps me with developing some code (CAN, interrupts, sleep modes, WD timer ...).
    I think, Harmony is useble, but docs are bad. Very bad for user, which starts first time with microchip. Maybe it's OK for user, which start with 8bit, then go to 16 bit and next to 32bit cpu. But bad for starting users.
     
     
    #12
    shaun_any
    New Member
    • Total Posts : 5
    • Reward points : 0
    • Joined: 2018/05/21 08:48:40
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/08/05 03:18:59 (permalink)
    0
    Actually I've found a hidden gem for harmony 3 docs,
     
    Go to the harmony 3 github and look inside the repo you are interested in, at the top is normally a link to a doc structure that explains the modules with example code.
     
    For example with the net module go to,
    https://github.com/Microchip-MPLAB-Harmony/net
     
    On the right hand side in the about section is,
    https://microchip-mplab-harmony.github.io/net/frames.html?frmname=topic&frmfile=index.html
     
    This was like Christmas when I found this and why they don't send you there is beyond me
    #13
    Jump to:
    © 2020 APG vNext Commercial Version 4.5