Build a Hardware Hexadecimal Code Calculator for ESP32 Debugging

Build a Hardware Hexadecimal Code Calculator for Embedded Debugging

When you are deep in the trenches debugging I2C sensor registers, parsing SPI flash dumps, or mapping CAN bus payloads, pulling out your phone to use a software programmer calculator is a workflow killer. You need a dedicated bench tool. A physical hexadecimal code calculator lets you punch in hex values, execute bitwise operations (AND, OR, XOR), and instantly view the decimal and binary equivalents without breaking your focus or touching a keyboard.

This guide walks through building a standalone hardware hex calculator tailored for embedded systems debugging. We will use an ESP32 for its ample GPIO and processing headroom, paired with a tactile 4x4 matrix keypad and a high-contrast OLED display.

Hardware Spec Sheet and Pin Mapping

Before wiring, verify your components. The ESP32-WROOM-32 has specific strapping pins (like GPIO 0, 2, 4, 12, and 15) that can cause boot loops if pulled high or low incorrectly during startup. The pin mapping below deliberately avoids these strapping pins to ensure reliable power-on behavior. For more on ESP32 pin constraints, refer to the official Espressif ESP32-WROOM-32 datasheet.

ESP32 Pin Mapping Table

Step-by-Step Assembly and Wiring

1. Prep the I2C Bus: Connect the OLED VCC to 3.3V and GND to GND. Connect SDA to GPIO 21 and SCL to GPIO 22. Bench tip: Most cheap OLED breakouts include 10kΩ pull-up resistors. The I2C specification prefers 4.7kΩ for 400kHz Fast Mode. If your display acts glitchy, solder 4.7kΩ resistors from SDA/SCL to 3.3V. See the NXP I2C-bus specification (UM10204) for pull-up calculations.
2. Wire the Keypad Matrix: The 4x4 keypad has 8 pins. Connect the first 4 pins (Rows) to GPIO 13, 14, 27, and 26. Connect the last 4 pins (Columns) to GPIO 25, 33, 32, and 17.
3. Verify Continuity: Before plugging in the ESP32, use your multimeter in continuity mode. Check that no adjacent keypad pins are shorted. Ensure the OLED VCC is strictly 3.3V; feeding it 5V will permanently damage the SSD1306 charge pump.
4. Mounting: For a permanent bench tool, mount the ESP32 and OLED on a 3D-printed base or a piece of perfboard. Membrane keypads can be adhered directly to the enclosure using the included double-sided tape.

Complete ESP32 Firmware (C++ / Arduino IDE)

This firmware requires the Adafruit_SSD1306, Adafruit_GFX, and Keypad libraries, installable via the Arduino Library Manager. The code below includes robust error handling for display initialization and uses strtoul for safe hexadecimal string parsing. For detailed library setup, check the Adafruit OLED breakout tutorial.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
#include <Keypad.h>

// --- Pin Definitions & Hardware Config ---
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C // Use 0x3D if your specific board requires it

const byte ROWS = 4;
const byte COLS = 4;
char keys[ROWS][COLS] = {
  {'1','2','3','A'},
  {'4','5','6','B'},
  {'7','8','9','C'},
  {'*','0','#','D'}
};
byte rowPins[ROWS] = {13, 14, 27, 26};
byte colPins[COLS] = {25, 33, 32, 17};

Keypad keypad = Keypad(makeKeymap(keys), rowPins, colPins, ROWS, COLS);
Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

String currentInput = "";
unsigned long parsedValue = 0;

void setup() {
  Serial.begin(115200);
  
  // Initialize OLED with error trapping
  if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial.println(F("SSD1306 allocation failed"));
    for(;;); // Halt execution to prevent I2C bus lockups
  }
  
  display.clearDisplay();
  display.setTextColor(SSD1306_WHITE);
  display.setTextSize(1);
  display.setCursor(0,0);
  display.println("Hex Calculator Ready");
  display.println("Type Hex, press '*'");
  display.println("to convert.");
  display.display();
}

void loop() {
  char customKey = keypad.getKey();
  
  if (customKey) {
    if (customKey == '*') {
      // Parse and convert
      if (currentInput.length() > 0) {
        parsedValue = strtoul(currentInput.c_str(), NULL, 16);
        renderResults();
      }
    } else if (customKey == '#') {
      // Clear screen
      currentInput = "";
      parsedValue = 0;
      display.clearDisplay();
      display.setCursor(0,0);
      display.println("Cleared.");
      display.display();
    } else {
      // Append character
      if (currentInput.length() < 8) { // Limit to 32-bit (8 hex chars)
        currentInput += customKey;
        updateInputDisplay();
      }
    }
  }
}

void updateInputDisplay() {
  display.clearDisplay();
  display.setCursor(0,0);
  display.print("Input: 0x");
  display.println(currentInput);
  display.display();
}

