The CEENBoT-API

About the CEENBoT-API

The CEENBoT-API or Application Programming Interface is a statically-compiled C library targeting the ATmega324P microcontroller in the CEENBoT 324 v2.2x platform. The library allows users to write C programs using Atmel Studio IDE compiler toolchain that invoke functions provided by the library which facilitate the use and control of the CEENBoT's electronics without the need to have intimate technical details of the CEENBoT's electronic subsystems at the register level. The API consists of an extensive library of functions that allow users to easily control various CEENBoT hardware resources, which include:

  • Writing character strings to the LCD (Liquid Crystal Display).
  • Controlling the Stepper Motors, whose parameters include speed, acceleration, and distance.
  • Access attached PS2 controllers connected on the CEENBoT's PS2 controller port.
  • Control of the LEDs (Red and Green LEDs) on the CEENBoT.
  • Access the three user push-buttons for user interaction.
  • Query the state of the infrared obstacle avoidance sensors.
  • Easy access and control serial ports available through the CEENBoT's I/O connectors: I2C, SPI, and UART ports.
  • Support for various peripherals such as the Parallax Ultrasonic Ping sensor, CMUcam4 and CMUcam5 (aka, Pixy).
  • Operate the speaker device for emitting beeps and tones.

In addition, the API provides services that are commonly needed in programming tasks, of which the most important is timing services, the ability to initiate timers to either operate as a 'one-shot' or 'persistent' ones which trigger a flag, or a user callback at specified intervals. This also include services for accessing the CEENBoT's ADC (Analog-to-Digital) subsystem for connecting analog devices such as photoresistors for providing additional sensing capability for robotic tasks and line-following sensors.

For this reason, the CEENBoT-API is more of a monolithic middleware (or microkernel) API, because it is dual function. It provides a simplified interface for programming the robot, but also provides some basic services that are typically furnished by operating systems of 'sufficient functionality'.

A key significant reason behind the existence of the CEENBoT-API is to support the Mobile Robotics course at the University of Nebraska-Lincoln (Omaha) campus.


Requirements

If you want to write C programs that make use of the CEENBoT-API you must be able to fulfill the following requirements:

  • You need a CEENBoT: Must be platform 324 v2.2x, and it must have an ATmega324 (or ATmega324P). CEENBoTs with the ATmega1284/P are NOT officially supported.
  • You must have downloaded and installed Atmel Studio 7, which is currently available for free (possibly with registration) from Microchip's website. Unlike AVR Studio 4, Atmel Studio 7 includes the AVR C toolchain as part of the installer which is very convenient.
  • You need to have an AVR-ISP (In-System Programming) cable. This can be obtained from Atmel or from third-party vendors. It should preferrably be a USB type AVR-ISP. An AVR-ISP programmer is pictured below.
  • AVR ISP Programmer
    Fig. 1 -- AVR ISP Prgrammer (USB type).
  • A Windows system. Atmel Studio only runs on Windows. If you have a Mac, you can install it on a Virtual Machine such as Parallels. If you don't know what that even means, pretend you didn't read this particular point.
  • Lastly, it should go without saying, that to do CEENBoT-API programming, you must be somewhat proeficient in the C programming language. This is the biggeset hurdle time and time again for people who want to use the CEENBoT-API. Many of the hurdles I see students deal with are easily traced to not understanding how the C language works. You have to be comfortable with writing functions, taking parameters, returning them, using pointers, parameter types, using structures, etc. If you don't have this, you'll be stumbling on your own feet time and time again. 'The C Programming Guide' by Kernighan and Ritchie (the K&R book) is the greatest, most beautiful straight-foward C programming book ever written. Maybe you should start there.

Use of the CEENBoT-API with AVR Studio 4 is no longer supported. However, you can still use it at your own risk. Old documentation is kept for this purpose. Please note that using Atmel Studio IDE is so much better and highly recommended. AVR Studio 4 only works on old 32-bit Windows (such as Windows XP) and does not work with newer versions of Windows. You should avoid it if at all possible.

The above set of requirements assume you're NOT using the CEENBoT Utility Tool and have not migrated your CEENBoT to make use of the Program Loader in which case you would need a USB-To-Serial cable (with gender changer) instead of the AVR-ISP cable. Further information can be found here.

In 2016 Atmel was purchased by Microchip. As a result, any attempt to visit Atmel's website in the the atmel.com domain will redirect you to Microchip's website, even though links to Atmel will appear on the web. What this means for Atmel's product line and their software tools is unknown, but as of Jan. 9, 2018, you can still download Atmel Studio version 7.


How You Should Proceed

