pxaRC - R/C and robotics software for Linux/PXA255/PXA270

$ tar zxvf pxarc-$VERSION.tar.gz
$ cp -r pxarc-$VERSION/package/buildroot $SOMEWHERE/gumstix-buildroot/package/pxarc
$ cd $SOMEWHERE/gumstix-buildroot/
$ echo 'source "package/pxarc/Config.in"' >> package/Config.in    # Optional (to see pxaRC in menuconfig).
$ make                                                            # Makes sure the toolchain is built.
$ make TARGETS="linux pxarc"                                      # Compiles pxaRC itself.
$ ls build_arm_nofpu/root/lib/modules/*/misc/                     # Newly-created modules should be there. 

$ tar zxvf pxarc-$VERSION.tar.gz
$ cd pxarc-$VERSION/src
$ vi Makefile    # Adjust $(BR) and $(LINUX_VERSION)
$ make
$ scp *.ko root@$IPADDRESS:
$ scp iprc_rx.target root@$IPADDRESS:iprc_rx
$ scp ppmrelay.target root@$IPADDRESS:ppmrelay
$ scp short2ascii.target root@$IPADDRESS:short2ascii
$ scp ascii2short.target root@$IPADDRESS:ascii2short
$ scp long2ascii.target root@$IPADDRESS:long2ascii
$ scp ascii2long.target root@$IPADDRESS:ascii2long

pxa_rtsched.ko provides real-time capabilities based on the PXA's fast interrupts (FIQ). Its main features are:

pxa_rtsched is intended to be used by other kernel modules such as pxa_opwm and pxa_ipwm through the API in pxa_rtsched.h. It has no user-accessible interface, apart from printing statistics in dmesg when unloaded.

The timer period is 271 ns for the PXA255 and 308 ns for the PXA270. This translates into about 12 bits of resolution when encoding or decoding typical R/C signals. In practice, due to as yet unidentified reasons, worst-case jitter and latency can exceed ±3 µs on a heavily loaded 200 MHz processor. This is good enough for most R/C applications, where servos have a dead-band (hysteresis) of several microseconds.

Figure 5.  20 µs pulses generated by pxa_rtsched, with ±2 µs jitter

pxa_rtsched uses OSMR1 (OS Match Register 1), which is normally available on ARM Linux. OSMR0 is used by the system timer, and OSMR3 is used by the watchdog.

The following tricks are used in order to reduce latency:

pxa_opwm.ko is a timer-based PWM/PPM signal generator for the PXA255 and PXA270, implemented as a loadable Linux kernel module. It can be configured to a generate a single multi-channel PPM signal and/or the associated single-channel PWM signals. Signals can be output on any GPIO pin.

pxa_opwm does not use the hardware PWM generators of the PXA.

pxa_opwm replaces pxa_mpwm, a previous implementation with 8-bit resolution.

Figure 6.  OPWM waveforms (PPM mode); meaning of timing parameters

GPIO pins, channels and timings are configured with module parameters as illustrated in Table 2, “ pxa_opwm module configuration examples ”.

A user-mode process controls pxa_opwm by writing 16-bit unsigned integers in host endianness to device special files. See Table 3, “ pxa_opwm devices ”. Signal generation begins after a program has opened the device and written values for all channels.

When the process releases the device, all outputs are reverted to logic 0. This should cause most ESCs to shutdown and most servos to become idle. This safety feature can be disabled with the module parameter persistent=1.

pxa_opwm is a straightforward application of pxa_rtsched. To generate a PPM frame of N pulses, pxa_opwm schedules a timed sequence of 2*N tasks (N for rising edges, N for falling edges). The associated optional PWM signals are toggled by the same tasks.

pxa_ipwm.ko is a PWM/PPM/DCM signal decoder and pulse counter based on edge-triggered GPIO interrupts, implemented as a loadable Linux kernel module.

GPIO pins, signal formats and timings are configured with module parameters as illustrated in Table 4, “ pxa_ipwm module configuration examples ”.

Figure 7.  PWM decoding; meaning of timing parameters

Figure 8.  PPM decoding; meaning of timing parameters

Figure 9.  DCM decoding; meaning of timing parameters

User-mode processes access pxa_ipwm by reading from a device special file. See Table 5, “ pxa_ipwm devices ”.

In PWM/PPM/DCM mode, read() fails with -ETIMEDOUT if no measurement more recent than timeout is available. If the signal does not match the configured timings, read() fails with -EIO (see figures). Otherwise it returns the latest measurement (without waiting for the next pulse). The channel value format is the same as for pxa_opwm.

In pulse counter mode, read() returns a 32-bit unsigned integer in host endianness. The first invocation of read() immediately returns the current value of the counter. Subsequent invocations wait until the counter increases. There may be some latency (configured with timeout=...); this is because there is no easy way for a FIQ routine to wake-up a user process.

A pulse counter can be set to an arbitrary value by writing to the device. However, there is no mechanism for atomically reading and resetting a counter.

pxa_ipwm registers with pxa_rtsched to receive edge-triggered GPIO interrupts. The FIQ handler records a timestamp for each edge into a FIFO queue (implemented as a circular buffer), and timestamps are translated into PWM/PPM/DCM values when read() is called. The FIQ handler also increases the pulse counters.

For an alternative to pxa_ipwm on the Gumstix platform, see [ROBOSTIX_RC_INPUT].

pxa_cfcam.ko captures images from a CMOS sensor connected directly to the PCMCIA/CF port of the PXA255. The hardware interfacing is described in [CFCAM].

Features:

pxa_cfcam_pnm.ko is a plugin for pxa_cfcam which decodes CMOS sensor data in Bayer format into uncompressed PNM format (24-bit color or 8-bit greyscale). The PNM header can be disabled with the module parameter pnm_header=0.

# modprobe pxa_cfcam
# modprobe pxa_cfcam_pnm
# dd if=/dev/cfcam0 of=/tmp/image.ppm bs=2M count=1

# modprobe pxa_cfcam
# modprobe pxa_cfcam_pnm bpp=1
# dd if=/dev/cfcam0 of=/tmp/image.pgm bs=2M count=1

# modprobe pxa_cfcam
# modprobe pxa_cfcam_pnm pnm_header=0

/* Simplified example; error handling not shown. */
int fd = open("/dev/cfcam0", O_RDWR, 0);
unsigned char *mem = mmap(NULL, 320*240*3*2, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0);
while ( 1 ) {
  u32 offset;
  read(fd, &offset, sizeof(offset));
  unsigned char *rgb = mem + offset;
  /* 'rgb' points to 320*240*3 bytes of RGB data */
}

