v0.0.6

WARNING: I can't test all firmware variants, since I don't have hardware for all of them, and I sometimes publish releases without testing on all hardware I own. Please use caution when trying out new releases, especially on devices that are hard to open to manually get into bootloader mode if something goes wrong, or devices for which the original firmware is not available for you to restore

This release was published on 2023/03/06
Release notes were last edited on: 2024/09/27

---

Documentation

This firmware is based on a slightly older version of TMK, as originally ported by Marfrit, but support for Televideo DEC keyboards has also been backported onto it, integrated with VIAL, and layouts have been made more TMK-like.

This firmware is expected to work with all sorts of atmega32u2/atmega32u4 devices, that includes manually wired devboards (such as Pro Micro), Soarer's converter cables from various vendors, etc... Many combinations have not been tested. If you have any issues please contact me. If you have any devices that might be easy to add support for, please contact me.

There are two variants for each firmware. The plain vial variant, and a vial_VERY_INSECURE variant. The vial_VERY_INSECURE variant allows the keyboard to be sent into bootloader mode, and reprogrammed by any application running on the host PC, however it's slightly safer for first-time users, because it doesn't require a working keyboard to be attached to the converter for it to be sent into bootloader mode from the VIAL app, or from Vial Web. The normal "vial" build is secure, so it requires Escape and Enter to be held for a number of seconds to unlock the keyboard to do some privileged changes to it.

Warning: you can still get your converter in a state in which it can't enter bootloader mode using just software, even if you choose the VERY_INSECURE variant, if you flash a firmware that is for a different chip, or for a different bootloader. Make sure you choose the correct .hex file to flash!

Warning: If you flash this on Soarer's converter hardware, then the scboot tool will not continue working to send it into bootloader mode, because it's a Soarer's-specific tool. Instead you will have to use the VIAL app (or Vial Web), and that will only work if you flash the correct firmware variant.

Notes specific to hardware:

