Network Protocol - macfeaster/Inet GitHub Wiki

The ATM server and clients communicate over TCP sockets. All data packets are exactly 10 bytes, with two exceptions:

  • When the client sends the boot command packet, the response is a null-terminated JSON string, which contains all necessary data for the client to operate. This includes the request and response commands available and available language packs.
  • When the client receives a command packet with command ID 70 (broadcast), it should expect a null-terminated JSON string, which contains new welcome/start menu messages for all available languages.

Data packet structure

+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+
|  Cmd  |                               Data                    | Code  |   ID  |
| 1 byte|                             7 bytes                   |1 byte | 1 byte|
+-------+-------+-------+-------+-------+-------+-------+-------+-------+-------+

Explanation:

CMD:
	1 byte, representing the command ID (0-119)
Data:
	Signed integer 64-bit, where the 8 most significant bits are discarded
#ID#:
	1 byte, representing the machine/ATM ID currently in use. The software update
	received by sending the boot command contains this ID.
#CODE#:
	Code for using elevated commands, one-time use. This is supplied separately
	to the user. 1 byte.

Available Commands

Request Commands

CMD (1 byte) Data (7 bytes) Code (1 byte) ID (1 byte)
boot (code 0) Not required N/A 0
login (code 1) Card number (16 digits) #Code# #ID#
logout (code 2) Not required N/A #ID#
balance (code 3) Not required N/A #ID#
withdraw (code 4) Amount to withdraw #Code# #ID#
deposit (code 5) Amount to deposit N/A #ID#
get_id (code 6) Not required N/A 0

Note: the get_id command must be sent after the boot command, to fetch a client identifier for signing.

Response Commands

Response commands can be one of three types:

  • 70-79 = general commands
  • 80-99 = error response codes
  • 100-119 = success response codes

For response codes, the code and data bytes consist entirely of zeroes. Only the Data field is used.

CMD (1 byte) Data (7 bytes)
new_identifier (code 70) Contains a new identifier for the client to use
invalid_cmd (code 80) The server received a command with unknown ID, or a series of uninterpretable bytes
invalid_cc (code 81) The credit card number received was not found in the customer database
invalid_scode (code 82) The security code provided was invalid
insufficient (code 83) Insufficient funds in the account
welcome (code 100) The user logged in successfully
balance (code 101) Response containing the user’s account balance
withdraw (code 102) Withdrawal successful, returns new account balance
deposit (code 103) Deposit successful, returns new account balance