CoffeeLink Network Protocol - Version 1.1.3			7/11/2001

1. Overview
---------------------------------------------------------------
CoffeeLink is a protocol for remotely controlling automated
coffeepots. The protocol is a simple, ASCII-based, request-reply
protocol similar to SMTP. It is intended to be layered over a reliable
TCP/IP connection.

2. Assumptions
---------------------------------------------------------------
We make the following assumptions about a coffee pot (also called
"device") controlled by the CoffeeLink protocol:

2.1 The coffee pot has a single pot. 
2.2 The coffee pot can only brew one pot of coffee at a time.
2.3 Brewing does not happen instantaneously. The exact amount of time
    required depends on the model of coffee pot.
2.4 The coffee pot has a maximum capacity (expressed in units of SMALL
    cups, with cup sizes defined in Section 6.10 below), which may
    vary by model. It can brew a specified amount of coffee up to its
    maximum capacity.
2.5 The coffee pot can make either caffeinated or decaffeinated coffee.
2.6 The coffee pot can adjust the strength of the brew.
2.7 The coffee pot has the ability to dump a partially filled pot of
    coffee down the drain and automatically prepare itself to brew
    another pot. This operation happens instantaneously.
2.8 The coffee pot has the ability to pour the brewed contents into a
    waiting coffee cup. This operation happens instantaneously.
2.9 The coffee pot can also add additions to a coffee cup that it has
    filled with coffee.  This operation happens instantaneously.  The
    available additions are described in Section 6 below.  The coffee
    additions can be customized.
2.10 After coffee is brewed, the temperature of the warming plate can
     be adjusted.

3. Device States
---------------------------------------------------------------
Coffee pots supporting the CoffeeLink protocol must conform to the
behavior of a simple state machine. CoffeeLink requires a coffee pot
to implement 3 distinct states:

3.1 CANBREW - the coffee pot is in a state where it is able to brew a
    new pot of coffee.
3.2 BREWING - the coffee pot is currently brewing a new pot of
    coffee. This operation can take some time.
3.3 COFFEEREADY - coffee has been brewed and is available to be
    poured.

3.4. State transitions occur as follows: 

StartState 		Event	 		     EndState
----------		-----			     --------
CANBREW 		BREW NOW command	     BREWING
CANBREW 		<queued brew time>	     BREWING
BREWING 		<brew time elapsed>	     COFFEEREADY
COFFEEREADY 		RSET			     CANBREW

4. General protocol information
---------------------
4.1 CoffeeLink messages consist of ASCII strings terminated by newline
    characters.
4.2 Clients issue commands to the server. 
4.3 Commands are 4-character alphabetic identifiers. 
4.4 Some commands have additional arguments.  In these cases, the
    command is followed by a space followed by additional
    arguments.  Each argument is separated by a space.
4.4.1 Client alphabetic commands must be in uppercase letters.
4.4.2 Any extra characters at the end of a valid client command are
      ignored.
4.4.3 A client request that cannot be understood results in the
      distinguished error code

   450 INVALIDCMD Sorry I didn't understand your request

4.5 A command is terminated with a newline.
4.6 A client command always results in a server response.
4.7 Server responses consists of a 3-digit numeric code followed in
    some cases by additional information.
4.7.1 Response codes starting with 2 indicate success.
4.7.2 Response codes starting with 4 indicate a command error.
4.7.3 Response codes starting with 5 indicate a hardware/device error.
4.8 Following the code may be additional information. 
4.8.1 Capitalized information in the response must be returned
      verbatim as shown in this document.
4.8.2 Mixed case information in the response may vary among models of
      coffee pots.

5. Connection initiation sequence
---------------------------------------------------------------
5.1 CoffeeLink connections are initiated by a client over a TCP/IP
    connection.
5.2 The standard port number for CoffeeLink is port 4000.
5.3 Upon receiving a connection, the CoffeeLink server device returns
    a response as follows:

200 COFFEEPOT <version> <model> <capacity> <time>

Once the server has returned this response, it should go into a loop
accepting client commands and returning responses, until the client
closes its connection.

5.4 Details:
<version> is a floating point number in 99.99 format
<model> is an arbitrary string containing no spaces
<capacity> is the maximum capacity of the coffee pot in SMALL cups
<time> is the current server time in HH:MM 24-hour format

