CCMInfo for Unix
by Lars Kellogg-Stedman <lars@larshshack.org>
and Ken Raeburn <raeburn@raeburn.org>

  DISCLAIMER: THIS SOFTWARE IS PROVIDED "AS IS", AND THE AUTHORS EXPRESSLY
  DISCLAIM ALL WARRANTIES, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND
  FITNESS FOR A PARTICULAR PURPOSE. 

  In no event shall the authors be liable for any special, incidental,
  indirect, or consequential damages of any kind, or any damages whatsoever
  resulting from the loss of use, data, or profits, whether or not advised
  of the possibility of damage, and on any theory of liability, arising out
  of or in connection with the use of this software.

  Or, in simpler terms:

  This software could render your cable modem inoperable, perhaps
  permanently so.  It is unlikely that the use of this software is
  permitted under the terms of your cable modem provider's terms of
  service.  Don't blaim us if you screw something up.

  USE THIS SOFTWARE AT YOUR OWN RISK.


What is CCMInfo?
================

From documentation available at
http://www.erols.com/andshaff/techpage/ccminfo.htm:

  CCMInfo is a tool that provides the subscriber with control and
  visibility into the operation of the Client Cable Modem (CCM).
  With CCMInfo, the subscriber may connect and hang up the
  telephone connection. Also the subscriber may obtain information
  about the ethernet, RF, and telephone links. 

While ports of CCMInfo exist for Windows and MacOS users, no such support
exists for Unix users (in fact, most cable modem service providers do 
not provide any sort of support for Unix users).

CCMInfo for Unix (ccm) is an attempt to fill this gap.  It doesn't have
a fancy GUI, but it will let you access most of the diagnostic and
debugging features of your Hybrid cable modem.

Will it work on my system?
==========================

ccm is known to compile under Linux (2.0.x and 2.2.x),
Irix 6.5, and NetBSD.  It will probably build just fine
on many other Unix-like systems.

Installing ccm
==============

(1) Run the configure script (type "./configure").  This should automatically
    configure ccm to build on your system.

(2) Type "make"

    If it compiles correctly, you can run it from the current directory
    without installing it.

(3) Type "make install"

Command Line Options
====================

ccm supports the following command line options:

  -m <ip address>       Specify a target cable modem.  You may have
                        multiple -m options on the command line; how these
			are used depends on whether your are in interactive
			or command line mode (see below).

  -r <retries>          If a command fails, ccm will try sending this many
                        more times.

  -t <timeout>          ccm will wait this long (in seconds) before
                        deciding a command has failed.

  -f <file>		read list of targets from file.  If you specify
  			"-" as the filename, ccm will read from stdin
			(note that this does not currently work in 
			interactive mode).

  -i                    enter interactive mode
  -v                    turn on verbose mode
  -d                    turn on debug mode (probably a no-op)

  -h                    display help
  -V                    display version information

Multiple Targets
================

You may specify multiple targets using the command line:

  $ ccm -m 1.1.1.1 -m 2.2.2.2 -m 3.3.3.3 ...

Or in interactive mode:

  ccm> /target 1.1.1.1
  ccm> /target 2.2.2.2
  ccm> /target 3.3.3.3

In batch mode, ccm will apply the given command to all the targets.

In interactive mode, the targets will all be part of the target list, and you
will be able to access them with the /target, /prev and /next commands, or
apply a command to them via the /apply command.

Interactive Mode Commands
=========================

The following commands are available in interactive mode.  All commands
must be prefixed by the command character, '/'.

Several of the commands accept a target specification as a parameter; this
is denoted by <target spec> in the parameter list.  The following syntax is
valid:

  n		a single number
  n-m		a range of targets
  n-		n and all following targets
  -m		m and all preceding targets
  failed	all targets for which the last command executed failed
  okay		all targets for which the last command executed suceeded
  all		all targets
  marked	all targets marked using the /mark command
  unmarked	all targets not marked using the /mark command

You can use any combination of these terms, so the following are all valid
commands:

  /mark 1-10 20-25 30
  /drop 1 5 failed 22-
  /list marked failed

Other syntax notes:

<host spec> can be either a hostname or an ip address.

The commands:

retries [n]		set number of retries to n, or display current
			value of retries.
timeout [n]		set timeout to n seconds, or display current
			timeout.
verbose			toggle the setting of the verbose flag
debug			toggle the setting of the debug flag

help			display a list of local commands
remotehelp		display (known) cable modem commands
version			display version information

target [<host spec>]	add a new target or display current target.
target n		set current target to target n.
prev			set current target to previous available target
next			set current target to next available target

mark [<target spec>]	mark targets matching <target spec> (or all targets
			if no specification given).
unmark [<target spec>]	unmark targets matching <target spec> (or all
			targets if no specification given).
apply <command>		apply <command> to all marked targets


list [<target spec>]	list targets matching <target spec>, or all targets 
			if no specification was given.
drop [<target spec>]	remove targets matching <target spec> from the
			list, or remove current target if no specification
			was given.

load <filename>		load list of targets (one per line) from
			<filename>.

Protocol Information
====================

The protocol used to communicate with the cable modem is mostly text-based.
However, there is a short header on both the outgoing and incoming packets.

  Outgoing Packets (TO the cable modem)
  ================

  We don't know so much about outgoing packets.  If you have any
  information, feel free to share it with us.

  Bytes 0-3        transaction id
  Bytes 4-10       unknown
  Byte 11          must be 1 -- sequence count?
  Bytes 12-27      unknown

  Incoming Packets (FROM the cable modem)
  ================

  Bytes 0-3        transaction id
  Byte 4           if nonzero indicates additional packets in response
  Byte 5           sequence count (increments for each packet in response)
  Bytes 6-7        success/failure, 0000=fail, FFFF=success
  Bytes 8-9        message length

So, what do all those cable modem commands do?
==============================================

Darned if I know.

http://www.erols.com/dhenley/tech/tech029.htm has information on the
output of the 'qamstat' command.

Keeping Up With The Joneses...
==============================

Code fixes happen faster than new releases come out.  If you want to
have the absolute, bleeding edge code, you can get it via anonymous CVS
by running the following two commands:

  (1) cvs -d :pserver:anonymous@cvs.larsshack.org:/cvs login

      When prompted for a password, just hit return.

  (2) cvs -d :pserver:anonymous@cvs.larsshack.org:/cvs co ccm

Now that you've got it, you can update it by cd'ing to the ccm
directory and running "cvs update".

Reporting Bugs
==============

Send bug reports to lars@larsshack.org.  Please include the output of
the 'ccm -V' command.


