Package: alienware-13r3-alien-effects
Alien Effects for Alienware 13 R3alieneffects-13r3is an lightweight and highly customizable application to control LED backlights (alien effects) of Alienware 13 R3 laptop in linux.Installation and usagepython version3.6 is recommended3.4 may not work2 is strongly discouragedsudo pip3 install alienware-13r3-alien-effectsto installTo install from source, clone this repo andsudo python3 setup.py installsudo alieneffects-13r3 --THEME_FILE <path-to-theme-file>to apply a themesudo alieneffects-13r3to open a Textual User Interface where you can select themesFirst field is the themes directoryAfter setting it, a list of files in the that directory will appear belowBy hovering through them, you can see the overview of each theme on the right panelPress enter to apply a themeSome themes have stochasticity (randomness) in them, so applying same theme multiple times can lead to different themesConfig fileThemes directory by default will be your home directoryYou can write a config file.alieneffects-13r3.jsonto specify themes directory{
      "THEMES_DIRECTORY": "/home/foo/bar/themes"
    }Writing your own themesThe log will be written to.alieneffects-13r3.logTheme files are also json files and can contain following keysDESCRIPTION - describes the themeTEMPO - the frequency of blinking and/or morphingDURATION - duration of each effectZONES - sequences of each zoneex. POWER_BUTTONex.SET_COLOR, COLORBLINK_COLOR, COLORMORPH_COLOR, COLOR1, COLOR2LOOP_SEQUENCESame sequence can be applied for multiple zones by delimiting zones with '|'If an effect does not have a color, a random color will be choosenThe 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 EngineeringAlienware 13 R3 has 8 configurable light zones as listed in the table below.All lights can be controlled via USB protocol.For this specific devicevendor Id = 0x187candproduct Id = 0x0529Commands 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 toAlienfxby trackmastersteveControl transfer: Write operation parametersbmRequestType = 0x21
    0... .... : Host to Device
    .01. .... : Request Type = Class
    ...0 0001 : Recipient = Interface
bRequest = 9
wValue = 0x0202
wIndex = 0Control transfer: Read operation parametersbmRequestType = 0xa1
    1... .... : Device to Host
    .01. .... : Request Type = Class
    ...0 0001 : Recipient = Interface
bRequest = 9
wValue = 0x0202
wIndex = 0CommandsCommandPacket Structure (bytes)DesciptionCommentReset2 7 t 0 0 0 0 0 0 0 0 0t : type, t=3 : reset all off and stops the execution of sequences t=4 : reset all onShould call before every change. This takes some time, and you should wait until the operation ends. Premature commands might fail.Get status2 6 0 0 0 0 0 0 0 0 0 0S : Sequence ID, Z : ZoneCan use this to wait until status is readyMorph2 1 S Z Z Z r g b R G BS : Sequence ID, Z : ZoneColor changes fromr g btoR G B. All bands use 8-bit color encoding. So each value must be between 0-255.Pulse2 2 S Z Z Z r g b 0 0 0S : Sequence ID, Z : ZoneSimple set2 3 S Z Z Z r g b 0 0 0S : Sequence ID, Z : ZoneLoop2 4 0 0 0 0 0 0 0 0 0 0S : Sequence ID, Z : ZoneWithout this, LEDs will go off after walking through the user-specified   color sequence. TODO: how does this know which sequence is the target? The last one mentioned? What happens if sequences are interleaved?)Execute2 5 0 0 0 0 0 0 0 0 0 0S : Sequence ID, Z : ZoneThis must be called at the end. Start executing color sequencesSave next command2 8 m 0 0 0 0 0 0 0 0 0m : mode, m=01: Initial State m=2: Plugged in - Sleep; Only the power-button works in this mode? m=5: Plugged in - Normal m=6: Plugged in - Charging m=7: On Battery - Sleep m=8: On Battery - Normal m=9: On Battery - LowSave the next command to the specified mode. Must be followed by an Action or LoopSave all2 9 0 0 0 0 0 0 0 0 0 0Save slots permanently. If this command is not called, data slots will be lost on rebootTempo2 e t t 0 0 0 0 0 0 0 0t: tempoAlienFX sets this value between 00:1e ~ 03:ae.Zone codesA 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 elsewhereMultiple zones can be addressed by ORing their codesFor example to address the entire keyboard use 0x1|0x2|0x4|0x8=0xF codeA 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 stuffZone Alienware 13 R3BinaryHexKeyboard right000 0000 0000 00010x0001Keyboard middle-right000 0000 0000 00100x0002Keyboard middle-left000 0000 0000 01000x0004Keyboard left000 0000 0000 10000x0008unknown/unused000 0000 0001 00000x0010Alien head000 0000 0010 00000x0020Alienware logo000 0000 0100 00000x0040Touch pad000 0000 1000 00000x0080Power button000 0001 0000 00000x0100How it works?Simple Set Color exampleSend a reset commandSend a set color effect command (to say touch pad)Send a loop commandSend an execute commandThe 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 exampleSend a reset commandSend a tempo commandSend a blink effect command (to say touch pad)Morph effect command needs 2 colorsSend a loop commandSend an execute commandBlink effect and Morph Effect need an extra tempo command, which determines the rate of blinking or morphing.Multiple effects at different zonesSend a reset commandSend a tempo commandSend a blink effect command (to say touch pad)Send a morph effect command (to say logo)Send a loop commandSend an execute commandThe 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 simultaneouslySend a reset commandSend a tempo commandSend 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 commandSend an execute commandThe 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 sequenceMultiple effects at different zones simultaneously and continuouslySend a reset commandSend a tempo commandSend a blink effect command on sequence 1 (to say touch pad)Send a loop commandSend a morph effect command on sequence 2 (to say logo)Send a loop commandSend an execute commandThe blink and morphing happens simulataneously and continously.
Multiple zones can be referenced at once for an effect as described in Zone codes sectionMiscSome zones (like power button) seems to be only be accessible in some states (like pugged in, on battery, on battery low) onlyIf same zone is addressed in different sequences flashing can happenIf you cannot control touch pad, setTrackpad backlighttoEnablein BIOS settingsDisclaimerAll the information here is obtained via trail and error reverse engineering, because the alienware lights software doesn't seem to be opensourceThere is no conclusive evidence that these methods are the best way to goBut they do work and did no harm to my system until nowReferencesAlienfxby trackmastersteve