5.5 Security: this version of the CoffeeLink protocol does not
    implement security.  A CoffeeLink-enabled coffee pot should accept
    connections from any client.

6. Client-to-server commands
---------------------------------------------------------------
6.1 HELP
--------
6.1.1 Description: request help on the command set supported by the
      coffee pot.
6.1.2 Response: The coffee pot returns information on accepted
      commands in any format. Clients should not rely on the format of
      information following the return code.
6.1.3 Example response:

200 HELP INFO STAT TEMP BREW AVLA CURA ADDA DELA POUR RSET EXIT


6.2 INFO
--------
6.2.1 Description: requests general information about the coffee pot
      device.  The device must return the same information as returned
      during connection initiation sequence.
6.2.2 Example response:

200 COFFEEPOT <version> <model> <capacity> <time>

6.2.3 Details:
<version> is a floating point number in 99.99 format
<model> is an arbitrary string containing no spaces
<capacity> is the maximum capacity of the coffee pot in SMALL cups
<time> is the current server time in HH:MM 24-hour format


6.3 STAT
--------
6.3.1 Description: requests coffee pot current status
6.3.2 Response: The device returns current status using one of the
      following response strings.

200 CANBREW
201 CANBREW <time>
202 BREWING <type> <qty> <strength>
203 COFFEEREADY <type> <qty> <strength> <minutes> <temp>
500 Device error

6.3.3 Details:

201 CANBREW status indicates that a brew has been queued for the
    specified <time>
<time> is in HH:MM (24-hour) format
<type> is literal C for caffeinated, D for decaffeinated
<qty> is an integer indicating number of SMALL cups of coffee: in 202
      BREWING status it refers to the number of SMALL cups brewing; in
      203 COFFEEREADY status it refers to the number of SMALL cups
      left in the pot
<strength> indicates brew strength set by BREW command
<minutes> is an integer indicating number of minutes since last brew
          cycle ended
<temp> is the current temperature of the warming plate


6.4 TEMP <temp>
--------
6.4.1 Description: requests a change in temperature of warming
      plate. Different models of coffee pot can accept different
      temperature ranges. However, all models should accept
      temperatures in the range 120-160. Note that this command can
      only succeed when the coffee pot is in the COFFEEREADY state.
6.4.2 Response: the device responds with one of the following response
      strings.

200 OK Temperature set
400 WRONGSTATE Can't set temperature unless coffee is ready
401 INVALIDARG Invalid temperature
500 Device error

6.4.3 Details:
<temp> is an integer indicating temperature to which to set the
       warming plate


6.5 BREW <when> <type> <qty> <strength>
--------
6.5.1 Description: initiates brew cycle on device. This command does
      not block, although actual brewing time may take several
      minutes. If <when> is the literal string NOW, then brewing
      begins immediately. If <when> is a time in format HH:MM (24 hour
      format), then the brew request is queued. A new BREW command
      automatically cancels any pending queued brew request. To
      determine when brewing is done, client can call STAT until it
      returns 201 COFFEEREADY.
6.5.2 Responses: the device should return one of the following responses

200 OK Starting to brew
201 OK Brew queued
400 WRONGSTATE Can't brew unless we are in CANBREW state
401 INVALIDARG Invalid <when> or <strength> specification
500 Device error

6.5.3 Details:
Server should return 200 when BREW NOW is successful.
Server should return 201 if BREW <time> is successful.
<when> should either be literal NOW or time in HH:MM (24 hour)
       format.  If <when> specifies a time earlier than the current
       time it is equivalent to BREW NOW.  The BREW command does not
       handle wraparound; it recognizes 0:10 as being earlier (not
       later) than 23:50.
<type> is literal C for caffeinated, D for decaffeinated.
<qty> should be an integer indicating the number of SMALL cups to
      brew. This number should be less than or equal to the maximum
      pot capacity returned by INFO.
<strength> indicates desired brew strength and should be an integer
           from 1-10.


6.6 AVLA
--------
6.6.1 Description: requests a list of the available coffee additions.
6.6.2 Responses: the device should provide a list of the available
      additions.

200 AVAILABLE[ <addition-type>:<addition-name>]+
201 UNAVAILABLE No additions available
500 Device error

6.6.3 Details:
The addition-type list and addition-name list are unbounded.  Any
token specified in the AVAILABLE list may be echoed back to the server
as a valid request.  The client need not infer any semantic content
from the token names.  Some examples might be ...

