SerialSense Documentation

Contents:

1. Introduction

SerialSense allows anyone to interface simple digital and analog sensors to a computer. It also gives you the ability to control custom hardware circuits with the digital outputs. This was designed to expand the sensor capabilities of ActivMedia's Pioneer robots. However, it will work with any PC that has a serial port. This document will show how to use the SerialSense with Pyro and also how to use it in a C++ program.

Features 

  • 5 floating analog inputs
  • 9 digital IO's
  • A dip switch can turn on/off a 47k pullup for each analog input
  • Each digital IO is configurable as an input or an output
  • 2 Cricket bus ports
  • 1 hardware encoder (future feature)

Requirements 

You must have at least one free serial port in order to use SerialSense. I also recommend that you are using Linux. My favorite Linux distribution is Gentoo. If you are using SerialSense with Pyro, then you already have the correct software installed. If you are programming in C++, then all you need is g++. There is a chance that you can program SerialSense in C++ on a Windows machine running cygwin, but this has not been tested.

Note: The port on the side of the Pioneer robot is not a serial port to the internal computer. You must buy a cable from VersaLogic, the makers of the motherboard in the Pioneers, that plugs into a pin header on the motherboard. The part number is CBL-2001. It costs $20 and it will give you 2 serialports. You have to call VersaLogic to order it. Click here for another guide I wrote that shows how to install the cable.

2. Setup

Linux Serial Ports 

First you must find out where your serial port is in the /dev folder. Usually /dev/ttyS0 is the path for COM1. I have also seen systems where it is /dev/ttyS00 and others that have it at /dev/tts/0. For the rest of this document replace /dev/ttyS0 references with the path to the serial port you are using.

Note: On the Pioneer robots I use the serial port is /dev/ttyS2 or /dev/ttyS3

Next you need to check the permissions on your serial port and change them if you do not have read and write privilages.

Code listing 2.1: Checking and Setting Serial Port Permissions

Check the permissions
$ ls -l /dev/ttyS0

Give read/write permissions to everyone.
$ chmod 666 /dev/ttyS0

Important: It is usually not the best idea to give everyone read and write permissions to anything. You can setup the permissions any way that you want. But later if you have problems and you can't figure out what is wrong, do not forget to recheck the permissions.

3. Working with Pyro

Building the Library 

In order to use SerialSense in Pyro, you must first build the shared library and python wrapper by using the supplied makefile.

Code listing 3.1: How to build the source for Pyro

$ wget http://www.cs.uml.edu/~achanler/robotics/serialsense/serialsense1.1C.tar.gz
$ tar -zxvf serialsense1.1C.tar.gz
$ cd serialsense
$ make

This produces two key files:

  • _serialsense.so
  • serialsense.py

Put these two files into the directory where your pyro brain will be.

A Simple Pyro Brain 

Here is a very simple Pyro brain to get you started. This brain does not do anything. It just shows you how to initialize the SerialSense class, open the serial port, and close the serial port.

Code listing 3.2: A very simple brain

from pyro.brain import Brain
from serialsense import *

class SimpleBrain(Brain):
    def setup(self):
        print "opening serial port"
        self.port = SerialSense("/dev/ttyS0")
        self.port.open()
    def destroy(self):
        print "closing serial port"
        self.port.close()
    def step(self):
        print "the step function"
        #insert code here to do something inside the step function

At the top of the brain the line from serialsense import * imports the SerialSense class into the program. In the setup function you must create an instance of the SerialSense class and open the serial port. You need to set the path to your serial port. All that is left is to add function calls in your step function that control the robot and use the SerialSense. Refer to the next chapter for a list of all the different member functions of the SerialSense class.

Note: SerialSense can also be programmed in regular python outside of pyro. If you want to do this, you should be able to figure it out from the calls made in the simple Pyro brain example.

4. Class Documentation

This chapter describes the SerialSense class constructor and all of the member functions you will be using.

Constructor and Setup Functions 

SerialSense(string path) This is the constructor that creates the object that will talk to the SerialSense through the serial port. All the other functions are members of this class.

integer open() This opens the serial port. You will use this function inside of your brain's setup method to open the serial port. If the call fails, -1 is returned. If it secceeds, 0 is returned.

integer close() This closes the serial port. You will use this inside your brain's destroy method to close the serial port. If the call fails, -1 is returned. If it secceeds, 0 is returned.

