{"id":17717270,"url":"https://github.com/bwesterb/tkbd","last_synced_at":"2025-03-14T02:31:10.304Z","repository":{"id":1885825,"uuid":"2811657","full_name":"bwesterb/tkbd","owner":"bwesterb","description":"Terminal Kamer Bezetting daemon voor faculteit NWI van de Radboud Universiteit","archived":false,"fork":false,"pushed_at":"2014-04-22T15:53:28.000Z","size":331,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-06T06:58:30.381Z","etag":null,"topics":["ru","welke-tk"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bwesterb.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}},"created_at":"2011-11-20T00:49:23.000Z","updated_at":"2014-04-22T15:53:28.000Z","dependencies_parsed_at":"2022-09-07T13:51:47.165Z","dependency_job_id":null,"html_url":"https://github.com/bwesterb/tkbd","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwesterb%2Ftkbd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwesterb%2Ftkbd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwesterb%2Ftkbd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bwesterb%2Ftkbd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bwesterb","download_url":"https://codeload.github.com/bwesterb/tkbd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243511641,"owners_count":20302592,"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":["ru","welke-tk"],"created_at":"2024-10-25T14:19:36.926Z","updated_at":"2025-03-14T02:31:09.990Z","avatar_url":"https://github.com/bwesterb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"tkbd\n====\n`tkbd` is a daemon run on the faculty of sciences of the\n[Radboud University Nijmegen](http://ru.nl) to register\nwhich computer lab PC's are free and which are taken.\n\n[tkb.js](http://github.com/bwesterb/tkb.js) is a frontend.\n\nHow it works\n------------\n### Information stored\n`tkbd` maintains three bits of information. See `state.py`.\n\n1. *occupation*: for each PC its current state, which is either:\n   - `o` the PC is turned off\n   - `x` the PC is in an unknown state\n   - `wf` the PC is free and booted in Windows\n   - `lf` the PC is free and booted in Linux\n   - `wu` the PC is used and booted in Windows \n   - `lu` the PC is used and booted in Linux\n   - `wx` the PC is booted in Windows, but we do not know if it is used\n   - `lx` the PC is booted in Linux, but we do not know if it is used\n2. *roomMap*: a list of rooms and the PC's in it.\n3. *schedule*: for each room, the possible reservations of it.\n4. *tagMap*: a list of tags and the rooms belonging to each tag.\n   For instance, in the `hg` tag (which is short for Huygens Gebouw)\n   are all the rooms of the Huygens Gebouw.\n\n### Source of information\nWhen people log in and out of computers, this is logged.\nA script watches the log and pushes changes to `tkbd` via\nHTTP requests on port 1235. See `cnczPush.py`.\n\nSecondly, another script periodically polls all PCs.\nThe results of this scan are also pushed to port 1235.\n\nThe schedule is pulled from [Ruuster](http://ruuster.nl).\nSee `ruuster.py`.\n\n### How to access it\n#### Joyce\n`tkbd` uses a bidirectional JSON message exchanging protocol over HTTP\ncalled Joyce.  A client can create many channels with the server.\nOn each of these channels, the server and the client can send messages\nto eachother.\n\n1. To create a channel, send a HTTP GET request to the server for `/?m=null`.\n   The server wil respond with an array `[\u003ctoken\u003e, \u003cmessages\u003e, \u003cstreams\u003e]`.\n   `token` contains the token assigned to this channel. `messages` is a list\n   of messages the server has send. `streams` is not important for `tkbd`.\n2. After this, you should send another HTTP GET request to the server. This\n   time for `/?m=[\u003ctoken\u003e]`. This time the server might not respond immediately.\n   When there is a message (or after a timeout), the server will\n   respond with a similar array `[\u003ctoken\u003e, \u003cmessages\u003e, \u003cstreams\u003e]`.\n3. To send a list of messages `messages`, send a HTTP GET request\n   to the server for `/?m=[\u003ctoken\u003e, \u003cmessages\u003e]`. Now there are two outstanding\n   HTTP requests. The one to send these messages and another to receive.\n   One of these two will be responded to immediately. The other will stay\n   open to receive messages.\n\nSo, what messages does `tkbd` send and `tkbd` likes to receive?\n\n#### Messages received by `tkbd`\nThese are the messages understood by `tkbd`.  See `cometApi.py`.\n\n1. `{\"type\": \"set_msgFilter\", \"schedule\":filter1, \"roomMap\":filter2, \"occupation\":filter3}`\n\n    When checking the occupation of PC's in the Huygens Gebouw, one is not interested\n    occupation updates for PC's in other faculties.  When the server receives this\n    message, it will set a message filter for the three types of messages.  A filter\n    is either a list of tags to allow (eg. `[\"hg\"]`) or `null` which means\n    \"do not filter\".\n    \n    The default filters are all `[]`.  That is: all rooms and PC's are filtered out and\n    thus no update is sent.\n    \n2. `{\"type\": \"get_occupation\"}`\n\n    When received, the server will send in return an `occupation` message.\n    (See below.)\n\n3. `{\"type\": \"get_roomMap\"}`\n\n    When received, the server will send in return a `roomMap` message.\n    (See below.)\n\n4. `{\"type\": \"get_schedule\"}`\n\n    When received, the server will send in return a `schedule` message.\n    (See below.)\n\n5. `{\"type\": \"get_tag_names\"}`\n\n    When received, the server will send in return a `tags` message. (See below.)\n\n6. `{\"type\": \"get_tagMap\"}`\n\n    When received, the server will send in return a `tagMap` message. (See below.)\n\n7. `{\"type\": \"get_historic_updates\", \"offset\": \u003coffset\u003e, \"count\": \u003ccount\u003e}`\n\n    When received, the server will send in return a `historic_updates` message.\n    (See below.)\n\n\n#### Messages sent by `tkbd`\nEvery messages sent by `tkbd` is one of the following. See `cometApi.py`.\n\n1. `{\"type\": \"welcome\", \"protocols\" : [1]}`\n\n    This is the first message sent. It tells which protocols `tkbd` understands.\n    Currently, there is only protocol supported: `1`.\n\n2. `{\"type\": \"occupation\", \"version\": \u003cversion\u003e, \"occupation\": \u003coccupation\u003e}`\n\n    It contains the current occupation of PC's. `occupation` is a dictionary\n    with as keys names of PC's and as values the state of the corresponding PC's.\n    Only PC's are included that match the current `occupation` filter.\n    (See `set_msgFilter`.)\n\n3. `{\"type\": \"roomMap\", \"version\": \u003cversion\u003e, \"roomMap\": \u003croomMap\u003e}`\n\n    `roomMap` is a dictionary with as keys names of rooms and as values the\n    corresponding list of PC's in that room.  Only PC's are included that\n    match the current `roomMap` filter. (See `set_msgFilter`.)\n\n4. `{\"type\": \"schedule\", \"version\": \u003cversion\u003e, \"schedule\": \u003cschedule\u003e}`\n\n    `schedule` is a dictionary with as keys names of rooms and as values the\n    corresponding schedule of that room.  A schedule of a room is a list of\n    events.\n    An event is a list with three element: the first element is the starting\n    time; the second is the ending time and the third is a decription of\n    the event.\n    Only rooms are included that match the current `schedule` filter.\n    (See `set_msgFilter`.)\n\n5. `{\"type\": \"occupation_update\", \"version\": \u003cversion\u003e, \"update\": \u003cupdate\u003e}`\n\n    This  message is sent, when the occupation of one or more PCs changes.\n    `update` is a dictionary with as keys PC names and as values the\n    new state of the corresponding PC.\n    Only updates are sent for PC's that match the current `occupation` filter.\n    (See `set_msgFilter`.)\n\n6.  `{\"type\": \"tags\", \"tags\": \u003ctags\u003e}`\n\n    This is the second message sent.  `tags` is the list of tags.\n\n7.  `{\"type\": \"tagMap\", \"tagMap\": \u003ctagMap\u003e}`\n\n    `tagMap` is a dictionary with as keys names of tags and as values the\n    corresponding list of rooms that have the tag.\n\n8.  `{\"type\": \"historic_updates\", \"count\": \u003ccount\u003e, \"offset\": \u003coffset\u003e, \"updates\": \u003cupdates\u003e}`\n\n    This gives `count` historic updates from the `offset`th one.\n    `updates` is a list of quadrupels\n    `[\u003cpc\u003e, \u003csource\u003e, \u003cunix timestamp\u003e, \u003coccupation\u003e]`.\n\nOn every update of the occupation, roomMap, tagMap or schedule, the\ncorresponding version is incremented by one.\n\nHow to install it\n-----------------\nThe simplest way to install `tkbd` is to run\n\n```\n$ easy_install tkbd\n```\n\n`easy_install` is a part of Python's\n[setuptools](http://pypi.python.org/pypi/setuptools).\n(In Debian, try `apt-get install python-setuptools`).\n\nHow to run it\n-------------\nTo run, simply execute:\n\n```\n$ mirte tkbd/setups/default\n```\n\nThis will run the default setup of `tkbd`.  For changes in occupation\nit will listen on port 1235.  This is not useful if you are not\nthe IT guys of the faculty. \n\nYou can configure `tkbd` to mirror another `tkbd` instance.  To\nmirror the default `tk.science.ru.nl`, simply run:\n\n```\n$ mirte tkbd/setups/slave\n```\n\nTo create a custom configuration, copy and edit one of the `.mirte` files\nin `src/setups`.\n\nChangelog\n---------\n* 0.3.10:\n   * Add mytimetable to fetch schedule from mytimetable\n     (eg. persoonlijkrooster.ru.nl).  By Wouter Geraedts.\n* 0.3.9\n   * ruuster: use event comment when course name equals Reserveringen\n   * state: updated rooms\n* 0.3.8:\n   * state: handle schedule exceptions correctly\n* 0.3.7:\n   * ruuster: handle more exceptions gracefully\n* 0.3.6:\n   * Add get_historic_updates to API\n* 0.3.5:\n   * Some minor improvements and bugfixes in the history and mirror modules\n* 0.3.4:\n   * keep history of occupation updates in a SQQLite3 database\n* 0.3.3:\n   * mirror: support tags\n   * ruuster: normalize event names\n   * ruuster: handle errors more gracefully\n* 0.3.2\n   * Fix: do not crash on new schedule.\n* 0.3.1\n   * Fix: special `null' tag filter to disable filter is properly set\n* 0.3.0\n  * Feature: add tags.  This will allow multiple `screens' running on the\n    same tkbd.\n* 0.2.4\n  * Fix: keep mirror running if master is down for a while\n  * Fix: ignore PCs with names ending with `docent'\n* 0.2.3\n  * Fix: properly package .mirte files\n  * Fix: send proper start and ending times for the scheduled events\n* 0.2.0\n  * Support for mirroring\n  * Fix some bugs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwesterb%2Ftkbd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbwesterb%2Ftkbd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbwesterb%2Ftkbd/lists"}