Demand Peripherals     Robotics and Automation Made Easy

Application Programmer's Interface

API refers to the protocol by which programmers control and monitor peripherals. The protocol uses ASCII strings sent over TCP connections. Using ASCII strings makes the protocol easy to learn, and using TCP lets the protocol work with any programming language.


   Application Architecture
   API Examples
   Sample Programs
   Power-up Sequence



The diagram below shows a typical architecture of the application programs running on a Linux host. The program dpserver provides the interface between the low level register read/write protocol to the FPGA and your high level applications that manage the peripherals.

The architecture supports more than one controlling application and applications can use either the select() family of routines for demultiplexing or have a separate thread for each TCP connection. Typically when your applications start they will open connection to port 8880 and issue a dpcat command (see below). This TCP connection is now dedicated to receiving a stream of sensor data from one peripheral. Add the file descriptor to the select list if you are using select() or just wait for data if you are using threads. You will probably find that you have one TCP connection for each monitored sensor and an additional connection that you use to send configuration changes to the peripherals.

A driver is that part of a peripheral that runs in dpserver and implements the API for that peripheral. The dpserver program receives packets from the FPGA and routes those packets to the appropriate driver. Dpserver also accepts TCP connections from applications and routes ASCII commands and data to the appropriate driver. The driver translates API commands into the appropriate low level register read and write commands to send over the FTDI USB-to-serial interface. There is always a one-to-one correspondence between FPGA peripherals and drivers. Since they are loaded dynamically drivers are implemented as shared libraries.



As described above, dpserver is a host resident program that has to be installed prior to using the system. Install dpserver with the following commands:

   tar -xf dpserver-latest.tgz
   cat dpserver
   sudo make install
The default installation directories are /usr/local/bin and /usr/local/lib. You can examine /usr/local/lib to see the .so files that are the individual peripheral drivers.

Before starting dpserver be sure to download the FPGA image to the FPGA card. Put the serial port into raw mode so that CR is not translated into CRLF during the download.

   sudo stty -F /dev/ttyUSB0 raw
   sudo cat DPCore.fpga > /dev/ttyUSB0
Of course you may need to modify the above since your FPGA card may not enumerate as ttyUSB0.

There are a few command line options for dpserver that are worth mentioning. By default dpserver listens on TCP port 8880. If you have more than one FPGA card or if port 8880 is already in use you can use the "-p" option to set the listen port. The "-f" option keeps the program in the foreground and prevents it from becoming a daemon, and the "-e" option routes error messages to stderr instead of syslog. A typical invocation of dpserver might look like this:
   dpserver -ef /dev/ttyUSB0
You can add yourself to the "dialout" group while you are experimenting with dpserver and the FPGA card.

Peripheral number zero, the enumerator, has a list of the peripherals in the FPGA image. This list dictates which .so driver files are loaded into dpserver. You can use the "-s" option to override the enumerator list and load a new driver instead of the one specified in the enumerator. For example, say you have a gpio4 in slot 2 and you want to overload it with a driver that you created called You can replace the expected driver with yours using the command:

   dpserver -ef -s2:bumper /dev/ttyUSB0



Peripherals are identified either by their name or, if there is more than one instance of a given peripheral in the system, by their slot number. Each peripheral has a set of one or more resources associated with it. A resource may be compound in that it may take more than one value. For example, a "config" resource may group common configuration values into one line.

A resource is an application visible name given a configuration parameter or a sensor value. For example, the buttons and LEDs on the FPGA cards are are in the "bb4io" peripheral and have resourse names of "buttons" and "leds" respectively. Resources can be read-write, write-only, or read-only depanding on the nature of the resource. Most configuration resources are read-write, and sensor reading are usually read-only.

Some sensor resources can be configured to automatically send a reading only when the input changes or when a timer expires. This can greatly simplify your application since you do not need to continuously poll sensors to detect changes. The Peripherals section of this web site gives a detailed description of the meaning and use of the resources for each peripheral



