General

Port Descriptions

Links

Vex Robotics under Unix

SDCC for Vex is here!

Using SDCC to program the Vex is unsupported and experimental. Improper programming may result in damage to your robot. I make no claims about the validity or safety of any information provided here.

Requirements

1. You will need 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. To produce a hex file with the correct base address, you need to to use this linker script, which is a slight modification of the default, 18f8520.lkr.
3. A great deal of firmware code is necessary to initialize and operate the Vex controller. The easiest way to get started is by using LibVexBot.

Vexctl

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.)

I have also tried a Keyspan USB to serial adapter with vexctl and it worked very well. You may need a male-to-female serial extension cable (with screws on both ends) to work with adapters other than the Vex's. Standard male serial connectors have posts, while standard female connectors have screws. The Vex dongle doesn't follow this standard: It has a female serial connector and posts. This can be remedied with a serial extension cable that has screws on both ends.

The New LibVexBot C Library

Why LibVexBot?

The Vex default code is full of cryptic references to PIC hardware resources whose names provide no clue as to what their purpose is in a Vex robot. In order to understand and modify the default code, the programmer has to locate these resources in the PIC spec sheet and/or header files. LibVexBot eliminates the need to know how PIC resources are wired to Vex ports.

For example, to enable interrupts on the Vex interrupt port 1, the default code uses the following code:

    INTCON3bits.INT2IE = 1;
    

In contrast, LibVexBot encapsulates the PIC-to-Vex port mappings, so you can program your Robot using simple, descriptive function calls that relate to the Vex controller as you see it:

    interrupt_enable(1);
    

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

    #define BUMPER1_PORT                5
    #define LIGHT_SENSOR1_PORT          2
    #define INTERRUPT_PORT_FROM_SONAR   1
    #define IO_PORT_TO_SONAR            6
    
    io_get_digital(BUMPER1_PORT);
    io_get_analog(LIGHT_SENSOR1_PORT);
    
    sonar_init_async(IO_PORT_TO_SONAR,INTERRUPT_PORT_FROM_SONAR);
    
    sonar_emit_pulse_async(IO_PORT_TO_SONAR,INTERRUPT_PORT_FROM_SONAR);
    
    if ( sonar_data_available(INTERRUPT_PORT_FROM_SONAR) )
	sonar_distance = sonar_read_async(INTERRUPT_PORT_FROM_SONAR);
    

Beginning programmers can program the Vex with no knowledge of the PIC processor details. Since the library is 100% open source, more advanced programmers can learn more by studying the library code, and modifying it as they please.

The source code includes an sample program with a rewritten version of the VEX default user routine using only LibVexBot calls, and debug output for the remote control, a limit switch, bumper switch, light sensor, line-follower, shaft encoder, and ultrasonic range finder.

LibVexBot was developed using MCC18 under FreeBSD and Wine. MPLAB projects are also included with the source code for Windows users.

Terminal Emulators

Cutecom under FreeBSD (click to enlarge)

Cutecom is a simple, easy-to-use graphical terminal emulator for serial communications, based on the QT user interface library. It is specifically designed with hardware developers in mind, so it isn't cluttered with lots of stuff you won't need, and includes some nice features that you won't find in other tools (like hex output).

Piklab

MCC18 under Wine

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)

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"

Virtualization

VirtualBox is probably worthy of some special attention. It's very fast (on my MacBook), has a nice QT based interface and a feature set comparable to Parallels, and it's free and open source. It currently runs on Linux, Mac, Solaris, and Windows hosts, and will likely be available for other platforms in the near 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 from the command line 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)

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)

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

    -kernel-kqemu 

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.