WebSocket Clock

Preface

There are a lot of web sites out there in the Internet that provide clocks to include in a webpage. Most of them focus on design and display the time of the local system clock of the user who visits the webpage. That clock can be quite wrong.

That's why the Physikalisch-Technische Bundesanstalt in Braunschweig, Germany, designed the WebSocket subprotocol 'Time' and runs a server for that protocol. This repository provides a script that implements the client side of that protocol and controls clocks for different time scales on a webpage.

This solution is GDPR complient. The server of the PTB is situated in the EU, and no data other than the local system time is transmitted to the server. All calculation is done locally.

What clocks can be displayed?

The following clocks are available:

Central European Time (CET, CEST)
Universal Time Coordinated (UTC) that is world time
Local Mean Time (LMT) of your location
Greenwich Mean Sidereal Time (GMST)
Local Mean Sidereal Time (LMST) of your location
Julian Date (digital only)
Modified Julian Date (digital only)
Dublin Julian Day (digital only)
Relative Time (additional data needed)
Countdown clock

Additionally:

Longitude that belongs to the displayed LMT or LMST
Length of the relative second

Prerequisites

Some knowledge in HTML and embedded SVG is useful but not essential.

Javascript must be enabled.

No jQuery required.

Installation

Put webSocketClock.js into some directory on your web server together with simpleclock.html from the html subdirectory of this repository.

You can then open simpleclock.html, and the clock starts running. Use parameters at the URL to control which kind of time is shown, for example simpleclock.html?tz=UTC for UTC.

If you want to create your own clock design replace simpleclock.html by an HTML file that includes the following:

    <script src="webSocketClock.js"></script>
    <script type="text/javascript">
      window.onload = function () {
        server_url = 'uhr.ptb.de/time'; // URL of the time server
        conf = {
          iso_date:false,             // date format
          longitude:13.040,           // longitude of the location
          UTC:{show:0,prefix:'ptb'},
          CET:{show:0,prefix:'ptb',name:'MEZ',offset:3600000,dst_name:'MESZ'},
          tz:{show:0,prefix:'ptb',name:'...',offset:...,dst_name:'...'},
          LMT:{show:0,prefix:'ptb',name:'LMT'},
          GMST:{show:0,prefix:'ptb'},
          LMST:{show:0,prefix:'ptb'},
          rel:{show:0,prefix:'ptb',url:'...'}
        }
        new WebSocketClock(server_url,conf); }
    </script>
    <svg ...>
      <!-- your clock face here -->
    </svg>

All the elements in conf can be omitted. In this case defaults take place. Replace the values in conf with values that meet your requirements.

The element "show" describes what to be shown:

0 - nothing is shown
1 - digital without date
2 - analagous without date
3 - both without date
4 - date only
5 - digital with date
6 - analogous with date
7 - both with date
16 - analogous 24 hour clock without date
17 - both digital and analogous 24 hour clock without date
20 - analogous 24 hour clock with date
21 - both digital and analogous 24 hour clock with date

values that can be or'ed or added with the other values:

8 - Microsoft Excel time
32 - full weekday name
64 - abbreviated weekday name

The element "prefix" needs to be set, if you have more than one clock on one page, only. Otherwise, the element can be omitted and the default "ptb" is used.

Examples for conf:

Central European Time clock
```
conf = {CET:{}};
```
The IDs of the HTML elements start with 'ptb' (the default).

UTC digital only

conf = {UTC:{show:5}};

The IDs of the HTML elements start with 'ptb'. To display the time, use:

<span id="ptbTime">--:--:--</span><br/>
<span id="ptbDate">--.--.----</span>

two clocks, one showing LMT, the other LMST
```
conf = {LMT:{prefix:'lmt'},LMST:{prefix:'lmst'}};
```
The IDs of the HTML elements for the LMT clock start with 'lmt', that of the LMST clock with 'lmst'.

Designing your own clock face

You may want to start with the command line tool createClockFace.py in the tools directory. Start it as

createClockFace.py --help

to see the available options. After you saved the resulting output to a file, you can further style the clock face.

Example: clock using roman numbers

sudo bash -c "tools/createClockFace.py --html --scale-style=line --scale-color=#267488 --digit=r,16px >/var/www/html/uhr.html"

Relative Time

In ancient times people divided both the light day and the night into 12 hours. Because sunrise and sunset vary in time, those hours also varied in length during the year. In summer the day hours were longer than the night hours, and vice versa in winter. Therefore it is called relative time (in german "Temporalzeit").

So with that clock 00:00:00 is at the time of sunrise or sunset, and 06:00:00 is at high noon or midnight local time.

To show that time, timestamps of sunrise and sunset are needed. That data is not provided by the PTB, so you have to provide it separately by a JSON file available for download. That JSON file must contain an array of sunset and sunrise timestamps, starting with a sunset in the past.

For example, that kind of time was used in ancient Israel. So you find such time data in the Bible. The time was used until the middle ages. So the Prague city hall clock shows this time.

IDs

If you set up a prefix other than ptb, replace "ptb" with the prefix you set up in configuration.

