Programming the Make Controller Kit

« Return to page index

A practical guide to writing your own programs on the Make Controller.

Overview

What we're trying to do, and how to get set up to do it.

The SAM7X

Toolchain

• On Windows, see the Build Firmware on Windows how-to.
• On OS X, download the appropriate GnuArm toolchain from the Downloads page.  Just run the installer and you're all set.
• On Linux and other platforms, there are a variety of options - check www.gnuarm.org for a recent source package.

IDE (Integrated Development Environment)

• The simplest, of course, is using your favorite text editor and the trusty old command line.
• A good, free, open source option is Eclipse - check the Build Firmware with Eclipse how-to for instructions on how to set it up.
• On OS X, you can use Xcode, a nice IDE that comes free with OS X.  Check the Build Firmware with Xcode how-to for instructions on getting set up.
  

Getting the Source Code

• Grab a source package from the Downloads page. 
  
• Pull the latest source from the MakingThings Subversion repository.

Project Layout

How projects are organized, and what the important pieces are.

When you download the firmware package, you'll see a handful of directories in there.  The main directories we're concerned with are the core and libraries.  Core contains the basic Make Controller code, and libraries contains modules that can be added/removed from projects as needed.

The doc folder contains the API documentation for the Make Controller.  Inside the projects directory are some example projects. The heavy directory, for example, contains the project used to create the main heavy.bin.  To create your own project, it's easiest to make a copy of one of the projects, rename it for your project, and then start making changes.

     - firmware
        |
        +-core
        |
        +-libraries
        |
        +-doc
        |
        +-projects

Relevant Files

Each project, at the very least, has two relevant files - make.c and config.h. 

config.h

This file contains configuration options for your program.  You can choose which systems you'd like to include - Ethernet, USB, OSC, etc.  Most of these systems take up lots of resources on the board so if you don't need them, you should comment them out and regain that space.  You can also set the amount of memory available to your project - this depends on a number of things and is discussed in further detail in the memory section of this tutorial.  By default, this is set to a value that should generally work for the heavy firmware.

make.c

This is where you actually start to write your program.  If you've started off by copying heavy, you can probably start to comment things out as heavy uses just about everything in the firmware API.  The Run( ) task in make.c gets called at startup and is a good place to fire up any initialization for your project.  In heavy this is where OSC systems are registered, the LED blink task is started and the Network and USB systems are turned on.

RTOS

A description of the operating system that runs on the Make Controller.

Often, when you're programming a microcontroller you're constrained by the fact that the processor can only do one thing at a time.  This can make programming difficult when you want your board to be doing more than one thing at a time.  Enter the operating system. 

The operating system, or RTOS (real-time operating system) as they're often called in the microcontroller world, is a system that can switch back and forth between different programs seemingly simultaneously, to give the illusion that more than one is running at a time.  This means you can write each of the elements of your programs separately, making it much easier to create more sophisticated programs.

Do I want to use an RTOS?

Not always.  Sometimes you need more precise control than an operating system can offer. 

The base element of time in the RTOS is called the tick.  Each time a tick rolls around, the RTOS checks to see if there's a task with higher priority than the current task and then switches to that task.  If a task blocks (sleeps), then the RTOS gives processor time to a lower priority task. 

By default on the Make Controller, the RTOS tick is 1 millisecond.  For most communications and control applications, this is just fine.  However, in some sensing applications you need microsecond timing.  So why not just make the RTOS tick shorter?  Well, you can definitely do that but it takes the processor some small amount of time to switch between tasks.  Once you get down much shorter than a millisecond, you're just spending most of your time switching between tasks, and not as much time running tasks.

So, ultimately it depends on your application whether or not you want to use the RTOS.  Currently, most of the Make Controller API is based on the assumption that an RTOS is being used.

Tasks

The most important part of the RTOS is a task.  You can have many tasks happening simultaneously although, as you might imagine, it's best to be as efficient as possible with your use of them.  A task is just a function, really, except it allows you to sit inside it forever, sleeping when you need to wait for something.  It's important to always sleep at some point - otherwise, the processor will never give time to any of the other tasks.  All tasks have the same signature - they look like:

void MyTask( void* parameter );

When you create a task, you need to specify a couple of things:

1. its name (arbitrary)
2. its priority - how important this task is relative to other tasks.
3. the amount of memory to allocate it - this is a little touchy-feely, and is discussed in the Memory section of this tutorial.

TaskCreate( MyTask, "Mine", 1000, 0, 1 ); // create the task, called "Mine, with 

void MyTask( void* parameter )
{
  // initialization here

  while( 1 )  // now loop forever
  {
    // do your task
  }
}

