Troubleshooting: OctoCue receiver

Installation checklist#

If you're having issues with OctoCue receiver, here's a couple of checks that might fix things quickly:

Check you're running a compatible operating system#

OctoCue receiver does not support 32-bit Windows - 64-bit Windows is the only PC operating system supported.

On macOS, you'll need macOS 10.15.7 (a recent Catalina version) or later.

Check your show machine names#

Each receiver machine connected to show needs to have a unique name; two machines with the same name connected to the same show will not work correctly.

To check this:

On windows, go to About your PC and look at the Device name field.
On macOS, it's in System Preferences - Sharing.

This restriction does not apply to computers used as presenter clickers, or those used to access the show control dashboard.

note

If you've checked these items and are still having issues, drop an email to support@octocue.com with a description of the issues you're experiencing and a copy of your local log file.

Details of where to find the log file are available on the Advanced Configuration page.

Windows troubleshooting#

OctoCue Receiver installation fails with the message 'Installation has failed. There was an error while installing the installation. Check setup log...'#

We've seen this issue if you try to install OctoCue Receiver on a 32-bit version of Windows - only 64-bit Windows is supported.

Given the 4 GB RAM limit on 32-bit Windows, we wouldn't recommend running a show on a 32-bit OS.

Every time I click, the deck goes forward (or back) two slides.#

This can happen if you're using Receiver 1.4.0+, which supports the PptDirect feature when running on Windows.

What typically happens is the receiver is controlling PowerPoint direct, but also still sending out keypresses - hence the double slide advance issue.

To fix this, you'll need to check your configurations files, located at %APPDATA%\OctoCue receiver\storage.

If you'd like to use PptDirect (recommended for better video playback compatibility):

In keypress.json, make sure useKeyPress is set to auto:

{
    "useKeyPress":"auto",
    "next":"PageDown",
    "back":"PageUp"
}

In pptdirect.json make sure usePptDirect is also set to auto:

{
    "usePptDirect":"auto"
}

info

In this configuration, OctoCue will use PptDirect when the OctoCue PowerPoint plugin is detected, but revert to emulated keypresses at all other times, so it can still control Keynote, Google Slides etc.

If either of these are set to true, they'll always be active - hence the chance of double clicks occurring.

For full details of all the configuration settings available in OctoCue Receiver, see the Advanced configuration page.

Prezi on Google Chrome not reacting to OctoCue clicks#

On 11 Feb 2022, we noticed that Prezi running on Chrome 98 does not react to OctoCue clicks correctly. We're currently investigating this issue.

As a temporary workround, please run Prezi presentations in Microsoft Edge (tested on 98.0.1108.50).

Slow clicks on Windows#

May 2022: We've seen some issues with slow clicks on Windows. See this article for details and options.

macOS troubleshooting#

Slow clicks on macOS#

We've seen a couple of issues of slow click response times on macOS. If you think you're having this issue, check your log files by right-clicking on the tray icon and selecting View event logs.

On OctoCue Receiver 1.4.x or later, a typical click event looks like:

[2021-02-10 21:55:51.911] [info] Pressing key PageDown
[2021-02-10 21:55:52.168] [info] Keypress took 253ms

These times will normally be less than 500ms, but we've seen some very slow times (>2,000ms) on macOS 10.14 (Mojave) and earlier versions of 10.15 (Catalina).

In all cases, updating to the latest version of Catalina (or up to 11.x Big Sur) have fixed the issues.

Failed clicks on macOS (12.x Monterey)#

We've seen some instances where the Accessibility app permission fails to apply correctly in macOS.

This causes [error] undefined entries in the receiver log:

[2021-05-28 14:07:12.895] [info] Pressing key PageDown
[2021-05-28 14:07:13.020] [error] undefined

To fix this we need to remove and re-add the Accessibility permission:

Go to System Preferences, Security & Privacy, Accessibility
Remove OctoCue Receiver from the list using the - button
Re-add OctoCue Receiver using the + button and browsing to your copy of OctoCue Receiver
Close and restart OctoCue Receiver

We've only seen this on a small number of machines, and don't have good information on why this happens - if you've experienced this issue, we'd appreciate you dropping us a quick email and letting us know.

Failed clicks on macOS (13.x Ventura)#

Similiar to the Monterey case above, we've seen permissions issues when machines have been updated to 13.x Ventura.

To fix this we recommend a clean-sweep and re-install, including the permissions:

Uninstall and removing permissions#

First, delete OctoCue Receiver.app from your Applications folder (or similar)

We're now going to remove the permissions (and application entries), starting with the Accessibility permission:

Go to System Preferences, Privacy & Security, Accessibility.
Select OctoCue Receiver from the list of entries, and then the - button at the bottom of the list.

Now we'll remove the Automation permission (called AppleEvents internally). Unfortunately this not possible via the GUI, so we need to jump into the terminal.

Go to System Preferences, Privacy & Security, Automation, where you should see Octocue Receiver listed.
Open a terminal window and run the following command:

tccutil reset AppleEvents com.electron.octocue-receiver

OctoCue Receiver should now be removed from the Automation window.

We've now removed OctoCue Receiver, and all of the old permissions from the system.

Reinstall and granting new permissions#

Go to https://support.octocue.com/docs/downloads and download the latest verion for macOS.
Unzip the file and copy OctoCue Receiver.app into your Applications folder.
Go to System Preferences, Privacy & Security, Accessibility.
Select the + button (at the bottom) and select OctoCue Receiver.app from your Applications folder to add it to the list.
Run Octocue Receiver.app. Log into a show and set the receiver to start listening for clicks.
When the receiver detects the first click, it'll prompt you that “OctoCue Receiver.app“ wants access to control “System Events.app“. Select OK to grant the automation permission.

You've now performed a clean install of OctoCue Receiver, and re-assigned the two permissions required. If you're still having issues after this procedure, please get in touch.

Apple Script testing on macOS#

Apple Script is the technology that OctoCue Receiver uses to emulate keypresses on macOS.

To test your Apple Script functions, we're going to run a couple of simple one-line Apple Script programs from the command line.

info

Before running test, please check the following:

Your macOS version, which should be 10.15.7 or later
That you've granted all the relevant permissions to OctoCue Receiver - both accessibility and automation permissions

First, open a terminal window - first CMD & spacebar to open spotlight, type terminal and hit enter.

The first test is a simple function test. At the command prompt, run the following:

osascript -e 'display dialog "Hello from OctoCue" with title "Apple Script Test"' 

You should see the following dialog appear.

Hit OK to close the window.

The next test will emulate a keypress:

osascript -e 'tell application "System Events" to keystroke "a"'

note

You may get asked to grant the accessibility permission to the Terminal application - see here for details

This command should output an a character on your command line:

user@Your-Mac ~ % osascript -e 'tell application "System Events" to keystroke "a"'
a%
user@Your-Mac ~ % a