• AVR Freaks

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

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

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

4 Replies Related Threads

    NKurzman
    A Guy on the Net
    • Total Posts : 18667
    • Reward points : 0
    • Joined: 2008/01/16 19:33:48
    • Location: 0
    • Status: offline
    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 : 228
    • 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 : 18667
    • Reward points : 0
    • Joined: 2008/01/16 19:33:48
    • Location: 0
    • Status: offline
    Re: EXPERIMENT: Is the Harmony documentation helpful in developing a project? 2020/05/19 10:24:51 (permalink)
    0
    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 : 611
    • 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
    Jump to:
    © 2020 APG vNext Commercial Version 4.5