Sunday Protocol Documentation

This is the documentation for the Drink Sunday Protocol. 
The original protocol was written by Joe Sunday [sunday@csh.rit.edu].

    See also: Sunday Protocol Error Codes

Index Command Summary
ACCTMGRCHK
Displays whether or not the Sunday Server has a valid pathway to the account management subsystem.

ADDCREDITS <username> <credits>
Adds credits to the supplied users account.

ADDUSER <user name> [password]
Adds a user to the list of known users.

CHPASS <user> <new password>
Changes the drink-specific password for the specified user.

CODE <slot> <button order>
Sets the drink machine to drop a drink once the specified order of buttons is pressed, ala simon.

DROP <slot index> [delay]
Requests an actual drop from the machine.

EDITSLOT <slotnum> <name> <cost> <quantity> <num_dropped> <enabled>
If the user is an Drink Admin, this command can be used to edit a single slot in the drink machine.

EDITUSER <username> <credits> [admin]
If the user is an Drink Admin, this command can be used to edit another user's account information.

GETBALANCE [user]
Returns the credit balance of the specified user.

ISVALIDUSER <user name>
Determines whether or not the specified username is known to the accounting system.

LOCATION
Displays the machines (stored) physical location, such as "NRH (North)".

LOG [message]
Adds a message to the drink logfile.

PASS <password>
Specifies a password, which can only be successful when issued after the USER command.

QUERYADMIN [user name]
Displays whether or not the specified user is an administrator.

QUIT
Tells the server the session is over and to close the connection.

RAND [delay]
Requests an actual drop of a random drink from the machine.

RMUSER <user name>
Removes a user from the list of known users.

SETADMIN <user name> <status>
Sets the status of the given users administrator flag.

SHUTDOWN [-r]
Stops the Drink software, and then shuts down the hardware. If '-r' is also specified, the machine reboots and the software is reloaded.

STAT [index]
Requests the contents of the machines slot(s).

TEMP
Displays the status of all known temperature sensors. Only works on Big Drink - NRH North.

USER <username>
 Specifies a username, beginning the login process.

VERSION
Prints the version of the Sunday Server that is running.

  Introduction:
The Sunday Drink Protocol is a SMTP-like interface to the CSH Drink server software. It was originally designed (quickly) by Joe Sunday in Fall 1999 when he rebuilt the drink hardware and wrote his own server to drive his hardware. While this new protocol was incompatible (and less feature-rich) than the existing protocol, many clients were written that support this protocol.

When (yet-again) rebuilding and redesigning the drink hardware and software in fall of 2000, the team decided to support both protocols for the most compatibility. In the process of writing the SundayServer class, we found some areas in which the Sunday protocol could be strengthened. (Note: We are still looking for adequate documentation of the 'classic' drink protocol, so we currently only support the Sunday protocol.)
Document Conventions:
  • In this document, lines sent from the client to the server shall begin with a : as follows:
    :DROP 5 50

  • Lines sent from the server to the client shall begin with a > as follows:
    >OK Credits: 500

    Either of these symbols in the first column of a line are there for clarity, and are not actually part of the protocol (and therefore, do not include them in your implementation).

  • Note that commands sent to the server are not case-sensitive, and commands/data sent to the client should not be interpreted as case sensitive. 

  • Data sent to the server will be treated as case-sensitive when dealing with users and passwords.

  • For commands which have parameters in [brackets], those parameters are optional.
    For commands which have parameters in <braces>, those parameters are required.

  • Commands which have some administrator-only features, but still can be used by regular users are listed wholly in the regular user commands section. A link is provided from in the administrator-only listing for the command, however no description is provided.
    Any subsequent references, such as a 'see also', should point to the version of the command in the regular section (where the command's body may be found).

Protocol Conventions
  • All error commands begin with 'ERR' followed by its unique ID, and then by a message describing the error. The first word of the description is the only word capitalized, and the description always ends in a period.
    Example:
    >ERR 204 You need to login.
    •  
  • All administrator-only commands require:
    1) The user to be logged in and 
    2) The user to be an administrator. 

    If the user is not authenticated, then the error '>ERR 204 You need to login.' will be issued.
    If the user is authenticated, but not an administrator, then the error '>ERR 200 Access denied' will be issued.

    Example [the user is authenticated, but is not an administrator]:
    :rmuser grahams
    >ERR 200 Access denied.

  • The error '>ERR 406 Invalid Parameters' will be thrown for any command where all the required parameters are not provided, or more parameters are provided than what is necessary.

    Example:
    :rmuser
    >ERR 406 Invalid parameters
    In this case, the user to delete was not provided.
  • If a command is not implemented in the current version of the drink software, the command will return '>ERR 451 Not implemented.'

  • In the event that a parameter provided does not meet formatting specifications, an error specific to that parameter will be sent. If there are more than one violations, an error will be sent for only the first violation.

    Example:
    :drop orange eight
    >ERR 409 Invalid slot.
    'orange' is not a valid slot number, so the error was sent. 'eight' is also not a valid delay time, however only one error may be reported in one command.

  • If the command that was specified is not a recognized command, the error
    '>ERR 452 Invalid command.' will be issued.