The implementation is not yet user friendly. Sensor configurations are hard-coded in pxa_cfcam.c. A configuration is selected with the module parameter sensor=N. To add support for a new sensor or a new image format, one must edit the code.

To characterize a new sensor, first obtain raw data as follows:

# modprobe pxa_cfcam sensor=0
# modprobe pxa_cfcam_pnm raw=1 bpp=1
# dd if=/dev/cfcam0 of=/tmp/image.pgm bs=2M count=1

pxa_cfcam first toggles the reset input of the sensor, and optionally configures it with I2C commands. It also sends the required number of clock pulses to cause the sensor to complete its initialization and start producing images.

Afterward, a looping list of DMA descriptor continuously reads raw data from the sensor, clocking it at the same time. Data received during the horizontal and vertical blanking intervals is discarded.

DMA interrupts are generated at the end of each line. When running in synchronous mode (without mmap()), pxa_cfcam transfers and converts data from the DMA buffer into the buffer referenced in the read() system call. When running in asynchronous mode (with mmap()), pxa_cfcam transfers and converts data from the DMA buffer into one half of a previously mmap'ed buffer, while userspace processes the other half. The two halves are swapped when read() is invoked.

pxa_cfcam does not use the HSYNC and VSYNC outputs of the sensor. This requires that the number of clock cycles in each frame and each sync interval be known in advance.