The API consists of space separated ASCII words sent over a TCP connection. Each command (or sensor reading) is terminated by a newline. There are four commands in the API:
   - dpset : write a configuration parameter
   - dpget : read a configuration parameter
   - dpcat : start streaming sensor data
   - dplist : list available peripherals or give help on specified peripheral

The commands have the following syntax

   dpset <slot#|peri_name> <resource_name> <value>
   dpget <slot#|peri_name> <resource_name>
   dpcat <slot#|peri_name> <resource_name>
   dplist [peri_name]


The FPGA card has buttons and LEDs that are visible from the API.

   dpset bb4io leds ff   # turn all LEDs on
   dpcat bb4io buttons   # wait for a button press

The dual DC motor controller peripherals, dc2, has controls for the PWM frequency, the mode (forward, reverse, brake, or coast), the PWM duty cycle, and a watchdog timer that stops the motors if there are no speed updates within a certain time.

   dpset dc2 PWMfrequency 20000    # set PWM freq to 20KHz
   dpset dc2 mode0 f     # motor 0 in forward mode
   dpset dc2 mode1 f     # motor 1 in forward mode
   dpset dc2 watchdog 15 # watchdog set to 1.5 seconds
   dpset dc2 speed0 40   # motor 0 at 40% PWM
   dpset dc2 speed1 70   # motor 0 at 70% PWM

The 6 digit LCD display peripheral, lcd6, lets you control individual segments or output fully formed digits.

   dpset lcd6 display 1234.56 # display a number 
   dpget lcd6 segments        # ask which segments are on

The octal 12-bit analog-to-digital peripheral, adc812, lets you specify the sample rate and whether or not to combine two inputs into one differential input ADC channel.
   dpset adc812 config 25, 0x00  # 25 ms updates, all singled ended
   dpcat adc812 samples   # start sample stream



The following is a simple but complete Python program that shows how to use the dpserver API. The source code is available here:

#!/usr/bin/env python
import socket
import sys

# This program opens two sockets to the dpserver, one
# to listen for button press events and one to update
# the LED display.  This code uses a blocking read but
# a select() implementation would work too.
# Pressing button 1 increments the count, button 2
# clears the count and button 3 decrements the count.
# Buttons are represented as hex values 1, 2, and 4.

# Global state information
count = 0

    sock_cmd = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock_cmd.connect(('localhost', 8880))
    sock_button = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock_button.connect(('localhost', 8880))
    sock_button.send('dpcat bb4io buttons\n')
    # loop forever getting button presses and updating the count
    while True:
        display_count = count
        if display_count < 0:
            display_count = count + 256
        sock_cmd.send('dpset bb4io leds ' "%x" '\n' % display_count)
        key = sock_button.recv(6)
        keyint = int(key[:3])
        if keyint == 1:
            count = (count + 1) % 256
        elif keyint == 2:
            count = 0;
        elif keyint == 4:
            count = (count - 1) % 256

except KeyboardInterrupt:
    # exit on Ctrl^C

except socket.error:
    print "Couldn't connect to dpserver"


The following is a simple but complete C program that shows how to use the dpserver API. The source code is available here: counter.c.

/* Counter.c  :  This program demonstrates the use of the
 * Demand Peripherals API for the Baseboard4 FPGA cards.
 * The idea is that we create a counter and watch the
 * buttons on the FPGA card.  If button 1 is press the
 * count goes down.  If button 2 is pressed the count
 * is zeroed, and if button 3 is pressed the count is
 * incremented.  The count is an 8 bit signed number
 * that is displayed on the LEDs of the FPGA card.
 * Build with: gcc -o counter counter.c
 * Be sure dpserver is running and listening on port 8880

/* Overview:
 *  Open a TCP connection to the FPGA card.
 *  Send commands to flash the LEDs
 *  Open a second connection to the FPGA card
 *  dpcat the button presses on the second connection
 *  loop forever
 *   -- wait for button press (ignore release events)
 *   -- decrement, clear, or increment counter
 * As a tutorial, this program is not flexible, uses
 * magic numbers,  ignores key bounce, and does a very
 * poor job of error checking.  It tries to be brief and 
 * readable instead.

#include <stdio.h>
#include <stdlib.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <unistd.h>
#include <fcntl.h>
#include <errno.h>
#include <stddef.h>
#include <string.h>    /* for memset */
#include <arpa/inet.h> /* for inet_addr() */