Check the Task documentation for more details.

Priority

When tasks are created, they are assigned a priority - from 0 to 5. Higher priority tasks will always run instead of tasks with lower priorities. And tasks that have the same priority take turns in a round robin process. The only time lower priority tasks get to run in a system with tasks with different priorities is when the higher priority tasks either sleep or are waiting for input from something.

It is a common source of problems to create a high priority task and then forget to sleep, allowing lower priority tasks to run. In Heavy the Blink task is run with the lowest priority, so if the Controller status LED stops blinking it might be an indication that some task is hogging the system.

Communication between tasks

When all your code is in one task, you never have to worry about different tasks accessing data and resources simultaneously. When you have multiple tasks, however, you do. The problem comes when you do an operation that has multiple parts. Task A starts working on the operation, but runs out of time. The operating system switches over to the other task, which then starts working on the same data. When the operating system switches back to the first task, it proceeds unaware of what might have happened. Disaster frequently results.  Tasks sometimes need to communicate with each other. This is done with message queues and semaphores.

Message queues are a feature that allows tasks to safely send and receive data amongst themselves. A task can sit waiting for a message, using no processor time at all. Another task can post a message to the queue and the first will be woken up and will be given the message.

Semaphores are a way to serialize access to a resource in a thread-safe way.

Check the Semaphores and Queues sections for details on how to use these.

Memory

Important concepts about how memory is used on the Make Controller.

Memory allocation

int bufferSize = 1024;
char *bufferPtr = Malloc( bufferSize );
if( bufferPtr != NULL )
  // then we allocated successfully

Free( bufferPtr );

Balancing the heap

Memory (stack) for tasks

char buffer[1024];

Big memory consumers

• The network system.  By far the biggest consumer of memory.
• The web server.
• printf and snprintf.  Compiled under newlib, these functions end up requiring quite a bit of memory.  Use them with caution.

Networking

Important concepts in using the Make Controller's Ethernet capabilities.

• If you're connecting to any kind of webserver or web application, you're almost for sure going to use TCP
• If you're communicating via OSC, chances are you'll want to use UDP
• If you absolutely need to know that your data gets where it's going, use TCP
• If you're sending lots of data and don't want the overhead of using TCP, use UDP

Debugging

How to debug your projects.

  int Debug( int level, char* string, ... );

  Debug( DEBUG_ALWAYS, "Hello" );

  Debug( DEBUG_ERROR, "Oh no!  No memory" );

  Debug( DEBUG_MESSAGE, "Done parsing.  Length %d", length );

IO Sharing

An overview of the mechanism used on the Make Controller to prevent double-use of the IO lines.

The Application Board has eight 1A outputs that can be used for a variety of different purposes. They can be used as single channel outputs, in pairs to drive motors or in fours to drive up to two stepper motors. This flexibility creates a problem - how to share all these lines in the easiest way possible?

The solution we arrived at was to have an arrangement where subsystems like Motor that need to use two different IO lines for each motor need to lock those lines before they'll run successfully. Let's say that we wanted to use Motor 0. The two lines that Motor 0 uses are the Digital Output lines 0 and 1. We'd like it if code requesting to use Digital Out 0 or 1 while the Motor is being used would be denied.

The most obvious way to do this is to force all users of all subsystems to Open( ) or Lock( ) the subsystem before use and Close( ) or Unlock( ) the subsystem afterwards. But this is adds an additional level of complexity that we didn't think was convenient. Especially since in the majority of cases an IO is used only once and requiring an additional step for the rare case where an IO is put to multiple different uses would be frustrating.

What we decided to do instead was to permit calls to subsystems to attempt to lock the relevent IO's up upon first use. If another subsystem attempts to use an IO that has been previously locked, that second subsystem is denied access. All the user of a shared IO needs to do is to remember to call subsystem_SetActive( 0 ) to deactivate a subsystem. When there is no sharing, there are no special considerations at all. Just use it.

Here are a couple of examples. The first shows how to use non-conflicting subsystems.

  // use a digital out - set digital out to 1
  DigitalOut_SetValue( 0, 1 );

  // use a non conflicting motor - motor 1 uses digital outs 2 & 3
  Motor_SetSpeed( 1, 1023 );

There is no need to worry about opening or closing a device since there are no conflicts.

The second example shows how to use conflicting subsystems.

  // use a digital out - set digital out to 1
  DigitalOut_SetValue( 0, 1 );

  // Now we're done with using DigitalOut 0 as a regular output,
  // deactivate it
  DigitalOut_SetActive( 0, 0 );

  // use a conflicting motor - motor 0 uses digital outs 0 & 1
  Motor_SetSpeed( 0, 1023 );