# 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
| | Notes | None | | Examples | None | | Source | extensions/razer/librazer.m line 48 |

# 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
| | Examples | None | | Source | extensions/razer/librazer.m line 23 |

# 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.
| | Notes | None | | Examples | None | | Source | extensions/razer/librazer.m line 443 |

# 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.
| | Notes | None | | Examples | None | | Source | extensions/razer/librazer.m line 388 |

# 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.
| | Notes | None | | Examples | None | | Source | extensions/razer/librazer.m line 278 |

# 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.
| | Notes | None | | Examples | None | | Source | extensions/razer/librazer.m line 498 |

# 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.
| | Notes | None | | Examples | None | | Source | extensions/razer/librazer.m line 333 |

© Copyright 2024 LateNite Films Pty Ltd. All rights reserved.