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.

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.

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.

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.

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.

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.

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.

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.

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.