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

0 Members and 1 Guest are viewing this topic.

Offline a_marmot

  • Thread Starter
  • Posts: 11
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: 11
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: 11
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 the microcontroller that these terminals must ultimately be connected to (see below).
« Last Edit: Tue, 31 January 2023, 10:25:46 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 11
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 below the keyboard with minimal removal of ABS supporting the keyboard PCB.
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 mode. 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).
« Last Edit: Tue, 31 January 2023, 10:12:51 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 11
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. But I did find the following Youtube videos very useful:

Schematix:
Tuffrabit:

General advice:

 Be patient, take your time, and don't try to force anything.
 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.

Offline a_marmot

  • Thread Starter
  • Posts: 11
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 left picture shows what the tray should look like after the plastic has been removed, pointing out in RED where the plastic has been cut. The picture on the right 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 also the 1cm wide section of plastic removed from the fin separating the MCU and breakout boards - this is needed for the wire bundles running between the MCU and the other boards.

Also shown is the placement of the (optional) lever microswitch, used as a dedicated mode toggle.
« Last Edit: Tue, 31 January 2023, 10:22:18 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 11
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). On the RP2040 they are marked as "DX".

The photo shows how it should look after wiring everything together (warning: different wire colors that in 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 ribbon shown in the photo is ridiculously long (for prototyping purposes), and must be replaced with the original (short) ribbon from the Orbweaver during reassembly.
« Last Edit: Tue, 31 January 2023, 10:28:17 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 11
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: 145
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: 11
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: 11
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 (pending review) which contains generic source code to define the key layers and set static colors for the keys in each layer. 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 and RGB animation, you can.

First, you'll need to download the QMK 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 need.

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 keymap.c 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).

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: Tue, 31 January 2023, 10:42:55 by a_marmot »

Offline a_marmot

  • Thread Starter
  • Posts: 11
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 »