{"id":20975352,"url":"https://github.com/roe-dl/websocket-clock-js","last_synced_at":"2025-05-14T14:30:35.979Z","repository":{"id":136490487,"uuid":"431549391","full_name":"roe-dl/websocket-clock-js","owner":"roe-dl","description":"Displaying the atomic clock of the PTB on a web page","archived":false,"fork":false,"pushed_at":"2024-11-17T13:48:46.000Z","size":523,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-02T18:54:54.403Z","etag":null,"topics":["atomic-time","clock","javascript","ptb","time","websocket"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roe-dl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-24T16:09:24.000Z","updated_at":"2024-11-17T13:48:50.000Z","dependencies_parsed_at":"2024-01-01T08:47:54.083Z","dependency_job_id":"916405bd-da2d-4a09-83bd-071d59058e65","html_url":"https://github.com/roe-dl/websocket-clock-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fwebsocket-clock-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fwebsocket-clock-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fwebsocket-clock-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fwebsocket-clock-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roe-dl","download_url":"https://codeload.github.com/roe-dl/websocket-clock-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254160643,"owners_count":22024574,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atomic-time","clock","javascript","ptb","time","websocket"],"created_at":"2024-11-19T04:42:50.897Z","updated_at":"2025-05-14T14:30:35.606Z","avatar_url":"https://github.com/roe-dl.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebSocket Clock\n\n\u003cimg src=\"simpleClock.png\" width=\"50%\" /\u003e\n\n## Preface\n\nThere are a lot of web sites out there in the Internet that provide\nclocks to include in a webpage. Most of them focus on design and\ndisplay the time of the local system clock of the user who visits\nthe webpage. That clock can be quite wrong.\n\nThat's why the Physikalisch-Technische Bundesanstalt in Braunschweig,\nGermany, designed the WebSocket subprotocol 'Time' and runs a \nserver for that protocol. This repository provides a script that\nimplements the client side of that protocol and controls clocks \nfor different time scales on a webpage. \n\nThis solution is GDPR complient. The server of the PTB is situated\nin the EU, and no data other than the local system time is \ntransmitted to the server. All calculation is done locally.\n\n## What clocks can be displayed?\n\nThe following clocks are available:\n\n* Central European Time (CET, CEST)\n* Universal Time Coordinated (UTC) that is world time\n* Local Mean Time (LMT) of your location\n* Greenwich Mean Sidereal Time (GMST)\n* Local Mean Sidereal Time (LMST) of your location\n* Julian Date (digital only)\n* Modified Julian Date (digital only)\n* Dublin Julian Day (digital only)\n* Relative Time (additional data needed)\n* Countdown clock\n\nAdditionally:\n\n* Longitude that belongs to the displayed LMT or LMST\n* Length of the relative second\n\n## Prerequisites\n\nSome knowledge in HTML and embedded SVG is useful but not essential.\n\nJavascript must be enabled.\n\nNo jQuery required.\n\n## Installation\n\nPut `webSocketClock.js` into some directory on your web server \ntogether with `simpleclock.html` from the `html` subdirectory of\nthis repository.\n\nYou can then open `simpleclock.html`, and the clock starts running.\nUse parameters at the URL to control which kind of time is shown,\nfor example `simpleclock.html?tz=UTC` for UTC.\n\nIf you want to create your own clock design replace simpleclock.html\nby an HTML file that includes the following:\n\n```\n    \u003cscript src=\"webSocketClock.js\"\u003e\u003c/script\u003e\n    \u003cscript type=\"text/javascript\"\u003e\n      window.onload = function () {\n        server_url = 'uhr.ptb.de/time'; // URL of the time server\n        conf = {\n          iso_date:false,             // date format\n          longitude:13.040,           // longitude of the location\n          UTC:{show:0,prefix:'ptb'},\n          CET:{show:0,prefix:'ptb',name:'MEZ',offset:3600000,dst_name:'MESZ'},\n          tz:{show:0,prefix:'ptb',name:'...',offset:...,dst_name:'...'},\n          LMT:{show:0,prefix:'ptb',name:'LMT'},\n          GMST:{show:0,prefix:'ptb'},\n          LMST:{show:0,prefix:'ptb'},\n          rel:{show:0,prefix:'ptb',url:'...'}\n        }\n        new WebSocketClock(server_url,conf); }\n    \u003c/script\u003e\n    \u003csvg ...\u003e\n      \u003c!-- your clock face here --\u003e\n    \u003c/svg\u003e\n```\n\nAll the elements in conf can be omitted. In this case defaults\ntake place. Replace the values in conf with values that meet your\nrequirements.\n\nThe element \"show\" describes what to be shown:\n\n* 0 - nothing is shown\n* 1 - digital without date\n* 2 - analagous without date\n* 3 - both without date\n* 4 - date only\n* 5 - digital with date\n* 6 - analogous with date\n* 7 - both with date\n* 16  - analogous 24 hour clock without date\n* 17  - both digital and analogous 24 hour clock without date\n* 20  - analogous 24 hour clock with date\n* 21  - both digital and analogous 24 hour clock with date\n\nvalues that can be or'ed or added with the other values:\n\n* 8 - Microsoft Excel time\n* 32 - full weekday name\n* 64 - abbreviated weekday name\n\nThe element \"prefix\" needs to be set, if you have more than one\nclock on one page, only. Otherwise, the element can be omitted\nand the default \"ptb\" is used.\n\nExamples for `conf`:\n\n* Central European Time clock\n  ```\n  conf = {CET:{}};\n  ```\n  The IDs of the HTML elements start with 'ptb' (the default).\n* UTC digital only\n  ```\n  conf = {UTC:{show:5}};\n  ```\n  The IDs of the HTML elements start with 'ptb'. To display the time, use:\n  ```\n  \u003cspan id=\"ptbTime\"\u003e--:--:--\u003c/span\u003e\u003cbr/\u003e\n  \u003cspan id=\"ptbDate\"\u003e--.--.----\u003c/span\u003e\n  ```\n* two clocks, one showing LMT, the other LMST \n  ```\n  conf = {LMT:{prefix:'lmt'},LMST:{prefix:'lmst'}};\n  ```\n  The IDs of the HTML elements for the LMT clock start with 'lmt',\n  that of the LMST clock with 'lmst'. \n\n## Designing your own clock face\n\nYou may want to start with the command line tool `createClockFace.py`\nin the `tools` directory. Start it as\n```\ncreateClockFace.py --help\n```\nto see the available options. After you saved the resulting output\nto a file, you can further style the clock face.\n\nExample: clock using roman numbers\n```\nsudo bash -c \"tools/createClockFace.py --html --scale-style=line --scale-color=#267488 --digit=r,16px \u003e/var/www/html/uhr.html\"\n```\n\n\u003cimg src=\"roman-clock-600.png\" width=\"50%\" /\u003e\n\n## Relative Time\n\nIn ancient times people divided both the light day and the night\ninto 12 hours. Because sunrise and sunset vary in time, those\nhours also varied in length during the year. In summer the day\nhours were longer than the night hours, and vice versa in winter.\nTherefore it is called relative time (in german \"Temporalzeit\").\n\nSo with that clock 00:00:00 is at the time of sunrise or sunset,\nand 06:00:00 is at high noon or midnight local time.\n\nTo show that time, timestamps of sunrise and sunset are needed.\nThat data is not provided by the PTB, so you have to provide it\nseparately by a JSON file available for download. That JSON file\nmust contain an array of sunset and sunrise timestamps, starting\nwith a sunset in the past. \n\nFor example, that kind of time was used in ancient Israel. So\nyou find such time data in the Bible. The time was used until the\nmiddle ages. So the Prague city hall clock shows this time.\n\n## IDs\n\nIf you set up a prefix other than `ptb`, replace \"ptb\" with the prefix\nyou set up in configuration.\n\nID | description\n---|-------------\n`clockLongitude` | longitude for the local time\n`ptbRelativeSecond` | length of the relative second in solar seconds\n`ptbFaceBackground` | background color of the clock face\n`ptbNotice` | connection state and error message\n`ptbTabDeviation` | deviation display area (used to switch display state)\n`ptbLinkDeviation` | button to switch on deviation display\n`ptbDeviationTitle` | tool tip for deviation display\n`ptbDeviation` | deviation display area (used to switch display state)\n`ptbOffset` | actual deviation text of the clock \n`ptbAccuracy` | actual accuracy text\n`ptbDate` | date text\n`ptbWeekday` | weekday text\n`ptbTime` | digital time text\n`ptbLocalTimezone` | time zone in effect\n`ptbHour` | ordinal number of the hour in effect for relative time\n`ptbHourName` | the word hour in the favorite language of the web browser for relative time\n`ptbHour24Hand` | direction of a hand with 1 turn in 24 hours\n`ptbHourHand` | direction of the hour hand\n`ptbMinuteHand` | direction of the minute hand\n`ptbSecondHand` | direction of the second hand\n`ptbExcelTimeZone` | timezone of the Microsoft Excel time \n`ptbExcelTime` | Microsoft Excel time (based on local timezone)\n`JDUTC` | Julian Date (UTC)\n`MJDUTC` | Modified Julian Date (UTC)\n`DJDUTC` | Dublin Julian Day (UTC)\n`UnixEpoch` | UNIX epoch time (based on UTC)\n`LabViewTime` | National Instrument's LabView time (based on UTC)\n`ptbCountdownDays` | countdown days\n`ptbCountdownHours` | countdown hours\n`ptbCountdownMinutes` | countdown minutes\n`ptbCountdownSeconds` | countdown seconds\n`ptbCountdownDaysLabel` | countdown days label\n`ptbCountdownHoursLabel` | countdown hours label\n`ptbCountdownMinutesLabel` | countdown minutes label\n`ptbCountdownSecondsLabel` | countdown seconds label\n\n## Weekday\n\nTo display the weekday the following values can be or'ed or added\nto the values in the `show` element:\n\n* +32 - full weekday name\n* +64 - abbreviated weekday name\n\nexample configuration:\n\n```\nconf = {cet:{show:7+32}};\n```\n\nWithin the clock face you need a text element with the ID\n`ptbWeekday`. \"ptb\" has to replaced by the prefix you set, if any.\n\n* in HTML: `\u003cspan id=\"ptbWeekday\"\u003e\u003c/span\u003e`\n* in SVG: `\u003ctext x=\"...\" y=\"...\" id=\"ptbWeekday\"\u003e\u003c/text\u003e`\n\nThe weekday is displayed according to the language setting of\nthe user's browser. This is done by using the Javascript function\n`toLocaleString()` for all languages except german. The german\nweekday names are set in the element `weekdays` of `WebSocketClock`\nand can be changed there if necessary (for example if you want\nto set it to some dialect form).\n\n## 24 Hour Clock\n\nYou can also create a clock with its hour hand turning once in a\nday only. To do so set `show` to 21 in the configuration. In the\nclock face replace the ID of the hour hand to `ptbHour24Hand`.\nTo create such a clock face you can use `createClockFace.py`\nwith the option `--24`\n\n\u003cimg src=\"24-hour-clock-600.png\" width=\"50%\" /\u003e\n\nIt is also possible to have both a 24-hour hand and a 12-hour\nhand in the same clock for specially designed clock faces. \nThe option `show` is 22 in that case. An example would be\nan additional sun symbol turning around during the day while\nthe normal hour hand shows the time.\n\n## Countdown clock\n\nThe countdown clock counts down days, hours, minutes, and seconds\nto a definite end timestamp.\n\n```Javascript\nend_ts = new Date(...)\nconf = {countdown:{end:end_ts}};\n```\n\nHTML example:\n```HTML\n\u003cspan id=\"ptbCountdownDays\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownDaysLabel\" clocklabel1=\"Tag\" clocklabeln=\"Tage\"\u003eTage\u003c/span\u003e,\n\u003cspan id=\"ptbCountdownHours\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownHoursLabel\" clocklabel1=\"Stunde\" clocklabeln=\"Stunden\"\u003eStunden\u003c/span\u003e,\n\u003cspan id=\"ptbCountdownMinutes\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownMinutesLabel\" clocklabel1=\"Minute\" clocklabeln=\"Minuten\"\u003eMinuten\u003c/span\u003e\nund\n\u003cspan id=\"ptbCountdownSeconds\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownSecondsLabel\" clocklabel1=\"Sekunde\" clocklabeln=\"Sekunden\"\u003eSekunden\u003c/span\u003e\n```\n\nCzech HTML example (Český příklad):\n```HTML\n\u003cspan id=\"ptbCountdownDays\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownDaysLabel\" clocklabel1=\"den\" clocklabel2=\"dny\" clocklabeln=\"dní\"\u003ední\u003c/span\u003e,\n\u003cspan id=\"ptbCountdownHours\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownHoursLabel\" clocklabel1=\"hodina\" clocklabel2=\"hodiny\" clocklabeln=\"hodin\"\u003ehodin\u003c/span\u003e,\n\u003cspan id=\"ptbCountdownMinutes\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownMinutesLabel\" clocklabel1=\"minuta\" clocklabel2=\"minuty\" clocklabeln=\"minut\"\u003eminut\u003c/span\u003e\na\n\u003cspan id=\"ptbCountdownSeconds\"\u003e\u003c/span\u003e\n\u003cspan id=\"ptbCountdownSecondsLabel\" clocklabel1=\"sekunda\" clocklabel2=\"sekundy\" clocklabeln=\"sekund\"\u003esekund\u003c/span\u003e\n```\n\nNote: In czech there is not only singular and plural, but another ending\nfor 2, 3, and 4. \n\nLabels:\n* `clocklabel1`: label if the value is 1\n* `clocklabel2`: label if the value is 2, 3, or 4\n* `clocklabeln`: label if the value is from 5 on or 0\n\nIf `clocklabel2` is missing, `clocklabeln` is used for 2, 3, and 4, too.\n\nAdditionally you can define a callback function, that is called when\nthe end time is reached. In this case the configuration looks like that:\n\n```Javascript\nend_ts = new Date(...)\nconf = {countdown:{end:end_ts,onend:function(config) {...}}};\n```\n\n## Links\n\n* [Example Page showing the possibilities](https://www.woellsdorf-wetter.de/clock/astronomy.html)\n* [PTB-Mitteilungen, 129. Jahrgang, Heft 4, Dezember 2019\u003c/a\u003e, Seite 11ff.](https://www.ptb.de/cms/fileadmin/internet/publikationen/ptb_mitteilungen/mitt2019/PTB-Mitteilungen_2019_Heft_4.pdf)\n* M. Gutbrod, T. Klein, D. Sibold: [WebSocket Subprotocol ‚Time‘](https://uhr.ptb.de/wst/paper). Physikalisch-Technische Bundesanstalt (PTB), Tech. Rep., 2017.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froe-dl%2Fwebsocket-clock-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froe-dl%2Fwebsocket-clock-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froe-dl%2Fwebsocket-clock-js/lists"}