{"id":13834464,"url":"https://github.com/zkmkarlsruhe/tfluna","last_synced_at":"2026-02-15T22:17:56.842Z","repository":{"id":115416023,"uuid":"486551298","full_name":"zkmkarlsruhe/tfluna","owner":"zkmkarlsruhe","description":"Forward TF-Luna LIDAR sensor events over OSC, UDP, or Thingsboard","archived":false,"fork":false,"pushed_at":"2022-07-26T09:12:47.000Z","size":667,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-20T19:40:06.731Z","etag":null,"topics":["intelligent-museum","networking","osc","python","tf-luna-lidar","thingsboard","udp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zkmkarlsruhe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-04-28T10:40:56.000Z","updated_at":"2024-07-10T07:58:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"1dd461d9-88af-404a-a338-ce871db09faa","html_url":"https://github.com/zkmkarlsruhe/tfluna","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zkmkarlsruhe/tfluna","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkmkarlsruhe%2Ftfluna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkmkarlsruhe%2Ftfluna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkmkarlsruhe%2Ftfluna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkmkarlsruhe%2Ftfluna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zkmkarlsruhe","download_url":"https://codeload.github.com/zkmkarlsruhe/tfluna/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkmkarlsruhe%2Ftfluna/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264528744,"owners_count":23623221,"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":["intelligent-museum","networking","osc","python","tf-luna-lidar","thingsboard","udp"],"created_at":"2024-08-04T14:00:35.202Z","updated_at":"2026-02-15T22:17:56.789Z","avatar_url":"https://github.com/zkmkarlsruhe.png","language":"Python","funding_links":[],"categories":["Integrations"],"sub_categories":["Hardware"],"readme":"tfluna\n======\n\n![tfluna icon](media/icon.png)\n\nForward TF-Luna LIDAR sensor events over OSC, UDP, or Thingsboard.\n\nThis code base has been developed by [ZKM | Hertz-Lab](https://zkm.de/en/about-the-zkm/organization/hertz-lab) as part of the project [»The Intelligent Museum«](#the-intelligent-museum). \n\nCopyright (c) 2022 ZKM | Karlsruhe.  \nCopyright (c) 2022 Dan Wilcox.  \nCopyright (c) 2020 Daniel Heiss \u003cheiss@zkm.de\u003e  \nCopyright (c) 2020 Marc Schütze \u003cmschuetze@zkm.de\u003e  \n\nBSD Simplified License.\n\nDescription\n-----------\n\nThis script sends TF-Luna 1D ToF (Time of Flight) LIDAR sensor proximity distance measurements over OSC (default) or UDP\nand optional \"isThere\" presence events to a [ThingsBoard URL](https://thingsboard.io).\n\nThe distance measurement format is an integer in cm (default) or a normalized float (inverted, 1 near to 0 far).\n\nDependencies\n------------\n\n* Python 3\n* [pyserial library](https://github.com/pyserial/pyserial/)\n* [python-osc library](https://github.com/attwad/python-osc)\n* [requests library](https://github.com/psf/requests)\n\nSetup\n-----\n\nInstall Python 3, if not already available. For instance, on macOS using [Homebrew](http://brew.sh):\n\n```shell\nbrew install python3\n```\n\nCreate a virtual environment and install the script's dependencies:\n\n```shell\nmake\n```\n\n### Enable Raspberry Pi serial port for TF-Luna\n\nThe TF-Luna can be read over one of the built-in serial ports connected to the GPIO pins. Older boards (RPi 3) can use UART 1 or 2 while newer boards (RPi 4+) have additional UARTs available.\n\nhttps://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts\n\n![pi tfluna wiring diagram](media/pi%20tfluna%20wiring%20diagram.png)\n\n_Note: RX/TX wires may be different colors._\n\n#### UART 1\n\nRPi 3 or RPi 4\n\nGPIO pin connections\n* GPIO 14: sensor TX\n* GPIO 15: sensor RX\n* 5V+: sensor 5V (red)\n* GND: sensor GND (black)\n\nThis serial port is used for bluetooth by default. Disable this service and ensure the mini UART uses UART 0 by adding the following to `/boot/config.txt`:\n\n~~~\ndtoverlay=pi3-disable-bt,pi3-miniuart-bt\n~~~\n\nThen reboot:\n\n~~~\nsudo reboot\n~~~\n\nThe serial port should now be available as `/dev/ttyAMA0`.\n\nIf the port cannot be read (permissions issues), try the following [suggested on Stack Exchange](https://raspberrypi.stackexchange.com/a/48258 ):\n\n1. Remove anything that looks like `console=serial0,115200\n, console=tty1` in `/boot/cmdline.txt` file\n2. Disable the default tty and give the user access to the `dialout` group\n~~~\nsudo systemctl mask serial-getty@ttyAMA0.service\nsudo adduser $USER dialout\n~~~\n3. Reboot\n~~~\nsudo reboot\n~~~\n\n#### UART 3\n\nRPi 4+\n\nGPIO pin connections\n* GPIO 4: sensor TX\n* GPIO 5: sensor RX\n* 5V+: sensor 5V (red)\n* GND: sensor GND (black)\n\nThis UART is disabled by default. Enable it by adding the following to `/boot/config.txt`\n\n~~~\ndtoverlay=uart3\n~~~\n\nThen reboot:\n\n~~~\nsudo reboot\n~~~\n\nThe serial port should now be available as `/dev/ttyAMA1`.\n\n### USB to TTL dongle\n\nSome versions of the TF-Luna come with an included \"USB to TTL\" dongle which is essentially a USB serial port adapter with bare pins for the sensor. \n\nOn macOS, once the adapter is plugged in, it's serial port should be available at some variation of `/dev/tty.usbserial-*` such as `/dev/tty.usbserial-410` or `/dev/tty.usbserial-510`.\n\nRunning\n-------\n\nStart reading the sensor at serial port `DEV` on the commandline via the virtual environment wrapper script:\n\n    ./tfluna DEV\n\nFor example:\n\n    ./tfluna /dev/ttyAMA1\n\nIt can simply sit in the background and send events over a networking connection. To configure the send address and ports as well as various other options, see the commandline argument help for tfluna by running:\n\n    ./tfluna -h\n\nDefaults are:\n\n* OSC to 127.0.0.1 on port 5005\n* message format: `/tfluna distance`\n* distance format: centimeters\n* max distance: 200 cm\n\nMessages are sent over UDP either formatted as OSC messages (default) or raw UDP packets by using the `--udp` option. The message name is `tfluna` by default but can be overridden by using the `--message` option:\n\nMultiple instances can be run at the same time by providing a different serial port DEV argument. Additionally, an optional device identifier can be added to the message to differentiate between instances via the `--id` option. \n\n~~~\nMessage format: message [id] distance\n\n  Ex. OSC: \"/tfluna\" distance\n\n  Ex. UDP: \"tfluna\" distance\n~~~\n\nDistance measurements can be sent in a normalized format by using the `--normalize` option which uses an inverted range of 1 near and 0 far to the max distance which can also be specified in cm with the `--max-distance` option.\n\nOptionally, a boolean \"isThere\" event can be sent to a ThingsBoard URL whenever\nsomeone moves in front or away from the sensor:\n\n~~~\n$ --tb-url http://board.mydomain.com/api/v1/TOKEN/telemetry\nTB: {\"isThere\": 0}\n~~~\n\nThe default \"isThere\" message name can be overridden via --tb-message:\n\n~~~\n$ --tb-url http://board.mydomain.com/api/v1/TOKEN/telemetry \\\\\n--tb-message proximity\nTB: {\"proximity\": 0}\n~~~\n\nTest Client\n-----------\n\nA simple test client is provided which receives UDP messages on the default 127.0.0.1 address and port 5005 and prints their contents to the console.\n\nTo use, start the client:\n\n    ./tests/udpreceive.py\n\nNext, start tfluna in another shell:\n\n    ./tfluna --udp\n\n_Note: This client can also receive and print OSC messages, however the message content is printed in it's raw byte format._\n\nThe Intelligent Museum\n----------------------\n\nAn artistic-curatorial field of experimentation for deep learning and visitor participation\n\nThe [ZKM | Center for Art and Media](https://zkm.de/en) and the [Deutsches Museum Nuremberg](https://www.deutsches-museum.de/en/nuernberg/information/) cooperate with the goal of implementing an AI-supported exhibition. Together with researchers and international artists, new AI-based works of art will be realized during the next four years (2020-2023).  They will be embedded in the AI-supported exhibition in both houses. The Project „The Intelligent Museum” is funded by the Digital Culture Programme of the [Kulturstiftung des Bundes](https://www.kulturstiftung-des-bundes.de/en) (German Federal Cultural Foundation) and funded by the [Beauftragte der Bundesregierung für Kultur und Medien](https://www.bundesregierung.de/breg-de/bundesregierung/staatsministerin-fuer-kultur-und-medien) (Federal Government Commissioner for Culture and the Media).\n\nAs part of the project, digital curating will be critically examined using various approaches of digital art. Experimenting with new digital aesthetics and forms of expression enables new museum experiences and thus new ways of museum communication and visitor participation. The museum is transformed to a place of experience and critical exchange.\n\n![Logo](media/Logo_ZKM_DMN_KSB.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzkmkarlsruhe%2Ftfluna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzkmkarlsruhe%2Ftfluna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzkmkarlsruhe%2Ftfluna/lists"}