TinyG Developer Notes

updated 7/9/13 - ash

These are random notes that may be useful for developers.

The best way to understand the code is to read it. It's pretty well commented. Here are some additional developer notes:

• Notes on TinyG program structure and modules that explain a few things that are too wordy for the code comments.
• Things we learned about github, usually the hard way
• Programming TinyG with the Atmel AVRISP mkii Programmer

Set Up a Windows Compile Environment for TinyG

This is the easiest way to get set up for compilation. It uses the pre-existing project files for AVRStudio4 or AtmelStudio6 to manage the git clone working directory. This page explains how to set up both, so make your choice.

NOTE: I still prefer Studio 4 for development and simulation, but TinyG also compiles in Atmel Studio 6.0 and 6.1 to take advantage of the newer C compiler and libraries for major releases. The code generated by 6.x is actually better than 4 - due to newer releases of AVRGCC and the libs, so if you work in 4 it's a good idea to also compile in 6 and go to production using 6. The .hex file for 6 is in the Debug dir, the .hex from 4 is in the default dir.

Clone the TinyG Github Repository

Run git clone to set up TinyG working directory. First you must install git. See github for instructions to do this if you haven't already.

From a command line navigate to the directory where you want the tinyg git directory to exist, then run:
git clone [email protected]:synthetos/TinyG.git

You should have a directory with all the source files and the Atmel project files for both Studio4 and Studio6. Some of the project files are ignored by git so they don't cause havoc.

To use the AVR tools you will need the AVRStudio4 project files or the AtmelStudio6 project files, or both. You can use both - they don't collide with each other. Studio4 uses the "default" sub-directory to manage its files; Studio 6 uses "Debug".

If you are using Studio 4 copy the tinyg.aws file from support into the tinyg working directory (/firmware/tinyg).

If you are using Studio 6.0 copy tinyg_6_0.cproj into the tinyg working directory and rename it to tinyg.cproj. If you are using Studio 6.1 do the same but for tinyg_6_1.cproj

Setup AVRStudio4

You can find AvrStudio 4.19 and the AVR toolchain you need here: http://www.atmel.com/tools/studioarchive.aspx Download these files:

AVR Studio 4.19 (build 730)
Atmel AVR 8-bit and 32-bit Toolchain 3.3.1 - Windows

Install the toolchain first, then AVRStudio. Click on the tinyg.aps file to start studio4. Run a Rebuild All from the Build tab to test that it's all working. You should get a clean build. The tinyg.hex file you want is in the /default directory.

You will need to set up the project configs like so. Of particular importance is including the floating point libs so the numeric displays will function properly.

In the Custom Options section, the custom compilation [All files] tab should read:
-gdwarf-2 
-std=gnu99
-Wall
-DF_CPU=32000000UL
-Os
-funsigned-char
-funsigned-bitfields
-fpack-struct
-fshort-enums

In the [Linker options] section if must read:   (Note: may need to scroll left window to the end)
-Wl,-u,vfprintf
-lprintf_flt
-lm

That's -W "ell" (not "one") and all other leading 'l's are also "ell"

Here's a useful link: http://www.avrfreaks.net/index.php?name=PNphpBB2&file=viewtopic&t=117023

To use Studio4 to program TinyG see Programming TinyG with the Atmel AVRISP mkii Programmer

Set up AtmelStudio6

Download and go through the Studio6 install process. We are using Atmel Studio 6.1-2440-beta at this point. Click on the tinyg.atsln file to start the project. A clean build should leave tinyg.hex in the /Debug directory.

To use Studio6 to program TinyG see Programming TinyG with the Atmel AVRISP mkii Programmer

Virgin AtmelStudio6 Setup (Importing TinyG or another project into Studio6)

You only need to do this is you are not using the pre-existing project files, as above

The simplest way to import TinyG or some other existing project into Studio6 is to clone the github repository and use the solution and project files provided. If for some reason these are not available or don't work or for some reason you just want to generate them yourselves the following instructions should help.

These instructions are for importing an existing project such as tinyg into Atmel Studio6 solution/project in a way that's compatible with how we have organized the directories on github. Studio6 likes to set up virgin projects and is not really set up for importing existing projects; someone at Microsoft or Atmel never really exercised this use case, it seems. So I trip over project import in 6 every single time. There is a menu item called "add existing project" but I think this is only useful for brining in a "project" into a "solution" and we are setting up a new "solution" in this case.