ID	description
`clockLongitude`	longitude for the local time
`ptbRelativeSecond`	length of the relative second in solar seconds
`ptbFaceBackground`	background color of the clock face
`ptbNotice`	connection state and error message
`ptbTabDeviation`	deviation display area (used to switch display state)
`ptbLinkDeviation`	button to switch on deviation display
`ptbDeviationTitle`	tool tip for deviation display
`ptbDeviation`	deviation display area (used to switch display state)
`ptbOffset`	actual deviation text of the clock
`ptbAccuracy`	actual accuracy text
`ptbDate`	date text
`ptbWeekday`	weekday text
`ptbTime`	digital time text
`ptbLocalTimezone`	time zone in effect
`ptbHour`	ordinal number of the hour in effect for relative time
`ptbHourName`	the word hour in the favorite language of the web browser for relative time
`ptbHour24Hand`	direction of a hand with 1 turn in 24 hours
`ptbHourHand`	direction of the hour hand
`ptbMinuteHand`	direction of the minute hand
`ptbSecondHand`	direction of the second hand
`ptbExcelTimeZone`	timezone of the Microsoft Excel time
`ptbExcelTime`	Microsoft Excel time (based on local timezone)
`JDUTC`	Julian Date (UTC)
`MJDUTC`	Modified Julian Date (UTC)
`DJDUTC`	Dublin Julian Day (UTC)
`UnixEpoch`	UNIX epoch time (based on UTC)
`LabViewTime`	National Instrument's LabView time (based on UTC)
`ptbCountdownDays`	countdown days
`ptbCountdownHours`	countdown hours
`ptbCountdownMinutes`	countdown minutes
`ptbCountdownSeconds`	countdown seconds
`ptbCountdownDaysLabel`	countdown days label
`ptbCountdownHoursLabel`	countdown hours label
`ptbCountdownMinutesLabel`	countdown minutes label
`ptbCountdownSecondsLabel`	countdown seconds label

Weekday

To display the weekday the following values can be or'ed or added to the values in the show element:

+32 - full weekday name
+64 - abbreviated weekday name

example configuration:

conf = {cet:{show:7+32}};

Within the clock face you need a text element with the ID ptbWeekday. "ptb" has to replaced by the prefix you set, if any.

in HTML: <span id="ptbWeekday"></span>
in SVG: <text x="..." y="..." id="ptbWeekday"></text>

The weekday is displayed according to the language setting of the user's browser. This is done by using the Javascript function toLocaleString() for all languages except german. The german weekday names are set in the element weekdays of WebSocketClock and can be changed there if necessary (for example if you want to set it to some dialect form).

24 Hour Clock

You can also create a clock with its hour hand turning once in a day only. To do so set show to 21 in the configuration. In the clock face replace the ID of the hour hand to ptbHour24Hand. To create such a clock face you can use createClockFace.py with the option --24

It is also possible to have both a 24-hour hand and a 12-hour hand in the same clock for specially designed clock faces. The option show is 22 in that case. An example would be an additional sun symbol turning around during the day while the normal hour hand shows the time.

Countdown clock

The countdown clock counts down days, hours, minutes, and seconds to a definite end timestamp.

end_ts = new Date(...)
conf = {countdown:{end:end_ts}};

HTML example:

<span id="ptbCountdownDays"></span>
<span id="ptbCountdownDaysLabel" clocklabel1="Tag" clocklabeln="Tage">Tage</span>,
<span id="ptbCountdownHours"></span>
<span id="ptbCountdownHoursLabel" clocklabel1="Stunde" clocklabeln="Stunden">Stunden</span>,
<span id="ptbCountdownMinutes"></span>
<span id="ptbCountdownMinutesLabel" clocklabel1="Minute" clocklabeln="Minuten">Minuten</span>
und
<span id="ptbCountdownSeconds"></span>
<span id="ptbCountdownSecondsLabel" clocklabel1="Sekunde" clocklabeln="Sekunden">Sekunden</span>

Czech HTML example (Český příklad):

<span id="ptbCountdownDays"></span>
<span id="ptbCountdownDaysLabel" clocklabel1="den" clocklabel2="dny" clocklabeln="dní">dní</span>,
<span id="ptbCountdownHours"></span>
<span id="ptbCountdownHoursLabel" clocklabel1="hodina" clocklabel2="hodiny" clocklabeln="hodin">hodin</span>,
<span id="ptbCountdownMinutes"></span>
<span id="ptbCountdownMinutesLabel" clocklabel1="minuta" clocklabel2="minuty" clocklabeln="minut">minut</span>
a
<span id="ptbCountdownSeconds"></span>
<span id="ptbCountdownSecondsLabel" clocklabel1="sekunda" clocklabel2="sekundy" clocklabeln="sekund">sekund</span>

Note: In czech there is not only singular and plural, but another ending for 2, 3, and 4.

Labels:

clocklabel1: label if the value is 1
clocklabel2: label if the value is 2, 3, or 4
clocklabeln: label if the value is from 5 on or 0

If clocklabel2 is missing, clocklabeln is used for 2, 3, and 4, too.

Additionally you can define a callback function, that is called when the end time is reached. In this case the configuration looks like that:

end_ts = new Date(...)
conf = {countdown:{end:end_ts,onend:function(config) {...}}};

Links

Example Page showing the possibilities
PTB-Mitteilungen, 129. Jahrgang, Heft 4, Dezember 2019, Seite 11ff.
M. Gutbrod, T. Klein, D. Sibold: WebSocket Subprotocol ‚Time‘. Physikalisch-Technische Bundesanstalt (PTB), Tech. Rep., 2017.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

WebSocket Clock

Preface

What clocks can be displayed?

Prerequisites

Installation

Designing your own clock face

Relative Time

IDs

Weekday

24 Hour Clock

Countdown clock

Links

Files

README.md

Latest commit

History

README.md

File metadata and controls

WebSocket Clock

Preface

What clocks can be displayed?

Prerequisites

Installation

Designing your own clock face

Relative Time

IDs

Weekday

24 Hour Clock

Countdown clock

Links