Unix Programming Resources


AIX BEOS Cygwin DesktopBSD FreeBSD Gentoo Linux Mac OS X
NetBSD OpenBSD PC-BSD QNX Solaris Ubuntu

Vex Quick Links

Download OpenVex
SDCC
Tutorial
Tutorial PDF
API Documentation

General

Project Home
More about POSIX
Open standards
FreeBSD and MacPorts
Robotics Programming FreeBSD on PowerPC

Shameless Commercial Plugs

C/Unix Programmer's Guide
Consulting Services

Free Unix Software

Office

OpenOffice.org
AbiWord

WEB

FireFox
Thunderbird

Graphics

Blender
FreeCAD
GIMP
Inkscape
Scribus

Open Source Programming Tools for Vex

This page is an information repository for programming Vex robots (and to some extent other PIC micro-controller based systems) under Unix, Mac, and Windows (Cygwin recommended).

Cortex Support

Vex Cortex support in OpenVex and Roboctl is currently in the planning stages. Starting with OpenVex 0.5.0, the API is no longer fully compatible with 0.4.4 and earlier. The API is being cleaned up and generalized to accommodate differences between the PIC and Cortex controllers. There are many small changes, but it should not prove difficult to modify programs written for 0.4.x. Improvements to the Doxygen API documentation are being made to help ease the transition.

The Cortex requires the gcc arm-none-eabi tool chain. FreeBSD ports and MacPorts for the gcc tool chain and stm32flash, a loader for the Cortex controller, are now available in my development ports collection. We have successfully tested stm32flash using HEX files produced by easyC (which runs fine under Wine). Stm32flash is a little buggy, and you may need to unplug/re-plug the USB cable to/from your computer occasionally to get a successful upload. Otherwise, it works well and is easy to use.

Vex Programming with SDCC


SDCC (Small Device C Compiler) is an open source C compiler that supports several different micro-controllers. SDCC is available in most *nix ports systems including FreeBSD ports, MacPorts, Gentoo Portage, Debian packages, etc. See the SDCC WEB site for instructions on installing on platforms that do not currently offer a port.

The entire system described here for programming Vex with SDCC has been tested on FreeBSD, Linux, Mac OS X, and Windows (Cygwin). The OpenVex source distribution contains a collection of "robotize" scripts to help you install these tools on any of the above environments. If you're running these tools under another platform, please send me a note so I can mention it here.

A DocBook tutorial for programming Vex with SDCC is in the works. (Click here for PDF version) This is a work in progress, and feedback is appreciated.

Vex programming under FreeBSD/KDE4.

