 | Extended SRF04 Library Example Last Modified: 2006-11-03 | | |
| Acroname Robotics | PDF webpage version  | ||
| | Extended SRF04 Library Example Last Modified: 2006-11-03 | | |
| Acroname Robotics | PDF webpage version | ||
| Introduction Many of the BrainStem downloads include TEA library files dedicated to specific processing tasks and interfacing sensors or other devices. These TEA library files are located in the aSystem subfolder of the main brainstem directory tree. A user may write additional TEA library files and place them in the aSystem or aUser subfolders of the main brainstem directory tree. This example discusses the requirements for making a library file and presents a library with enhanced functions for the Devantech SRF04 range finder. Theory - Creating Custom Libraries A TEA library is a collection of functions, subroutines, macros, or defined values. A TEA program can access any of the routines or defined values in a TEA library by using a #include statement and a file name. Angle brackets around a filename tell the compiler to look for the file in the aSystem folder. Quotes around a filename tell the compiler to look for the file in the aUser folder. Some examples are shown below: #include <aCore.tea>
#include "aMylib.tea"
A TEA library has no main routine so it is not a complete program. A library file also needs some compiler directives for proper compilation. A template for a TEA library file is shown below: /* filename: aMylib.tea */
#ifndef _aMylib_T_
#define _aMylib_T_
/* (include other aSystem files you might need here) */
/* (define constants specific to your application here) */
/* (your functions and subroutines go here) */
#endif /* _aMylib_T_ */
The naming convention for TEA libraries is a lower-case "a" following by a capitalized name. All the code in a library file is wrapped in a #ifndef statement. This statement checks for a defined name that is based on the unique name of the library. This defined name is made with a "_" prefix, followed by the library name, followed by a "_T_" suffix. When the compiler processes a library file for the first time, it enters the #ifndef statement, defines the library name, and builds the code. Once that library name is defined, the processor will no longer attempt to build the code. This #ifndef technique ensures that the code is built only once. It is necessary since many files may include the same library file. If the compiler tried to build the same code more than once, it would encounter duplicate names and generate errors. The recommended naming convention for functions and subroutines in a library file is to use the name of the library, followed by an underscore, followed by the capitalized name of the routine. This provides an easy way to know which file contains the source code for the routine. This convention is also handy for macros and defined values. Creating a library is useful when chunks of code start appearing over and over again in an application. Placing code in one place makes it easier to maintain. Changing or adding code in existing library files is not recommended since installing a new release of BrainStem software will overwrite the modifications. A TEA program that calls library functions can look quite small, but all library routines called by that program will get linked into the executable file. This is important to remember since the BrainStem has a file structure that uses lots of small program files. Source Code - A Library with Enhanced SRF04 Routines One of the first libraries written for the BrainStem is "aSRF04.tea". It contains routines for using the Devantech SRF04 ultrasonic range finder. This file has functions that allow a user to get readings from one SRF04 ranger connected to digital IO pins. One pin acts as an output to initialize the ranger. Another pin acts as an input for measuring the sonar echo pulse from the ranger. The latest BrainStem GP modules have servo outputs that may also be used as digital outputs. They can also be used to initialize the ranger. The old SRF04 library routines could only use digital outputs to initialize the sonar. With four servo outputs, and four digital IO pins capable of pulse timing, a GP module can handle four SRF04s without any additional circuitry.
The following "aSRF04x.tea" library has functions for implementing a sonar interface that uses digital pins or servo pins. It permits the use of multiple sensors. It also conforms to all the requirements described above. Note the #ifndef usage, the routine names, and inclusion of other system files. In the routines for taking sonar measurements, programming is done with raw TEA VM opcodes (the equivalent of BrainStem "assembly language") to make the code as compact as possible. Most system library files use opcode programming to reduce code size. If a user is comfortable with this low-level BrainStem programming, it is worth the effort. The sonar measurement routines use dynamic port calculation based on indexes for the INIT and ECHO pins. In the old SRF04 library, ports are hard-coded based on defines. Calculating port addresses makes the interface more flexible. /* filename: aSRF04x.tea */
#ifndef _aSRF04x_T_
#define _aSRF04x_T_
#include <aIOPorts.tea>
#include <aServo.tea>
#include <aDig.tea>
void aSRF04x_ConfigForServo(char init, char echo)
{
aServo_SetConfig(init, 0);
aDig_Config(echo, 1);
}
void aSRF04x_ConfigForDigital(char init, char echo)
{
aDig_Config(init, 0);
aDig_Config(echo, 1);
}
int aSRF04x_ServoReadInt(char init, char echo)
{
int val = 0;
asm
{
/* precalculate the echo port */
pushsb 5
pushlb aPortDigitalBlockSize
multb
pushls aPortDigital + aOffsetDigitalPTime
adds
/* this will be used to turn off init pulse */
pushlb 0
/* calculate servo config port address */
pushsb 9
pushlb aPortServoBlockSize
multb
pushls aPortServo + aOffsetServoConfig
adds
/* turn on servo output */
pushlb SRV_DSTA /* this sets output bit */
pushss 3 /* copy port address */
popbmx
/* stall to create a pulse width */
pushlb 1
popbm aPortVMTimer
/* turn off servo output */
/* (copy of config port address is still on stack) */
/* (writes the 0 byte initially put on stack) */
popbmx
/* await the echo from precalculated echo port */
pushmsx
/* pop the result into val */
popss 2
}
return val;
}
int aSRF04x_DigReadInt(char init, char echo)
{
int val = 0;
asm
{
/* precalculate the echo port */
pushsb 5
pushlb aPortDigitalBlockSize
multb
pushls aPortDigital + aOffsetDigitalPTime
adds
/* this will be used to turn off init pulse */
pushlb 0
/* calculate digital port address */
pushsb 9
pushlb aPortDigitalBlockSize
multb
pushls aPortDigital + aOffsetDigitalIO
adds
/* turn on digital output */
pushlb 1 /* turns on digital bit */
pushss 3 /* copy port address */
popbmx
/* stall to create a pulse width */
pushlb 1
popbm aPortVMTimer
/* turn off digital output */
/* (copy of digital port address is still on stack) */
/* (writes the 0 byte initially put on stack) */
popbmx
/* await the echo from precalculated echo port */
pushmsx
/* pop the result into val */
popss 2
}
return val;
}
#endif /* _aSRF04x_T_ */
Source Code - Example TEA Program Using Enhanded SRF04 LIbrary A test program for two of the routines in the new library file is listed below. Since the #include statement uses quotes, the library must be placed in the aUser folder for the program to compile. The program takes 50 readings from an SRF04 sonar configured to use digital IO pin 1 for sonar echo timing and servo output 0 for sonar initialization. /* filename: test.tea */
#include <aCore.tea>
#include <aPrint.tea>
#include "aSRF04x.tea"
#define aSRF04_INIT 0
#define aSRF04_ECHO 1
void main()
{
int i;
int r = 0;
aSRF04x_ConfigForServo(aSRF04_INIT, aSRF04_ECHO);
for (i = 0; i < 50; i++) {
r = aSRF04x_ServoReadInt(aSRF04_INIT,aSRF04_ECHO);
aPrint_IntDec(r);
aPrint_Char('\n');
aCore_Sleep(2500);
}
}
Revision History:
| ||||||
| voice: 720-564-0373, email: sales@acroname.com, address: 4822 Sterling Dr., Boulder CO, 80301-2350, privacy © Copyright 1994-2008 Acroname, Inc., Boulder, Colorado. All rights reserved. |
