
$Id: PROTOCOL,v 1.2 1997/05/26 10:50:58 bri Exp $

Brian Ward <bri@blah.math.tu-graz.ac.at>
This document describes the protocol and API of mtd.

Commands to mtd and corresponding API (for writing new drivers) to the
interface are as follows. OFD refers to the output file descriptor.

    lc <addr> <dir> <speed> <functions> <topspeed>
    int control_loco(int OFD, int loco_addr, int direction,
		    int speed, int functions, int top_speed);

    Control a locomotive. All arguments are integers; <addr>, <dir>,
    <speed>, are loco address, direction (0 or 1), speed, respectively.
    <functions> is an integer, each bit of which controls a function; set
    the bits for each function that is to be turned on. Bit 0 (decimal 1) is
    function 0, and on most locos, it controls the headlights. <top_speed>
    is the total number of speed steps which can be used on the loco;
    <speed> should be lower than it (NMRA standard is 14, and 14 should be
    used if you don't know).

    Causes a command acknowledgement report.


    li <addr>
    int get_loco_info(int OFD, int loco);

    Get information on a loco; <addr> is the loco you want information on.
    Causes an "li" report, see below.


    ac <acc_addr> <ac_fun> <is_on>
    int control_acc(int OFD, int acc, int ac_fun, int is_on);

    Control an accessory. <acc_addr> is the address of the accessory,
    <ac_fun> is the "output channel" of the accessory (like 0 or 1,
    controlling the direction of a turnout), and <is_on> says whether to
    turn the accessory on or off.

    A little more detail is required here. First, when controlling
    something that has an electromagnetic coil, like a standard turnout,
    you need to first turn the accessory on, and then TURN IT OFF AGAIN
    shortly thereafter. Otherwise you'll melt the coil. However, something
    like a signal wants to be kept on all the time.
    
    Furthermore: the addresses start at 0. On the Lenz LH100 hand-held, the
    addresses start at 1; so, say, turnout 9 on the LH100 would be turnout
    8 to mtd and API. This is how it works on the LI100 interface, and
    numbering from 0 is just the sensible thing to do anyway. Why Lenz
    chose to start from 1 on the LH100 is a mystery to me. If this causes
    problems, fix it in the "user program."

    Causes a command acknowledgement report.


    vr
    int get_version(int OFD);

    Get the type and version of the digital system. Causes a "vr" report,
    see below.


    st
    int get_status(int OFD);

    Get the status of the system. Causes an "st" report, see below.


    go
    int power_on(int OFD);

    Turn the track power on.


    po
    int power_off(int OFD);

    Turn the track power off.


    es
    int emerg_stop(int OFD);

    Emergency stop. Stop all locomotives but don't cut track power.


    Programming doesn't work right at the moment due to a lack of current
    documentation.


Reports from the interface are reported (to stdout, usually then piped to
something else) as follows:

    Command acknowledgement reports:

    ok

    Previous command was okay.


    un

    Previous command unrecognized.


    er ip

    Error between interface and computer. This can happen when you drill
    two or more commands at the interface right after another.


    er ic

    Error between interface and command station. Something's wrong with the
    DCC hardware.


    Other stuff:

    vr <xxx>

    <xxx> is the type and version of the DCC system.


    st <status>

    <status> is an integer reporting the status of the system. 1 =
    emergency stop, 2 = emergency shutdown of power (booster shut down),
    4 = "start," 8 = progamming mode. These represent bits and can be added
    together to show multiple malfunctions.


    oc <addr>

    Some other controller just took over the loco at address <addr>.


    li <addr> <dir> <speed> <functions> <top_speed> <other_controller>

    Locomotive information. <addr> - <top_speed> have the same meaning as
    "lc" above, and <other_controller> is 1 if another controller used that
    loco last.


    mi <mode>

    Mode information. There has most likely been a change of mode. Modes
    recognized so far are:

	go - everything ok
	prog_mode - programming mode
	power_off - track power is off


    ul [<byte> [<byte> [<byte> ..]]]

    Unknown Lenz packet. We got something we don't really know the meaning
    of. The packet itself is presented after the "ul".


    There are some others, but they aren't documented here yet. Mostly,
    they deal with programming, which doesn't work yet.


