USB-Servo/common/usbservo.h
2006-10-28 12:40:42 +00:00

218 lines
8.4 KiB
C

#ifndef __usbservo_h_included__
#define __usbservo_h_included__
/**
* \file usbservo.h
* \brief Global definitions and datatypes, used by the firmware and the commandline-client. Also contains the main doxygen-documentation.
* \author Ronald Schaten
* \version $Id: usbservo.h,v 1.1 2006/10/28 12:40:42 rschaten Exp $
*
* License: See documentation.
*/
/**
* \mainpage USB-Servo
*
* \section sec_intro Introduction
*
* The USB-Servo is a device to control a servo via USB. A servo is a motorized
* device that is commonly used in remote controlled cars and planes. I built
* this device to activate a toy puppet. The puppet has a button on its bottom,
* if you press the button the puppet collapses. When the computer is able to
* press the button, I can use the puppet to signal information like someone's
* online-state in the Jabber-network: when my friend goes online, the puppet
* stands up, when he logs off it collapses.
*
* Servos are connected with three-wire-cables. A red and a black one for the
* power, and a yellow one for the signal. Power has to be between 4.8 and 6
* volts, so the 5 volts from the USB-port is in the range. The signal doesn't
* take much current, so you can connect it directly to the controller. The
* angle of the servo is controlled with pulse width modulation (PWM). It gets
* a signal of about 50Hz (one pulse every 20ms), the length of the pulse tells
* the servo the angle to adjust.
*
* A problem that I didn't really solve is the power consumption: I don't know
* the current that runs through the motor. It seems to be low enough not to
* cause any problems, but I don't know how high it will get when the servo is
* blocked. <b>YOU HAVE BEEN WARNED</b>, I don't feel responsible for USB-ports
* catching fire... :-/
*
* There are three parts included in the distribution: The firmware for an
* ATmega8 microcontroller, a commandline-client that can be run under Linux,
* and the circuits needed to build the device.
*
* This project is based on my USB-LED-Fader, which itself is based on the
* PowerSwitch example application by Objective Development. Like those, it
* uses Objective Development's firmware-only USB driver for Atmel's AVR
* microcontrollers.
*
* Objective Development's USB driver is a firmware-only implementation of the
* USB 1.1 standard (low speed device) on cheap single chip microcomputers of
* Atmel's AVR series, such as the ATtiny2313 or even some of the small 8 pin
* devices. It implements the standard to the point where useful applications
* can be implemented. See the file "firmware/usbdrv/usbdrv.h" for features and
* limitations.
*
* \section sec_install Building and installing
*
* Both, the firmware and Unix command line tool are built with "make". You may
* need to customize both makefiles.
*
* \subsection sec_fw Firmware
*
* The firmware for this project requires avr-gcc and avr-libc (a C-library for
* the AVR controller). Please read the instructions at
* http://www.nongnu.org/avr-libc/user-manual/install_tools.html for how to
* install the GNU toolchain (avr-gcc, assembler, linker etc.) and avr-libc.
*
* Once you have the GNU toolchain for AVR microcontrollers installed, you can
* run "make" in the subdirectory "firmware". You may have to edit the Makefile
* to use your preferred downloader with "make program". The current version is
* built for avrdude with a parallel connection to an stk200-compatible
* programmer.
*
* If working with a brand-new controller, you may have to set the fuse-bits to
* use the external crystal:
*
* \code
* avrdude -p atmega8 -P /dev/parport0 -c stk200 -U hfuse:w:0xC9:m -U lfuse:w:0x9F:m
* \endcode
*
* Afterwards, you can compile and flash to the device:
*
* \code
* make program
* \endcode
*
* \subsection sec_client Commandline client and demo application
*
* The command line tool and the demo application require libusb. Please take
* the packages from your system's distribution or download libusb from
* http://libusb.sourceforge.net/ and install it before you compile. Change to
* directory "commandline", check the Makefile and edit the settings if
* required and type
*
* \code
* make
* \endcode
*
* This will build the unix executable "usb-servo" which can be used to control
* the device, and the demo application "xservopointer".
*
* \section sec_usage Usage
*
* Connect the device to the USB-port. If it isn't already, the servo will move
* to the 0-position.
*
* \subsection sec_commandline Commandline client
*
* Use the commandline-client as follows:
*
* \code
* usb-servo status
* usb-servo set <angle>
* usb-servo test
* \endcode
*
* \subsubsection sec_params Parameters
*
* - \e angle: The angle you want to set the servo to. 0 is full left, 255 is
* full right.
*
* \subsubsection sec_examples Examples
*
* <b>Get the status of the servo:</b>
* \code
* usb-servo status
* \endcode
* This will tell you the angle the servo is currently put to.
* \code
* Current servo angle: 42
* \endcode
*
* <b>Set a new angle:</b>
* \code
* usb-servo set 23
* \endcode
* This sets the servo to the angle 23. 0 is full left, 255 is full right, so
* with 23 the servo will be almost on the left side.
*
* <b>Test the device:</b>
* \code
* usb-led-fader test
* \endcode
* This function sends many random numbers to the device. The device returns
* the packages, and the client looks for differences in the sent and the
* received numbers.
*
* \subsection sec_xservopointer Demo application xservopointer
*
* This is a pure fun thing, nobody will need it. That was reason enough to
* write it...
*
* To use it, you have to position the servo centered above the screen (with a
* little tweaking in the source, you can change that position). Then, you
* attach a pointer to the servo and start the application.
*
* You'll never ever have to search for your mouse cursor in the future. The
* pointer on the servo will always show you where to search.
*
* \section sec_drawbacks Drawbacks
*
* The main drawback is the mentioned power consumption. I tested it with my
* servo on my notebook, it is not sure to work on other systems. <b>THIS MAY
* BE HARMFUL FOR YOUR COMPUTER</b>, and nobody but yourself will be
* responsible for any damages.
*
* Another, not so big problem is the crude implementation of the PWM. I got
* the timing-values by trial and error, and they might not fit on your servo.
* On the other hand, I think that servos should be interchangeable. But this
* is my first and only one, so I can't say anything about that.
*
* \section sec_files Files in the distribution
*
* - \e Readme.txt: Documentation, created from the htmldoc-directory.
* - \e firmware: Source code of the controller firmware.
* - \e firmware/usbdrv: USB driver -- See Readme.txt in this directory for
* info
* - \e commandline: Source code of the host software (needs libusb). Here, you
* find the pure commandline client (usb-servo) and the fun demo application
* (xservopointer).
* - \e common: Files needed by the firmware and the commandline-client.
* - \e circuit: Circuit diagrams in PDF and EAGLE 4 format. A free version of
* EAGLE is available for Linux, Mac OS X and Windows from
* http://www.cadsoft.de/.
* - \e License.txt: Public license for all contents of this project, except
* for the USB driver. Look in firmware/usbdrv/License.txt for further info.
* - \e Changelog.txt: Logfile documenting changes in soft-, firm- and
* hardware.
*
* \section sec_thanks Thanks!
*
* I'd like to thank <b>Objective Development</b> for the possibility to use
* their driver for my project. In fact, this project wouldn't exist without
* the driver.
*
* \section sec_license About the license
*
* My work - all contents except for the USB driver - are licensed under the
* GNU General Public License (GPL). A copy of the GPL is included in
* License.txt. The driver itself is licensed under a special license by
* Objective Development. See firmware/usbdrv/License.txt for further info.
*
* <b>(c) 2006 by Ronald Schaten - http://www.schatenseite.de</b>
*/
#include <stdint.h>
/* return codes for USB-communication */
#define msgOK 0 /**< Return code for OK. */
#define msgErr 1 /**< Return code for Error. */
/* These are the vendor specific SETUP commands implemented by our USB device */
#define CMD_ECHO 0 /**< Command to echo the sent data */
#define CMD_GET 1 /**< Command to fetch values */
#define CMD_SET 2 /**< Command to send values */
#endif