{"id":13759548,"url":"https://github.com/jahnf/Projecteur","last_synced_at":"2025-05-10T09:32:54.903Z","repository":{"id":33761346,"uuid":"154564223","full_name":"jahnf/Projecteur","owner":"jahnf","description":"Linux Desktop Application for the Logitech Spotlight device (and similar devices) - Digital Laser Pointer","archived":false,"fork":false,"pushed_at":"2024-09-03T22:19:14.000Z","size":1991,"stargazers_count":387,"open_issues_count":18,"forks_count":33,"subscribers_count":14,"default_branch":"develop","last_synced_at":"2024-11-15T13:58:26.784Z","etag":null,"topics":["desktop-application","linux","logitech","logitech-spotlight-device","presentation","qml","qt5","virtual-laser"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jahnf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2018-10-24T20:21:35.000Z","updated_at":"2024-11-15T05:24:21.000Z","dependencies_parsed_at":"2023-11-12T07:25:35.332Z","dependency_job_id":"d95dfa42-7872-457f-9701-159456556351","html_url":"https://github.com/jahnf/Projecteur","commit_stats":{"total_commits":540,"total_committers":17,"mean_commits":"31.764705882352942","dds":"0.16296296296296298","last_synced_commit":"89bdac1fee8aa963d992bd6430f16241862833fb"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahnf%2FProjecteur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahnf%2FProjecteur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahnf%2FProjecteur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jahnf%2FProjecteur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jahnf","download_url":"https://codeload.github.com/jahnf/Projecteur/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224941032,"owners_count":17395811,"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":["desktop-application","linux","logitech","logitech-spotlight-device","presentation","qml","qt5","virtual-laser"],"created_at":"2024-08-03T13:00:55.245Z","updated_at":"2024-11-16T16:31:04.712Z","avatar_url":"https://github.com/jahnf.png","language":"C++","readme":"# Projecteur\n\ndevelop: [![Build Status develop][gh-badge-dev]][gh-link-dev]\nmaster: [![Build Status master][gh-badge-rel]][gh-link-rel]\n\nLinux/X11 application for the Logitech Spotlight device (and similar devices). \\\nSee **[Download](#download)** section for binary packages.\n\n[gh-badge-dev]: https://github.com/jahnf/Projecteur/workflows/ci-build/badge.svg?branch=develop\n[gh-badge-rel]: https://github.com/jahnf/Projecteur/workflows/ci-build/badge.svg?branch=master\n[gh-link-dev]: https://github.com/jahnf/Projecteur/actions?query=workflow%3Aci-build+branch%3Adevelop\n[gh-link-rel]: https://github.com/jahnf/Projecteur/actions?query=workflow%3Aci-build+branch%3Amaster\n\n## Motivation\n\nI saw the Logitech Spotlight device in action at a conference and liked it immediately.\nUnfortunately as in a lot of cases, software is only provided for Windows and Mac.\nThe device itself works just fine on Linux, but the cool spotlight feature is\nonly available using additional software.\n\nSo here it is: a Linux application for the Logitech Spotlight.\n\n## Table of Contents\n\n- [Projecteur](#projecteur)\n  - [Motivation](#motivation)\n  - [Table of Contents](#table-of-contents)\n  - [Features](#features)\n    - [Screenshots](#screenshots)\n    - [Planned features](#planned-features)\n  - [Supported Environments](#supported-environments)\n  - [How it works](#how-it-works)\n    - [Button mapping](#button-mapping)\n      - [Hold Button Mapping for Logitech Spotlight](#hold-button-mapping-for-logitech-spotlight)\n  - [Download](#download)\n  - [Building](#building)\n    - [Requirements](#requirements)\n    - [Build Example](#build-example)\n  - [Installation/Running](#installationrunning)\n    - [Pre-requisites](#pre-requisites)\n      - [When building Projecteur yourself](#when-building-projecteur-yourself)\n    - [Application Menu](#application-menu)\n    - [Command Line Interface](#command-line-interface)\n    - [Scriptability](#scriptability)\n    - [Using Projecteur without a device](#using-projecteur-without-a-device)\n    - [Device Support](#device-support)\n      - [Compile Time](#compile-time)\n      - [Runtime](#runtime)\n    - [Troubleshooting](#troubleshooting)\n      - [Opaque Spotlight / No Transparency](#opaque-spotlight--no-transparency)\n      - [Missing System Tray](#missing-system-tray)\n      - [Zoom is not updated while spotlight is shown](#zoom-is-not-updated-while-spotlight-is-shown)\n      - [Wayland](#wayland)\n      - [Wayland Zoom](#wayland-zoom)\n      - [Device shows as not connected](#device-shows-as-not-connected)\n  - [Changelog](#changelog)\n  - [License](#license)\n\n## Features\n\n* Configurable desktop spotlight\n  * _shade color_, _opacity_, _cursor_, _border_, _center dot_ and different _shapes_\n  * Zoom (magnifier) functionality\n* Multiple screen support\n* Support of devices beyond the Logitech Spotlight (see [Device Support](#device-support))\n* Button mapping:\n  * Map any button on the device to (almost) any keyboard combination.\n  * Switch between (cycle through) custom spotlight presets.\n  * Audio Volume / Horizontal and Vertical Scrolling (Logitech Spotlight).\n* Vibration (Timer) Support for the Logitech Spotlight\n* Usable without a presenter device (e.g. for online presentations)\n\n### Screenshots\n\n[\u003cimg src=\"doc/screenshot-settings.png\" height=\"300\" /\u003e](./doc/screenshot-settings.png)\n[\u003cimg src=\"doc/screenshot-spot.png\" height=\"300\" /\u003e](./doc/screenshot-spot.png)\n[\u003cimg src=\"doc/screenshot-button-mapping.png\" height=\"300\" /\u003e](./doc/screenshot-button-mapping.png)\n[\u003cimg src=\"doc/screenshot-traymenu.png\" /\u003e](./doc/screenshot-traymenu.png)\n\n### Planned features\n\n* Support for more customizable button mapping actions.\n* Support of more proprietary features of the Logitech Spotlight and other devices.\n\n## Supported Environments\n\nThe application was mostly tested on Ubuntu 18.04, Ubuntu 20.04 (GNOME) and\nOpenSuse 15 (GNOME) but should work on almost any Linux/X11 Desktop. In case\nyou are building the application yourself, make sure you have the correct udev\nrules installed (see [pre-requisites section](#pre-requisites)).\n\n## How it works\n\nWith a connection via the USB Dongle Receiver or via Bluetooth, the Logitech Spotlight\ndevice will be detected by Linux as a HID device with mouse and keyboard events.\nAs mouse events, the device sends relative cursor movements and left button presses.\nActing as a keyboard, the device basically just sends left and right arrow key press\nevents when forward or back is pressed on the device.\n\nThe mouse move events of the device are what we are mainly interested in. Since the device is\nalready detected as a mouse input device and able to move the cursor, we simply detect\nif the Spotlight device is sending mouse move events. If it is sending mouse events,\nwe will 'turn on' the desktop spot (virtual laser).\n\nFor more details: Have a look at the source code ;)\n\n### Button mapping\n\nButton mapping works by **grabbing** all device events of connected\ndevices and forwarding them to a virtual _'uinput'_ device if not configured\ndifferently by the button mapping configuration. If a mapped configuration for\na button exists, _Projecteur_ will inject the mapped action instead.\n(You can still disable device grabbing with the `--disable-uinput` command\nline option - button mapping will be disabled then.)\n\nInput events from the presenter device can be mapped to different actions.\nThe _Key Sequence_ action is particularly powerful as it can emit any user-defined\nkeystroke. These keystrokes can invoke shortcut in presentation software\n(or any other software) being used. Similarly, the _Cycle Preset_ action can be\nused for cycling different spotlight presets. However, it should be noted that\npresets are ordered alphabetically on program start. To retain a certain\norder of your presets, you can prepend the preset name with a number.\n\n#### Hold Button Mapping for Logitech Spotlight\n\nLogitech Spotlight can send Hold event for Next and Back buttons as HID++\nmessages. Using this device feature, this program provides three different\nusage of the Next or Hold button.\n\n1. Button Tap\n2. Long-Press Event\n3. Button Hold and Move Event\n\nOn the Input Mapper tab (Devices tab in Preferences dialog box), the first two\nbutton usages (_i.e._ tap and long-press) can be mapped directly by tapping or\nlong pressing the relevant button. For mapping the third button usage (_i.e._\nHold Move Event), please ensure that the device is active by pressing any button,\nand then right click in first column (Input Sequence) for any entry and select\nthe relevant option. Additional mapped actions (e.g. _Vertical Scrolling_,\n_Horizontal Scrolling_, or _Volume control_) can be selected for these hold\nmove events.\n\nPlease note that in case when both Long-Press event and Hold Move events are\nmapped for a particular button, both actions will executed if user hold the\nbutton and move device. To avoid this situation, do not set both Long-Press\nand Hold Move actions for the same button.\n\n## Download\n\nThe latest binary packages for some Linux distributions are available for download on cloudsmith.\nCurrently binary packages for _Ubuntu_, _Debian_, _Fedora_, _OpenSuse_, _CentOS_ and\n_Arch_ Linux are automatically built. For release version downloads you can also visit\nthe project's [github releases page](https://github.com/jahnf/Projecteur/releases).\n\n* **Latest release:**\n  * on cloudsmith: [![cloudsmith-rel-badge]][cloudsmith-rel-latest]\n  * on secondery server: [![projecteur-rel-badge]][projecteur-rel-dl]\n* Latest development version:\n  * on cloudsmith: [![cloudsmith-dev-badge]][cloudsmith-dev-latest]\n  * on secondary server: [![projecteur-dev-badge]][projecteur-dev-dl]\n\nSee also the **[list of Linux repositories](./doc/LinuxRepositories.md)** where _Projecteur_\nis available.\n\n[cloudsmith-rel-badge]: https://img.shields.io/badge/dynamic/json?color=blue\u0026labelColor=12577e\u0026logo=cloudsmith\u0026label=Projecteur\u0026prefix=v\u0026query=%24.version\u0026url=https%3A%2F%2Fprojecteur.de%2Fdownloads%2Fstable-latest.json\n[cloudsmith-rel-latest]: https://cloudsmith.io/~jahnf/repos/projecteur-stable/packages/?q=format%3Araw+tag%3Alatest\n[cloudsmith-dev-badge]: https://img.shields.io/badge/dynamic/json?color=blue\u0026labelColor=12577e\u0026logo=cloudsmith\u0026label=Projecteur\u0026prefix=v\u0026query=%24.version\u0026url=https%3A%2F%2Fprojecteur.de%2Fdownloads%2Fdevelop-latest.json\n[cloudsmith-dev-latest]: https://cloudsmith.io/~jahnf/repos/projecteur-develop/packages/?q=format%3Araw+tag%3Alatest\n[projecteur-rel-badge]: https://img.shields.io/badge/dynamic/json?color=blue\u0026label=Projecteur\u0026prefix=v\u0026query=%24.version\u0026url=https%3A%2F%2Fprojecteur.de%2Fdownloads%2Fstable-latest.json\n[projecteur-dev-badge]: https://img.shields.io/badge/dynamic/json?color=blue\u0026label=Projecteur\u0026prefix=v\u0026query=%24.version\u0026url=https%3A%2F%2Fprojecteur.de%2Fdownloads%2Fdevelop-latest.json\n[projecteur-dev-dl]: https://projecteur.de/downloads/develop/latest\n[projecteur-rel-dl]: https://projecteur.de/downloads/stable/latest\n\n## Building\n\n### Requirements\n\n* C++14 compiler\n* CMake 3.6 or later\n* Qt 5.7 and later\n\n### Build Example\n\n```sh\n    git clone https://github.com/jahnf/Projecteur\n    cd Projecteur\n    mkdir build \u0026\u0026 cd build\n    cmake ..\n    make\n```\n\nBuilding against other Qt versions, than the default one from your Linux distribution\ncan be done by setting the `QTDIR` variable during CMake configuration.\n\nExample: `QTDIR=/opt/Qt/5.9.6/gcc_64 cmake ..`\n\n## Installation/Running\n\n### Pre-requisites\n\n#### When building Projecteur yourself\n\nThe input devices detected from the Spotlight device must be readable to the\nuser running the application. To make this easier there is a udev rule template\nfile in this repository: `55-projecteur.rules.in`\n\n* During the CMake run, the file `55-projecteur.rules` will be created from this template\n  in your **build directory**. Copy that generated file to `/lib/udev/rules.d/55-projecteur.rules`\n* Most recent systems (using systemd) will automatically pick up the rule.\n  If not, run `sudo udevadm control --reload-rules` and `sudo udevadm trigger`\n  to load the rules without a reboot.\n* After that, the input devices from the Logitech USB Receiver (but also the Bluetooth device)\n  in /dev/input should be readable/writable by you.\n  (See also about [device detection](#device-shows-as-not-connected))\n* When building against the Qt version that comes with your distribution's packages,\n  you might need to install some  additional QML module packages. For example this\n  is the case for Ubuntu, where you need to install the packages\n  `qml-module-qtgraphicaleffects`, `qml-module-qtquick-window2`, `qml-modules-qtquick2` and\n  `qtdeclarative5-dev` to satisfy the application's run time dependencies.\n\n### Application Menu\n\nThe application menu is accessible via the system tray icon. There you will find\nthe preferences and the menu entry to exit the application. If the system tray icon is missing,\nsee the [Troubleshooting](#missing-system-tray) section.\n\n### Command Line Interface\n\nAdditional to the standard `--help` and `--version` options, there is an option to send\ncommands to a running instance of _Projecteur_ and the ability to set properties.\n\n```txt\nUsage: projecteur [OPTION]...\n\n\u003cOptions\u003e\n  -h, --help              Show command line usage.\n  --help-all              Show complete command line usage with all properties.\n  -v, --version           Print application version.\n  -f, --fullversion       Print extended version info.\n  --cfg FILE              Set custom config file.\n  -d, --device-scan       Print device-scan results.\n  -l, --log-level LEVEL   Set log level (dbg,inf,wrn,err), default is 'inf'.\n  --show-dialog           Show preferences dialog on start.\n  -m, --minimize-only     Only allow minimizing the preferences dialog.\n  -D DEVICE               Additional accepted device; DEVICE=vendorId:productId\n  -c COMMAND|PROPERTY     Send command/property to a running instance.\n\n\u003cCommands\u003e\n  spot=[on|off|toggle]     Turn spotlight on/off or toggle.\n  spot.size.adjust=[+|-]N  Increase or decrease spot size by N.\n  settings=[show|hide]     Show/hide preferences dialog.\n  preset=NAME              Set a preset.\n  quit                     Quit the running instance.\n```\n\nA complete list the properties that can be set via the command line, can be listed with the\n`--help-all` option or can also be found on the man pagers with newer versions of\n_Projecteur_ (`man projecteur`).\n\n### Scriptability\n\n_Projecteur_ allows you to set almost all aspects of the spotlight via the command line\nfor a running instance.\n\nExample:\n\n```bash\n# Set showing the border to true\nprojecteur -c border=true\n# Set the border color to red\nprojecteur -c border.color=#ff0000\n# Send a vibrate command to the device with\n# intensity=128 and length=0 (only Logitech Spotlight)\nprojecteur -c vibrate=128,0\n```\n\nWhile _Projecteur_ does not provide global keyboard shortcuts, command line options\ncan but utilized for that. For instance, if you like to use _Projecteur_ as a tool while sharing\nyour screen in a video call without additional presenter hardware, you can assign global\nshortcuts in your window manager (e.g. GNOME) to run the commands `projecteur -c spot=on`\nand `projecteur -c spot=off` or `projecteur -c spot=toggle`, and therefore\nturning the spot on and off with a keyboard shortcut.\n\nA complete list the properties that can be set via the command line, can be\nlisted with the `--help-all` command line option.\n\n### Using Projecteur without a device\n\nYou can use _Projecteur_ for your online presentations and video conferences without a presenter\ndevice. For this you can assign a global keyboard shortcut in your window manager\n(e.g. KDE, GNOME...) to run the command `projecteur -c spot=toggle`. You will then be able to\nturn the digital spot on and off with the assigned keyboard shortcut while sharing\nyour screen in an online presentation or call.\n\n### Device Support\n\nBesides the _Logitech Spotlight_, the following devices are currently supported out of the box:\n\n* AVATTO H100 / August WP200 _(0c45:8101)_\n* August LP315 _(2312:863d)_\n* AVATTO i10 Pro _(2571:4109)_\n* August LP310 _(69a7:9803)_\n* Norwii Wireless Presenter _(3243:0122)_\n* Kensington PowerPointer _(1ea7:0002)_\n\n#### Compile Time\n\nBesides the Logitech Spotlight, similar devices can be used and are supported.\nAdditional devices can be added to `devices.conf`. At CMake configuration time,\nthe project will be configured to support these devices and also create entries\nfor them in the generated udev-rule file.\n\n#### Runtime\n\n_Projecteur_ will also accept devices as supported when added via the `-D`\ncommand line option.\n\nExample: `projecteur -D 04b3:310c`\n\nThis will enable devices within _Projecteur_ and the application will try to\nconnect to that device if it is detected. It is, however, up to the user to make\nsure the device is accessible (via udev rules).\n\n### Troubleshooting\n\n#### Opaque Spotlight / No Transparency\n\nTo be able to show transparent windows, a **compositing manager** is necessary. If there is no\ncompositing manager running you will see the spotlight overlay as an opaque window.\n\n* On **KDE** it might be necessary to turn on Desktop effects to allow transparent windows.\n* Depending on your Linux Desktop and configuration there might not be a compositing manager\n  running by default. You can run `xcompmgr`, `compton` or others manually.\n  * Examples: `xcompmgr -c -t-6 -l-6 -o.1` or `xcompmgr -c`\n\n#### Missing System Tray\n\n_Projecteur_ was developed and tested on GNOME and KDE Desktop environments, but should\nwork on most other desktop environments. If the system tray with the _Application Menu_\nis not showing, commands can be send to the application to bring up the preferences\ndialog, test the spotlight, quit the application or set spotlight properties.\nSee [Command Line Interface](#command-line-interface). There is also a command\nline option (`-m`) to prevent the preferences dialog from hiding, allowing it\nonly to minimize - behaving more like a regular application window.\n\nOn some distributions that have a **GNOME Desktop** by default there is\n**no system tray extensions** installed (_Fedora_ for example). You can install the\n[KStatusNotifierItem/AppIndicator Support][appind-ext] or the [TopIcons Plus][topicon-ext]\nGNOME extension to have a system tray that can show the _Projecteur_ tray icon\n(and also from other applications like Dropbox or Skype).\n\n[appind-ext]: https://extensions.gnome.org/extension/615/appindicator-support/\n[topicon-ext]: https://extensions.gnome.org/extension/1031/topicons/\n\n#### Zoom is not updated while spotlight is shown\n\nZoom does not update while spotlight is shown due to how the zoom currently works. A screenshot is\ntaken shortly before the overlay window is shown, and then a magnified section is shown wherever\nthe mouse/spotlight is.\nIf the zoom would be updated while the overlay window is shown, the overlay window it self would\nshow up in the magnified section. That is a general problem that other magnifier tools also face,\nalthough they get around the problem by showing the magnified content rectangle always in the\nsame position on the screen.\n\n#### Wayland\n\nWhile not developed with Wayland in mind, users reported _Projecteur_ works with\nWayland. If you experience problems, you can try to set the `QT_QPA_PLATFORM` environment\nvariable to `wayland`, example:\n\n```bash\nuser@ubuntu1904:~/Projecteur/build$ QT_QPA_PLATFORM=wayland ./projecteur\nUsing Wayland-EGL\n```\n\n#### Wayland Zoom\n\nOn Wayland the Zoom feature is currently only implemented on KDE and GNOME. This is done with\nthe help of their respective DBus interfaces for screen capturing. On other environments with\nWayland, the zoom feature is not currently supported.\n\n#### Device shows as not connected\n\nIf the device shows as not connected, there are some things you can do:\n\n* Check for devices with _Projecteur_'s command line option `-d` or `--device-scan` option.\n  This will show you a list of all supported and detected devices and also if\n  they are readable/writable. If a detected device is not readable/writable, it is an indicator\n  that there is something wrong with the installed _udev_ rules.\n* Manually on the shell: Check if the device is detected by the Linux system: Run\n  `cat /proc/bus/input/devices | grep -A 5 \"Vendor=046d\"` \\\n  This should show one or multiple spotlight devices (among other Logitech devices)\n  * Check that the corresponding `/dev/input/event??` device file is readable by you. \\\n    Example: `test -r /dev/input/event19 \u0026\u0026 echo \"SUCCESS\" || echo \"NOT readable\"`\n* Make sure you don't have conflicting udev rules installed, e.g. first you installed\n  the udev rule yourself and later you used the automatically built Linux packages to\n  install _Projecteur_.\n\n## Changelog\n\nSee [CHANGELOG.md](./doc/CHANGELOG.md) for a detailed changelog.\n\n## License\n\nCopyright 2018-2021 Jahn Fuchs\n\nThis project is distributed under the [MIT License](https://opensource.org/licenses/MIT),\nsee [LICENSE.md](./LICENSE.md) for more information.\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjahnf%2FProjecteur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjahnf%2FProjecteur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjahnf%2FProjecteur/lists"}