-
Notifications
You must be signed in to change notification settings - Fork 1
NXTP Protocol
While other internet time protocols such as NTP exist and are popular, the NXTP protocol is designed to be as simple and fast as possible, to encourage its use with retro computers.
The Client Computer is a retro computer or other general purpose computer, who wishes to know the current time.
The Client Program is a piece of software running on the Client Computer, whose task it is is to query the date or time from the Server Program. Usually it seeks to store the returned date or time in a temporary or permanent fashion, so that clock software running on the Client Computer can display the current time accurately.
The Server Computer is another computer on the public internet accessible on a published IP address or DNS hostname. Alternatively it can be a computer on a private intranet, whose address is known only to the Client Program.
The Server Program is a piece of software running on the Server Computer, whose responsibility it is to provide the current time to any Client Program asking for it.
NXTP is a versioned protocol. This allows each version to be simple and well-defined, yet the protocol as a whole can be extended as necessary.
Client Programs can choose which version to implement, and can have a reasonable expectation that public servers will support their chosen version.
Server Programs can easily support multiple versions, since the Universal Header can be tested before detailed protocol validation.
The general worflow sequence of Client and Server interactions is as follows:
- The Client Program makes a TCP connection to the Server Computer, at its listening port.
- Client Program sends a well-formed NXTP protocol Request packet.
- Server Program validates any or all aspects of the Request packet.
-
- If valid, the Server Program sends a well-formed Response packet for the same protocol version as the Request.
- If invalid, the Server Program doesn't send anything.
- The Server Program closes the TCP connection.
- If a Response packet was received, the Client Program validates any or all aspects of the Response packet.
-
- If valid, the Client Program displays and/or stores the received Date and Time.
- If invalid, the Client Program displays an error message.
- The Client Program closes the TCP connection.
Future protocol versions may support additional steps or alternative sequences, which will be detailed in the documentation for that protocol version.
Every version of the NXTP protocol supports the universal header in both the Request and Response packets. The Universal Header is the first byte of both the Request and Response packets.
| Field Name | No of Bytes | Status | Value/Notes |
|---|---|---|---|
| ProtocolVersion | 1 | Mandatory | The current and latest version is 1 |
Protocol version 1 allows the Client Program to send a Timezone Code, and receive the local Date and Time in that timezone, including any daylight savings time currently in effect.
A timezone code is an ASCII string of between 0 and 60 characters, with no spaces. The reference Server Program implementation recognises a list of 139 codes listed here, which broadly correspond to the list returned by the .NET Core 3.0 TimeZoneInfo.GetSystemTimeZones API (with a few additional aliases), although the .NET Core codes contain spaces, whereas the NXTP Timezone Codes do not.
Server Programs may be written to work with different platforms or frameworks, but every Version 1 Server Program must support the 139 Timezone Codes referenced here. They may also support additional Timezone Codes.
Client Programs have no intrinsic knowledge of Timezone Codes. An optional Timezone Code may be supplied to a Client Program by the end user, but this is passed to the Server Program without any semantic validation.
We must also bear in mind that while retro computers may have Real Time Clock chips, they very likely have no intrinsic knowledge of Coordinated Universal Time, Daylight Saving Time, the IANA Time Zone Database, business rules for working with the Database, or means to update the Database with national legislative changes. And it would be unreasonable to expect them to do so, given the size and complexity of the database. So the intent of the NXTP protocol is to offload that work to more capable computers on the internet.
| Field Name | No of Bytes | Status | Value/Notes |
|---|---|---|---|
| ProtocolVersion | 1 | Mandatory | The value is always 1 for this protocol version |
| TimezoneCodeLen | 1 | Mandatory | The length of TimezoneCode in bytes. Between 0 and 60 |
| TimezoneCode | 0..60 | Optional | One of the 139 Version 1 Timezone Codes in ASCII encoding. If not supplied the Server Program must return Greenwich Mean Time (as if the Client Program had supplied a Timezone Code value of GMT). |
| RequestChecksum | 1 | Mandatory | The XOR checksum of the Request Packet |
| Field Name | No of Bytes | Status | Value/Notes |
|---|---|---|---|
| ProtocolVersion | 1 | Mandatory | The value is always 1 for this protocol version |
| DateLen | 1 | Mandatory | The length of Date in bytes. This value is always 10 |
| TimeLen | 1 | Mandatory | The length of Time in bytes. This value is always 8 |
| Date | 10 | Mandatory | A calendar date, in fixed dd/MM/yyyy format, using ASCII encoding |
| Time | 8 | Mandatory | A time of day, in fixed HH:mm:ss format, using ASCII encoding |
| ResponseChecksum | 1 | Mandatory | The XOR checksum of the Response Packet |
Date and Time are fixed in the specified formats, as these correspond to the fixed input formats of the reference ZX Spectrum Next Client Program. International Client Programs should also expect to receive times in these fixed formats. Suitable transformations can be made by the Client Program after successful receipt of the Response Packet.
Version 1 checksums are calculated for both the Request Packet and the Response Packet.
They consist of a cumulative bitwise exclusive-or transformation of a set consisting of Initial Seed Value plus all the bytes of the Response or Request, except the final Checksum byte itself.
The Initial Seed Value for the Version 1 Protocol is the byte value 123 (decimal).
This Request packet gets the Date and Time in the default GMT zone:
| Field Name | No of Bytes | Value |
|---|---|---|
| ProtocolVersion | 1 | 1 |
| TimezoneCodeLen | 1 | 0 |
| TimezoneCode | 0 | |
| RequestChecksum | 1 | 123 ^ 1 ^ 0 = 122 |
This Request packet gets the Date and Time in the EasternStandardTime zone:
| Field Name | No of Bytes | Value |
|---|---|---|
| ProtocolVersion | 1 | 1 |
| TimezoneCodeLen | 1 | 19 |
| TimezoneCode | 19 | EasternStandardTime |
| RequestChecksum | 1 | 123 ^ 1 ^ 19 ^ E ^ a ^ s ^ t ^ e ^ r ^ n ^ S ^ t ^ a ^ n ^ d ^ a ^ r ^ d ^ T ^ i ^ m ^ e = 61
|
This Response packet returns a Date of 25/12/2019 and a Time of 21:43:25:
| Field Name | No of Bytes | Value |
|---|---|---|
| ProtocolVersion | 1 | 1 |
| DateLen | 1 | 10 |
| TimeLen | 1 | 8 |
| Date | 10 | 25/12/2019 |
| Time | 8 | 21:43:25 |
| ResponseChecksum | 1 | 123 ^ 1 ^ 10 ^ 8 ^ 2 ^ 5 ^ / ^ 1 ^ 2 ^ / ^ 2 ^ 0 ^ 1 ^ 9 ^ 2 ^ 1 ^ : ^ 4 ^ 3 ^ : ^ 2 ^ 5 = 117
|