addition-type: "milk" | "sweetener" | "alcohol" | ...

addition-name: "cream" | "half-and-half" | "skim" |
	       "sugar" | "sweet-n-lo"    |
	       "rum"   | "kahlua"        | ...


6.7 CURA
--------
6.7.1 Description: requests a list of the currently selected coffee
      additions. 
6.7.2 Responses: the device returns a list of the currently selected
      coffee additions.

200 CURRENT[ <addition-type>:<addition-name>]*
201 UNAVAILABLE No additions available
500 Device error

6.7.3 Details:
The addition-type list and addition-name list are as above in Section
6.6.


6.8 ADDA <addition-type> <addition-name>
--------
6.8.1 Description: adds the specified addition to the coffee pot's list
      of currently selected additions.  This command can be called
      multiple times to add multiple additions.  Incremental quantities
      of an addition can be specified by multiple calls.  ADDA is a
      valid command in any state.
6.8.2 Responses: the device should confirm or deny the new addition.

200 OK Addition added
400 INVALIDARG Invalid <addition-type> or <addition-name> specification
500 Device error


6.9 DELA <addition-type> <addition-name>
--------
6.9.1 Description: removes the specified addition from the coffee pot's
      list of currently selected additions.  This command can be
      called multiple times to delete multiple additions.  DELA is a
      valid command in any state.
6.9.2 Responses: the device should confirm or deny the request to
      delete an addition.

200 OK Addition deleted
201 OK Addition was not previously selected
400 INVALIDARG Invalid <addition-type> or <addition-name> specification
500 Device error


6.10 POUR <size> <qty>
---------
6.10.1 Description: pours <qty> cup(s) of coffee of size <size> into
       <qty> spare coffee cup(s), adding the previously selected
       additions.  After each POUR, the additions list is reset to the
       empty list.
6.10.2 Responses: the device should return one of the following
       responses

200 OK Pouring cup(s) of coffee
400 WRONGSTATE Can't pour unless we are in COFFEEREADY state
401 UNAVAILABLE Specified <qty> more than available coffee amount
402 INVALIDARG Invalid <size> or <qty> specification
500 Device error

6.10.3 Details:

<size> should be literal SMALL, MEDIUM, or TALL.  A MEDIUM cup is the
       same volume as two SMALL cups, and a TALL cup is the same
       volume as three SMALL cups.  
<qty> should be an integer indicating the number of <size> cups to
      POUR.  This should be less than or equal to the equivalent
      volume of SMALL cups that are available in the coffee pot.

Note: POUR, which effects an instantaneous response, does not result
      in any state transitions.  If a client POURs less than the total
      amount of brewed coffee, the pot is still in the COFFEEREADY
      state.  Even if all the coffee is poured, the pot remains
      COFFEEREADY until a RSET command is issued.  The pot needs to
      dump the old beans before the device can be used to make new
      coffee.


6.11 RSET
---------
6.11.1 Description: resets the coffee pot in preparation for brewing
       another pot. If the device is in the CANBREW state with no
       queue, nothing happens.  If in the CANBREW state with a brew in
       the queue, the brew is canceled.  If the device is in the
       BREWING state, an error occurs. If the device is in the
       COFFEEREADY state, the device dumps any coffee currently in the
       pot, dumps its old beans, and enters the CANBREW state
       instantaneously.  Also, RSET causes the additions list to be
       reset to the empty list.
6.11.2 Responses:

200 OK Resetting device
201 OK In CANBREW state, nothing to do
202 OK Canceled queued brew
400 WRONGSTATE Brewing, please wait until done
500 Device error


6.12 EXIT
---------
6.12.1 Description: terminates the client's connection to the coffee
       pot and tells the device to start listening for new client
       connections on the CoffeeLink port.
6.12.2 Responses:

200 OK Connection terminated
500 Device error

6.12.3 Details:
The protocol makes no demands on the behaviour of the device after an
EXIT command has been sent.  The coffee pot is free to interrupt any
processes and reset itself.  Or the pot could simply continue in its
present state.

7. Connection Termination Sequence
---------------------------------------------------------------
The client/server connection is assumed to exist until the client
sends an explicit EXIT command.  The server responds as in 6.12 above.
As also noted in 6.12, the server is free to proceed however it wants
with regard to brewing coffee, but it must clear the CoffeeLink port
for new client connections.