The directory structure we use is:

.../GitRepository/solution/project for example:

.../TinyG/firmware/tinyg

To get this do the following:

1. Create a git repository in the main directory (TinyG).

2. Open studio6 and create a new project. Parameters are:

• TinyG is a "GCC C Executable Project"
• The Name is "tinyg"
• The Location is the path for the git repository
• The Solution name is "firmware". Allow it to create a new solution and to create a directory for the solution

3. Select the processor - TinyG uses an xmega192a3. Kinen slaves usually use mega328p

4. Now move all the .c and .h files into the project directory (e.g. tinyg). If there's a collision with the main.c or PROJECT.c file then replace the project-generated file with the one you are moving in. If there's a collision with the .cproj file do not replace it, instead use the one that's already in the directory (the newer one).

5. Go to the Solution Explorer that should be in a right-hand nav box. Right click the orange project directory icon and select add / existing item. Select all the .c, .h and any other files IN THE MAIN DIRECTORY that are necessary for the compiler / linker. Don't attempt to add sub-directories until step 6. Don't bother to add .txt, .doc, .md, any .cproj or .atsln files, any AVRstudio4 project files, or anything else that you may have under git management but are not actually part of the compile/link process. If there are compilation or linking artifacts this might be a good time to run make clean. You may have to go back multiple times to select as the file browser doesn't work the way you think it should - at least not under VMware on OSX.

6. Now do this to add the files in project sub-directories. (Aside): If you have an exiting project with sub-directories (like tinyg) there is no straightforward way to add the files to the project and leave the directory structure intact. You can't just click on the directory to add the entire directory. If you try to add a new directory it won't let you because that name is already used. If you add the items as "existing items" then navigate and click them it moves the files into the parent directory. Here's what you must do.

• Either move the sub-directory out of the path or rename it (e.g. xio_ORIG) to get it out of the way.
• Create a new directory off the parent directory with the name you want (e.g. xio).
• Move the files from the original directory into the new directory
• Go back to the nav, click on the newly created directory and select "add existing files". Add the files that are found in the newly populated sub-directory.

7. Setup the following values in the project file. CLick on the "tinyg" directory in the solution explorer then go to the Project / Properties tab from the drop-down menus. Enter the following values if they are not already set:

IN THE TOOLCHAIN TAB

  AVR/GNU COMPLIER
    Optimization should be set to -Os

    SYMBOLS
      F_CPU=32000000UL

  AVR/GNU LINKER 
    General: 
      Check the "use vprintf linrary" box

    Libraries: make sure these lines exist:
       printf_flt
       libm

 IN THE DEVICE TAB
  The DEVICE should be ATxmega192A3

8. Now try to build it from the Build / Build Solution menu. If it doesn't build it's probably because you left out a file in the solution explorer. Check the files against the directory to make sure you haven't left anything out.

Notes:

(1) It gets worse. If you mess up and do things wrong studio6 will remember your paths in "recents" and fail the next time you try to set something up because things aren't where it thinks they should be. You have to go to the File/Recent Projects and Solutions, try to open the old paths, then remove them when they can't be found (you must have deleted the directories beforehand)

More AtmelStudio6 Topics

AtmelStudio6 fails verification when programming the xmega

We've seen this with earlier versions and Studio6.0 build 1996. Make sure you are up to Studio6 build 1996, service pack 2. See the help tab. Also make sure you rae on the latest firmware for the AVRISP mkii.

We've found that even though the verification failed the programming is good. You can either turn off verification or chose to ignore the warning. By the way - we've never seen this failure on Studio4. I actually think this is a bug in Studio6 rather than and actual failure. I have not seen any code die or act erratically when I get these errors.

Can't view ASCII strings in the debugger

There is a way around this: http://www.avrfreaks.net/index.php?name=PNphpBB2&file=printview&t=105137&start=0

Add the variable as a quickwatch and append ",c" to it. If the var is part of a struct you need the entire reference, e.g. tg.inbuf,c
Then add the quickwatch to the watch. Of course this is impractical if you have a lot of ASCII vars to track

From the Studio6 Help Pages:

While debugging you might want to track a value of a variable or an expression. To do so you can right click at the expression under cursor and select Add a Watch or Quickwatch

To add a QuickWatch expression to the Watch window In the QuickWatch dialog box, click Add Watch.