• for Pro Micros use converter_ibmpc_usb_atmega32u4_caterina_vial.hex firmware

  • only 16MHz atmega32u4 pro micros are supported that have caterina bootloader. This includes the Sparkfun Pro Micro, Qwiic Pro Micro and various pro micro clones from ebay, and aliexpress, including USB-C pro micros. It does NOT include other devices which only have a pro micro-like footprint.
    • the clock pin is pro micro pin 2, aka PD1
    • the data pin is pro micro pin 3, aka PD0
    • the reset pin, which is needed by a very few keyboards, is pro micro pin 10, aka pin PB6
      • reset is driven to both PB6 and PB7 (PB7 is what Soarer's firmware used originally)
    • some Pro Micro replacements will be supported by different firmware variants:
      • For example Elite-C V4 pro micro replacement board will probably work with converter_ibmpc_usb_atmega32u4_atmel_dfu_vial.hex (not tested)
    • some Pro Micro replacements will likely never be supported:
      • nice!nano has an nrf chipset, will not be supported
      • rp2040/rp2350-based pro micros run at 3.3V, so not currently supported (may be supported in the future, but only if using level shifters)

• for Teensy 2.0 use converter_ibmpc_usb_atmega32u4_halfkay_vial.hex firmware. Since the halfkey bootloader is proprietary, it's not expected to show up in any other devices, unless it embeds a teensy board.

• for Orihalcon's Soarer's converter cables use converter_ibmpc_usb_atmega32u4_atmel_dfu_vial.hex. The soarer's converter cables this has been tested on come with atmega32u4 chips, and a bootloader compatible with the bootloadHID protocol, HOWEVER, the bootloadhid firmware doesn't correctly enter bootloader mode when triggered from VIAL. Experimentally I have verified that however the atmel_dfu firmware correctly enters bootloader mode, so please use that one. For flashing use either QMK Toolbox, or the bootloadHID command line utility. (Note: when first flashing VIAL firmware you will have to use scboot, to get it into bootloader mode).

  • WARNING: if you make a mistake while flashing one of these cables, and flash the wrong firmware that can't enter bootloader mode, then you will have to cut up the USB end of the cable, and short the RESET pin to GND to get it into bootloader mode again.
    • See this imgur post if this happens: https://imgur.com/a/HT6RKKI

• for Tinkerboy's older Soarer's converter cables (specifically the ones with the silkscreen "KBD Converter v1.2" on the bottom of their PCB), use converter_ibmpc_usb_atmega32u4_atmel_dfu_vial.hex, and flash it normally, using QMK Toolbox, or dfu-programmer.

  • WARNING: if you make a mistake while flashing one of these cables, and flash the wrong firmware that can't enter bootloader mode, then you will have to open up the USB end of the cable, and short the RESET pin to GND to get it into bootloader mode again. (This is easier than on the Orihalcon cables, because the different style of connector which is not potted)
    • See this imgur post if this happens: https://imgur.com/a/6forxAM

• Tinkerboy's newer VIAL QMK converters advertised as formerly Soarer's Converter, (specifically the ones with silkscreen "KBD Converter v1.3" on the bottom of their PCB) come with firmware that is derived from the work in this repository, and modified. I don't know what the modifications are.

  • If you would like to put my build onto one of these devices, then use converter_ibmpc_usb_atmega32u2_atmel_dfu_vial.hex
  • No build of Soarer's firmware exists for atmega32u2 devices
  • To get one of these devices to enter bootloader mode via the hardware method, please follow https://imgur.com/a/ZSljNfW
  • I've heard rumours that with the shipped firmware, VIAL may not be able to enter bootloader mode on some of these, so you may have to use the hardware method.

• some other integrated soarer's converter cables may be similar to Orihalcon's, but we don't know for sure, if you have one of these converters, or a different Soarer's converter please contact me to update the information here:

  • XTPTFABS (we know it's an atmega32u4-based device. We don't know which bootloader it has. Someone on discord tried the halfkey build, and that leaves the device working, but unable to enter bootloader mode. Now to do any further testing they would need to cut up the USB end, and they are not interested in that. They probably should have tried the atmeldfu build instead. These are very well potted/molded, just like the Orihalcon cables, so it's hard to open up if something goes wrong)
    • We've also seen here that XTPTFABS can be flashed successfully with official soarer's firmware, and that the protocol seen by QMK Toolbox is bootloadHID, so that suggests so far it's exactly like Orihalcon's product. So I suggest trying converter_ibmpc_usb_atmega32u4_atmel_dfu_vial.hex with it. The risk that you'll have to cut it up to reflash again is significant. If you tried it, please report back, and let me know if bootloader entry still works after flashing the atmel_dfu firmware.
  • craftsman-part cables - (no information is known about these)
  • fastlane-a cables - (no information is known about these)
  • Some pictures show up in all three of these listings, while some are unique.
  • We've seen here and here that someone ordered a "mystery" converter similar to the 3 in this section (not clear from exactly which seller), and when they ran scinfo on it, it reported the same bogus memory size of 2816 bytes that Orihalcon's February 2020 cables report. The correct value should be 2560 (and is what Soarer's official builds report). All info we've seen so far suggests to us that all three of these might actually be copies of Orihalcon's product. Even if this is based on the same firmware and/or the same design as Orihalcon's original product, there's no guarantee it will behave the same.
    • note: Orihalcon was clearly using modified Soarer's firmware. The other noticable change between Soarer's 1.12 and Orihalcon's 1.12 is that Interface 1 and 2 are flipped when looking at lsusb output. We don't really know why Orihalcon was using a modified firmware.

• t4teeee0's Soarers converters - use converter_ibmpc_usb_atmega32u4_caterina_vial.hex

• retrobit4004's Soarer's Converters - not tested, but most pictures show normal pro micros, so you should probably use converter_ibmpc_usb_atmega32u4_caterina_vial.hex. At the moment locklights that are on the converter board are not enabled.

• Retro Fuzion's XT/AT 2 USB Keyboard adapter - Soarers Converter - (no information is known about these)

Generic usage notes

• Make sure to select the most appropriate layout in the Layout tab.

CHANGES from v0.0.5:

• an-achronism's fixes to Unicomp Pause/Break key
• fixes to Code Set 2 layout around windows keys/modifiers.