search

jahnf / Projecteur

Linux Desktop Application for the Logitech Spotlight device (and similar devices) - Digital Laser Pointer
MIT License
374 stars 33 forks source link
desktop-application linux logitech logitech-spotlight-device presentation qml qt5 virtual-laser

readme

Projecteur

develop: Build Status develop master: Build Status master

Linux/X11 application for the Logitech Spotlight device (and similar devices). \ See Download section for binary packages.

Motivation

I saw the Logitech Spotlight device in action at a conference and liked it immediately. Unfortunately as in a lot of cases, software is only provided for Windows and Mac. The device itself works just fine on Linux, but the cool spotlight feature is only available using additional software.

So here it is: a Linux application for the Logitech Spotlight.

Table of Contents

Features

Screenshots

Planned features

Supported Environments

The application was mostly tested on Ubuntu 18.04, Ubuntu 20.04 (GNOME) and OpenSuse 15 (GNOME) but should work on almost any Linux/X11 Desktop. In case you are building the application yourself, make sure you have the correct udev rules installed (see pre-requisites section).

How it works

With a connection via the USB Dongle Receiver or via Bluetooth, the Logitech Spotlight device will be detected by Linux as a HID device with mouse and keyboard events. As mouse events, the device sends relative cursor movements and left button presses. Acting as a keyboard, the device basically just sends left and right arrow key press events when forward or back is pressed on the device.

The mouse move events of the device are what we are mainly interested in. Since the device is already detected as a mouse input device and able to move the cursor, we simply detect if the Spotlight device is sending mouse move events. If it is sending mouse events, we will 'turn on' the desktop spot (virtual laser).

For more details: Have a look at the source code ;)

Button mapping

Button mapping works by grabbing all device events of connected devices and forwarding them to a virtual 'uinput' device if not configured differently by the button mapping configuration. If a mapped configuration for a button exists, Projecteur will inject the mapped action instead. (You can still disable device grabbing with the --disable-uinput command line option - button mapping will be disabled then.)

Input events from the presenter device can be mapped to different actions. The Key Sequence action is particularly powerful as it can emit any user-defined keystroke. These keystrokes can invoke shortcut in presentation software (or any other software) being used. Similarly, the Cycle Preset action can be used for cycling different spotlight presets. However, it should be noted that presets are ordered alphabetically on program start. To retain a certain order of your presets, you can prepend the preset name with a number.

Hold Button Mapping for Logitech Spotlight

Logitech Spotlight can send Hold event for Next and Back buttons as HID++ messages. Using this device feature, this program provides three different usage of the Next or Hold button.

  1. Button Tap
  2. Long-Press Event
  3. Button Hold and Move Event

On the Input Mapper tab (Devices tab in Preferences dialog box), the first two button usages (i.e. tap and long-press) can be mapped directly by tapping or long pressing the relevant button. For mapping the third button usage (i.e. Hold Move Event), please ensure that the device is active by pressing any button, and then right click in first column (Input Sequence) for any entry and select the relevant option. Additional mapped actions (e.g. Vertical Scrolling, Horizontal Scrolling, or Volume control) can be selected for these hold move events.

Please note that in case when both Long-Press event and Hold Move events are mapped for a particular button, both actions will executed if user hold the button and move device. To avoid this situation, do not set both Long-Press and Hold Move actions for the same button.

Download

The latest binary packages for some Linux distributions are available for download on cloudsmith. Currently binary packages for Ubuntu, Debian, Fedora, OpenSuse, CentOS and Arch Linux are automatically built. For release version downloads you can also visit the project's github releases page.

See also the list of Linux repositories where Projecteur is available.

Building

Requirements

Build Example

    git clone https://github.com/jahnf/Projecteur
    cd Projecteur
    mkdir build && cd build
    cmake ..
    make

Building against other Qt versions, than the default one from your Linux distribution can be done by setting the QTDIR variable during CMake configuration.

Example: QTDIR=/opt/Qt/5.9.6/gcc_64 cmake ..

Installation/Running

Pre-requisites

When building Projecteur yourself

The input devices detected from the Spotlight device must be readable to the user running the application. To make this easier there is a udev rule template file in this repository: 55-projecteur.rules.in

Application Menu

The application menu is accessible via the system tray icon. There you will find the preferences and the menu entry to exit the application. If the system tray icon is missing, see the Troubleshooting section.

Command Line Interface

Additional to the standard --help and --version options, there is an option to send commands to a running instance of Projecteur and the ability to set properties.

Usage: projecteur [OPTION]...