static int  cmdfd;          // FD for commands to the FPGA card
static void sndcmd(char *cmd); // send a command to the board, get prompt

int main()
    int8_t counter;         // the 8-bit count to display
    int  tmp_int;           // a temporary integer
    int  evtfd;             // FD for button events from the FPGA card
    struct sockaddr_in skt; // network address for dpserver
    int  adrlen;
    char strled[99];        // command to set the leds
    char strevt[99];        // where to receive the button press string
    int  buttons;           // latest button event as an integer

    // Open connection to DPserver daemon
    adrlen = sizeof(struct sockaddr_in);
    (void) memset((void *) &skt, 0, (size_t) adrlen);
    skt.sin_family = AF_INET;
    skt.sin_port = htons(8880);
    if ((inet_aton("", &(skt.sin_addr)) == 0) ||
        ((cmdfd = socket(AF_INET, SOCK_STREAM, 0)) < 0) ||
        (connect(cmdfd, (struct sockaddr *) &skt, adrlen) < 0)) {
        printf("Error: unable to connect to dpserver.\n");

    /* Blink the LEDs */
    sndcmd("dpset bb4io leds ff\n");
    sndcmd("dpset bb4io leds 00\n");
    sndcmd("dpset bb4io leds ff\n");
    sndcmd("dpset bb4io leds 00\n");

    /* Open another connection to receive button events */
    (void) memset((void *) &skt, 0, (size_t) adrlen);
    skt.sin_family = AF_INET;
    skt.sin_port = htons(8880);
    if ((inet_aton("", &(skt.sin_addr)) == 0) ||
        ((evtfd = socket(AF_INET, SOCK_STREAM, 0)) < 0) ||
        (connect(evtfd, (struct sockaddr *) &skt, adrlen) < 0)) {
        printf("Error: unable to connect to dpserver.\n");

    counter = 0;   // leds are already showing zero

    /* Start the stream of button events */
    write(evtfd, "dpcat bb4io buttons\n", 20);
    /* the above command never returns so we do not use sndcmd() */

    while(1) {
        /* wait for a button press */
        read(evtfd, strevt, 3);    // two digits and a newline
        sscanf(strevt, "%d", &buttons);

        /* Examine pressed button and change counter */
        /* (We don't keep the old button value so do not do
           edge detection.  ie. One button at a time please) */
        if (buttons & 1) {
        if (buttons & 2) {
            counter = 0;
        if (buttons & 4) {

        /* display new value of count */
        sprintf(strled, "dpset bb4io leds %02x\n", (counter & 0xff));

/* sndcmd():  Send a command to dpserver and wait for a response.  The
 *     response will be a prompt character, which we ignore and return,
 *     or an error message which we send to stderr. */
static void sndcmd(char *cmd)
    size_t count;          // number of chars in command to send
    char   c;              // prompt or error message character
    int    retval;         // return value of read()

    count = strlen(cmd);        // should sanity check count
    write(cmdfd, cmd, count);   // should look at write() return value

    /* loop getting characters.  Return on a prompt character '\' and
     * send any other character to stderr. */
    while (1) {
        retval = read(cmdfd, &c, 1);
        if (0 >= retval)
            exit(1);       // did TCP conn go down?
        else if ('\\' == c)
            return;        // got a prompt char.  Done with command
            write(2, &c, 1);    // send to stderr


The following is a simple C program that shows how use the select() system call to monitor several sensor simultaneously. The source code is available here: quad_demo.c.

/* A program to demonstrate how to use Baseboard peripherals  */
/* in an event driven program using select().                 */
/*   The program uses two peripherals, the buttons and LEDs   */
/* on the Baseboard (bb4io), and the dual quadrature decoder, */
/* quad2.  The program configures the quad2 to report every   */
/* 50 milliseconds and prints to standard output the counts   */
/* and frequency of the quadrature inputs.  Pressing button   */
/* one on the Baseboard turns on or off quadratures output.   */
/* The LEDs on the Baseboard are incremented on each reading  */
/* from the quadrature decoder.                               */
/*    gcc -o quad_demp quad_demp.c                            */
/*    ./quad_demp                                             */

/* This program is more complete than the first sample but is */
/* still not production ready.  Please use or refactor this   */
/* code as you see fit for your application.                  */

#include <stdio.h$gt;
#include <stdlib.h$gt;
#include <unistd.h$gt;
#include <netinet/in.h$gt;
#include <sys/socket.h$gt;
#include <sys/errno.h$gt;
#include <sys/time.h$gt;
#include <string.h$gt;

/************************* Defines *****************************/
#define DPSRVADDR    ""
#define DPSRVPORT    8880
#define MXCMD        80   /* limits dpserver command size */
#define MXBUF        99   /* limits size of response from dpserver */

/********************** Global Variables ***********************/
int     fd_cmd;           // fd to send commands to dpserver
int     outenable;        // set ==1 to print quad2 readings on stdout
void    sndcmd(int, char *, int);  // write a string down an FD
void    do_quad(char *);  // process input line of quadrature data

int main (int argc, char *argv[])
    int    fd_quad;       // fd to stream of quadrature readings
    int    fd_button;     // fd to buttons on the FPGA card
    fd_set rfds;          // bit masks for select statement
    int    mxfd;          // Maximum FD for the select statement
    struct timeval tv;    // for the one second timer
    int    ret;           // return value for select() call
    char   cmd[MXCMD];    // print commands to dpserver here
    char   inbuf[MXBUF];  // read from dpserver goes here
    char   qbuf[MXBUF];   // data from the quadrature sensor goes here
    int    qinx;          // index into qbuf
    int    nread;         // return value for read()   
    int    gotline;       // ==1 if found a full line in the data stream
    int    cmdlen;        // length of command to send
    int    i;             // generic loop counter
    int    value;         // value read from bb4io button
    int    count;         // number of quad2 readings
    struct sockaddr_in skt; // network address for dpserver
    int    adrlen;

    /* Initialize the state */
    count = 0;
    outenable = 1;
    qinx = 0;

    // Open connections to dpserver
    adrlen = sizeof(struct sockaddr_in);
    (void) memset((void *) &skt, 0, (size_t) adrlen);
    skt.sin_family = AF_INET;
    skt.sin_port = htons(8880);
    if ((inet_aton("", &(skt.sin_addr)) == 0) ||
        ((fd_cmd = socket(AF_INET, SOCK_STREAM, 0)) < 0) ||
        (connect(fd_cmd, (struct sockaddr *) &skt, adrlen) < 0) ||
        ((fd_quad = socket(AF_INET, SOCK_STREAM, 0)) < 0) ||
        (connect(fd_quad, (struct sockaddr *) &skt, adrlen) < 0) ||
        ((fd_button = socket(AF_INET, SOCK_STREAM, 0)) < 0) ||
        (connect(fd_button, (struct sockaddr *) &skt, adrlen) < 0)) {
        printf("Error: unable to connect to dpserver.\n");

    /* Clear the LEDs */
    cmdlen = snprintf(cmd, MXCMD, "dpset bb4io leds 0\n");
    sndcmd(fd_cmd, cmd, cmdlen);

    /* Configure quad2 for an update every 50 milliseconds */
    /* Then start the stream of quad2 readings             */
    // (note that we send the dpcat command on fd_quad.  This is
    // means the quadrature readings will be available on fd_quad
    cmdlen = snprintf(cmd, MXCMD, "dpset quad2 update_period 50\n");
    sndcmd(fd_cmd, cmd, cmdlen);
    cmdlen = snprintf(cmd, MXCMD, "dpcat quad2 counts\n");
    sndcmd(fd_quad, cmd, cmdlen);

    /* Start the data stream of button presses from the Baseboard */
    cmdlen = snprintf(cmd, MXCMD, "dpcat bb4io buttons\n");
    sndcmd(fd_button, cmd, cmdlen);

    /* Watch for button press events, quadrature readings, and */
    /* timeout each second  */
    mxfd = (fd_quad $gt; fd_button) ? (fd_quad+1) : (fd_button+1);
    while (1) {
        FD_SET(fd_quad, &rfds);
        FD_SET(fd_button, &rfds);
        tv.tv_sec = 1;
        tv.tv_usec = 0;

        ret = select(mxfd, &rfds, (fd_set *)NULL, (fd_set *)NULL, &tv);
        /* if select error -- bail out on all but EINTR and EAGAIN */
        if ((ret < 0) && ((errno != EINTR) && (errno != EAGAIN))) { 
            perror("Failure in select() ");

        if (ret == 0) {  // timeout
            // this timeout does not occur on one second boundaries
            // but one second after the last time we processed a 
            // read-ready file descriptor.  To make a _periodic_
            // timer you would use gettimeofday to intelligently
            // set tv_sec and tv_usec before each call to select().

        if (FD_ISSET(fd_button, &rfds)) {
            ret = read(fd_button, inbuf, MXBUF);
            if (0 $gt; ret) {
                if ((errno != EINTR) && (errno != EAGAIN)) 
                    perror("Error reading button press from bb4io");

            // While tempting in its simplicity, the code below has a bug.
            // There is no guarantee that read() will return the newline
            // at the end of a button sensor reading.  The next read would
            // see the newline from the previous reading and not see the new
            // value.  This case is handled properly for quad2 readings.
            if (sscanf(inbuf, "%d", &value) == 1) {
                if (1 == value)        // output quadrature readings on first button
                    outenable = 1;
                else if (2 == value)
                    outenable = 0;     // suppress readings on second button

        if (FD_ISSET(fd_quad, &rfds)) {
            // increment count and send to LEDs
            cmdlen = snprintf(cmd, MXCMD, "dpset bb4io leds %x\n", count & 0x00ff);
            sndcmd(fd_cmd, cmd, cmdlen);

            // read() is not guaranteed to return full lines of text.  Since we may
            // get part of a line, we need to store the partial line (qbuf) while
            // waiting for the next read.  Worse, if the processor is busy we may
            // find more than one line of input in the buffer.  We need to scan the
            // collected characters looking for a newline.  If found we process the
            // line and move any remaining characters to the beginning of the buffer.
            // The code below would normally go in a subroutine that is used for
            // reading sensor streams.

            /* Get data from quadrature sensor.  There may already be characters */
            /* in the buffer so add to end of qbuf */
            nread = read(fd_quad, &(qbuf[qinx]), (MXBUF - qinx));
            if (0 $gt;= nread) {
                if ((errno != EINTR) && (errno != EAGAIN)) 
                    perror("Error reading the quadrature peripheral");
            qinx += nread;

            /* Scan for a complete lines. */
            do {
                gotline = 0;
                // Scan for a newline.    If found, replace it with a null
                for (i = 0; i < qinx; i++) {
                    if (qbuf[i] == '\n') {
                        qbuf[i] = (char) 0;
                        gotline = 1;

                        // move any remaining characters to start of buffer
                        (void) memmove(qbuf, &(qbuf[i+1]), (qinx - (i+1)));
                        qinx -= i+1;
            } while ((gotline == 1) && (qinx $gt; 0));

/* sndcmd() : send a command to the dpserver.  Report      */
/* write errors to stdout but try to continue.             */
void sndcmd(int fd, char *cmd, int length)
    int     nwrt;   // number of bytes written

    if (0 $gt;= length) {
        printf("Error sending command of length %d\n", length);

    nwrt = write(fd, cmd, length);
    if (nwrt != length) {
        printf("Error sending command to dpserver.  Wrote only %d of %d bytes\n", nwrt, length);


/* do_quad() : get quadrature readings from a line of sensor data. */
void do_quad(char *qline)
    int    ret;           // return value for sscan() call
    int    tick0, tick1;  // quadrature ticks
    float  period0, period1; // seconds to get ticks
    float  freq0, freq1;  // tick frequency

    ret = sscanf(qline, "%d %f %d %f", &tick0, &period0, &tick1, &period1);
    if (4 != ret) {
        printf("error reading quadrature ticks and periods\n");

    if ((0 == tick0) || (0 == period0))
        freq0 = 0.0;
        freq0 = (float) tick0 / period0;
    if ((0 == tick1) || (0 == period1))
        freq1 = 0.0;
        freq1 = (float) tick1 / period1;

    // print the counts and their frequency
    if (outenable)
        printf("%d %f %d %f\n", tick0, freq0, tick1, freq1);

    // In  a fully event driven system, this is where we
    // would do the PID loop to control motor speed.
    // do_pid(freq0, freq1);
    // and where we could do odometry
    // do_odometry(tick0, tick1);




At power-up the FPGA is unprogrammed and all FPGA pins are pulled high. You download the FPGA image (DPCore.fpga) over the USB-serial link. The image is a binary file so you have to put the serial link into a mode that does not translate a newline character into a newline and carriage return. Once the serial port is configured you can download the FPGA binary using the Linux 'cat' command. Here are the commands to load the FPGA image to a Baseboard4 that enumerated on the USB bus as ttyUSB0:
      sudo stty -F /dev/ttyUSB0 raw
      sudo cat DPCore.fpga > /dev/ttyUSB0
After the FPGA is loaded the status LED on the Baseboard4 will turn green.

It is awkward to deal with serial ports when you are not a privledged user. Since most serial ports are owned by the 'dialout' group. you may find it convenient to add youself the dialout group with the command
      sudo adduser YourName dialout
As a member of the dialout group you can use the serial port without using the sudo command.

Once the FPGA is loaded you can start the dpserver program. The only required option is the device name of the USB serial device to the FPGA card. Keeping the program in the foreground with the -f option lets you see any start-up errors. The -e option is handy to force errors to standard-out and not the system logger.

When dpserver starts it does not know what peripherals to expect in the FPGA. What is in the FPGA is listed in the enumerator peripheral which is always in slot zero. The dpserver issues dpget commands to slot zero to read the list of peripherals in the FPGA. Once it has the list it loads the driver library for each peripheral in the list. Once all of the drivers are loaded the program opens the TCP socket to listen for connection requests from your applications.


FPGA Defined Peripherals
User Interface
FPGA Configuration
FPGA Buttons & LEDs
Text LCD and Keypad
Quad WS2812 Interface
Quad Slide Pot
Tone Generator
IR Recv/Xmit
6 Digit LCD
RC Decoder
Keyfob RF Decoder
Rotary Encoder Interface
Motion Control
Dual DC Motor Controller
Dual Quadrature Decoder
Quad 13 Bit Servo
Bipolar Stepper Controller
Unipolar Stepper Controller
Simple Input / Output
Quad Binary Output
Quad Binary Input
Octal Input/Output
32 Channel Binary Output
32 Channel Binary Input
Octal 12-bit ADC
Quad Ping))) Interface
Octal SRF04 Interface
Quad Event Counter
Generic I2C
Generic SPI
Octal 8-Bit DAC
Quad Digital Potentiometer
Quad PWM Output
Quad PWM Input
4 Bit Pattern Generator
Real Time Clock
Dual Watchdog Timers

Interface Cards
User Interface
Audio Amplifier
IR Recv/xmit
Six Digit LCD Display
Keyfob RF Receiver
Rotary Encoder
Quad Switch Card
Text LCD / keypad
Quad Slide Pot
Motion Control
Dual 7-amp H-bridge
Quad Open Drain Driver
Quad 10 Amp Relay Card
Input / Output
Octal 8-Bit DAC
Quad Digital Potentiometer
Octal 12-bit ADC
Octal SRF04
Generic I2C
Generic SPI
USB 2.0 Hub
Real Time Clock
Slot Expander
Octal Input/Output
32 Channel Input
32 Channel Output
Power Distribution Card
15 Amp Power Distribution
5 Volt Switching Regulator
ATX Power Break-Out Card
Disk Drive Power Break-Out
MP43 Aluminum Mounting Plate
WW2 Prototyping Card
WW1 Small Prototyping Card