Connection Details:
A Sunday Protocol Server listens for TCP connections on port 4242. As a connection to the server is made, the server sends one line (referred to as the 'banner') which the client can either discard or use in any way it sees fit. The server then waits for a command, and upon receiving a command, will process it, respond, and wait for another command.

The socket connection will timeout after a minute of inactivity. 
In the case that the socket is closed due to inactivity, the server will issue the following error, and then close the socket:
>ERR 450 Timeout, disconnecting.

Also, only a certain number of connections are allowed to the Sunday Server. This is to prevent just one subsystem from hogging all available resources. In the event no more connections are allowed at the moment, the server will issue the following error, and then disconnect the socket:
>ERR 205 Maximum user count reached.

Server Command/Response Pairs:

There are several client commands. Each command is on a separate line, and if the command accepts arguments, the arguments are space-delimited, except where noted.

Example:
 :USER grahams

When a command is sent to the server, the client should then wait for a response from the server. This response is a single line, either beginning with OK (to indicate success) or ERR (to indicate failure), followed by a single space which is in turn followed by a brief description of the error (sometimes containing state information).

If the response is multi-line (as in the case of STAT), the status message is included as the last line, and can be used to indicate the end of the response.

Example:
>OK Credits: 500
The above example is returned after the PASS command, and the response also includes this user's balance.

>ERR 409 Invalid slot.
 The above example is returned if the client specified a drop on a non-existent slot.

Username and Password Formatting Specifications:

All usernames and passwords must not contain spaces.  
Usernames and passwords are case-specific.
Commands:

These are command that a client, or even a user telneting in may use. Note that most commands require to be logged in (authenticated), however, there are a few commands that may be used by anyone who connects to the machine.
Also, please note that this section includes commands which may have features that only administrators may use in addition to their normal, non-administrator-specific features. 

See also Administrator only commands.

ACCTMGRCHK
Displays whether or not the Sunday Server has a valid pathway to the account management subsystem. If the Sunday Server does not have a valid pathway to the authentication management subsystem, then the USER and PASS command pairs will never return positive, nor will any of the other user account functions. This applies especially in the case the drink system uses  the Networked Account Management system, since it is contained within a separate system, and therefore may not always be available when the Sunday Server system is available.

Clients may use this query to check to see if authentication will work. They can then display an error to the user, thus saving the user valuable time from trying to authenticate.

Note that this command and the drink software architecture is not specific to either the Networked Account Manager or the Basic (local) Account Manager.

Does not require the user to be authenticated.

Server responses:

>OK Account server subsystem running.
The subsystem is available and therefore authentication is operational.

>ERR 350 Account server subsystem is not ready.
The subsystem is not available and thus authentication is not available.


