Fresh KDS Local Network Discovery

Overview

The Fresh KDS application exposes, publishes, and receives messages on two separate ports.

Each protocol and port is used for different purposes. The User Datagram Protocol (UDP) is a core communication protocol to send messages to other nodes on the network. This will be used for broadcasting, described below. The Transmission Control Protocol (TCP) will be used to exchanges messages with the KDS application from your client POS.

Discovery Broadcast

In order to know where to send TCP packet and message data, you will first need to know to which node on your network data should be sent.

Each node (tablet) with KDS installed and running - also referred to as “screens” - sends a UDP broadcast message containing the Device Identifier, IP Address , and SDK version every two (2) seconds. To discover Fresh KDS screens on your network, listen for these UDP broadcast messages on port 28000.

The broadcasted message must be parsed by your consuming implementation. These values are unlabeled as they come across the network to your device (they are not structured using traditional XML/JSON paradigms); as such, the way we think about parsing data from Hexidecimal must change. As recommended elsewhere, language-native libraries (or otherwise) may be of assistance in converting the data to the necessary formats for consumption downstream by your implementation.

UDP & Hexadecimal Primer

UDP communicates using the Hexadecimal numeral system format. Each eventually plain-text ASCII character is represented by two characters in Hexadecimal format (representing a single Hexadecimal value). For instance, the literal FreshKDS (8 characters in length) is represented by 16 characters in Hexidecimal format. Each ASCII character, e.g. F, is represented by two characters, e.g. 46 - a single Hexidecimal value.

Example Broadcast

46726573684B445300000000312E300000000000C0A801030000000000004537413039414144374239380000000000000000656D756C61746F720000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

Theoretically, every value included in the above message will be delimited by a termination character in Hexadecimal: 00; however, relying on this exclusively can be problematic. Continue reading to learn how Fresh Technology has leveraged conventional TCP/UDP paradigms to transfer data.

Parsing UDP Broadcast Messages

The first legitimate segment in the above UDP broadcast message is:

46726573684B445300000000

Key things to understand about this message:

1. This segment has a character length of 24 characters.
2. This segment has a Hexadecimal length of 12 Hexidecimal values (a Hexademical value being a pair of characters).
3. Only 18 characters, 8 Hexadecimal values are populated.

In order to not break existing parsing expectations and to future-proof our over local network communications, Fresh Technology has built in buffer (blank values) to each segment of the broadcasted UDP message. This is critical for understanding our recommendation for parsing the broadcasted message.

Parsing Algorithm Recommendations

In How To Read The Broadcast Parsing Table below, you will see two key values: the starting Hexidecimal index of the needed value and the Hexidecimal length of that value.

Theoretically, every value is terminated or delimited by the first occurrence of 00 in the UDP broadcast. Where this becomes problematic is the need to represent 0 with Hexadecimal (such as an IP address): 0 in Hexadecimal is 00. Hence, as mentioned previously, we do not recommend using 00 as the delimiter between values. Rather, what we encourage is the use of the Hexadecimal index in conjunction with the Hexadecimal length to grab the correct number of characters from the provided Hexadecimal string.

How To Read The Broadcast Parsing Table

To re-use the above example:

46726573684B445300000000

In the above example, the value FreshKDS has total length of 12 Hexidecimal values (24 characters); however, only 8 values of those Hexidecimal pairs have meaning to you. How do you know this? Remember: it is not the 00 delimiter. You know this because this document tells you; this documentation defines the protocol for interacting with Fresk KDS via TCP/UDP.

In the table below, you will see a record like:

Index is in reference to the larger broadcasted message:

46726573684B445300000000312E300000000000C0A801030000...

Index tells us the position of the first Hexidecimal pair (the pair itself being two (2) characters in length) that represents the start of the described value. “Pairs” tells you how many Hexidecimal pairs you need to capture the entire value. Length tells you the character length - the true Index - 1 - of the position of the final character in the broadcast that contributes to a Hexidecimal pair.

Broadcast Parsing Table

Note(s)

• Version in the table above refers to the version of the protocol defined in this document. If the version is the same as you are expecting, you can be assured your parsing algorithm will work as there have been no changes to the message body’s structure.
• Name the logical name of the screen broadcasting the UDP message (for which the full example value is 656D756C61746F720000000000000000000000000000000000000000000000000000000000000000000000000000000000000000)