Welcome to Orangutan-lib
Orangutan-lib is a C library for the Orangutan
family of robot controllers from Pololu
Robotics. Distribution of Orangutan-lib is provided for by Sourceforge.net. It is very much a
work in progress, but releases are posted frequently, and we take
suggestions for new features on the Pololu Robotics Forums. Plans
are also afoot to port the library to the AVR Butterfly, as time
The purpose of Orangutan-lib is to provide enough functionality to get
someone up and running, to do this using (mostly) easy to read code with
lots of comments, and to arrange things so there are as few
cross-dependencies as possible, making it easy to take only those features
you want and incorporate them into your own code. To put this in terms of
robotics, expect Orangutan-lib to give you enough functionality to build a
mini-sumo robot or a line follower. To program a robo-magellan platform,
you'll need to add a lot of your own code.
Orangutan-lib was written under AVR
Studio 4 and WinAVR. It
should work under other development environments, but the Makefiles are
all generated by AVR Studio 4, so expect to have to tweak them. The 0.3
release will include a script for converting all the AVR Studio 4
Makefiles to gcc makefiles. It may work under other compilers, but
there is some WinAVR/GCC specific code that will have to be re-written.
If you're not using AVR Studio 4 and WinAVR, we really can't make any
If you happen to use Orangutan-lib in one of your projects, please
let us know so we can get that warm fuzzy feeling inside that comes from
knowing you've helped someone else. Also, please post information about
your project to the Pololu Robotics Forums so everyone else can take
inspiration from what you've done.
More Functionality Every Day
Orangutan-lib 0.3 has been out for a couple of weeks, but development hasn't stopped. In light of a discussion on the Pololu Forum, software SPI routines are in the pipe, and all three sets of SPI routines are being changed to allow all four modes of operation for the SPI bus. (The code in the 0.3 release only operated in mode 0, but some of the sensor hardware from Sparkfun operates in mode 3! Can't leave out sensors from Sparkfun!)
While testing out some I2C hardware I finally stuck a watch crystal onto an Orangutan and started playing with it. TIMER2 can be used with an external clock source (asynchronous mode - not synchronous with the system clock), allowing a 3.2768kHz watch crystal to generate interrupts once per second. Add some variables and some cascading logic, and you have an interrupt-driven RTC. Still need to add a watch crystal, though. But at about $0.50 it's not a big deal. A bigger deal is that it eats two I/O pins. Cost analysis is up to you.
Still on the subject of I2C, software I2C routines will also be in the 0.4 release. This is a work in progress.
Work on integrating the X2 functionality into Orangutan-lib is chugging right along. (For what it's worth the X2's on-board ATmega168 operates in mode 0, so that worked right out of the box. Thank goodness.)
Since more routines will be added over the next few weeks and months, it bears repeating: In the supported subsystems list to the left, subsystems with an asterisk in front of them are written and in testing, but not in the current release. Still, if you like living on the hairy edge, feel free to grab the source tree from Sourceforge's Subversion server.
One last important notice: orangutan-examples-0.1.zip is very very dated. Most of it works, but the LCD code in that release was the very old, extremely buggy version that was in orangutan-lib-0.1.zip. It doesn't constitute a good example. Before the 0.4 release, the examples will all be cleaned up and released at the same time.
That will likely be the last release of Orangutan-Examples. The original intent was that they would provide single-file examples of things to do with the Orangutan and Baby-Oragnutan. But as the X2 was released and more and more #ifdefs were added to the code, the idea of having a single file program that would run equally well on all three Orangutans and be easily read by a novice programmer got harder and harder. The end result is that new users are encouraged to download Orangutan-lib, and skip the examples altogether. The motivation to fix them... this one last time... is so that the code will at least work reliably.
Sorry for the long-winded update. Back to coding!
Orangutan-lib 0.3 Released
Orangutan-lib 0.3 has been released. Please give it a few hours to clear all the Sourceforge mirrors, and the file will be available. This fixes a pretty massive bug in the LCD code, adds SPI support for the Baby-O, I2C Master for all three platforms, count-up and count-down timers, and a bunch of extension examples that take the core library code and expand on it.
The Orangutan-X2 is partially supported. The LCD code will run on either the Orangutan or the Orangutan-X2. All of the code that is not Orangutan-specific (counters, servos, UART, etc.) will also work on the Orangutan-X2. But the X2-specific hardware (buzzer, melodies, motors, and UART through the SPI port) is currently unsupported. Not to fear, though! Pololu has full code for the SPI interface on the X2 web page. Have a look!
The hope is that Orangutan-lib 0.4, which will also incorporate the X2's onboard hardware, will not be long in coming. But in the meanwhile, the fixes and new features in 0.3 can be used on any of the Orangutans.
And a reminder, in the supported subsystems list to the left, subsystems with an asterisk in front of them are written and in testing, but not in the current release. Still, if you like living on the hairy edge, feel free to grab the source tree from Sourceforge's Subversion server.
To download the latest version either click on the "download" tab at the top of the page or go to the Sourceforge Orangutan-lib Project.
Orangutan-lib 0.3 Coming Soon!
The 0.3 release of Orangutan-lib is coming soon. I know I said that a while ago (quite a while ago) but a lot has happened in the interim that slowed things down and, at the same time, made things better. The Orangutan-X2 is here, which we've started coding for. Not all of the X2 stuff is ready, but enough has changed that a new release is called for. I've also picked up some nice Atmel debugging hardware, an STK500 and a Dragon, which should help future development.
New features in 0.3 will include SPI, I2C Master, count-up and count-down timers, and the beginnings of the Orangutan extensions code, which builds on the base library code in order to interface the Orangutan with specific hardware. Documentation for all of it will be available when 0.3 is released.
There's one serious bug fix that will be going into Orangutan-lib 0.3: In testing out LCD code for the Orangutan-X2, I found out that the LCD code in the 0.2 release was seriously broken. The code that should have been waiting for the LCD's busy flag to clear was busted, and failed to work properly. The fix has been checked into the source tree, and will be in the 0.3 release.
In the interest of not releasing another one like this, please be patient as the last of the testing is done for 0.3 (including further testing on the LCD routines!)
Orangutan-X2 - Signed, Sealed, Delivered
The fine folks at Pololu have donated an X2 to the Orangutan-lib project. I just picked it up from the post office and unwrapped it. Gorgeous!
Code is already being posted to the Pololu Forums, so be sure to go check it out. (And since the X2 docs have a complete set of SPI routines, including a last minute update by Ben from Pololu, which was posted to the forum this morning, the SPI routines will be in the 0.3 release, guaranteed.) Time to get busy!
Orangutan-X2 to Ship Soon
Details on the Orangutan-X2 are up on the Pololu site, and it looks like the new design will be shipping soon!
The new architecture is a big departure from the Orangutan and Baby-Orangutan, so large chunks of Orangutan-lib 0.2 won't work on it right out of the box. This will be rectified by the time 0.3 is released. A lot of the time-intensive tasks on the X2 (PWM for motors, buzzer, UART, etc.) has been moved off a secondary processor (an ATMega168), leaving the primary processor (an ATMega644) almost completely idle. The two communicate over the SPI bus, making the calls for those hardware subsystems a series of SPI calls. This frees up the 644's timers for other tasks. The LCD uses a full 8-bit interface, so the LCD code will also change as a result.
The X2 looks to be a powerful addition to the Orangutan line. Give us a little time and Orangutan-lib will compile as well for it as it does for the other two.
AVRFreaks.net - Orangutan-lib 0.2 reaches 100th download!
Orangutan-lib 0.2 has reached its 100th download from AVRFreaks.net! This is something of a milestone, and sets a nice tone for another announcement: Orangutan-lib 0.3 is coming up soon. A number of new functions have been added that weren't on the list, and software tx-only UART and SPI are the only two left.
In the 0.3 release there will be a new category of goodies: extensions. In the 0.2 release all of the modules that comprise Orangutan-lib are independent and don't rely on each other. This was done to make the buffet-style pick 'n choose nature of the library easier. In the 0.3 release there will be an additional directory for extension code. Extensions will each rely on a single existing Orangutan-lib module, but will provide additional functionality. Already there are two extensions checked into the Subversion source tree: one to read out the Devantech SRF04 ultrasonic rangefinders (which relies on the I2C module), and another for displaying small bar graphs on the LCD (which relies on the LCD module). Additional extensions will be added prior to release, but the core library code will still have no cross-dependencies.
The 0.3 release will also include the script to convert the AVR Studio/WinAVR tree to a UNIX/avr-gcc tree, simplifying the use of the library on UNIX, Linux, and OSX development platforms.
So where do we go from here? That's up to you. If you've got an Orangutan and a project in mind, give Orangutan-lib a try. If it doesn't do everything you want, drop us a line. If the functionality you need is something others are likely to want, chances are it can be developed for the 0.4 release. And if you're using Orangutan-lib on a project and it does do everything you want, please let us know.
UNIX / OSX Support Coming Soon & I2C Master
One of the folks in our local robotics club uses OSX for AVR development. With his help we should soon have better support for the OSX development platform.
I've also set up the avr-gcc toolchain on my Linux machine, so UNIX gcc support should be available soon as well.
My guess is the same fix will address both platforms. So far the differences seem to be minimal. The name of the executable for gcc is different (avr-gcc vs avr-gcc.exe), there are a couple of differences with compiler flags, and avr-size takes different flags as well. If this really is all it takes, then support for these platforms will be a matter of running a script on the orangutan-lib directory tree. (Which is nice, because having to hand-code new Makefiles for every example program in the library would be a pain.) Once the script has been tested on both platforms it'll be checked into the Subversion source tree, and will be included in the next release of Orangutan-lib.
On other news, Peter Fleury kindly gave us permission to include his i2cmaster.h / i2cmaster.c code into the library, so interfacing to I2C devices is possible now. The code has been checked into the Subversion source tree, and will also be included with the next release of Orangutan-lib. Docs will be coming very very soon. Thanks, Peter!
The new version of Orangutan-lib has been released. New in this version is support for the Orangutan's buzzer, pin change interrupts on all general-purpose I/O pins, new symmetric PWM motor code (thanks to Steve!), support for driving up to eight servos on any of the general purpose I/O pins, and hardware UART support.
Documentation has also been updated for almost all of these. You can click on the supported subsystem to your left to be taken to the docs for that subsystem, or you can use the "documentation" tab at the top of the page. Additional docs will be written as time permits.
Plans for the next release are to include Tx-only software UART, I2C, and SPI support.
And a big huge mahalo to the folks at Pololu for fixing my Orangutan after I damaged it! Couldn't have got this release out without you guys.
To download the latest version either click on the "download" tab at the top of the page or go to the Sourceforge Orangutan-lib Project.
New Release (Still) Coming
Sorry, still no 0.2 release. I managed to kill the H-bridge chip on my Orangutan while testing the symmetric PWM code. Pololu was kind enough to replace the chip for me, but until the mail comes in I'm unable to test Orangutan-specific functions (should be in tomorrow). I should be back up and running by the end of the weekend, so it's a temporary setback at the very worst.
Meanwhile, the symmetric PWM code is done and checked into the Subversion tree. It's pwm.c and pwm.h, and will replace the existing pmw0.c, pwm0.h, pwm0_int.c, and pwm0_int.h in the 0.2 release. This code, based off of Steve's pwm0_int code, represents a complete re-write of the older pwm0.c code, so lots has changed: The pins to motor A and the pins to motor B are the reverse of the older code, but it now matches the silkscreen on the bottom of the Baby-O. The code will run either on TIMER0 or TIMER2, based on a flag set in device.h. And behavior is symmetric! Yaaay!
The relay-style motor code has also been dinked with, mostly to match the pin definitions in the new PWM code. The basic functionality is the same.
Range checking has been added to the servo routines. This will be tested quite thoroughly prior to release. (Nothing like stripping a servo geartrain to realize range checking can sometimes be worth the additional overhead. DOH!)
Still to be tested is Steve's new LCD code (I wish I hadn't blown my Orangutan!) and the RS-232 code (two serial level shifters should arrive the same day as my Orangutan). Timers, rotary encoders, I2C, and SPI will wait until the 0.3 release.
In the meanwhile, a first stab at honest to goodness documentation is now online. You can either click on the "documentation" link at the top of the screen, or you can click on any of the supported subsystems in the menu to the left. Subsystems marked with an asterisk are not in the current release, but are in testing for the next release.
New Release Coming
We've been busy over the past few days. Symmetric PWM code is in testing, as is a more efficient set of LCD routines that's closer to the CrystalFontz datasheet. Servo routines have been added, and RS-232 and I2C routines are in the works. There are more examples with more on the way, and real honest-to-goodness documentation should be done in the next few days.
It's time for a new release! Orangutan-lib 0.2 and Orangutan-examples 0.2 will be out some time in the next several days. Please be patient as there's a lot more code to test this time.
New Developer - New Code
Steve Judd has kindly offered to join the coding team for Orangutan-lib! Steve has a strong background in both programming and robotics, so this means really good things for the library. Steve is going through the LCD code to bring it more in line with the LCD datasheet, and has written a set of generic timer routines. These will be included in the library in the near future. I've also made some progress on a set of routines for driving R/C servos using the Orangutan and Baby-O. These will also be in the library in the near future. So expect a new release in the next week or two with new functionality and some bug fixes.
A very kind soul at work has loaned me their oscilloscope for some indeterminate period of time. This has been the big snafu hang-up with getting the servo code working. I can never tell if it's doing what I expect! With the loan of the scope, though, I should be able to get the servo code tested and debugged some time in the very near future. This should also let me test the PWM motor code more thoroughly than I've done so far, and get the countdown timer code knocked out, too. A big thanks to my co-worker, and to people everywhere who humor the geeks around them.
I'm in the process of putting all of the source code to Orangutan-lib under Subversion revision control. The Subversion tree will be made availble on the Sourceforge page for Orangutan-lib, so if you like downloading bleeding-edge source code, you can. This is also a step in the right direction for collaborative development of Orangutan-lib.
Version 0.1 of Orangutan-lib and Orangutan-examples released
The first release of Orangutan-lib and Orangutan-examples are both available on the Sourceforge Orangutan-lib Project. This first release cleans up a lot of the commends, formatting, and coding conventions of the pre-release version that had been posted on the old site. It has been tested on an Orangutan and on a Baby-Orangutan. My apologies for the changes to the command names for some of the library's functions. I'm pretty sure they're beginning to cement, and probably won't change in the future.
Sourceforge project approved!
Sourceforge approved my request to start a project for Orangutan-lib! I've begun migrating my old site to this new one, and will be moving all the source code to Sourceforge as soon as possible. Please bear with me as this transition happens.