CHPASS [user] <new password>
Changes the drink-specific password for the specified user. If the system is not using drink-specific passwords, their current password will not be changed, and this command will do nothing.
If the user who is issuing the command is not an administrator, then they may only change the drink-specific password for their own account.
In the instance the user is an administrator they may change the drink-specific password for anybody.
Requires an authenticated user.
user - the user for who the password will be changed. If not specified, then the current user is assumed.
new password - the new password for the specified user. The password is required, and may not contain any spaces.
Server Responses:

>OK Password changed.
Indicates the password was successfully changed.

>ERR 200 Access denied.
The current user (who is not an administrator) tried to change another user's password.

>ERR 204 You need to login.
The USER and PASS commands have to be successfully issued before CHPASS can be called.

>ERR 406 Invalid parameters.
The number of parameters provided was not 2.

>ERR 407 Invalid password.
The password specified does not meet password formatting standards.
 
>ERR 410 Invalid user.
The specified user was not found in the account database.


CODE <slot> <button indices>
Sets the drink server to drop the specified drink when the specified sequence of buttons is pressed on the front of the machine. This feature will only work on big drink.

THIS FEATURE NOT YET COMPLETE.

DROP <slot index> [delay]
Requests an actual drop from the machine. The client is disconnected following this command to ensure that someone doesn't hog the machine in the case of a single-threaded server. If the drop is not successful, i.e. an error is issued, then the client is not disconnected. Requires an authenticated user.
slot index - the index of the slot you wish to drop a beverage from .
delay - the number of seconds you wish to wait before the drop occurs. Defaults to 0 if this argument is not given.
NOTE: The initial version of this protocol did not have the delay argument. That version of the protocol is now DEPRECATED. The reasoning behind this is that if the client implements the delay, the server cannot, for instance, show a countdown on an LCD panel. The client can always countdown on it's end (with decent accuracy). 

Server responses:

>OK Credits remaining: <n>
Indicates that the drop was successful, returns the user's new balance and then disconnects the user.

>ERR 100 Slot empty.
Indicates that the selected slot is empty.

 >ERR 101 Drop failed, contact an admin.
Indicates that there was a failure in dropping the drink, which is generally a bad thing.

>ERR 203 User is poor.
Indicates that the user's balance is not enough to purchase the drink contained in the specified slot.

>ERR 204 You need to login.
The USER and PASS commands have to be successfully issued before DROP can be called.

 >ERR 403 Invalid delay.
The delay time provided was not a 32-bit number.  This error is not generated if the delay is less than zero or larger than the maximum allowed delay (usually 60 seconds).

>ERR 406 Invalid parameters.
The number of parameters was not 1 or 2.

>ERR 409 Invalid slot.
Indicates that the supplied slot number is not valid in the machine.


GETBALANCE [user]
Returns the credit balance of the specified user. Only administrators may retrieve the balance of other users.
Requires the user to be authenticated.

    user - The user to retrieve the balance of. If this argument is not supplied, the current user is assumed.

Server Responses:

>OK Credits: <credits>
Indicates the command was successful, and displays the requested users credit balance.

>ERR 204 You need to login.
The USER and PASS commands have to be successfully issued before GETBALANCE may be called.

>ERR 200 Access denied.
The current user (who is not an administrator) tried to access another user's credit balance.
 
>ERR 410 Invalid user.
The specified user was not found in the account database.

>ERR 406 Invalid parameters.
The number of parameters specified was not 1.


LOCATION
Displays the machines (stored) physical location, such as "NRH (North)". The format of this field is completely arbitrary at the moment. The current locations in use are "NRH (North)" for Big Drink and "NRH ( South)" for Little Drink. These two location specifications mean that the machines are on the 3rd floor of the Nathaniel Rochester Hall building in Rochester, NY.

Note that the response is not in quotes, and that everything after the 'OK ' is to be interpreted as the actual location.

