Skip to content

Developer Guide

Jump to bottom
Chris Vig edited this page Sep 1, 2025 · 1 revision

This page contains developer-focused documentation for SuperKey. If you want to build or modify the SuperKey firmware, you're in the right place.

Pre-Requisites

The following tools and libraries are required in order to build firmware images for SuperKey:

No third-party libraries are required, other than avr-libc's C standard library.

Quick Start

I recommend always using a Linux environment for developing SuperKey's software. I personally use WSL on Windows, with VS Code as my primary editor / IDE.

Environment Setup

Exact installation steps will vary depending on the Linux distribution used. On Ubuntu-based platforms (including WSL), the following commands will install all required tools. (Note that the compiler package is confusingly named gcc-avr, not avr-gcc).

sudo apt-get update
sudo apt-get install -y avr-libc binutils-avr cmake gcc-avr make
# for documentation only:
sudo apt-get install -y doxygen graphviz
# for firmware upload only:
sudo apt-get install -y avrdude

Building Firmware

The build environment is configured and set up using CMake:

cd superkey
cmake -S . -B ./build/

You can then build the entire project using make:

cd build
make

Uploading Firmware

The executable is uploaded to the MCU using avrdude and an AVRISP mkII programmer. The AVRISP connects to the microcontroller via its SPI interface. This requires connecting 5 wires to the device PCB, as shown in the list below. Headers are provided on the PCB to support this.

  • ISP ground to device ground
  • ISP RESET to device RESET (pin 9)
  • ISP SCK to device SCK (pin 8)
  • ISP MOSI to device MISO (pin 7)
  • ISP MISO to device MOSI (pin 6)
icsp

The microcontroller fuses must be set correctly before the device will function (see the Hardware Guide for additional details). The fuses only need to be set once, and can then be left alone for the rest of the device's lifetime. The avrdude command to program the fuses is:

avrdude -c avrispmkii -P usb -p m1284p -U lfuse:w:0xdf:m -U hfuse:w:0x99:m -U efuse:w:0xfd:m

The avrdude command to upload the firmware is:

avrdude -c avrispmkii -P usb -p m1284p -U flash:w:superkey.ihex -D -V
  • The -c and -P arguments may need to be updated if you're using a programmer other than the AVRISP mkII.
  • The -D argument is optional, and disables the Flash erase cycle.
  • The -V argument is optional, and disables the post-upload verification.

A future improvement is to support firmware uploads via the serial interface.

Notes

Build Configuration

SuperKey supports a large number of build options to allow configuring your device. These options (and their default values) are defined in configuration.cmake in the root directory. Option values are injected into the source code as preprocessor #defines by the build system.

You should not normally edit configuration.cmake - instead, update build/CMakeCache.txt once the build system has been initialized. Any changes you make to that file will be immediately included in the next build.

Feature Enablements

  • FEATURE_ENABLE_DEBUG_PORT - Set to _FEATURE_OFF to omit the debug port from the build.

Feature Options

  • FEATURE_OPT_INTF_PORT_BAUD - Baud rate for the interface serial port. (usart_baud_t)
  • FEATURE_OPT_DEBUG_PORT_BAUD - Baud rate for the debug serial port. (usart_baud_t)

Configuration Defaults

  • CONFIG_DFLT_WPM - Default words-per-minute setting. (wpm_t)
  • CONFIG_DFLT_WPM_ELEMENT_SCALE - Default element scale for all Morse code elements. (wpm_element_scale_t)
  • CONFIG_DFLT_BUZZER_ENABLED - Is buzzer enabled by default? (bool)
  • CONFIG_DFLT_BUZZER_FREQUENCY - Default buzzer frequency, in Hz. (buzzer_freq_t)
  • CONFIG_DFLT_LED_STATUS_ENABLED - Is the status LED enabled by default? (bool)
  • CONFIG_DFLT_LED_KEY_ENABLED - Is the keyer LED enabled by default? (bool)
  • CONFIG_DFLT_IO_TYPE_TRS_(n)_(TIP/RING) - I/O type for the TIP or RING pin of TRS connector n. (io_type_t)
  • CONFIG_DFLT_IO_POLARITY_TRS_(n)_(TIP/RING) - I/O polarity for the TIP or RING pin of TRS connector n. (io_polarity_t)
  • CONFIG_DFLT_KEYER_PADDLE_MODE - Default keyer paddle mode. (keyer_paddle_mode_t)
  • CONFIG_DFLT_KEYER_PADDLE_INVERT - Are keyer paddles inverted by default? (bool)

Device Pinout

  • PIN_IO_PIN_TRS_(n)_(TIP/RING) - GPIO pin for the TIP or RING pin of TRS connector n. (gpio_pin_t)
  • PIN_LED_STATUS - GPIO pin for the status LED. (gpio_pin_t)
  • PIN_LED_KEY - GPIO pin for the keyer LED. (gpio_pin_t)

Clone this wiki locally