#hs.razer

Razer device support.

This extension supports the following Razer keypad devices:

Razer Nostromo
Razer Orbweaver
Razer Orbweaver Chroma
Razer Tartarus
Razer Tartarus Chroma
Razer Tartarus Pro
Razer Tartarus V2

It allows you to trigger callbacks when you press buttons and use the scroll wheel, as well as allowing you to change the LED backlights on the buttons and scroll wheel, and control the three status lights.

By default, the Razer keypads triggers regular keyboard commands (i.e. pressing the "01" key will type "1"). However, you can use the :defaultKeyboardLayout(false) method to prevent this. This works by remapping the default shortcut keys to "dummy" keys, so that they don't trigger regular keypresses in macOS.

Like the hs.streamdeck extension, this extension has been designed to be modular, so it's possible for others to develop support for additional Razer devices later down the line, if there's interest.

This extension was thrown together by Chris Hocking for CommandPost.

This extension is based off the hs.streamdeck extension by Chris Jones.

Special thanks to the authors of these awesome documents & resources:

#API Overview

Functions - API calls offered directly by the extension

discoveryCallback
getDevice
init
numDevices
unitTests

Methods - API calls which can only be made on an object returned by a constructor

backlightsBreathing
backlightsCustom
backlightsMode
backlightsOff
backlightsReactive
backlightsSpectrum
backlightsStarlight
backlightsStatic
backlightsWave
blueStatusLight
brightness
callback
defaultKeyboardLayout
greenStatusLight
name
orangeStatusLight
redStatusLight
yellowStatusLight

#API Documentation

#Functions

#discoveryCallback

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer.discoveryCallback(fn) -> none | | Type | Function | | Description | Sets/clears a callback for reacting to device discovery events | | Parameters |

fn - A function that will be called when a Razer device is connected or disconnected. It should take the following arguments: A boolean, true if a device was connected, false if a device was disconnected An hs.razer object, being the device that was connected/disconnected

| | Returns |

None

#getDevice


Signature	`hs.razer.getDevice(num) -> razerObject \| nil`
Type	Function
Description	Gets an hs.razer object for the specified device
Parameters	num - A number that should be within the bounds of the number of connected devices
Returns	An hs.razer object or `nil` if something goes wrong
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 92

#init

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer.init(fn) | | Type | Function | | Description | Initialises the Razer driver and sets a discovery callback. | | Parameters |

fn - A function that will be called when a Razer device is connected or disconnected. It should take the following arguments: A boolean, true if a device was connected, false if a device was disconnected An hs.razer object, being the device that was connected/disconnected

| | Returns |

None

| | Notes |

This function must be called before any other parts of this module are used

#numDevices


Signature	`hs.razer.numDevices() -> number`
Type	Function
Description	Gets the number of Razer devices connected
Parameters	None
Returns	A number containing the number of Razer devices attached to the system
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 75

#unitTests


Signature	`hs.razer.unitTests() -> none`
Type	Function
Description	Runs some basic unit tests when a Razer Tartarus V2 is connected.
Parameters	None
Returns	None
Notes	Because `hs.razer` relies on a physical device to be connected for testing, this method exists so that Hammerspoon developers can test the extension outside of the usual GitHub tests. It can also be used for user troubleshooting. This feature currently only works on the Razer Tartarus V2.
Examples	None
Source	extensions/razer/razer.lua line 87

#Methods

#backlightsBreathing


