Contents

Overview

The purpose of this guide is to get you up and writing code against the C Libraries for the BrainStem®.  This guide assumes you are a savvy C programmer with good familiarity with your compiler environment, pre-processor functions, and software organization. 

Basic Concepts

The BrainStem C Development happens on the host computer.  This refers to the computer that is communicating with the BrainStem(s) via the link.  This link is typically the serial port but other options exist.  There are several libraries that help package and ship the protocol to the BrainStem modules.  This is done with no specific reference to which type of link you are using.  In this way, you can later change to some other link format without re-writing your code. 

There are two fundamental concepts to understand:

• Stream
• Packet

Streams are a data abstraction that can recieve or transmit bytes without any policy.  Some streams can both send and receive bytes.  These bytes are 8 bits with no flow control or record structure.  It is just a stream of bytes.  This is very similar to the C++ stream concept.  Streams should be used wherever possible to allow cross-platform support and changing out the underlying data transport without changing your code. 

Streams are implemented along with several other basic I/O mechanisms in the aIO library.  This library offers a tokenizer, file I/O, symbol table, settings file, and timing abstractions.  Using these allows your code to gracefully move around between platforms and versions of your Operating Systems.  The aIO library calls are documented in the C section of the BrainStem Reference. 

Packets are the basic exchange element to and from the BrainStem modules.  These packets can be sent across the link (again, typically serial port) or across the IIC module from other devices.  Packets have very little policy.  They contain an address byte, a length byte, and zero or more data bytes. 

The aStem library handles the creation, debug logging, sending, receiving, and formatting of packets.  Although the packet protocol is simple and easily managed on your own, we strongly urge you to stick to the aStem library as it is done, tested, and you will get any future enhancements to the protocol for free (such as error correction) with just a re-compile.  The aStem library calls are documented in the C section of the BrainStem Reference. 

Preparing for C Development

To start with, you will need the libraries, source files, and include files required for software development.  These can all be downloaded via the internet. 

Step 1

Directory Structure

The entire BrainStem directory tree is self-contained.  All settings, preferences, applications, and shared libraries are all in the tree.  This allows you to install the tree anywhere, move it around, and remove it without trying to track down a specific preference, registry, shared library or settings file.  The directory structure is also quite flat as it is supported on many operating systems with very minimal file systems at best (handhelds and embedded systems). 

There are three directories that are most important for C Development, aInclude, aSource, and aBinary.  The aInclude directory contains the files you will need to include in your code to access the library and support routines.  The aSource directory contains the source code for the support routines and the include files on operating systems where a shared library has an accompanying library include file (such as .lib files for .dll files on Windows).  Finally, the aBinary directory contains the actual shared library files as well as the destination executable files. 

As you develop, you can write code however you like but we suggest you make a directory under the brainstem root level for your code and then create sub-directories for each application you write in that directory.  Your final object code should land in the aBinary directory to avoid any path problems when the Operating System tries to load the shared libraries.  If you do this and stick to project relative references to files, you should have very few problems building and running your code.  In addition, you will easily be able to move the source tree around on your system(s) without any ill effects. 

Required Defines

There are only a couple of required defines to worry about.  You will to signal what Operating System you are writing code for with a global define as follows:

• aWIN for Windows 95, 98, NT, 2000, XP
• aMAC for MacOS
• aUNIX for Linux
• aPALM for PalmOS
• aWINCE for WinCE

Access Paths

Since all the files are not in a specific directory, you will likely need to specify a search path (hopefully relative) to the three directories listed above.  On Windows using MSDEV, this can be done in the project options dialog (with settings like "../../aInclude").  On Unix, this is best done with the -I compiler directive.  Other systems typically have similar options. 

Examples

There are some basic example programs in the C Development distribution.  Even if the compiler you are using is not supported with a project file or makefile, it is useful to look through these examples to see some of the typical structure in a program that talks with the BrainStem. 

Basic Structure

Most code for the BrainStem follows a similar main loop:

The other tasks should not starve the system processing.  If they do, the heartbeat will be lost.  Some adjustment can be made with a slower heartbeat speed on the BrainStem or disabling link-based heartbeats altogether but this is strongly discouraged. 

If you have other tasks that need longer processing times (AI processing, path planning, mapping algorithms, etc.) you may want to fire these off in a separate thread and manage the packets in and out with messaging.  How to do this is strongly dependent on the Operating System and other factors and is beyond the scope of this guide. 

Convenience Functions

Most any BrainStem command can found in a wrapper function that builds the packet, sends it down the link, and waits on the reply packet.  These are named for the specific I/O functions and mirror the similar routines in the TEA language.  For instance, to read analog voltage from the BrainStem module at address 4, you would do something like:

This would create a packet for the A/D request, ship it, and then wait for the reply packet.  It would then retrieve the reading from the reply and store the value in the storage for "val" from the call.  This is not part of the library and is supplied as both an include file "aA2D.h" and a source file "aA2D.c".  You can look at the code in "aA2D.c" or other source files to see how this is all done. 

Asynchronous I/O

All data requests for the BrainStem modules are asynchronous which means you make a request and then the reply comes back to you.  This approach does not block any processors waiting for the data to come back but it takes some getting used to.  The above A/D reading is and example of this.  The "aStem_GetPacket" call lets you supply a filter function to sniff the packets coming in to find the reply to a specific request or requests.  The packets that are not the ones being sought are queued up for later processing.  Most of this asynchronous behavior is hidden in the convenience functions but it is important to understand.  Again, inspection of these supplied routines is a great way to sort this out should you need to do similar things. 

Learning More

This is a start at getting up and coding against the BrainStem module interface libraries.  Please let us know if there is other information you need or if you get stuck in this process.  We want to improve this document to get people up and running more quickly. 

Specific Compilers, Hardware, Operating Systems

We would like to support every compile environment we can but we cannot also justify the cost of each environment and the upgrades associated with keeping up-to-date with each.  If you have a specific compiler you would like to see examples for and have access to a legal and free copy for use to use in house to create examples as well as on-going support, we will consider supporting all of our examples on that particular compile environment.  We cannot violate any licensing agreement to do such work and therefore must have a full license for such work. 

Similar to the compiler issue, we would like to support as many machine and operating system architectures as possible.  If you have a specific hardware or OS that you would like supported and can provide the hardware for such support on an on-going basis, we will consider porting the libraries to that hardware and managing them.  There must be a sound reason to support new hardware and a community of users that warrants such an effort. 

What's Next

You may want to look at the document in the reference on coding conventions used at Acroname.  This borders on religion so take what you like from it but it is useful information that reinforces some of the ideas described here.