Input and Output Functions 

These functions are used to read and write to the ports on SerialSense. If you have worked with the HandyBoard robot controller, you will very quickly learn how to use these functions.

integer analog(integer port) This reads one of the analog inputs, ports 0 to 4. If a value is passed that is not 0 through 4, -1 is returned. On success, an 8-bit unsigned integer is returned.

Note: The dip switches inline with the analog ports allow you to turn on and off a 47k ohm pull up resistor. This feature exists because some sensors rely on the pull up to be there and others such as the sharp IR distance sensors do not work with a pull up resistor.

integer digital(integer port) This will read one of the digital inputs, ports 5 through 10. If the voltage on the input is 5 volts, 1 is returned. If the voltage is 0 volts, then 0 is retuned. You can also read the analog ports with this function too. If the analog value is greater then 127, then 1 is returned, else 0. If an invalid port is specified, -1 is returned.

Note: All the digital IO ports have a 47k ohm pull up resistor.

integer setupIO(integer port, integer whichway) This will configure a digital IO pin as either an input or an output. If whichway = 1, then the port will become an input. If whichway = 0, then the port will become an output. This is easy to remember if you think of the first letters of input and output. I is similar to 1 and O is similar to 0. If an invalid port is specified, -1 is returned, else 0 is returned.

Note: All the digital IO ports are configured as digital inputs when the device turns on.

integer set(integer port) This will set a digital output to +5 volts. If an invalid port is specified, -1 is returned, else 0 is returned.

integer clear(integer port) This is the same as set() except that it will set the digital output specified to 0 volts.

Special Functions 

integer sonar() This function will read a devantech SRF04 Ranger. The trigger (connector with red on it) plugs into port 13. And the reciever plugs into port 10.

Note: In order to make this function work, you need to call setupIO(13,0) to make port 13 an output and setupIO(10,1) to make port 10 an input.

void servo(integer reg, integer data) This function will control the Cricket's 8 Servo Motor Controller board through one of the Cricket bus connectors. Refer to the Cricket servo board documentation to get a list of the registers and how they work.

Note: If you would like support for other Cricket bus devices, please send me an email.

5. Programming in C++

To program SerialSense in C++, all you need to do is add the line #include "serialsense.h" to your code, and then compile and link to serialsense.cpp. These files and an example c++ program are in serialsense1.1C.tar.gz. Here is the code from the example C++ program simple.cpp.

Code listing 5.1: code listing for simple.cpp

#include <stdio.h>
#include "serialsense.h"

int main(int argc, char ** argv)
{

        SerialSense *ss = new SerialSense("/dev/ttyS0");
        ss->open();

        while(1)
        {
                printf("Digital input 7 = %d\n",ss->digital(7));
        }
        return 0;
}

Follow these instruction to build and run simple.cpp.

Code listing 5.2: Building simple.cpp

$ wget http://www.cs.uml.edu/~achanler/robotics/serialsense/serialsense1.1C.tar.gz
$ tar -zxvf serialsense1.1C.tar.gz
$ cd serialsense
$ g++ -o simple simple.cpp serialsense.cpp

 Then turn on SerialSense, Connect the serial cable and run the program
$ ./simple

6. Error Messages

There are 3 possible error messages that can be printed to stderr while running SerialSense

"SerialSense: read from serial timed out." This message can occur if SerialSense loses power, if your serial cable gets disconnected, or if you specify the wrong serial port in the class constructor.

"SerialSense: read failed because serial port is closed." This message will happen if you do not call the open() function. Let me know if you find another way to get this message.

"/dev/ttyS0: Permission Denied" You will get this error message if you do not have the permissions set correctly for the serial port you want to use.

7. Bugs

Right now there is one major bug. Digital port 10 cannot be configured as an output. If you do configure it as an output, know matter if you try to set or clear the port, it will always be at zero volts.

8. Links

9. About this Doc

This document was written in an xml format designed by the people who created Gentoo Linux. To learn how to create similar documents, read Gentoo Linux XML Guide and Documentation Development Tips & Tricks.


The contents of this document are licensed under the Creative Commons - Attribution / Share Alike license.
line
Updated 23 Aug 2004
line
Andrew Chanler
Inventor

line
Summary:  This guide shows you how to use the SerialSense.
line
Copyright 2004 Andrew Chanler. Questions, Comments, Corrections? Email Orlot@rocketmail.com.