Author Topic: Razer Orbweaver Chroma MCU mod  (Read 978 times)

0 Members and 1 Guest are viewing this topic.

Offline a_marmot

  • Thread Starter
  • Posts: 12
Razer Orbweaver Chroma MCU mod
« on: Sun, 22 January 2023, 03:13:19 »
Hey all, I just completed a mod of a Razer Orbweaver Chroma, replacing the stock controller with a RP2040 and QMK.  It allows the device to have multiple programmable key layers with permanent OS-independent on-board memory (no Razer software needed to control the keymap or RGB). New switches and keycaps as well. The following posts break down the mod into sections, with step by step instructions, a component buylist, and QMK resources to program the controller. Enjoy.
295643-0
« Last Edit: Sat, 28 January 2023, 11:18:08 by a_marmot »

Offline suicidal_orange

  • * Global Moderator
  • Posts: 4772
  • Location: England
Re: Razer Orbweaver Chroma MCU mod
« Reply #1 on: Sun, 22 January 2023, 16:15:48 »
This is the perfect place to post the instructions - great mod!  :thumb:
120/100g linear Zealio R1  
GMK Hyperfuse
'Split everything' perfection  
MX Clear
SA Hack'd by Geeks     
EasyAVR mod

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #2 on: Sat, 28 January 2023, 11:20:03 »
1) First, why the mod? 

There are basically two issues.  The first is that the Orbweaver (as well as other Razer products) lack on-board memory.  So you are dependent on Razer's software to operate the device. This is particularly challenging when working across multiple platforms (PC, mac, linux), all of which need their own system extensions, and a connection to Razer cloud for keyboard profiles.  The second (and maybe more serious) problem is that Razer does not reliably support their products. The software is generally buggy, they do not update the software for older products, and they have essentially abandoned macOS, making the device useless except for PC.

In contrast, I have had great experience with Logitech G502 and Wooting 60HE, both of which have onboard memories, allowing the devices to operate without system extensions.  Of course these devices still have software to program them.  But once they are programmed (in any OS), they can work across platforms without ongoing need of software support or a cloud connection.

So basically my objective with this mod was to replace the stock Razer MCU with my own Raspberry Elite-Pi RP2040 microcontroller running QMK.
« Last Edit: Sat, 28 January 2023, 11:42:07 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #3 on: Sat, 28 January 2023, 12:16:36 »
2) What makes the mod possible?

Most companies use custom integrated PCBs with proprietary OEM components.  Had Razer done that in this case, the mod would be impossible, since access to the key matrix and RGB LEDs would require tapping into traces on the PCB.  Maybe that's possible, but certainly beyond my limited abilities! 

However, in the case of the Orbweaver Chroma, Razer (luckily) didn't do that.  Instead they used 3 separate PCBs, one for the proprietary MCU, another hosting the keyboard and RGB diode matrixes, and a third with the thumb pad key matrix. They also used a stock RGB LED matrix controller (IS31FL3731) for the LEDs, which they placed on the same PCB as the keyboard. These satellite boards communicate with the MCU through an 18-pin ribbon connector and an 8-pin JST connector.  In other words, all the components we would need for a hand-wired keyboard, thumb pad, and RGB matrix are conveniently provided by Razer!  All we have to do is tap into them with our own MCU. 

The image below summarizes the wiring on the two satellite boards (which I traced using a Fluke multimeter and/or oscilloscope). The keyboard PCB has a 18-pin ribbon connector (R1~R18), which provides direct access to the 4 rows (R17, R16, R15, R14) and 5 columns (R13, R12, R11, R10, R9) of the keyboard diode matrix.  This ribbon also hosts a I2C serial interface (R2, R3 = SDA, SCL) for communication with the IS31 RGB matrix controller (which independently controls the RGB LED matrix). The keyboard also requires 5V, GND (R4, R1) and 3.3V (R8) for the I2C pull-up resistors (which are also conveniently provided on the PCB!). The thumb pad PCB has a 8-pin JST connector (J1~J8), providing access to two additional rows of dioded keys: J2 (ALT, LEFT, RIGHT, DOWN, UP) and J3 (Spacebar, null, null, null, null). These keys share the same columns as the main keyboard on lines J4, J5, J6, J7, and J8. Thus it is possible to add up to 4 additional buttons without adding additional rows or columns to the overall 6x5 key matrix.

