Serial Sense 1.0C








Andrew Chanler 
Orlot@rocketmail.com
May 2004



Description:
    The SerialSense allows anyone to interface simple digital and analog sensors to a computer.  It also gives you the ability to control custom circuits with the digital outputs. This was designed to expand the sensor capabilities of ActiveMedia's Pioneer robots. However, it will work with any PC that has a serial port.  This document is aimed for use inside Pyro, however, serialsense can be programed in python, and c++ (see Appendix A).

Features:
5 floating analog inputs
9 digital IO's
each digital IO is configurable as an input or an output
2 cricket bus ports (see http://www.handyboard.com/cricket for more info on cricket bus devices)

Future Features:
1 hardware encoder



Requirements to use with Pyro on a Pioneer robot.
  Software:
    Linux
    Swig
    Python
  Hardware:
    one free serial port


Note: The port on the side of the Pioneer robot is not a 
    serial input.  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 will give you 2
    serialports. You have to call VersaLogic to order it.
    Go to www.versalogic.com to find their phone number.
    See appendix B for more info on installing the cable.


Setup your Serial Port
1)  Find out where your serial port is in the /dev folder.
    The most common path for COM1 is /dev/ttyS0
    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 your serial port.

2)  Check the permissions on it.
    Assuming your port is /dev/ttyS0 run
    $ls -l /dev/ttyS0
    if the read and write bits are not turned on, then run
    $chmod 666 /dev/ttyS0


How to build the source:

$tar -zxvf serialsense1.tar.gz
$make

This produces two key files:
    _serialsense.so
    serialsense.py

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



Getting started in pyro:

A very simple brian:

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"



At the top of the brain the line
from serialsense import *
imports the SerialSense class into the program.

In the setup method 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 read and write to the different ports on the SerialSense.










Documentation:


Part A) Setup the serial communications.


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.


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


NOTE: If you hold the SerialSense so that the ports are closest to you, port zero is on the far right and port 15 is on the far left. Also note that port 14 and 15 are for future development to add support for a hardware encoder and a connection to a cricket bus.



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.


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. If an invalid port is specified, -1 is returned.


integer set(integer port)
This will set a digital output to +5 volts. Valid port numbers are 11 through 13.  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 digital output 13. And the reciever is plugs into digital input 10.  (note: in order to make this function work, you need to call setupIO(13,0) to make port 13 an output)


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. http://www.handyboard.com/cricket/bus/ 

































Appendix A – Programming outside of pyro

Pyro brains are not the only way to use the serialsense.  You can also program in Python and C++.  

To program in C++, copy the files serialsense.h, serialsense.cpp, and simple.cpp from serialsense.tar.gz to your project folder.  simple.cpp is not needed but it is a sample C++ program that shows how to write your own C++ program that can access the serialsense.


To program in python... well if you can write a pyro brain that uses the serialsense, then you can figure out how to do this outside of pyro.









































Appendix B