void renderResults() {
  display.clearDisplay();
  display.setCursor(0,0);
  display.print("Hex: 0x");
  display.println(String(parsedValue, HEX));
  
  display.print("Dec: ");
  display.println(String(parsedValue, DEC));
  
  display.print("Bin: ");
  // Manual binary padding for readability
  String binStr = String(parsedValue, BIN);
  while(binStr.length() < 8) binStr = "0" + binStr;
  display.println(binStr);
  
  display.display();
}

Debugging: Common Errors and First Checks

Embedded hardware rarely works perfectly on the first power-on. If your hexadecimal code calculator fails to boot or read inputs, follow this decision path.

Error: "SSD1306 allocation failed"

Exact Error String: SSD1306 allocation failed (Printed to Serial Monitor, followed by a hard lockup).

Ranked Causes:

1. Insufficient RAM / Memory Fragmentation: The Adafruit library attempts to malloc a 1024-byte buffer for the 128x64 display. If your ESP32 heap is fragmented or exhausted by other libraries, this fails. Fix: Reboot the board. If using other heavy libraries, switch to the U8g2 library which handles memory allocation more efficiently in page-buffer mode.
2. I2C Bus Lockup: If the ESP32 was reset while the OLED was mid-transaction, the OLED might be holding the SDA line LOW. Fix: Power cycle both the ESP32 and the OLED simultaneously.

Error: Keypad Ghosting or Multiple Inputs

Symptom: Pressing '5' registers as '5' and 'A' simultaneously.

Ranked Causes:

1. Missing Internal Pull-ups: The Keypad library usually handles this, but if your specific ESP32 core version has a bug with INPUT_PULLUP, the floating column pins will pick up EMI noise from the OLED's charge pump. Fix: Add external 10kΩ pull-up resistors to the 4 Row pins.
2. Membrane Short: The ribbon cable on cheap keypads can crease and short adjacent traces. Fix: Test continuity across the ribbon cable pins with the keypad unpressed.

Extending and Simplifying the Build

Depending on your bench needs, you might want to alter the scope of this hexadecimal code calculator.

How to Simplify the Build

If you are short on GPIO pins or want to avoid matrix scanning debounce issues entirely, replace the 4x4 membrane keypad with an I2C capacitive touch keypad (like the MPR121 breakout). This reduces the keypad wiring from 8 pins down to just 2 (SDA/SCL) sharing the OLED's I2C bus. You will need to change the I2C address of one of the devices (usually by bridging a solder jumper on the OLED) to avoid address collisions.

How to Extend the Build

To turn this from a simple converter into a true embedded debugging multi-tool:

• Add Bitwise Operations: Map the 'A', 'B', 'C', and 'D' keys to AND, OR, XOR, and NOT operations. Store a secondary variable in RAM to allow two-operand math (e.g., 0xFF AND 0x0F).
• UART Sniffer Mode: Wire the ESP32's RX pin (GPIO 16) to a target microcontroller's TX line. Add a mode that intercepts live serial hex dumps, parses them on the fly, and displays the ASCII equivalent on the OLED. This is invaluable for debugging proprietary RF modules or GPS NMEA sentences.

Hexadecimal Calculator FAQ

How do I use a hexadecimal code calculator for I2C address scanning?

A standard hex calculator converts values, but for I2C scanning, you need a dedicated sniffer. However, you can use this build to manually calculate 7-bit vs 8-bit I2C addresses. Many datasheets list the 8-bit address (which includes the R/W bit). To find the 7-bit address your ESP32 Wire library needs, type the 8-bit hex value into this calculator, convert it to binary, and shift it right by one bit (drop the least significant bit). The resulting hex value is your 7-bit address.

What is the difference between a hex calculator and a standard scientific calculator?

A standard scientific calculator operates in base-10 (decimal) and handles floating-point math. A hexadecimal code calculator operates in base-16 and strictly handles integer arithmetic and bitwise logic (AND, OR, XOR, bit-shifting). In embedded systems, you rarely care that a register value is '255' in decimal; you care that it is 0xFF in hex, meaning all 8 bits are HIGH. Hex calculators preserve the bit-boundary visualization that decimal calculators obscure.

Why does my hex calculator show negative numbers for large unsigned hex values?

If you input 0x80000000 or higher and the decimal output shows a negative number, you are experiencing signed integer overflow. In C++, a standard 32-bit long is signed, meaning the most significant bit (bit 31) acts as a negative sign flag. To fix this in the firmware, change the parsedValue variable type from unsigned long to uint32_t and ensure your string conversion functions cast it as an unsigned integer before printing.

Can I use an Arduino Uno instead of an ESP32 for this hex calculator build?

Yes, but with memory caveats. The Arduino Uno (ATmega328P) only has 2KB of SRAM. The 128x64 OLED buffer alone consumes 1024 bytes (50% of your total RAM). While the Adafruit_SSD1306 library will technically compile and run on an Uno, you will have very little headroom for string manipulation or complex keypad parsing. If you must use an Uno, switch to the U8g2 library and use a page-buffered rendering mode to reduce the RAM footprint to roughly 128 bytes.