Common Description of a Communication Protocol Used for Fiscal Devices Manufactured by Datecs Ltd.

Down below I will describe two modifications to a communication protocol for some of the most widely-used models of fiscal devices manufactured by Datecs LTD. If you are not familiar with the terms related to this protocol, it would be helpful to take a look at the links related to the terminology before proceeding with the topic in depth. If you’re already an expert in this topic or are comfortable enough with the terminology used down below, you can confidently skip this part and go on ahead. My goal in this part is to help those who have been introduced to the topic recently.

Terminology

• The meaning of the Byte and Bit;
• Number systems:
  • For brevity, the decimal system will be referred to as DEC;
  • For brevity, the hexadecimal system will be referred to as HEX;
• You can find the used  data types in my articles here. For example a variable of type Word represent unsigned integer values in range [0..65535]
• An article briefly describing synchronous and asynchronous communication - here; 
• An article briefly describing packaged and non-packaged messages - here; 
• For the sake of brevity, we’ll to refer to fiscal devices as FD or Slave;
• We will refer to the computer (more precisely, the software sending messages to FD) as Host;
• Transport protocol:
  • By serial communication between Host and Slave we will mean connectivity based on RS-232 or USB;
  • By BT communication between Host and Slave we will mean connectivity based on Bluetooth;
  • By TCP/IP communication between Host and Slave we will mean connectivity based on TCP/IP;
• Specific, single-byte messages:
  • When Slave sends a NAK byte to Host, we actually mean that Slave sends a byte with a value of 15H (HEX);
  • When Slave sends a SYN byte to Host, we actually mean that Slave sends a byte with a value of 16H (HEX);

 

Synchronous protocol

The protocol for communicating with Datecs LTD fiscal devices is synchronous.

• The order for initiating, sending and receiving messages is synchronised; 
• The time is synchronised; 
• The size and format of messages are synchronised;

Synchronisation of the order for initiating, sending and receiving messages

The fiscal device (Slave) cannot initiate communication. It is instead always initiated by the program located on the relevant computer (Host). Receiving information from a fiscal device through a communication channel without initiating it is typically a sign of a defective device or a uncleaned buffer.

 

• Host initiates communication by sending a packaged message to Slave, containing a command; 
• Depending on its current status, Slave may or may not execute the desired operation, after which it must reply with a packaged message (or with a single byte, in some cases); 
• Host should wait for Slave’s response before sending another message, unless the timeout window has expired (see time-based synchronisation);

 

Time-based Synchronisation

• To every command coming from Host, Slave must respond no later than 60ms (with either a packaged message or with a specifically determined single-byte code); 
• Host has a 500ms timeout for receiving Slave’s reply;
• If Host does not receive a reply within 500ms, it should transmit the same message again, using the same sequence number and the same command;
• After two unsuccessful attempts, Host should indicate that there is either no connection with Slave or that there is a hardware malfunction within the device;
• A 500ms timeout window is used when communicating using RS-232 or USB. When using a different transport protocol (such as TCP/IP), a greater timeout window should be allowed, depending on the quality of the connection.

 

Support for a normal delay in a response from Slave

If the command is such that Slave will experience a delay when replying, Slave begins sending SYN bytes through the channel every 60ms. This way, Slave tells Host it is busy at present but is fully operational and in working order, i.e it is telling Host to wait a little.

 

Message format-based Synchronisation

• All commands and replies between Host and Slave (aside from the single-byte messages described above) are packaged in a specifically determined format, known in advance; 
• “Randomness” is allowed solely in the area of logical data but the location of this data in the package, as well as its maximum size, is strictly determined;
• The formats of the packaged message from Slave to Host and vice versa are specifically defined yet “different”, as Slave’s reply contains additional information on the status of the device. Even if the device has nothing to send Host in the form of logical data (i.e the data area is blank), it will still reply so that the program (Host) can, based on the status bytes, check the condition of the device and check for any issues (for example, running out of paper);
• In case of a problem or noise in the communication channel, it is entirely possible for Slave to receive a command with a erroneous control sum (checksum). In this case Slave replies with a single NAK byte. That indicates that Host should repeat its message without any changes to it - or simply resend it.

 

 

Protocol Modifications

The two modifications described below can be roughly split into an “old protocol” and a “new protocol”. The so-called “old protocol” arose at a time when DOS was the most-widespread OS and exists for the sake of compatibility with old but still active products. The second modification, which we will refer to as “new protocol” has several notable improvements:

• Assigns a greater interval of permissible commands (i.e, it accommodates for the creation of new, unknown at the time commands in the future);
• It allows for a larger volume of data to be transferred in a single command;
• Elements of standardisation of commands, a result of the experience of software developers and the accumulated requirements of different software developers:
  • An error code as the first parameter in the reply of the device - generally applicable to all models developed in adherence to this protocol;
  • Standardising separators in the data area;
  • Assigning more status bytes in the reply of Slave;

Both protocols are valid and equally popular, so I will describe both modifications. The differences have different colors. The values are given in HEX. 

• 01 (Start) - Start byte.
  • Length: 1 byte; 
  • Value: 01H;
