README

--------------------------------
cdctool 0.0.5
Copyright (c) 2010 Dave Fletcher
All Rights Reserved
--------------------------------

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License. 


-------
PURPOSE
-------

cdctool is a cross-platform serial tool for sending and receiving short
amounts of text from a serial connection.

When building devices with USB capable microcontrollers, a quick and simple
option for communicating with a host PC is to use CDC, a virtual serial port.
This handy mechanism is built into all modern PC operating systems. However,
the way you open a serial port, set line settings, and start speaking serial
are very different between Microsoft Windows and POSIX based platforms. This
library and program bridges the differences between the two APIs and supplies
a console tool for making communication in scripts much simpler.

Example (Windows):

  $ echo "V" | cdctool COM4
  Bumble-B 0.4 (userial 1.6)
  
Example (Linux):

  $ echo "V" | cdctool /dev/ttyACM0
  Bumble-B 0.4 (userial 1.6)


-----------------
COMMAND LINE TOOL
-----------------

`cdctool` is a command line tool. See `cdctool --help` for details on 
program usage. cdctool is a wrapper for the functions in libcdctool.


-------
LIBRARY
-------

`libcdctool` is the C library that `cdctool` uses. It is separated from the
cdctool command line tool so other applications can take advantage of this
cross-platform code.

Run `make doxygen-doc` and look at ./lib/doc/index.html for API documentation.

-----------------------------
BUILDING FROM SOURCE PACKAGES
-----------------------------
On most platforms, versioned cdctool source code packages can be built with:

./configure --prefix=/usr && make && sudo make install

NOTE: To build cdctool in Windows, you will need to use MinGW32 compiler.
Cygwin is NOT supported since the -mno-cygwin option refuses to work with
gnulib. You will need to first build popt for MinGW32.

---------------
GIT MAINTAINERS
---------------
When building from the git source tree you will need to first run the
./gnulib.sh script in the source directory. It generates the gnulib files
from a gnulib installation. It expects to find the gnulib-tool program in
the ../gnulib directory. It should be located outside the cdctool source
tree. You can obtain this directory using
`git clone git://git.savannah.gnu.org/gnulib.git`. Example:

  $ mkdir cdctool-working
  $ cd cdctool-working
  $ git clone git://github.com/dfletcher/cdctool.git
  $ git clone git://git.savannah.gnu.org/gnulib.git
  $ cd cdctool
  $ ./gnulib.sh
  $ ./configure --prefix=/usr
  $ make