USB/RS232 - specifications

RS232 specifications are more complex than any other, it implies a strict data structure and data exchange workflow. This section will only talk about technical specifications regarding RS232, the concert data structure will be fully explained in other section.

So USB/RS232 means cash register and POS will be linked thanks to a cable, USB or RS232. The type of cable does not matter, the communication will work the same way in Concert. Unlike WIFI, USB/RS232 is half-duplex, it means cash register and POS cannot emit and receive messages simultaneously.

This is the list of speeds (baud or symbols/s) that PayXpress supports:

Each frame is composed of max 512 data bytes.

A data byte will be composed of 7 bits of data and a bit of parity.

The parity used in concert specifications is EVEN. It means the number of raised bits (1 bit) is always even in a data byte. If the 7 bits of data contain a even raised bits number, parity bit is 0, if it is odd, parity bit is 1.

This is a security control to prevent any tampering of the data. Regarding the 7 bits of data, they are ASCII-7 and the range of supported characters begins to 0x20 (hex) SPACE until 0x7F (hex) DEL. You can find the list of supported characters in this table.

In a frame, the first data byte is a command that defines the meaning of the frame. All the commands are described in the table below:

The specifications define the order of commands when cash register and POS communicate. Like in Ethernet/WIFI, the POS is in a waiting state and it is up to the cash register to initiate the communication.

• ENQ is always the first command to be sent, it opens a new session receiver side

• ACK is sent by the receiver to confirm that it successfully received the sender message

• NAK in the other hand is sent by the receiver to confirm that it did not receive the sender message or data controls failed

• STX and ETX are always sent together like this “STX<message>ETXlrc”. Sometimes, the word “message” in Concert specifications is used to refer to the entire frame

 This exchange data flow is fully explained below with diagram and tables.

Constant/variables names

Listening procedure for cash register & POS

Emitting procedure for cash register

Developer implementation notes

Unlike Ethernet/WIFI, USB/RS232 connection does not allow any multithreading processus. Do not start any new request if there is already one in running, it will lead to errors for both of them.

Parity and LRC controls on STX<message>ETXlrc receipt can be performed both in the same time because they only concern one frame and the same data. As a reminder, parity control is only done on ASCII-7 data bytes (no command byte) and LRC is computed from all ASCII-7 data bytes + ETX byte. This is a code snippet (kotlin) which performs both controls:

fun isParityBitOrLrcOk(frame: List<Byte>, lrc: Byte? = null): Boolean {
    var isParityAndLrcOk = false
    var computedLrc: Byte = 0x0
    // frame only contains ASCII-7 data bytes
    for (byte in frame) {
        val oneBitsCount = byte.countOneBits()
        // oneBitsCount is odd, there is a parity error
        if (oneBitsCount % 2 != 0) {
            return isParityAndLrcOk 
        }
        // LRC Computation
        if (lrc != null)
            computedLrc = computedLrc xor byte
    }
    // Frame does not contain ETX command, do a XOR using ETX value manually
    if (lrc != null && frame.last() != 0x03.toByte())
        computedLrc = computedLrc xor 0x03
    // Compare incoming LRC to the computed one
    return lrc == null || computedLrc == lrc
}

Same thing has to be done during the message building when cash register wants to send a message to the POS. This is a code snippet (kotlin) which builds the data to be sent with parity and lrc computation:

fun buildChunksForEmit(dataToSend: String): String {
    val commandStringBuilder = StringBuilder()
    var computedLrc: Byte = 0x0
    commandStringBuilder.append("02") // STX
    for (char in dataToSend) {
        val binaryRepresentation = char.code.toByte()
        val oneBitsCount = binaryRepresentation.countOneBits()
        val isOdd = oneBitsCount % 2 != 0
        val binaryRepresentationWithParity = 
            if (isParityCheckEnabled && isOdd) it.raiseBit(8)
            else it
        computedLrc = computedLrc xor binaryRepresentationWithParity 
        commandStringBuilder.append(
            binaryRepresentationWithParity
                .toUByte()
                .toInt()
                .toString(16)
        )    
    }
    // padStart ensure LRC hex representation length will always be 2
    val lrcAsString =
        (computedLrc xor 0x03)
            .toUByte()
            .toInt()
            .toString(16)
            .padStart(2, '0')
    val etxAndLrc = "03$lrcAsString" // ETX + LRC
    commandStringBuilder.append(etxAndLrc)
    return commandStringBuilder.toString()
}

If you want to use the code snippet above, please be careful, it builds a hex representation of the string, so each byte will become two chars. It is helpful for debugging/logs but make sure when you are sending this hex string that you convert each two chars couples in one byte before.