Razer App Controller

An unofficial Macro Deck 3 plugin. Not affiliated with or endorsed by Razer Inc.

Control Razer devices from Macro Deck 3 buttons while Razer Synapse 4 keeps running:

switch, step or cycle Synapse profiles on any Razer device set a device's lighting effect in its Synapse profile, or use Chroma lighting (static, breathing, spectrum, wave, with brightness and speed) without Synapse control toggle a keyboard's gaming mode step or temporarily set the mouse's DPI

Tested on a Razer Naga Trinity and a Razer Cynosa Chroma with Synapse 4.0.827.

Install

Build the package with macrodeck-plugin build --source src/RazerController --rid win-x64 --output ./artifacts, or use a release artifact. In Macro Deck 3, install com.keystonedigital.razer--win-x64.macroDeckPlugin. It is not signed, so Macro Deck asks you to confirm and marks it unverified. Open the plugin's settings (Synapse control) and turn on Enable Synapse control. Also tick Restart Synapse when I save, then save. Or skip that and sign out of Windows and back in. Opening Synapse from the Start menu does not work: that shortcut starts it without the flag.

Mouse DPI and Chroma lighting work without step 3. Profiles, Synapse lighting effects and gaming mode need it. Until you turn it on, the plugin does not touch Synapse's startup entry and does not use the debug port, even if the port is already open.

What Synapse control changes

Turning it on adds --inspect=127.0.0.1:9229 to the end of the RazerAppEngine value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run. Nothing else in that entry changes. Turning it off removes exactly that flag again and leaves the rest of the entry as it is. Both take effect the next time Synapse starts.

The plugin never changes the entry or restarts Synapse on its own. Synapse sometimes rewrites its startup entry and drops the flag. Then razerstatus shows flagmissing, and you save the settings again to put it back. If Synapse is running without the flag, razerstatus shows restartneeded. Open the plugin's settings, tick Restart Synapse when I save and save. Or sign out of Windows and back in.

Security

While Synapse control is on, Razer Synapse opens a debug port on 127.0.0.1:9229. Any program or Windows user on this PC can connect to that port and run code inside Razer Synapse, not only control it. Turn it on only if you trust every program and every user on this PC.

The plugin connects only to 127.0.0.1, checks that the port belongs to RazerAppEngine.exe before using it, and sends nothing off the PC. Turning the setting off removes the flag; see What Synapse control changes.

Chroma lighting does not use the debug port. It talks to the Razer Chroma SDK's own local server, the same way games with Chroma effects do.

Actions

Action What it does Switch Synapse profile Picks a device, then one of: a chosen profile, next, previous, or cycle through chosen profiles Synapse lighting (saved to profile) Off, Static, Breathing, Spectrum, Wave, Reactive, Ripple or Starlight, saved in the Synapse profile, with the effect's own settings: colour, second colour or random colours (Breathing, Starlight), duration (Reactive, Starlight), direction (Wave). Needs Synapse control Synapse brightness (saved to profile) Sets a device's lighting brightness in its Synapse profile, or makes it brighter or dimmer by a step. 0 switches the lighting off. Needs Synapse control Chroma lighting (temporary, no setup) Static colour, Breathing (one or two colours), Spectrum cycling, Wave or Off, with brightness and speed, on all Razer devices or one device type, through the Razer Chroma SDK. The plugin draws the animated effects itself. Works without Synapse control. Needs the Chroma module in Synapse with Chroma apps allowed. The colour lasts while Macro Deck runs; Synapse lighting (give control back) returns to the profile Gaming mode On, Off or Toggle. Gaming mode disables the Windows key Step mouse DPI One DPI stage up or down within the active profile Temporary mouse DPI A DPI value until the next profile switch or DPI step

Each Synapse action waits until Synapse confirms the change, about 1.5 seconds at most. Otherwise it reports "Synapse did not apply the change".

Variables

Variable Value razerstatus ready, controloff, flagmissing, restartneeded, inspectorunavailable, inspectoruntrusted, synapseunrecognised, nodevices or starting razermouseprofile Active profile of the first mouse razermousedpi Current mouse DPI razermousedpistage stage/count, 0/n when on a temporary DPI razerkeyboardprofile Active profile of the first keyboard razerkeyboardeffect Off, Static, Breathing, Spectrum, Wave, Reactive, Ripple or Starlight razerkeyboardgamingmode true or false razerkeyboardbrightness Lighting brightness of the first keyboard, 0 to 100 razermousebrightness Lighting brightness of the first mouse, 0 to 100

Troubleshooting by razerstatus

controloff: Synapse control is off in the plugin's settings. Mouse DPI and Chroma lighting still work. flagmissing: Synapse removed the flag from its startup entry. Open the plugin's settings and save them again. restartneeded: Synapse is running without the flag. Open the plugin's settings, tick Restart Synapse when I save and save. Or sign out of Windows and back in. inspectorunavailable: Synapse is not running or not listening on port 9229. Start Synapse. The plugin reconnects on its own. inspectoruntrusted: something other than Razer Synapse is using port 9229. The plugin refuses to talk to it. synapseunrecognised: Synapse is reachable, but its device windows were not found. A Synapse update may have changed them. Check the host log in %APPDATA%\MacroDeck\logs. nodevices: Synapse reports no connected Razer devices.

Development

dotnet build dotnet test dotnet run --project tools/ManualInspectorCheck -- --roundtrip # live: switches and restores, needs Synapse macrodeck-plugin test --project src/RazerController --report markdown --output conformance.md

docs/superpowers/specs/ holds the design. docs/superpowers/plans/ holds the implementation plan.