#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. YOU HAVE BEEN WARNED, 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 * 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 * * Get the status of the servo: * \code * usb-servo status * \endcode * This will tell you the angle the servo is currently put to. * \code * Current servo angle: 42 * \endcode * * Set a new angle: * \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. * * Test the device: * \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. THIS MAY * BE HARMFUL FOR YOUR COMPUTER, 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 Objective Development 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. * * (c) 2006 by Ronald Schaten - http://www.schatenseite.de */ #include /* 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