Does not require the user to be logged in. Does not require any parameters.

Server Responses:

>OK NRH (North).
Indicates that the specified machine is on the north end of the 3rd floor of NRH. 


PASS <password>
Specifies a password, which can only be successful when issued after the USER command. The password is (unfortunately) transmitted in plain-text, and the server response will indicate the user balance if successful. 
If this command fails for any reason, the 'USER' command will have to be resent.

Server responses:

>OK Credits: <balance>
Where <balance> is an integer representing the user's balance. This response should be interpreted as a successful login.

>ERR 202 Invalid username or password.
Indicates that either the username supplied during the USER command is invalid, or the password supplied is invalid (insufficiently formatted), or not correct.

>ERR 201 USER command needs to be issued first.
This response will be generated if the USER command was not issued before PASS was issued.

>ERR 406 Invalid parameters.
The number of parameters specified was not 1.

see also USER


 QUIT
Tells the server the session is over and to close the connection.

Server response:

>OK Disconnecting.
Indicates that the server is going to disconnect the client.


RAND [delay]
Requests a drop of a random drink from the machine. The client is disconnected following this command (to ensure that someone doesn't hog the machine in the case of a single-threaded server).
The random slot will be selected from enabled slots which contain cans.
Requires that the user be authenticated.
 
delay - the number of seconds you wish to wait before the drop occurs (defaults to 0 if this argument is not given).
Server responses:

>OK Credits remaining: <n>
Indicates the users new balance. This should be interpreted as a successful drop.

>ERR 204 You need to login.
The USER and PASS commands have to be successfully issued before DROP can be called.

>ERR 403 Invalid delay.
The specified delay was not a number.

>ERR 406 Invalid parameters.
The number of parameters specified was not 1.

>ERR 101 Drop failed, contact an admin.
 Indicates that there was a failure in dropping the drink, which is generally a bad thing

>ERR 104 No slots available.
Indicates that all of the slots are empty.

>ERR 203 User is poor.
Indicates that the user's balance is not enough to purchase the drink contained in this slot.


STAT [index]
Requests the contents of the machines slot(s). Does not require the user to be authenticated.
If the contents of only a single slot is desired, that slot index can be specified.
index - Optional. If specified only that slot will be printed.
Server responses:

:stat
>0 "Coke" 50 13 200 true
>1 "Mountain Dew" 50 15 199 true
>OK 2 Slots retrieved.

:stat 0
>0 "Coke" 50 13 200 true


Each line contains the stats for one slot. The fields are space-delimited, except for the drink name. Their contents are as follows:

<Slot Number> <Contents> <Cost> <Number Available> <Total Number Dropped> <enable flag>

NOTE: Contents is wrapped in quotes, and may contain spaces.

The final line from the server is a typical status message, and it is in the form:
>OK <n> Slots retrieved

n is the number of slots retrieved.

NOTE: Clients should not assume that the slot numbers will be contiguous. The server may contains slots 0-4, but 3 may be disabled. The server may skip disabled/empty slots and simply subtract skipped slots from the 'OK' status message at the end of the output.


TEMP
Displays the current machine cabinete temperature. Note that the temperature that is returned is in units of celsuis.
This feature currently only works on Big Drink.

Server Responses:

>OK <temperature>
The command was successful in retrieving the temperature.

>ERR 351 Unable to determine temperature.
There was a subsystem failure in retrieving the cabinete temperature.


USER <username>
Specifies a username, beginning the login process. If a user was already logged in, it invalidates the current user. 

Server response:
>OK Password required.
The command completed successfully; next, the 'PASS' command should be specified.

>ERR 406 Invalid parameters.
The number of parameters specified was not 1.


While you might expect to get an error if the username does not exist in the system, this could be a potential security hole (allowing a nefarious person to determine which usernames are valid). Therefore, this command can not be used to simply determine if the user is a valid user. The only way to determine this through the system is to log on as an administrator and issue the isvaliduser command.

see also PASS


 VERSION
Shows what version of the SundayServer the drink server is running.

Server response:

> OK SundayServer $Revision: #15 $
Shows the current version. The version is always reported in this format.



Administrator-Only Commands  
These are commands that only administrators can issue.

All commands under this section may issue these two errors in the appropriate cases:

>ERR 204 You need to login.
The USER and PASS commands have to be successfully issued before the command can be called.

>ERR 200 Access denied.
The current user is not an administrator.


ADDCREDITS <username> <credits>
Adds credits to the supplied users account. Both parameters are required.
user name - the username to add credits to.
credits - the number of credits to add to the users current balance. This value may be negative to subtract credits.

Server Responses:

>OK Added credits.
Indicates that the operation was successfully performed.

>ERR 410 Invalid user.
The specified username is unknown to the drink accounting system.

>ERR 402 Invalid credits.
The value given for the credits parameter was not a number. The only characters allowed are numbers and a single leading dash '-' to signify a negative integer.

>ERR 406 Invalid parameters.
The number of parameters specified was not 2

see also: EDITUSER


ADDUSER <user name> [password]
Adds a user to the list of known users. If the drink software is using drink-specific passwords, then the password is required. If the system is using CSH IMAP (the default authentication mechanism), then the password will be discarded.
Also with the CSH IMAP authentication mechanism, if the newly created username does not match a CSH username, then the new account is useless.
user name - the username of the new user. The username must meet username formatting specifications.
password - the users password. The password must meet password formatting specifications.
The new user will be created with the defaults - zero credits, no administrator privileges. 

Server Responses:

>OK User created.
 Indicates the account was properly created.

>ERR 352 Unable to create user.
The Account Manager subsystem was unable to create the user, for an unknown reason.

>ERR 406 Invalid parameters.
The number of parameters specified was not 2.

>ERR 407 Invalid password.
The supplied password does not meet password specifications. Passwords may not contain spaces.

>ERR 410 Invalid user.
The supplied username does not meet username formatting specifications.

>ERR 412 User already registered.
The specified username is already a registered user, and thus the name cannot be re-registered.


CHPASS [user] <password>
See non-administrator commands, CHPASS


EDITSLOT <slotnum> <name> <cost> <quantity> <num_dropped> <enabled>
Edits all values for a single slot. All arguments are required.
slotnum The number (0-N) of the slot you wish to edit
name The name of the slot, e.g. "Coke". It must be wrapped in double quotes even if it does not contain spaces.
cost The cost of the drink in this slot, in credits.
quantity The number of drinks contained in this slot
num_dropped Change the "Total Dropped" accumulator for this slot.
enabled "true" if the slot is enabled, "false" if not
Examples:
:editslot 0 "Mountain Dew" 50 43 307 true
>OK Changes saved.
Server responses:

>OK Changes saved.
The requested change has been saved into the user database

>ERR 409 Invalid slot.
The user tried to edit a non-existent slot.

>ERR 401 Invalid cost.
The specified cost was not a number.

>ERR 408 Invalid quantity.
The specified quantity was not a number.

>ERR 405 Invalid num_dropped.
The specified number of cans that had already been served was not a number.

>ERR 404 Invalid enable flag.
The specified enabled/disabled flag was not either 'true' or 'false'.

>ERR 406 Invalid parameters.
The number of parameters provided was not 6. 


EDITUSER <username> <credits>[admin]
Changes another users credit and admin status in one command. 
username - the username of the user to edit
credits - the number of credits to add to the user's account
admin - (optional) "true" to make the user a drink administrator, "false" to remove the users administrator status.
NOTE: While there is nothing wrong with using this command to edit a user's balance, it can be somewhat limiting. First of all, if you wish to decrease a user's balance, you have to pass a negative value.

Second, this command will NOT create a user if they don't already exist in the system.

Server responses:

>OK Changes saved.
The requested change has been saved into the user database

>ERR 410 Invalid user.
The user tried to edit a non-existent user's account.

>ERR 402 Invalid credits.
The specified number of credits was not a number.

>ERR 400 Invalid admin flag.
The specified boolean admin flag was not either 'true' or 'false'.

>ERR 406 Invalid parameters.
The number of parameters specified was not 2 or 3.


 See also GETBALANCE, ADDCREDITS


GETBALANCE [user]
See GETBALANCE, listed in the general commands section.


ISVALIDUSER <user>
Determines whether or not the specified username is known to the accounting system. 

        username - The name of the user to test to see if it is known to the accounting system.

Server Responses:

>OK true User is known.
Indicates that the supplied user is known to the accounting system.

>OK false User is not known.
Indicates that the supplied user is not known to the accounting system.

>ERR 406 Invalid parameters.
 The number of parameters specified was not 1.


LOG [message]
Adds a message to the drink logfile. The message may contain any characters. Everything that comes after the 'LOG ' command is printed to the logfile. The file is time stamped with the issuing users username. 

    message - the message to leave in the log file.

If there is no message, then a simple timestamp with the users name is left.

Server Responses:

>OK Message added to log file.


QUERYADMIN <user>
Displays whether or not the specified user is an administrator. The single username parameter is required.

    username - the name of the user whose administrator status is to be displayed.

Server Responses:

>OK true User is an administrator.
Indicates that the user is an administrator

>OK false User is not an administrator.
Indicates that the user is not an administrator.

>ERR 410 Invalid user.
The specified username is not known to the drink accounting system.

>ERR 406 Invalid parameters.
The number of parameters specified did not equal 1.


RMUSER <user>
Removes a user from the list of known users. This does not affect the user's CSH account.

    username - The user to delete from the list of known users.

Server Responses:

>OK User removed.
Indicates that the user was successfully removed from the list of known users.

>ERR 353 Could not remove user.
The Account Manager subsystem failed to remove the supplied, valid user. This error will only occur if the system has checked the validity of the request (IE, the issuing user is an admin user,  and the provided username to remove is a valid username), and attempts to remove the user, but fails.

>ERR 410 Invalid user.
The user was not found in the list of known users.

>ERR 406 Invalid parameters.
The number of parameters specified did not equal 1. 


SETADMIN <user name> <status>
Sets the status of the given users administrator flag. The status flag must be either 'true' or 'false'.

Both the username and the status flag are required.
username - the name of the user whose administrator status is to be changed.
status - the new value of the administrator status flag for the specified user
Server Responses:

>OK Admin flag set.
Indicates the operation was successful.

>ERR 354 Unable to set admin flag.
The error will only occur after all the normal parameter validation has occured and properly validated.
This error will only occur when the server actually attempts to change the user's admin status, and is unable to, due to the Account Manager subsystem failing to do so.

>ERR 410 Invalid user.
Indicates that the user specified is not known to the drink accounting system.

>ERR 400 Invalid admin flag.
Indicates that the status flag specified did not match either 'true' or 'false'.

>ERR 406 Invalid parameters.
Indicates that the number of parameters specified was not 2. see also: EDITUSER


SHUTDOWN [-r]
Tells the server to close all active connections, cleanup and then exit. 
If the -r option is specified, the Operating System the software is running on is to be rebooted. This does not imply that the software is to be brought back up with the OS. That can be achieved by placing the correct commands in the appropriate startup scripts. 

Server Responses:
:shutdown
>OK Shutting down server.
The software will exit.

:shutdown -r
>OK Rebooting.
 The software will reboot the underlying Operating System.

>ERR 406 Invalid Parameters
More than one parameter was specified.

>ERR 411 Invalid reboot flag.
The single parameter specified was not '-r'.

This document is maintained by:
Sean Graham [grahams@csh.rit.edu] and Kevin Thompson [antiduh@csh.rit.edu].

Last Revised: $Date: 2003/08/19 $