The secondary terminal labels (in parentheses) refer to the terminal position on a RP2040 microcontroller used in this mod (see below).
« Last Edit: Wed, 01 February 2023, 11:47:33 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #4 on: Sat, 28 January 2023, 13:42:27 »
3) What will you need.

Tools:

Fine screwdrivers and spudger for disassembly/reassembly of the Orbweaver.
Soldering iron
Solder sucker (probably a desoldering gun if you plan to replace the key switches!).
Scroll saw or other means to cut out a section of a standard PCB breadboard.
Cutting tools for plastic (razor blade, x-acto knife, wire dykes).
Fine file for smoothing/rounding edges of PCBs.
Epoxy, ideally Scotch Weld 2216.

Parts:

Raspberry Elite-Pi RP2040. I got one from Keebio (https://keeb.io/collections/diy-parts/products/elite-pi-usb-c-pro-micro-replacement-rp2040). This version of the RP2040 has the perfect form factor for this mod, as it is short enough to fit sideways below the keyboard with USB-C port aligned with the existing hole for a USB cable.
18-pin 0.5 mm ribbon breakout board: (https://www.amazon.com/dp/B09VPKGF7L)
8-pin JST connector and wire leads. You can make up your own, or buy pre-crimped (https://www.amazon.com/dp/B09F3TMG52). Alternatively you could try to adopt the Y-cable that is already inside the Orbweaver thumb pad.
8 rows x 4 terminal section of solder breadboard (https://www.amazon.com/dp/B081MSKJJX). I used a scroll saw to cut out the 8x4 section.  But you could probably also score and break the board as needed. Space is tight, so you want to remove as much unused board as possible. 
Optional: new MX-style switches. Get ones with alignment pins since the switches are soldered directly to the keyboard PCB (there is no plate). I prefer linear switches like the Gateron yellows (https://www.amazon.com/dp/B0BBPPP7HD)
Optional: supply of 4-pin R-C-B-G common-anode diodes (https://www.ebay.com/itm/323454847919). To replace the key switches you must first desolder the LEDs. It is easier to replace them than to resolder used LEDs.  In principle you could use R-C-G-B (the more common configuration), but would need to switch blue and green in QMK software.
Optional. I added an extra switch to the side of the Orbweaver for cycling keyboard profiles. As shown below I used an arcade microswitch and diode: (https://www.amazon.com/dp/B074868HZV, https://keeb.io/collections/diy-parts/products/1n4148-diodes). To actuate the switch I used a black plastic button removed from a PCB tactile switch (https://www.amazon.com/dp/B0722LBKV7).
Optional: If you can get a hold of an original monochrome green Orbweaver, it shares the same frame as the Chroma, but the top piece is made of black molded ABS instead of polystyrene.  This makes it much easier to remove webbing for a keycap replacement.  It's also a great source of spare parts in case you lose any from your Chroma. 

« Last Edit: Sat, 04 February 2023, 23:09:08 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #5 on: Sat, 28 January 2023, 14:01:43 »
4) Disassembly.

It's a pain to take an Orbweaver apart. There are lots of interconnected pieces that are hard to disassemble in a clear step by step process. The following geekhack post has lots of pictures: https://geekhack.org/index.php?topic=48771.0  I also found the following Youtube videos very useful:

Schematix:
Tuffrabit:



General advice:

Be patient, take your time, and don't try to force anything.
There are two ball bearings with springs used for the adjustable pads. These can (and will) go flying!  So you may wish to do the initial disassembly in a contained area like a dry bucket until you know where those components are and can make arrangements to extract or contain them. Some discussion about the ball bearings can be found here: https://geekhack.org/index.php?topic=48771.0
Keep the pieces organized for later reassembly. I used a sheet of clean clear polypropylene to store the sticky pads. 
When removing the keyboard PCB, be very careful not to break the ABS plastic tabs that hold it down.  They are not very flexible, and break easily.
The cosmetic sticker on the thumb pad must be removed to get the thumb assembly apart. I gave up on trying to save it. But YMMV.
« Last Edit: Sat, 04 February 2023, 11:44:36 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #6 on: Sat, 28 January 2023, 15:03:56 »
5) Modifying the plastic parts.

To make room for the RP2040 and ribbon breakout board, you'll need to remove some of the ABS plastic on the bottom tray.  To accomplish this I used a combination of tools including wire dykes, x-acto chisel, and razor blade. The pictures below show before and after images of the tray, pointing out in RED where the plastic must be cut. The rightmost picture shows where the new components will go. In order to fit, the corner of the RP2040 board must be rounded slightly with a file (2 millimeters). But leave enough material to support the USB housing. Note the upside-down placement of the ribbon breakout board - this is the orientation it will have when connected to the keyboard above it by a folded (but not twisted) ribbon cable.  Also note the 1cm wide section of plastic removed from the fin separating the MCU and breakout board - this is needed for the wire bundles running between the MCU and the breakout board.

Also shown is the placement of the (optional) lever microswitch, used as a dedicated mode toggle. It also plays a secondary role in confining the RP2040 to a fitted rectangular area, making it MUCH easier to secure in place, and more resistant to movement when the USB cable is plugged-in an un-plugged.
« Last Edit: Mon, 06 February 2023, 22:42:46 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #7 on: Sat, 28 January 2023, 15:36:11 »
6) Wiring.

Shown below is a wiring diagram for the mod.  There is not enough room under the keyboard for a pin header, so I recommend direct wire connections to the RP2040 and breakout board. In order to avoid having to solder multiple wires to a single terminal, I used a 8 row x 4 pin section of breadboard, which fits nicely under the palm rest area just inside the hole for the wires running to the thumb pad. The terminals marked "GPX" refer to the terminal position on the microcontroller (this is the nomenclature used by QMK). In the RP2040 documentation they are marked as "DX": https://docs.keeb.io/elite-pi-guide?utm_source=store. The photo below shows how it should look after wiring everything together (warning: the wire colors in this photo differ from the circuit diagram, sorry!).  Note that the wires need to enter the breakout board from the bottom, so they enter from the top when it is flipped upside-down. The long ribbon shown in the photo was for prototyping purposes only, and must be replaced with the original (short) ribbon from the Orbweaver during reassembly.

295718-0

An alternate approach for wiring J1~J8 from the thumb assembly to the breadboard is to use the existing cord.  It combines J1~J8 with 5 additional wires from the thumb pad LEDs into a single 14-pin JST.   If you cut these wires just below the 14-pin JST, the 8 wires marked in the picture correspond to J1~J8. This approach has the added benefit of not having to take apart the thumb assembly.  I have never tried to reverse-engineer the thumb pad diodes (I just don't care about them), but in theory these could also be added to unused pins on the RP2040 to control them. 

296042-1
« Last Edit: Sun, 05 February 2023, 01:22:55 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #8 on: Sat, 28 January 2023, 15:51:18 »
7) Optional mode switch.

I wanted to avoid dedicating any regular keys or thumb buttons (or defining key combos) to toggle keymaps. So I added an optional mode switch. This required drilling a hole in the side of the Orbweaver for a button stem, which actuates the lever micro switch inside. I used epoxy to fix the switch in place.  See photos.  This type of switch also has the added benefit of boxing in the RP2040, making it MUCH easier to secure in place!

The mode switch is incorporated into the rest of the key matrix by wiring one end to row 6 (GP 9) on the breadboard, and the other (via diode) to column 2 (GP13). 
« Last Edit: Sun, 29 January 2023, 05:03:11 by a_marmot »

Offline PlayBox

  • Posts: 149
Re: Razer Orbweaver Chroma MCU mod
« Reply #9 on: Sat, 28 January 2023, 15:54:56 »
that's a very quality post for a newcomer tbh
propably sent from my amazon kindle 10th gen

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #10 on: Sat, 28 January 2023, 16:13:54 »
#8) Optional keycap mod. 

Others have discussed this previously (in particular Tuffrabit on Youtube). But the Orbweaver uses nonstandard keycaps with shallow shells.  In order to swap to normal keycaps, you must remove the plastic webbing and rim that surrounds the switches in the polystyrene top piece.  The photo below shows what it needs to look like after you are done.  Polystyrene is very hard and difficult to carve, so you'll need to be patient and take care not to cut yourself, or break the piece.  The styrene itself is bright white, so try not to scratch the black coating.  (Tip: if you do scratch the black coating, india ink does a pretty good job of masking it.)

Note the webbing hosts two of the screw mounts anchoring it to the base tray.  So the device loses some structural integrity by doing this (you can feel the added flexibility if you lift up on the top piece after reassembly). I have not it found this to be an issue in practice, but... I'm currently investigating ways to anchor the top piece to the tray more securely, especially in the upper right area of the keyboard. 
« Last Edit: Tue, 31 January 2023, 10:37:11 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #11 on: Sat, 28 January 2023, 16:15:57 »
9) QMK

The RP2040 microcontroller is supported by QMK firmware.  However, a modded Orbweaver is essentially a handwired custom board, and thus is not configurable using the QMK online configurator tool or VIA. If you want full control over the keymaps and RGB color, You'll need to get a copy of the QMK programming environment and compile the firmware yourself. 

The good news is you don't have to start from scratch.  I have created a folder on the QMK Github repository which contains generic source code to define the key layers and set static colors for the keys in each layer (https://github.com/qmk/qmk_firmware/tree/master/keyboards/handwired/orbweaver). That's as far as I have taken it.  But QMK is incredibly powerful, so if you want to do additional things like dynamic RGB effects and RGB animation, you probably can. If you decide you want to build new features, the QMK folks are very helpful and respond quickly on the QMK discord channel.

To use QMK, you'll first need to download the QMK programming environment.  Follow instructions at https://docs.qmk.fm/#/newbs (exact procedure depends on your OS).  This will create a local copy of the QMK compiler and all the files you'll need (including the orbweaver-specific files).

Then, under keyboards/handwired/orbweaver/keymaps/default, you'll find a file entitled keymap.c.  This is the file you need to edit or replace to set your keymaps and key colors.  The default keymap just has two layers (0, 1).  But you can add more (I currently use 4).  The default layer 0 is set to the Razer default keys.  Here's what it looks like in the code:

  • = LAYOUT_keypad(

        KC_ESC, KC_1, KC_2, KC_3, KC_4,
        KC_TAB, KC_Q, KC_W, KC_E, KC_R,
        KC_CAPS, KC_A, KC_S, KC_D, KC_F,
        KC_LSFT, KC_Z, KC_X, KC_C, KC_V,
        KC_LALT, KC_UP, KC_DOWN, KC_RIGHT, KC_LEFT,
        KC_SPACE, TO(1)

Here TO(1) is assigned to the optional extra side button described above. This button toggles to layer 1, which has a key to toggle back to layer 0, etc. The key nomenclature can be found at https://github.com/qmk/qmk_firmware/blob/master/docs/keycodes.md.

They colors for each key layer are defined in the section below the key maps, and look like this:

         {
      {0x00, 0x00, 0xFF},{0xE7, 0xFF, 0x00},{0xE7, 0xFF, 0x00},{0xE7, 0xFF, 0x00},{0xE7, 0xFF, 0x00},
      {0xFF, 0x70, 0x00},{0x00, 0xFF, 0xFF},{0x80, 0x00, 0xFF},{0x00, 0xFF, 0xFF},{0x00, 0xFF, 0xFF},
      {0xFF, 0x70, 0x00},{0x80, 0x00, 0xFF},{0x80, 0x00, 0xFF},{0x80, 0x00, 0xFF},{0x00, 0xFF, 0xFF},
      {0xFF, 0x70, 0x00},{0x00, 0xFF, 0xFF},{0x00, 0xFF, 0xFF},{0x00, 0xFF, 0xFF},{0x00, 0xFF, 0xFF}
   },


These are the RGB levels in hexidecimal (0~255) for {R, G, B} for each key (top view).  The color maps are listed in order for layers 0, 1 (more if you add them).  Note that if you replaced the Razer R-C-B-G diodes with more standard R-C-G-B diodes, this is where you would need to switch green and blue.

Once you have the keys and colors defined, you can open a shell in the QMK programming environment, and type the command:

$ qmk compile -kb /handwired/orbweaver -km default

This will create a firmware file entitled orbweaver_default.uf2 in the qmk_firmware folder in your user folder.  Plug the PR2040 into a USB and put it into bootloader mode (how depends on platform), and copy the firmware to the MCU.  It should immediately appear as an available input device with RGB lighting corresponding to the default keymap.

Maybe if one of you is a programming whiz you can come up with more sophisticated firmware with an app to control it (like wooting or logitech). This is beyond my limited programming abilities.


« Last Edit: Wed, 01 February 2023, 12:24:57 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 12
Re: Razer Orbweaver Chroma MCU mod
« Reply #12 on: Sat, 28 January 2023, 16:16:21 »
10) Reassembly

Carefully reassemble the Orbweaver, placing the boards where they need to be.  I found it helpful to use heatshrink tubing around bundles of wires to keep them tidy. I also used a few drops of Scotch Weld 2216 to secure the boards in place. The OP shows a picture of the final product in operation!

Any questions, please do not hesitate!
« Last Edit: Sun, 29 January 2023, 05:00:45 by a_marmot »