Alien Effects for Alienware 13 R3

alieneffects-13r3 is an lightweight and highly customizable application to control LED backlights (alien effects) of Alienware 13 R3 laptop in linux.

Installation and usage

• python version
  • 3.6 is recommended
  • 3.4 may not work
  • 2 is strongly discouraged
• sudo pip3 install alienware-13r3-alien-effects to install
• To install from source, clone this repo and sudo python3 setup.py install
• sudo alieneffects-13r3 --THEME_FILE <path-to-theme-file> to apply a theme
• Some themes have stochasticity (randomness) in them, so applying same theme multiple times can lead to different themes

Config file

• Themes directory by default will be your home directory

• You can write a config file .alieneffects-13r3.json to specify themes directory

    {
      "THEMES_DIRECTORY": "/home/foo/bar/themes"
    }

  Writing your own themes

• The log will be written to .alieneffects-13r3.log

• Theme files are also json files and can contain following keys
  • DESCRIPTION - describes the theme
  • TEMPO - the frequency of blinking and/or morphing
  • DURATION - duration of each effect
  • ZONES - sequences of each zone
    • ex. POWER_BUTTON
      • ex.
        • SET_COLOR, COLOR
        • BLINK_COLOR, COLOR
        • MORPH_COLOR, COLOR1, COLOR2
        • LOOP_SEQUENCE
• Same sequence can be applied for multiple zones by delimiting zones with ‘|’
• If an effect does not have a color, a random color will be choosen
• The simplest theme is to switch off all lights

    {
      "DESCRIPTION": "sets all zones to black color i.e. switches off all lights",
      "ZONES": {
        "POWER_BUTTON|ALIENWARE_LOGO|ALIEN_HEAD|LEFT_KEYBOARD|TOUCH_PAD|MIDDLE_LEFT_KEYBOARD|MIDDLE_RIGHT_KEYBOARD|RIGHT_KEYBOARD": [
          {
            "EFFECT": "SET_COLOR",
            "COLOR": [0, 0, 0]
          },
          {
            "EFFECT": "LOOP_SEQUENCE"
          }
      ]
      }
    }

• The random theme sets random color to all zones

  {
  "DESCRIPTION": "set same random color for all zones",
  "TEMPO": 300,
  "DURATION": 11000,
  "ZONES": {
    "ALIENWARE_LOGO|ALIEN_HEAD|LEFT_KEYBOARD|TOUCH_PAD|MIDDLE_LEFT_KEYBOARD|MIDDLE_RIGHT_KEYBOARD|RIGHT_KEYBOARD": [
      {
        "EFFECT": "SET_COLOR"
      },
      {
        "EFFECT": "LOOP_SEQUENCE"
      }
    ]
  }
  }

Introduction - Reverse Engineering

Alienware 13 R3 has 8 configurable light zones as listed in the table below.

All lights can be controlled via USB protocol.

For this specific device vendor Id = 0x187c and product Id = 0x0529

Commands can be passed using control transfers of USB protocol.

Note that this application can only be used for Alienware 13 R3 model, for other models refer to Alienfx by trackmastersteve

Control transfer: Write operation parameters

bmRequestType = 0x21
    0... .... : Host to Device
    .01. .... : Request Type = Class
    ...0 0001 : Recipient = Interface
bRequest = 9
wValue = 0x0202
wIndex = 0

Control transfer: Read operation parameters

bmRequestType = 0xa1
    1... .... : Device to Host
    .01. .... : Request Type = Class
    ...0 0001 : Recipient = Interface
bRequest = 9
wValue = 0x0202
wIndex = 0

Commands

Zone codes

• A 16 bit code space is to reference each light zone.
• One hot encoding is used; i.e. address for each zone has 1 at a unique place and 0’s elsewhere
• Multiple zones can be addressed by ORing their codes
  • For example to address the entire keyboard use 0x1|0x2|0x4|0x8=0xF code
• A lot more zone codes and command codes might exist, which can do things we dont know about (yet),
  • For example setting multiple zones to different colors and such stuff

How it works?

Simple Set Color example

• Send a reset command
• Send a set color effect command (to say touch pad)
• Send a loop command
• Send an execute command

The touch pad color changes and stays put.
If the loop command is not issued then the color goes away after a certain time.

Blink or Morph example

• Send a reset command
• Send a tempo command
• Send a blink effect command (to say touch pad)
  • Morph effect command needs 2 colors
• Send a loop command
• Send an execute command

Blink effect and Morph Effect need an extra tempo command, which determines the rate of blinking or morphing.

Multiple effects at different zones

• Send a reset command
• Send a tempo command
• Send a blink effect command (to say touch pad)
• Send a morph effect command (to say logo)
• Send a loop command
• Send an execute command

The blinking happens for sometime and stops.
Then morphing happens for sometime and stops.
This happens because both are set on same sequence.

Multiple effects at different zones simultaneously

• Send a reset command
• Send a tempo command
• Send a blink effect command on sequence 1 (to say touch pad)
• Send a morph effect command on sequence 2 (to say logo)
• Send a loop command
• Send an execute command

The blink and morphing happens simulataneously.
But the blinking stops after some time.
This happens because loop command affects the latest sequence issued before it.
So we need to send two loop commands after every set of commands belonging to one sequence

Multiple effects at different zones simultaneously and continuously

• Send a reset command
• Send a tempo command
• Send a blink effect command on sequence 1 (to say touch pad)
• Send a loop command
• Send a morph effect command on sequence 2 (to say logo)
• Send a loop command
• Send an execute command

The blink and morphing happens simulataneously and continously.
Multiple zones can be referenced at once for an effect as described in Zone codes section

Misc

• Some zones (like power button) seems to be only be accessible in some states (like pugged in, on battery, on battery low) only
• If same zone is addressed in different sequences flashing can happen
• If you cannot control touch pad, set Trackpad backlight to Enable in BIOS settings

Disclaimer

• All the information here is obtained via trail and error reverse engineering, because the alienware lights software doesn’t seem to be opensource
• There is no conclusive evidence that these methods are the best way to go
• But they do work and did no harm to my system until now

References

Alienfx by trackmastersteve