• LEN - Length of message. This is the number of bytes from the start byte <01> (excluding itself) to the data terminator <05> (including itself), plus a fixed offset of 20H.
  • Old protocol:
    • Length: 1 byte;
    • Values: from 20H to FFH;
  • New protocol:
    • Length: 2 bytes (word), coded in 4 bytes;
    • Values:  Since the possible values in this protocol are in the interval  [0..65535] (DEC), your program should fill in the necessary value in the variable of type word. Every digit of these two bytes is transmitted and 30H is added to it. As a result, there will be four bytes in the packaged message for this field. The reason for this coding is related to the internal execution of the protocol in fiscal devices and is of no matter.
    • Example: the variable with a value of 1AE3H in the packaged message is presented as four bytes with values as follows: 31H,3AH,3EH,33H;
• SEQ - The sequence number of the packaged message. Slave records the same sequence number in its reply. If Slave receives a message with a value of identical to the one from the last message it has received, it does not perform an action but instead repeats the last message it has sent.
  • Old protocol;
    • Length: 1 byte;
    • Values: from 20H to 7FH;
  • New protocol:
    • Length: 1 byte;
    • Values: from 20H to FFH;
• CMD - The number of the command.
  • If Slave receives non existing or non valid command code, it replies with a packaged message with a length of zero in the data field and raises the status bit for an invalid command to one;
  • When the Slave replying to a given message - the Slave use the same value of the command code in the packed message to the Host;
  • The upper boundary for the value of permissible commands depends on the given device.
  • Old protocol:
    • Length: 1 byte;
    • Values: from 20H to 7FH;
  • New protocol:
    • Length: 2 bytes (word), coded in 4 bytes;
    • Values:  Since the possible values in this protocol are in the interval  [0..65535] (DEC), your program should fill in the necessary value in the variable of type word. Every digit of these two bytes is transmitted and 30H is added to it. As a result, there will be four bytes in the packaged message for this field. The reason for this coding is related to the internal execution of the protocol in fiscal devices and is of no matter;
    • Example: the variable with a value of 1AE3H in the packaged message is presented as four bytes with values as follows: 31H,3AH,3EH,33H;
    • Notice: The list of specific, permitted and valid values of commands for a given fiscal device should be acquired from that specific device’s documentation. That a given value is possible doesn’t  necessarily mean it is permitted or used;
• Data - Logical data. The format and length of the data area depend on the command; 
  • If the command doesn’t require sending data to Slave, or if consequently Slave’s response to Host has no data, then the length of this field is zero.
  • If when sending a command from Host to Slave there is a syntax error in the data, Slave replies with a packaged message with a zero-length data field and raises the value of status bit for syntax error to one;
  • Length (Host to Slave): 0 - 213 bytes;
  • Length (Slave to Host) 0 - 218 bytes;
  • Values: 09H, 0AH and the values in the interval between 20H and FFH;
• 04 (Separator) - Separator. In the packaged message from Host to Slave, this is the byte which serves as a marker separating the logical data from the data on Slave’s status (status bytes).
  • Length: 1 byte;
  • Value: 04H;
• STATUS - the data field containing information on the current status of the fiscal device. In subsequent articles I will refer to bytes from this field as “status bytes”.
  • The meaning of every bit of every status byte should be acquired from the documentation of the relevant device;
  • The condition of a given bit corresponds logically to a specific device condition. In subsequent articles I will call all such bits “status bit”, and when referring to the condition of a given status we will refer to the value of the given status bit.
  • Unfortunately, it is possible for the position of a given status to change between different devices or even for the given status to be absent due to hardware specifics.
  • On the whole bits can be categorized in the following groups and subgroups:
    • Ones which can be ignored:
      • A given status bit can be saved for future use (depending on the situation it can always have a value of 0 or 1);
      • A given status bit can be saved for internal use (depending on the situation it can always have a value of 0 or 1);
    • Ones which should be paid special attention to:
      • Informative status bits - they carry information on the logical or physical condition of the device. Some operations are not permitted in certain situations and therefore it would be prudent to monitor them well. For example:
        • If the printer is out of paper - it cannot print out any documents whatsoever;
        • If the printer isn’t fiscalized - apparently it cannot issue fiscal receipts;
      • Error status bits - they carry general information on the error which has occurred. This can be a non-permitted command, a syntactic error etc. Sometimes (with the old protocol) the only way for the program to make a correct decision for resolving the situation is to assemble the information from all available statuses in the reply of Slave;
  • Old protocol:
    • Length: 6 bytes;
    • Values for each of the bytes: from 80H to FFH;
  • New protocol:
    • Length: 8 bytes;
    • Values for each of the bytes: from 80H to FFH;
• 05 (Data Terminator) - Separator.
  • In the packaged message from Host to Slave this is the byte which serves as a market, separating the logical data from the rest of the packaged message.
  • In the packaged message from Slave to Host this is the byte which serves as a market, separating the status data from the rest of the packaged message.
    • Value: 05H;
    • Length: 1 byte;
• BCC - Checksum. The checksum includes the values from <01> (excluding itself) to <05> (including itself). Since the possible values in this protocol are in the interval  [0..65535] (DEC), your program should fill in the necessary value in the variable of type word. Every digit of these two bytes is transmitted and 30H is added to it. As a result, there will be four bytes in the packaged message for this field. The reason for this coding is related to the internal execution of the protocol in fiscal devices and is of no matter;
  • Example: the variable with a value of 1AE3H in the packaged message is presented as four bytes with values as follows: 31H,3AH,3EH,33H;
  • Length: 2 bytes (word), coded in 4 bytes;
  • Values: from 30H to 3FH.
• 03 (Terminator) - A byte marking the end of the packaged message.
  • Length: 1 byte.
  • Value: 03H.

 

 

---

If you believe anything in this article is incorrect, incomplete or insufficient, please do write to me and I will correct it.