The general steps you should carry out to get started with the CEENBoT-API is as follows, provided, of course, that you meet all the requirements:

  1. Quickly read the Things You Should Know Before You Use the API section further down on this page. After you've done that, and you're sure you want to proceed...
  2. Go to Atmel's website, and create an account with them (i.e., you need to register to download their software, which is FREE).
  3. Download and install the latest version of Atmel Studio 7 (you cannot do this unless you register with Microchip/Atmel).
  4. Download the CEENBoT-API static library from the Downloads section below, extract its contents in a known location. The static library is distributed as a 'ZIP' file. Just decompress its contents. It contains a static library (*.a) and header files (*.h).
  5. Download and read the CEENBoT-API: Getting Started Guide. That guide shows you how to set up a CEENBoT-API project in Atmel Studio 6 (whose instructions are still valid for Atmel Studio 7), and also how to create a template so that you don't have to setup a project (and its settings) from scratch, which is the recommended strategy for users who own their own PCs (i.e., with administrative privileges). You will be shown how to compile a CEENBoT-API program. You will be repeating these steps when you write your own CEENBoT-API programs, so it is very important you read that entirely and are successful in completing the tutorial.
  6. Once you're confident after having completed the Getting Started Guide, download and read the CEENBoT-API: Programming Fundamentals. That guide shows you some of the most common tasks that users will want to know and learn about when writing CEENBoT-API programs.
  7. Download and keep handy the latest CEENBoT-API: Programmer's Reference. That document is over 250 pages long, and it contains all the details regarding all the function calls for all the subsystems that are accessible via the API including function arguments, return types, and detailed usage. This document is a reference. Just like a dictionary cannot teach you how to write, the API reference does not teach how to program. It contains detailed information once you become experienced with the API, not withstanding the fact, you should be *very* comfortable programming in the C language.
  8. Write short test programs to aid in your understanding of the API features and to ensure something does and behaves the way you think it does (sometimes that's not the case).

Downloads

Below you will find download links to the latest version of the CEENBoT-API static library along with any pertinent documentation that exists for it. Under the Download Link column, right-click and select "Save As...", or something along those lines.

Please note that there's an UN-OFFICIAL source of the CEENBoT-API's source code that has been posted here. These updates were neither supervised, supported, nor sanctioned by me. The source is NOT up to date and does not constitute the latest revision of the API. The individuals involved in this project have released API revisions with revision numbers that collided with internal [and official] development. You are cautioned against using it in production/field work. I do hope to get the official source code to be made available soon if time allows.

Please read the Things You Should Know Before You Use the API section further below before you proceed with experimenting with the API.

Please note that revision numbers have no relation to other files or the static library. The fact some documents have the same revision number is pure coincidence.

CEENBoT-API Static Library
File/Desc. File Type Revision Size Posted Download
Link
CEENBoT-API static library v2.06.000R ZIP v2.06.000R 209KB 3/12/2017 Download

CEENBoT-API Documentation
File/Desc. File Type Revision Size Posted Download
Link
CEENBoT-API: Getting Started Guide (Atmel Studio 6/7) PDF 1.5 2.8MB 1/11/2019 Download
CEENBoT-API: Getting Started Guide (AVR Studio 4) [Old] PDF 1.08 2.8MB 7/4/2015 Download
CEENBoT-API: Programming Fundamentals PDF 1.12 237KB 1/10/2016 Download
CEENBoT-API: Programmer's Reference PDF 1.14 1.5MB 1/10/2016 Download

Miscellaneous Items
File/Desc. File Type Revision Size Posted Download
Link
CEENBoT v2.23 Platform 324 Schematics PDF 2.23 409KB 7/4/2015 Download
CEENBoT v2.21 Platform 324 Schematics PDF 2.21 1.4MB 7/4/2015 Download
Original v2.2x CEENBoT Platform 324 Factory Firmware (for ATmega324P) HEX 1.104R 74KB 1/18/2019 Download
Original v2.2x CEENBoT Platform 324 Factory Firmware (for secondary MCU ATtiny48) HEX 1.104R 6KB 1/18/2019 Download

The schematics were created by the makers of the CEENBoT, and are provided here for convenience. The original source is located here. Be cautioned that these links may be removed at any time as the schematics are the property of CEENBoT, Inc.

The original CEENBoT's Factory Firmware is provided here also for convenience. The original files are located here. However since CEENBoT, Inc's site seems to be 'changing', I feel compelled to make a bonafide good faith effort to make sure the firmware remains available in case the original web source is no longer available. Please note that the original 'factory' firmwares are the property of CEENBoT, Inc. For battery-charging purposes, the factory firmware for the ATmega324P MCU is what you're after. Make sure to right-click and select "Save As..." since browsers tend to just want to display the HEX file as text, even though that's not the intention here. Version v1.104R is the last official version thus far released by CEENBoT, Inc. Please do make an effort to visit CEENBoT, Inc's site first when seeking the factory firmware, before choosing to download from the link in the above table.


Very Important: Things You Should Know Before You Use the API

Your CEENBoT comes pre-programmed with a default firmware, which throughout all documentation in this site is simply referred to as the factory firmware authored by the makers of CEENBoT. It is very important for users to be aware that the 'factory firmware' and a 'CEENBoT-API Program' are completely separate and distinct pieces of firmware.

When you write CEENBoT-API programs and you flash up and overwrite the contents of FLASH memory of your CEENBoT to run your API program, that you are erasing the factory firmware given everytime you flash up a program, a 'chip erase' is performed as part of the programming process of the ATmega324 microcontroller. And to be clear, even if you didn't do a 'chip erase' the previous firmware is overwritten by flashing up a new one. In either case, and when you do this, you do not have access to any of the factory firmware's features, of which the most important is the ability for you to RECHARGE YOUR BATTERY! So let me reiterate this one more time to be clear:

You need the factory firmware to recharge your battery AFTER you're done playing with your CEENBoT, whether it was running an API program or not.

This means that you need to have access to the factory firmware in hand (i.e., saved somewhere on your computer, or thumb drive, etc) ready for when you need the battery charging feature. You can obtain the factory firmware in two ways:

  • By downloading the latest version from CEENBoT, Inc's website located here. Look under Firmware for CEENBoT, Inc 324 Version 2.21 and 2.23 boards. The file you're interested is ATmega 324P microcontroller (v. 1.xxxR) Or...
  • By using your AVR-ISP cable to retrieve the factory firmware that is present on your CEENBoT (assuming you haven't yet overwritten it with an API program) and save that on your machine for later use. Also on CEENBoT, Inc's website, there's a document called Updating Firmware on the CEENBoT, which discusses how to upload the factory firmware to your robot. These same instructions for 'updating' firmware can be used to upload any firmware targeted for the CEENBoT. Do note that the document was written with AVR Studio 4, while the current generation of AVR tools is Atmel Studio 7, so it is a little outdated. Also, the CEENBoT-API: Getting Started Guides(s) show you how to upload API firmware to your CEENBoT using AVR Studio 4 or Atmel Studio 7. These same instructions can also be used to upload ANY firmware targeted for the CEENBoT (including the factory firmware).

So, please keep in mind the following points:

  • Keep a copy of the factory firmware and know WHERE to always get the latest version of the firmware (Answer: CEENBoT, Inc's website).
  • Know how to flash up your factory firmware to your CEENBoT. The procedures are the same as those outlined in the CEENBoT-API: Getting Started Guide(s), so once you become comfortable flashing firmware, it'll become second nature.
  • CEENBoT-API programs have NO BATTERY CHARGING CAPABILITY! You will NOT be notified, nor given ANY indication (by design) if your battery is low or in need of recharging. However, low battery levels become apparent through visual and performance cues: (e.g., Robot struggles to move, or motion is not as precise; LCD backlight begins to dim, specially when the motors are moving; robot begins to reset itself for no reason, etc).
  • Very Important: Hooking up the CEENBoT to its charger has NO EFFECT while it is running a CEENBoT-API program. Once again, IF YOU WANT TO CHARGE THE CEENBoT, YOU NEED TO HAVE THE FACTORY FIRMWARE FLASHED IN!
  • Don't be a fool: If your CEENBoT begins to shows symptoms of low battery while running an API program, STOP what you're doing, flash up the factory firmware and recharge your CEENBoT. DO NOT WAIT UNTIL THE BATTERY COMPLETELY DIES OUT TO DO THIS! YOU NEED ENERGY TO FLASH YOUR FIRMWARE ONTO THE CEENBoT --- IF YOUR BATTERY IS DEAD, THIS CANNOT BE DONE! (This is a WORST-CASE scenario!)

If your CEENBoT shows symptoms of a low battery while running API programs, STOP what you're doing, flash up the factory firmware and recharge your battery! If your CEENBoT completely dies out, you will be UNABLE to do this!

Now that we have that out of the way, go and head over to the 'Downloads' section and start downloading.

There's a suit of software tools called the CEENBoT Bootloader Package. This contains a bootloader and a program loader that runs on the CEENBoT, which gives you the ability to upload multiple CEENBoT-API programs, and to simply call up a program by RESETTING the CEENBoT and selecting which program you'd like to load by selecting one from the little menu shown on the CEENBoT's display (LCD), which is very convenient. This also includes having IMMEDIATE access to the factory firmware, that is necessary for charging your battery. For more information see the 'The CEENBoT Bootloader' section of The CEENBoT Portal.