<Options>
  -h, --help              Show command line usage.
  --help-all              Show complete command line usage with all properties.
  -v, --version           Print application version.
  -f, --fullversion       Print extended version info.
  --cfg FILE              Set custom config file.
  -d, --device-scan       Print device-scan results.
  -l, --log-level LEVEL   Set log level (dbg,inf,wrn,err), default is 'inf'.
  --show-dialog           Show preferences dialog on start.
  -m, --minimize-only     Only allow minimizing the preferences dialog.
  -D DEVICE               Additional accepted device; DEVICE=vendorId:productId
  -c COMMAND|PROPERTY     Send command/property to a running instance.

<Commands>
  spot=[on|off|toggle]     Turn spotlight on/off or toggle.
  spot.size.adjust=[+|-]N  Increase or decrease spot size by N.
  settings=[show|hide]     Show/hide preferences dialog.
  preset=NAME              Set a preset.
  quit                     Quit the running instance.

A complete list the properties that can be set via the command line, can be listed with the --help-all option or can also be found on the man pagers with newer versions of Projecteur (man projecteur).

Scriptability

Projecteur allows you to set almost all aspects of the spotlight via the command line for a running instance.

Example:

# Set showing the border to true
projecteur -c border=true
# Set the border color to red
projecteur -c border.color=#ff0000
# Send a vibrate command to the device with
# intensity=128 and length=0 (only Logitech Spotlight)
projecteur -c vibrate=128,0

While Projecteur does not provide global keyboard shortcuts, command line options can but utilized for that. For instance, if you like to use Projecteur as a tool while sharing your screen in a video call without additional presenter hardware, you can assign global shortcuts in your window manager (e.g. GNOME) to run the commands projecteur -c spot=on and projecteur -c spot=off or projecteur -c spot=toggle, and therefore turning the spot on and off with a keyboard shortcut.

A complete list the properties that can be set via the command line, can be listed with the --help-all command line option.

Using Projecteur without a device

You can use Projecteur for your online presentations and video conferences without a presenter device. For this you can assign a global keyboard shortcut in your window manager (e.g. KDE, GNOME...) to run the command projecteur -c spot=toggle. You will then be able to turn the digital spot on and off with the assigned keyboard shortcut while sharing your screen in an online presentation or call.

Device Support

Besides the Logitech Spotlight, the following devices are currently supported out of the box:

Compile Time

Besides the Logitech Spotlight, similar devices can be used and are supported. Additional devices can be added to devices.conf. At CMake configuration time, the project will be configured to support these devices and also create entries for them in the generated udev-rule file.

Runtime

Projecteur will also accept devices as supported when added via the -D command line option.

Example: projecteur -D 04b3:310c

This will enable devices within Projecteur and the application will try to connect to that device if it is detected. It is, however, up to the user to make sure the device is accessible (via udev rules).

Troubleshooting

Opaque Spotlight / No Transparency

To be able to show transparent windows, a compositing manager is necessary. If there is no compositing manager running you will see the spotlight overlay as an opaque window.

Missing System Tray

Projecteur was developed and tested on GNOME and KDE Desktop environments, but should work on most other desktop environments. If the system tray with the Application Menu is not showing, commands can be send to the application to bring up the preferences dialog, test the spotlight, quit the application or set spotlight properties. See Command Line Interface. There is also a command line option (-m) to prevent the preferences dialog from hiding, allowing it only to minimize - behaving more like a regular application window.

On some distributions that have a GNOME Desktop by default there is no system tray extensions installed (Fedora for example). You can install the KStatusNotifierItem/AppIndicator Support or the TopIcons Plus GNOME extension to have a system tray that can show the Projecteur tray icon (and also from other applications like Dropbox or Skype).

Zoom is not updated while spotlight is shown

Zoom does not update while spotlight is shown due to how the zoom currently works. A screenshot is taken shortly before the overlay window is shown, and then a magnified section is shown wherever the mouse/spotlight is. If the zoom would be updated while the overlay window is shown, the overlay window it self would show up in the magnified section. That is a general problem that other magnifier tools also face, although they get around the problem by showing the magnified content rectangle always in the same position on the screen.

Wayland

While not developed with Wayland in mind, users reported Projecteur works with Wayland. If you experience problems, you can try to set the QT_QPA_PLATFORM environment variable to wayland, example:

user@ubuntu1904:~/Projecteur/build$ QT_QPA_PLATFORM=wayland ./projecteur
Using Wayland-EGL

Wayland Zoom

On Wayland the Zoom feature is currently only implemented on KDE and GNOME. This is done with the help of their respective DBus interfaces for screen capturing. On other environments with Wayland, the zoom feature is not currently supported.

Device shows as not connected

If the device shows as not connected, there are some things you can do:

Changelog

See CHANGELOG.md for a detailed changelog.

License

Copyright 2018-2021 Jahn Fuchs

This project is distributed under the MIT License, see LICENSE.md for more information.