ASF, Converting example projects to my MCU, changing "implementation"

Go To Last Post
3 posts / 0 new
Author
Message
#1
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Still very new to AVR embedded C programming with Atmel Studio 7 and running into a steep learning curve.  It seems Atmel Software Framework (ASF) is supposed to be the way to quickly get functionality with abstracted programming schemes, but I find ASF bewildering.  My frame of reference is something like Arduino or (without hardware) Matlab -- Matlab's documentation is incredible and it's easy to look up all aspects of the language, functionalities available, and how to use them.  When I look for something similar for ASF, I usually don't find what I'm looking for or get even more confused than I was before. Am I missing something?

 

Let's take an example:  I want to do some USART communication and see my MCU's output on terminal.  So in Atmel Studio I start a new Example Project and find one called "USART Example - UC3C-EK".  This evaluation kit and project are set up for the AT32UC3C0512C and I have a custom board with AT32UC3C1512C - very similar.  When I change the "device" (to my MCU), I get a warning saying "ASF does not support device change since some of the existing modules in the project may not work."  ...that seems like a major difficulty with using example projects, but ok.  When I look at the main code in the example project, I see there are tons of pin definitions for different devices, like this:

#elif BOARD == UC3C_EK
#  define EXAMPLE_USART                 (&AVR32_USART2)
#  define EXAMPLE_USART_RX_PIN          AVR32_USART2_RXD_0_1_PIN

Let's say that I want to understand what these mean (crazy, right?).  If I highlight anything, right click, and go to "View Help" it simply opens a web page for the Atmel Studio 7 Getting Started Guide, which is really about using the IDE itself, and has no reference anywhere in it to the language, macros, or functions of ASF. When I Google search for something like  &AVR32_USART2 to see what it means and how it should be used, I get an ASF page like this, which seems pretty useless.  If I then search from the main ASF documentation page, I will get something like this, which is a little more helpful but also makes some things very confusing, for example:

 

If I understand correctly, these are values that can be returned by some of the transmit/receive functions?  Why are they all preceded by #define ??  Are these things really being defined?  I wouldn't ever define them in my implementation, would I?  Can you see how this is confusing?  

 

Let's ignore that for now and say I want to edit the original example code to make it work with my MCU.  If I right click on a pin definition and do "Goto Implementation" it takes me to the header file for the original MCU the example project was based on and shows the pin definition, which eventually is just a number, like 42.  Having already changed the device of the project to my MCU, how do I make an implementation point to the header file for my MCU?  Furthermore, where do I even find the header file for my MCU (or rather, how do I introduce it to my project)?  If I start typing a new pin definition, the autocomplete ("Intellisense", I guess) populates a list of possible pins that it seems to be getting from a header file, but how do I change this to my MCU?  Once I accept a suggestion, I can look at the implementation and it seems to have definitions for both the original MCU and mine:

 

Which raises the question: at compile time, which of those will it choose for the definition?  How do I strip the references to the original board out of my project?  

 

Clearly I have a lot of confusion here.  Sorry if this sounds more like a general complain about ASF or Atmel studio, but I hope that answering some of these questions here will help other beginners as they find it.  Thanks for the help.

 

 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

All reasonably useful APIs have a steep learning curve.
Start with the processor datasheet and write code to manipulate the internal modules to achieve a result, eg. checking the status of the USART, transmitting a byte via SPI, etc.,
and congratulations!, because you have created an API and are on the way to fame and glory. (possibly).
The ASF is Atmels' encapsulation of that process., the hard part is learning their style and layout.


The base layer of the ASF is organised around the internal modules of a processor and these are called 'drivers'.
eg. the timers have a TC 'driver', the usarts have a USART 'driver', the I/O ports use the GPIO 'driver' and so on.
The ASF 'Services' and 'Components' use those 'drivers' to provide higher-level functionality.


The 'driver' header files will show what features are available and at this 'low-level' there is no escaping the fact that you must have some knowledge of what the module actually does.
eg. the TC (Timer/Counter) driver has tc_start(,), tc_stop(,), tc_write_ra(,,), ... routines.
tc_write_ra(,,) will put a value into the RA register of a timer/counter but you need to know what the RA register is actually used for.
You select appropriate routines and use them to achieve your goal(s).
All APIs should return a status/error cods to indicate what happened when you call a routine.
Some actions do not need a return status but if (for example) you call usart_putchar(,) and it doesn't appear to be working then the return code will point towards the problem area.



The processor header-file is 'selected' automatically from the processor model that you have selected in Atmel Studio. (the avr32/io.h file is the start of that rabbit warren).
The processor header file then pulls in the appropriate header files of the modules that are in that processor and these contain the specific details of each module, (eg. the addresses of the registers, the control/status bit-definitions, etc).
The module-specific header files also have structures and definitions to assist in accessing the module registers.
There can be significant internal differences in processors which have similar part numbers, therefore the generic "ASF does not support device change since some of the existing modules in the project may not work." warning is reasonable.

Last Edited: Wed. Oct 19, 2016 - 11:07 PM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

@mikech  Thank you for your thoughtful response to my vague and wandering question(s).  It's helpful to hear about the relationship between modules, drivers, services, components, etc., because most of that is mysterious to a newcomer and I still have not found a good primer on all of this so far.  I think your suggestion of starting with the simplest things first is a good one ("you must learn to crawl before you can run" approach).  I've actually started reading Make: AVR Programming by Elliot Williams and it's been helpful and relatable, such as this note about the MCU datasheets: 

"But the datasheets are imposing—the ATmega 48/88/168 series is 450 pages long! And the data- sheets don’t seem helpful at first—the datasheet tells you everything about how the chip works, but almost nothing about how you should work with the chip. Some sections of the datasheets are nearly impenetrable unless you already know the basics of what’s going on inside the chip already. "

I think some of what you suggest would be simpler with a development board, whereas I was sort of thrust into a position where I needed to make this chip do certain things within the context of a custom PCB designed by someone else.  Overall I would say the introduction to this world of programming has been difficult and there is a higher level of prerequisite knowledge required compared to what I expected (clearly my usage of higher-level programming languages and faint memories of CS101 don't cut it).

 

Any suggestions for beginning resources would be appreciated.