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 ); CONCLUSION
void TMR_CallbackFn (uint32_t status,uintptr_t context )
/* this will only happen after the timer is started */
clkData.clkstate = CLKS_STATE_EVENT;
TMR2_PeriodSet(100000); // Set the period (ms)
TMR2_Start(); // Start the timer
: 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?