Signature	`hs.razer:backlightsBreathing([color], [secondaryColor]) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to the breath mode.
Parameters	[color] - An optional `hs.drawing.color` value [secondaryColor] - An optional secondary `hs.drawing.color`
Returns	The `hs.razer` object. `true` if successful otherwise `false` A plain text error message if not successful.
Notes	If neither `color` nor `secondaryColor` is provided, then random colors will be used.
Examples	None
Source	extensions/razer/librazer.m line 844

#backlightsCustom


Signature	`hs.razer:backlightsCustom(colors) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to custom colours.
Parameters	colors - A table of `hs.drawing.color` objects for each individual button on your device (i.e. if there's 20 buttons, you should have twenty colors in the table).
Returns	The `hs.razer` object. `true` if successful otherwise `false` A plain text error message if not successful.
Notes	The order is top to bottom, left to right. You can use `nil` for any buttons you don't want to light up. Example usage: `lua</li><li> hs.razer.new(0):backlightsCustom({hs.drawing.color.red, nil, hs.drawing.color.green, hs.drawing.color.blue})</li><li>`
Examples	None
Source	extensions/razer/librazer.m line 891

#backlightsMode


Signature	`hs.razer:backlightsMode(mode) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights mode.
Parameters	mode - "static", "flashing", "fading"
Returns	The `hs.razer` object. `true` if successful otherwise `false`. A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 555

#backlightsOff


Signature	`hs.razer:backlightsOff() -> razerObject, boolean, string \| nil`
Type	Method
Description	Turns all the keyboard backlights off.
Parameters	None
Returns	The `hs.razer` object. `true` if successful otherwise `false`. A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 630

#backlightsReactive


Signature	`hs.razer:backlightsReactive(speed, color) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to the reactive mode.
Parameters	speed - A number between 1 (fast) and 4 (slow) color - A `hs.drawing.color` object
Returns	The `hs.razer` object. `true` if successful otherwise `false` A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 744

#backlightsSpectrum


Signature	`hs.razer:backlightsSpectrum() -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to the spectrum mode.
Parameters	None
Returns	The `hs.razer` object. `true` if successful otherwise `false` A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 712

#backlightsStarlight


Signature	`hs.razer:backlightsStarlight(speed, [color], [secondaryColor]) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to the Starlight mode.
Parameters	speed - A number between 1 (fast) and 3 (slow) [color] - An optional `hs.drawing.color` value [secondaryColor] - An optional secondary `hs.drawing.color`
Returns	The `hs.razer` object. `true` if successful otherwise `false` A plain text error message if not successful.
Notes	If neither `color` nor `secondaryColor` is provided, then random colors will be used.
Examples	None
Source	extensions/razer/librazer.m line 787

#backlightsStatic


Signature	`hs.razer:backlightsStatic(color) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to a single static color.
Parameters	color - A `hs.drawing.color` object.
Returns	The `hs.razer` object. `true` if successful otherwise `false`. A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 596

#backlightsWave


Signature	`hs.razer:backlightsWave(speed, direction) -> razerObject, boolean, string \| nil`
Type	Method
Description	Changes the keyboard backlights to the wave mode.
Parameters	speed - A number between 1 (fast) and 255 (slow) direction - "left" or "right" as a string
Returns	The `hs.razer` object. `true` if successful otherwise `false` A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 662

#blueStatusLight

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer:blueStatusLight(value) -> razerObject, boolean | nil, string | nil | | Type | Method | | Description | Gets or sets the blue status light. | | Parameters |

value - true for on, false for off</li></ul> | | **Returns** | <ul><li>The hs.razer object.</li><li>truefor on,false for off, or nil if something has gone wrong
A plain text error message if not successful.

#brightness


Signature	`hs.razer:brightness(value) -> razerObject, number \| nil, string \| nil`
Type	Method
Description	Gets or sets the brightness of a Razer keyboard.
Parameters	value - The brightness value - a number between 0 (off) and 100 (brightest).
Returns	The `hs.razer` object. The brightness as a number or `nil` if something goes wrong. A plain text error message if not successful.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 221

#callback


Signature	`hs.razer:callback(callbackFn) -> razerObject`
Type	Method
Description	Sets or removes a callback function for the `hs.razer` object.
Parameters	`callbackFn` - a function to set as the callback for this `hs.razer` object. If the value provided is `nil`, any currently existing callback function is removed.
Returns	The `hs.razer` object
Notes	The callback function should expect 4 arguments and should not return anything: `razerObject` - The serial port object that triggered the callback. `buttonName` - The name of the button as a string. `buttonAction` - A string containing "pressed", "released", "up" or "down".
Examples	None
Source	extensions/razer/librazer.m line 147

#defaultKeyboardLayout


Signature	`hs.razer:defaultKeyboardLayout(enabled) -> boolean`
Type	Method
Description	Allows you to remap the default Keyboard Layout on a Razer device so that the buttons no longer trigger their factory default actions, or restore the default keyboard layout.
Parameters	enabled - If `true` the Razer default will use its default keyboard layout.
Returns	The `hs.razer` object. `true` if successful otherwise `false`
Notes	None
Examples	None
Source	extensions/razer/razer.lua line 52

#greenStatusLight

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer:greenStatusLight(value) -> razerObject, boolean | nil, string | nil | | Type | Method | | Description | Gets or sets the green status light. | | Parameters |

value - true for on, false for off</li></ul> | | **Returns** | <ul><li>The hs.razer object.</li><li>truefor on,false for off, or nil if something has gone wrong
A plain text error message if not successful.

#name


Signature	`hs.razer:name() -> string`
Type	Method
Description	Returns the human readable device name of the Razer device.
Parameters	None
Returns	The device name as a string.
Notes	None
Examples	None
Source	extensions/razer/librazer.m line 125

#orangeStatusLight

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer:orangeStatusLight(value) -> razerObject, boolean | nil, string | nil | | Type | Method | | Description | Gets or sets the orange status light. | | Parameters |

value - true for on, false for off</li></ul> | | **Returns** | <ul><li>The hs.razer object.</li><li>truefor on,false for off, or nil if something has gone wrong
A plain text error message if not successful.

#redStatusLight

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer:redStatusLight(value) -> razerObject, boolean | nil, string | nil | | Type | Method | | Description | Gets or sets the red status light. | | Parameters |

value - true for on, false for off</li></ul> | | **Returns** | <ul><li>The hs.razer object.</li><li>truefor on,false for off, or nil if something has gone wrong
A plain text error message if not successful.

#yellowStatusLight

| | | | --------------------------------------------|-------------------------------------------------------------------------------------| | Signature | hs.razer:yellowStatusLight(value) -> razerObject, boolean | nil, string | nil | | Type | Method | | Description | Gets or sets the orange status light. | | Parameters |

value - true for on, false for off</li></ul> | | **Returns** | <ul><li>The hs.razer object.</li><li>truefor on,false for off, or nil if something has gone wrong
A plain text error message if not successful.