[Cutecom

Many thanks to Ag Primatic for his tenacity and brilliant detective work, which made the SDCC port a reality much sooner than expected.

What you'll need

  1. SDCC version 2.7.0 or later in order to successfully compile for the Vex's PIC 18F8520 MCU (use sdcc -mpic16 -p18f8520 file.c).
  2. A make program. BSD or GNU make work best.
  3. The OpenVex API library (See below).
  4. Vex programming hardware (the orange USB-serial cable, dongle, and RJ45 cable). This is included with the commercial programming kits (easyC, MPLAB, RobotC, all of which run only on Windows) but can also be purchased separately. (P/N: 276-2186)
  5. An editor or IDE to write your code. I use APE (Another Programmer's Editor), but any editor should work.
  6. A programming tool (for uploading firmware to the Vex controller). Unix/Mac/Cygwin users can use vexctl, part of the roboctl project (see below).
  7. A terminal emulator. For *nix systems, including Mac, I recommend cutecom. For Windows, Bray++ Terminal is the best tool I've found. Both are described in detail below. Both are much more flexible than the terminal included with the IFI loader.

Vexctl

Programs can be uploaded to the Vex robot from *nix and Cygwin using the vexctl command, part of the roboctl project. Besides being a multi-platform program, vexctl also has the advantage of being much faster than the Windows IFI loader. Default firmware uploads typically take about 5 seconds (2280 bytes/sec) vs. the 20-30 seconds I've experienced with the Windows IFI loader.

Communicating with the controller requires a serial port and driver. Modern Macs do not have serial ports. The orange USB-Serial adapter in the Vex programming kit uses the PL-2303 chip set from Prolific. There are two drivers available for the Mac.

The commercial driver is available at this link. After installing the driver, plugging in the USB-serial adapter will create the device node /dev/cu.usbserial.

There is also a PL-2303 driver available at Sourceforge. It creates a device called /dev/cu.PL2303-0000101D. This driver is much slower, and doesn't seem to work with Parallels. (You may be unable to connect the USB device to Windows.)

Both FreeBSD and Linux come with a driver for the Prolific adapter. Run "man vexctl" after installing roboctl for more information.

You can also use a serial port directly if your PC has one. Note: Standard male DB-9 serial connectors have posts, while standard female connectors have screws. The Vex dongle has a female serial connector with posts, and hence cannot be plugged into the back of your computer of any other standard male DB-9 serial port. A serial extension cable with screws on both ends will resolve this.

I have also tried a Keyspan USB to serial adapter with vexctl and it worked very well.

The OpenVex API Library (formerly LibVexBot)

The OpenVex API is an open source C library which makes it easy to program Vex robots using SDCC or Microchip's MCC18 compiler.

OpenVex was developed on FreeBSD using SDCC, and MCC18 under Wine. It has also been tested on Mac (Intel and PowerPC), Ubuntu Linux, and Cygwin. It is the world's first SDCC-compatible firmware for Vex robots, and the only available option for programming the VEX from non-Windows systems. Best of all, OpenVex is FREE, and always will be. OpenVex is released and distributed under the GNU Public License.

Why OpenVex?

OpenVex is meant to be an educational tool, making it easier to get started with Vex robotics programming while teaching software engineering principles (such as abstraction, coherence, etc.) by example.

Programming in OpenVex is almost as easy as EasyC, without the limitations that hamper more advanced programmers. Beginners can program Vex robots with no knowledge of the PIC processor details. Since the library is 100% open source, more advanced programmers can learn more by studying and modifying the library code.

In contrast, the Vex default code is written entirely at the "bare metal" level, full of cryptic references to PIC hardware resources whose names provide no clue as to what purpose they serve in a Vex robot. For example, to enable interrupts on the Vex interrupt port 2, the default code uses the following:

    INTCON2bits.INT3IP = 0;
    INTCON2bits.INTEDG3 = 1;
    INTCON3bits.INT3IE = 1;
    

OpenVex frees you from such details by encapsulating them in API (application programming interface) functions, so you can program your Robot using simple, descriptive function calls that relate to the Vex controller as you see it. For example, to enable interrupt port 2 on the Vex using OpenVex, you would write:

    interrupt_enable(2);
    

OpenVex supports all the common Vex sensors, using synchronous I/O ports or interrupts where appropriate. You can plug any sensor into any appropriate port: you need only provide the right port numbers when calling the API functions. For example:

    #define BUMPER1_PORT                5
    #define LIGHT_SENSOR1_PORT          2
    #define SONAR_INTERRUPT_PORT        1
    #define SONAR_OUTPUT_PORT           6
    
    ...
    
    io_get_digital(BUMPER1_PORT);
    io_get_analog(LIGHT_SENSOR1_PORT);
    
    sonar_init_async(SONAR_OUTPUT_PORT, SONAR_INTERRUPT_PORT);
    
    ...
    
    sonar_distance = sonar_read_async(SONAR_OUTPUT_PORT, SONAR_INTERRUPT_PORT);
    
For more details, see the complete API documentation.

The source code includes sample code with a complete rewrite of the VEX default code, using only OpenVex calls.

The combination of OpenVex, SDCC, and the Unix platform can greatly reduce the time and frustration of the code development cycle.

Unix systems such as FreeBSD and Linux run far faster than Windows on the same hardware. In addition, they don't require frequent updates, are far less vulnerable to malware, and almost never need to be rebooted. If you like to spend your time being creative, rather than installing updates, removing viruses, and rebooting, you'll love working with Unix.

SDCC on FreeBSD compiles the entire OpenVex 4.4.3 suite (7,774 lines of code) in 3.5 seconds on a ThinkPad T42 (Pentium M 1.6GHz), 1.25 seconds on a desktop system with an Athlon 64 X2 2.2GHz and SATA drive.

Especially problematic are Windows machines that are not in constant use, such as student laptops. A Windows machine that has been sitting in a cabinet for a month could take an hour or more and several reboots to catch up on critical security updates, and will be essentially unusable during this time.

The Test Bot

Specifications:

  • Front-wheel direct drive with omni-wheels in back (maximizes control of front-mounted implement)
  • Shaft encoders geared 1:1 with drive wheels
  • I/O ports 1-4 configured for analog input
  • Implement mounted on servo, range limited by software
  • Ultrasonic sensor mounted on vertical servo shaft for scanning during autonomous mode

Robot used to test OpenVex 0.4.3 and earlier

[Front View] [Bottom View] [Back View]

Robot used to test OpenVex 0.4.4

[Front View] [Bottom View] [Back View]

Terminal Emulators

In order to see debugging output from your Vex code, you'll need a terminal emulator that can receive output from the Vex serial port. Unix has a plethora of terminal emulators and serial communication tools dating back to the simple cu and tip commands, and pre-www geek toys like kermit and minicom.

The nicest terminal I've found for working with the Vex is cutecom (see screen shot above). Use the QT4 version (now the default FreeBSD port, and MacPorts cutecom-qt4[-mac]). If you're using Windows, I recommend Bray++ Terminal over the IFI Loader's terminal. The former is much more powerful and flexible.

A Comparison of Vex Programming Options

  • SDCC and OpenVex

    The only free and open source compiler and library, and the only system that runs on non-Windows platforms.

    OpenVex abstracts the firmware into layers to make it easier to program the Vex at any level. Beginners can use the most abstract layer, which consists of function and macro calls that refer to motor and I/O ports. More advanced programmers can dig into the lower layers to learn more about how the Vex controller works.

  • Microchip's MCC18 and the Vex default code

    Not for the faint-hearted. The MCC18 compiler and MPLAB integrated development environment are somewhat difficult to install and learn. This system was designed for use by professional embedded programmers, not high school students trying to learn about robotics. In addition, the Vex default code is written in a way that makes it extremely difficult, if not impossible, for beginners to tackle on their own.

  • Intelitek's easyC

    The easyC system consists of the MCC18 compiler, WPIlib, which abstracts the firmware in a similar manner to OpenVex, and an IDE with a drag-and-drop interface. This is a nice system for beginners who know nothing about C programming. Unfortunately, programmers typically outgrow easyC rather quickly, and the interface begins to feel cumbersome.

  • RobotC

    RobotC is an interpreted C language that runs on both Vex and Lego controllers. It uses a special firmware that contains an interpreter for RobotC's proprietary byte code. Hence, you must load the RobotC firmware before loading RobotC programs. This system also limits performance, since it involves another program running your program.

    For Lego controllers, the RobotC firmware replaces the default firmware used to run NXT-G and NXC programs. This can be a problem for users who want to switch back and forth between RobotC and the standard firmware, because the NXT brick will only accept new firmware a limited number of times.

    For Vex controllers, the interpreter firmware shares Flash RAM space with your program. MCC18 and SDCC, on the other hand, compile C programs to native PIC machine language, so your program is the only code in the controller's program memory, and it runs at native hardware speed.

Other options for the sake of completeness...

Piklab

Piklab is a KDE-based integrated development environment (IDE) for PIC micro-controllers. It can interface with SDCC as well as commercial PIC compilers. Piklab is available as an official FreeBSD port. An experimental MacPort is available as part of the collection on this site (installed by update_jb_ports).
Piklab running under PC-BSD (Click to enlarge)

[Piklab

Piklab MacPort (Click to enlarge)

[Piklab

Piklab includes a communications interface, but at the time if this writing, it cannot communicate with the Vex. Hence, if you program in Piklab, you will need to use vexctl from the command line to upload your programs.

MCC18 under Wine

One option for running Windows programs (on Intel Unix systems only) is the Wine API. Unlike hardware emulators and virtual machines, which emulate PC hardware in order to run a real Windows (or other) OS, Wine emulates the Windows API (application program interface) so that you can run Windows executables directly under Unix. (Intel based systems only.) This is a much more ambitious endeavor than emulating hardware and letting a real Windows system provide the API, but it eliminates the need for a Windows license and the space required for a Windows installation.

Wine allows us to run the MCC18 compiler from the Unix command line. I've written a set of simple wrappers to make the MCC commands (mcc18, mpasm, mplib, mplink) look like native Unix commands (i.e. you don't need to prefix every command with "wine"). They're available in my FreeBSD ports and MacPorts collections as lang/mcc18_wrapper. For other systems, just download the distfile, unpack it, and install the scripts somewhere in your PATH.

EasyC under Wine

My early attempts at running MPLAB and EasyC under wine met with mixed success, but wine 0.9.59 runs EasyC 2.9.08 almost flawlessly. I still haven't had much luck with MPLAB (student edition v6.61) under Wine, so I run it under a virtual machine (see below).

EasyC under Wine (Click to enlarge)

[EasyC

To install EasyC under Wine: (Contributed by Ivan "Rambius" Ivanov)

  1. Install Wine (e.g. from emulators/wine port on FreeBSD, or PBI on PC-BSD)
  2. Get EasyC (7-day trial available at Intelitek download site)
  3. wineconsole easyC_V2_for_Vex_2908.exe
  4. wineconsole "easyC V2 for Vex.exe"
You may need to specify the full pathname of the .exe file, unless you configure wine to find it automatically.

Virtualization

Some other options to program the Vex include running MPLAB, ROBOTC, or EasyC under a commercial virtual machine such as Parallels, VirtualBox, or the open source QEMU project.

VirtualBox is probably worthy of some special attention. It's very fast, has a nice QT based interface and a feature set comparable to Parallels, and it's free and open source. It currently runs on FreeBSD, Linux, Mac, Solaris, and Windows hosts, and will likely be available for other host platforms in the future.

You may be able to use the Windows IFI loader under the guest Windows OS with some finagling, or you can drop the .hex files onto the Unix filesystem from Windows and use vexctl to upload them.

Windows IFI Loader under Parallels

You must have a Mac serial port driver installed in order to use the USB-serial adapter under Parallels. (See discussion of PL-2303 drivers above.) Otherwise, Parallels won't be able to find the device and offer it to the guest OS through the Devices menu.

Commercial IFI Loader running under Parallels (Click to enlarge)

[IFI

QEMU

QEMU is an open source emulator and virtual machine that runs a wide variety of guest operating systems on a wide variety of hosts. It has some bottlenecks compared with other systems like Parallels and VirtualBox, but the QEMU 0.9.1 under FreeBSD with standard acceleration is plenty fast on my AMD64 system for running EasyC and MPLAB.

I install the QEMU FreeBSD port with the kqemu acceleration module enabled, and launch with:

    qemu -m 256 -localtime -usb -usbdevice tablet winxp.qcow2
    

QEMU run this way has been flawless for me. It does require a little patience, since it takes a few minutes to settle down after booting Windows, and Microsoft Update is rather slow (yes, even slower than on a real machine). You can make make it fairly painless by running Windows for a while every day so that Microsoft Update can do it's thing while you're not using Windows. If you only boot up Windows when you need to use it, you'll be competing with Windows Update all the time.

You can set up and run QEMU guests from the command line (which I prefer), or use a GUI interface like QEMU Launcher, qtemu or AQEMU, all of which are available as FreeBSD ports.

MPLAB under QEMU (click to enlarge)

[MPLAB

Standard kqemu acceleration currently only virtualizes the user code (i.e. non-privileged instructions run by programs). Adding

    -kernel-kqemu 
enables full acceleration, which will cause qemu to virtualize kernel-mode instructions as well. This makes a big difference in speed in some cases, but I've seen some instability when using it, which probably explains why it's not the default mode yet.

I recommend the qcow2 format and a generous virtual disk size (at least 10G for Windows XP). The qcow2 format limits the size of the file containing your virtual disk to the blocks actually used, so allocating a bigger virtual disk won't cost you any more disk space. Changing the size after Windows runs out of room is a real pain, however, so there's good reason not to allocate too small. My virtual disk (winxp.qcow2) has a size of 30G (this is what Windows sees), but currently only takes up 3.6G on my FreeBSD filesystem.

FreeBSD, Linux, and many other Unix systems support sparse files, so using the raw disk format with QEMU won't actually take up more disk blocks than the qcow2 image, initially. However, some common Unix tools used to copy files (e.g. scp) don't preserve sparse files, so I tend to avoid them. I was not able to measure any difference in speed between a Windows XP system on a qcow2 image and the same system on a raw image.