Hamhire Tech Tips

Nixie Indicator, Behind the Scenes — Making a Presentation Video

Sat, 07 Nov 2026 20:00:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/projects/nixie-indicator-presentation.html -

As the hardware and software took shape, I wanted material to share on social media and video platforms. The project had already accumulated a set of 3D models. They provided an opportunity to try producing a polished presentation video and introduction images for the device.

This article walks through refining the models, synthesizing music, and creating animation with an agent. Here is the finished landscape-format video.

Your browser does not support the video tag.

Modeling

The engineering models provided a useful starting point. I imported the two PCBs, enclosure, and fasteners from a STEP assembly into Blender, unified units and coordinates, and retained the relationships between parts. I could then compose shots of the complete device or isolate boards and enclosure parts for exploded views.

图 1. Existing engineering models, including an assembly section and both enclosure halves

Models intended to verify dimensions and positions still needed another refinement pass for close-up shots. Surfaces, edges, and internal structures became much more apparent through the camera. I began with the tube interiors, then worked through PCB materials and other parts.

Refining the Nixie Tubes

The tubes were the focus of the device’s close-ups, and I wanted to reproduce their internal structure as closely as possible. The official datasheet offers limited dimensions, mainly the overall outline, character size, and pin positions. It provides too little information to reconstruct the electrodes, mesh, and supports directly.

图 2. Tube outline and pin dimensions in the DGM01 datasheet

Drawing source is page 3 of the iNixie Lab DGM01 datasheet.

I asked the agent to compare photographs of the actual tube and consult material on other tubes, including the IN-18, to understand the structure. My own observations supplied further corrections. The digits occupy different planes, so viewing angle changes how the electrodes, mesh, and supports occlude one another. The ten digit shapes, their depth order, and their mounting gradually approached the present result through repeated adjustments.

Some details have little impact at a distance but matter in close-up. The main vertical stroke of 1 is thicker than the other strokes, and 5 has distinctive bends and openings. A generic font struggled to reproduce that character. I eventually had the curves fitted to photographs, then refined the metal clips, insulating supports, mesh cage, and internal leads.

The glass needed separate attention. Alongside the cylindrical outline, I added inner and outer walls, a curved top, and the narrowed base so that its edges could reflect and refract light. At close range, those details and the internal metalwork together determine the tube’s sense of thickness.

The glow comes from excited gas around the electrodes and has a soft, mist-like appearance. I therefore asked the agent to model the metal electrodes and gas discharge separately. The metal stays non-emissive, while a separate volumetric emission layer around each character controls its glow.

Glow and glass highlights had to be judged together. Excessively bright reflections obscured digits and mesh. A very dark image lost the glass curvature. Soft lighting from the side and rear outlined the tube while keeping the orange-red digits prominent.

图 3. Tube-interior modeling and the illuminated result

PCBs and Other Components

The board outlines and component positions were available already, but materials required several iterations. Plastic packages, metal leads, connectors, and the board surface each needed different reflectivity and roughness for convincing close-up detail.

The PCB surface also needed more than a flat black plane. Using the actual design files, I had the agent reproduce subtle relief from traces and copper areas, add silkscreen, and refine the surface appearance of the solder mask and copper regions. Changes in lighting and camera angle then made that relief visible.

The initial models lacked solder joints, making the components look as if they had simply been placed on the boards. I separated the pads and solder, added joint shapes around SMD leads and through-hole connections, and adjusted the silver-gray reflections. Joining the components visually to the board made the assembly much more convincing.

图 4. Traces, silkscreen, and solder joints on the two boards

I refined other parts similarly, adding a matte grain to the enclosure, knurling and chamfers to the knob, and separate appearances for the LCD’s dark reflective surface and active display. Materials continued to evolve with the lighting in individual scenes.

Rhythm and Storyboarding

For pacing, I drew on a workflow shared by He Tongxue in a YouTube Short. Starting with a rough visual concept, I established the musical style and overall rhythm before refining shots and scenes. A video only a few seconds long has limited room, so duration, changes in pace, and transitions needed early decisions. As shots developed, I adjusted the music again.

Set the musical rhythm. Establish a beat and place accents for illumination, expansion, and reassembly.
Plan the shots. Allocate time between close-ups and wider views, choose cameras and movement, and refine the musical timing.
Preview with untextured models. Check pace, framing, and part motion.
Test-render key frames. Use final materials and lighting on representative frames to refine details.
Render the sequence. Export the full frame sequence and combine it with the soundtrack.

Synthesizing the Music

Before creating music, I had a rough set of shots in mind, including the glowing tubes, PCB close-ups, and an exploded assembly. I compared four soundtrack styles, chose one, and continued refining the shots around it.

The agent wrote scripts to generate audio waveforms directly. Sound can be represented as a waveform over time, and simple electronic timbres can be constructed programmatically. Frequency controls pitch, envelopes shape how a sound starts and fades, and noise, filters, and multiple voices can be combined into a rhythmic track.

I settled on a mechanical electronic style at 150 BPM. The script generated drums, bass, short plucked tones, and metallic percussion, then mixed them on a common timeline. As the animation developed, I adjusted their placement. A digit lighting up gets a short cue. The exploded view reduces rhythmic density. Reassembly builds momentum, with a brief pause before the final accent as the complete device lights up.

图 5. Soundtrack voices and the mixed waveform

For a short piece with a clearly defined sound, scripted synthesis is inexpensive and highly controllable. Moving a cue to the instant a part settles or extending a background layer takes a change to timing and envelopes. Waveform generation, mixing, and export happen locally, allowing the soundtrack to evolve alongside the storyboard.

Designing the Shots

The storyboard turns the overall rhythm into individual shots, deciding cuts, slower movements, holds, and actions that coincide with musical accents. I then worked out the content of each scene.

Tube close-ups open with the internal layers, glass, and glow.
PCB close-ups move gently across components to show the two boards' details.
Expansion and reassembly reveal the enclosure and board structure, then return to a complete, illuminated device.

Landscape and portrait versions needed separate camera arrangements. A landscape exploded view can spread parts sideways, while a portrait composition needs more vertical layers. Close-ups also require repositioning the subject because cropping can remove the very detail the shot is meant to show.

图 6. Shot sequence and pacing for the landscape video

Scene Design

The Exploded Assembly

An exploded view reveals structure normally hidden by the enclosure. Shells, boards, the front screen, and fasteners need enough separation to be readable while retaining a clear relationship to their assembled positions. I kept the complete assembly as the starting point and chose expansion directions and distances around the camera.

A spacious static layout still needs a feasible animation path. The upper shell’s two tube openings require it to rise along the tube axes before moving sideways. Screws behind the front board need to travel along their mounting directions, with timing offset slightly from the board’s return. Reflections and shadows can obscure those relationships in a final render, making an untextured preview easier to inspect.

I used those previews to check for obvious intersections, whether the upper shell stayed in frame, and whether each part remained legible at full expansion. Once the motion worked, I restored the finished materials. The sequence expands continuously, pauses briefly, and reassembles, giving the viewer time to understand the structure.

图 7. Untextured exploded view and the matching final render

The Complete Device and Lighting

The closing shot returns to the complete device. Both tubes, the front screen, and the right-hand knob need to be visible, and the black enclosure needs separation from its surroundings. I wanted a dark image in which outlines and surface changes describe the form, with the brightest areas reserved for the glowing digits and screen.

The enclosure uses the matte grain of black PA12S, and the knob has knurling and beveled edges. The screen retains a reflective black surface while off and shows the quota interface when the assembled device lights up. Those material differences give the lights distinct surfaces to reveal.

Lighting changes with expansion and reassembly. At full expansion, the foreground lights reach their set brightness so the interior is visible. Background lightboxes then fade, followed by the wall and floor during reassembly, leaving the finished device against black. Local tube lighting follows the tubes as they move, keeping the glass within its illumination.

The black device needs a clear outline while the glow retains its color. Increasing the brightness of the entire scene makes glass and metal compete for attention. I focused on where light fell and whether reassembly, illumination, and the fading background formed a coherent sequence.

图 8. Scene lighting and the illuminated device

Rendering and Output

Before final rendering, I checked timing and motion with an untextured animation. Comparing several frames from expansion, the hold, and reassembly made it easier to see whether the shell cleared the tubes, parts stayed in frame, and the return sequence worked.

图 9. Untextured animation preview, read left to right and top to bottom

Next came key-frame test renders. I selected representative frames from each scene and rendered them with the intended lighting and materials. Glass reflections, glow color, PCB details, and dark enclosure surfaces all needed inspection. A material can look different as the camera or lights move, so I adjusted it against multiple frames before committing to the complete sequence.

Close-ups emphasize glass and metal, while exploded and whole-device shots must handle more surfaces and darker regions. I used scene-specific sampling and denoising, rendered full frame sequences locally on the GPU with Cycles, and combined them with the music.

Color handling also mattered. Exposure and display transforms influence the saturation of the orange-red glow. The rendered PNGs had already undergone display mapping, so the editing project needed consistent handling to avoid applying another display transform and changing color or contrast.

图 10. Final material close-ups of the tubes, enclosure, and knob

I also used the scenes to produce introduction images for platforms such as Xiaohongshu. Reframing the whole device, selected details, and internal structure for image layouts, with short explanations, provided another way to browse and share the project.

Reflections

What stood out was how smoothly AI participated across the process, and GPT’s current spatial understanding. Refining tube interiors, arranging expansion paths, moving cameras, and positioning lights could all progress through descriptions, previews, and further adjustments.

My role centered on creative direction and visual judgment. The character of the image, details worth emphasizing, shot duration, and balance between reflections and glow all needed decisions. The agent quickly turned those requirements into results I could watch and revise. Repeated comparison and selection brought the image closer to what I had in mind.

- https://hamhire.tech/en/posts/projects/nixie-indicator-presentation.html - Licensed under CC BY-NC-ND 4.0

Nixie Indicator, Part 2 — Giving the Glowing Digits Useful Data

Fri, 06 Nov 2026 20:00:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/projects/nixie-indicator-software.html -

Once both tubes lit up, the device had the appearance I wanted. Turning a pair of glowing digits into something I would glance at every day still required software. The original idea of putting AI to work on its own quota would only come together when the allowance on my computer actually appeared inside the tubes.

This article covers the firmware and desktop companion, including data sources, the meaning of a two-digit display, and how a small screen and one knob bring configuration and everyday use together.

图 1. The same quota on the computer and on the desk, shown schematically

The Data Path

Initially, I wanted the device to speak the ChatGPT desktop application’s native protocol and retrieve quota information itself. For more conventional monitoring, I also wanted Prometheus queries. Once connected to the network, the device could obtain data from either service.

The first attempt proved less convenient than expected. With its default startup configuration, the application only listened on the loopback interface, beyond the reach of an ESP32 on the LAN. The native protocol also introduced long-term uncertainty. Reflashing the device whenever an integration changed would be cumbersome.

I added a desktop companion to decouple collection from display. It calls the application-specific protocol locally, handles connections and queries, and exposes the results as standardized Metrics over the LAN. Native-protocol connections and account-related operations stay on the computer. The ESP32 retrieves configured metrics without understanding each source’s internal protocol.

Changes to an upstream protocol can then be handled in the client’s collector while retaining the metric interface. The device needs no firmware update for those adaptations. CPU load, memory usage, temperature, and game frame rate can use the same path. The device still handles retrieval, validity, and display, with those responsibilities separated from any particular application.

The final design supports two ways to connect.

Direct Metrics access. Read values from the desktop companion or another exporter, suitable for displaying current values.
Prometheus. Query an existing monitoring service for historical trends and server-side calculations as well as current values.

The desktop companion is one data source, and the device remains a general-purpose metric display. An existing monitoring service can supply it independently. Direct access also works without deploying Prometheus.

图 2. A metric’s journey through direct access or Prometheus

Firmware Design and Implementation

Choosing the Framework

As in the hardware work, Codex and I used incremental, spec-driven development. We documented responsibilities, interfaces, and constraints before implementing and validating each stage, and recorded subsequent changes in the design documents. The basic stack consists of the following components.

PlatformIO and ESP-IDF organize the project, build firmware, and provide networking and peripheral support.
LVGL and esp_lvgl_port handle widgets, menus, and screen updates.
esp_lcd and SPI DMA connect rendering to the physical LCD.
NVS stores network settings, metric rules, and display preferences. Live values and temporary state stay in memory.
Wokwi provides firmware simulation for early display and input checks.

I had mainly used Arduino in earlier projects. AI substantially reduced the work of establishing and maintaining the project framework, making it easier to switch to ESP-IDF and gain finer control over tasks, peripherals, and low-level configuration.

Firmware tasks run on the FreeRTOS integrated into ESP-IDF. I organized the architecture around separate domains, first defining responsibilities, state ownership, and public interfaces, then arranging their interactions.

Networking collects data and supports remote access and management.
Device control accepts values and requests and determines hardware output centrally.
User interaction displays metrics and device state and forwards user actions to the control side.

Explicit interfaces keep changes focused when adding pages or integrating data sources.

图 3. Firmware domains and their supporting layers

I covered the main logic with unit tests, used simulation to check interaction and the data path, and moved to hardware testing once the end-to-end flow broadly worked.

GUI and Menu Interaction

The first firmware design questions concerned the GUI and system menu. What should be visible every day, where should settings live, and how should navigation work? I used LVGL to draw the LCD interface and organized pages around those usage scenarios.

LVGL handles interface composition and rendering. The main metric, trend chart, and system menu are separate views. Menu rows, focus outlines, and status icons reuse common components so that visual changes and interaction feedback remain consistent.

Between the GUI and the screen, esp_lvgl_port and esp_lcd coordinate rendering with SPI DMA pixel transfers. LVGL produces regions to refresh, the driver submits transfers, and completion signals let the interface reuse the buffers. Coordinating drawing and transmission became an important part of the screen implementation.

The knob handles everyday metric selection, brightness adjustment, and self-tests. Requests go through a common control layer, and values retrieved over the network use the same output path.

图 4. Browsing metrics, entering the menu, and selecting a primary metric

During acceptance checks, I considered whether the interaction matched familiar devices, alongside layout, information hierarchy, and appearance, then refined it through use.

Character coverage and language support

Alongside Chinese and English, we added Japanese and German. An embedded display needs its glyphs packaged in the firmware, so translating strings covers only part of the work. Noto Sans fonts were converted into LVGL font data. Japanese requires the appropriate glyphs, while long German words require layout checks.

Custom metric titles need their own character coverage. We extracted characters from core, general, and industry-specific Chinese and Japanese metric vocabularies, then added letters, numbers, units, and required symbols.

Fonts occupy a substantial share of the firmware, especially when Chinese and Japanese glyphs are combined with multiple sizes. Fixed UI strings use subsets of the characters actually needed. Custom titles draw on the vocabulary lists. Large sizes retain only digits and essential symbols, and some Chinese and Japanese fonts use lossless compression. Character coverage, type size, and readability need to be balanced to leave room for other features and updates.

The Japanese menu

Controlling the Tubes

Part 1 described the mapping between digits and physical tube pins. Firmware uses that mapping to generate serial data on a dedicated SPI bus, while PWM on BLANK controls brightness. The LCD uses a separate SPI bus so that large screen transfers do not occupy the tube-update bus.

Metric values can remain unchanged for long periods. The firmware therefore cycles through the cathodes once an hour and also provides display rest and a digit-by-digit self-test.

Tube maintenance and cathode poisoning

Each digit is a separate cathode. During discharge, ion bombardment causes sputtering and material loss on the active cathode. Released material can deposit on other cathodes. When only a few digits are used for long periods, deposits on less frequently lit cathodes can interfere with discharge and produce partially unlit digits or incomplete strokes, a condition known as cathode poisoning.

Periodically lighting every digit is a common preventive measure and the reason for the hourly cycling routine.

Dalibor Farny’s tube-maintenance documentation

The tubes show a two-digit integer from 00 to 99. The LCD supplies the complete value, name, unit, and status. Fractional values are converted to integers, and out-of-range values are limited to the two-digit display range. The original value remains on the LCD.

图 5. Value handling on the tubes and LCD

Failure to retrieve data must remain distinct from a zero value. For quota display, a temporarily unreachable service and an exhausted allowance require different states. An old value may be retained within the rule’s allowed interval, but its status must show that it has become stale.

Wi-Fi Setup

Provisioning uses a conventional SoftAP flow. The device opens a temporary hotspot, a phone connects and submits home Wi-Fi credentials through a web page, and the device joins the target network. The LCD provides the setup entry point and status.

图 6. Moving from the temporary hotspot to home Wi-Fi

After a successful connection, the device saves the configuration and stops the hotspot. The phone rejoins the same Wi-Fi and opens the management page at the device’s new address. Failed attempts can be retried after correcting the settings. Routine disconnections trigger automatic reconnection, and changing networks starts provisioning again from the menu.

图 7. Connecting to the hotspot, entering Wi-Fi credentials, and completing setup

Firmware Updates

With network access available, I included OTA updates so that new firmware could be uploaded through a browser or the desktop app. The current flow selects a local file and uploads it over the LAN. USB flashing remains available for maintenance.

The design uses two application slots in flash. One runs the current firmware and the other receives the new image. The current version stays intact while the alternate slot is written and validated. Only then does the boot target change. An interrupted transfer or failed validation leaves the original version available.

On its first boot, the new firmware checks basic functions such as storage, control tasks, and the GUI before confirming the version. A failed trial boot uses the rollback mechanism to return to the valid older image. After confirmation, the slots exchange roles and the next update writes to the other slot. Reserving room for two images adds a practical constraint to the font-size budget discussed earlier.

图 8. Updating and rolling back with two application slots

Possible OTA extensions

The desktop companion could later check releases, show release notes, and download matching firmware before passing it to the existing upload flow. The device could also fetch firmware from an update service, with signature verification and stable or testing channels. Those remain future extensions. The current focus is LAN updates.

Remote Management and the Desktop Companion

Web Management

Once on the LAN, the device provides a web interface for settings that are awkward to edit on a small screen. Page assets ship with the firmware and are accessible through the device address. A browser authorization request must be approved on the device before management access is granted.

The interface handles display preferences, data sources, firmware uploads, and PromQL configuration with result previews. A common management API carries the requests, while the device owns the configuration rules. The desktop companion reuses that API to keep the two entry points consistent.

The metric page places settings beside the preview. PromQL, display name, unit, and chart style are configured on the left. The current value and historical trend appear on the right. Editing a query and checking its result together makes it easier to verify that the intended information is being collected.

图 9. Metric configuration and query preview in the browser

Desktop Implementation

The companion focuses on collector configuration and quick device management, using Tauri 2, Rust, and TypeScript. The UI handles configuration and inspection. A Rust backend collects data, serves Metrics, and connects to the device. Collection runs separately from the window, allowing the tray application to continue working after the window closes.

Each source appears as a separate card, with its enable switch, collection state, and current values.

System information covers CPU and memory usage.
Hardware monitoring covers GPU load, graphics memory, and available temperature sensors.
FPS collection follows the foreground application’s frame rate.
Codex observation, currently labeled Beta, retrieves local quota information.

Returning to the original purpose, the Codex collector reads the quota on the computer and exports a remaining percentage for the returned quota window. The device consumes an ordinary metric. Application-protocol and account-related handling remain in the client. The displayed value is the remaining proportion of a quota window, rather than an exact token-by-token balance.

After pairing, the app lets me choose metrics from the local results, reorder them, select the primary metric, preview retrieval, and open device settings or firmware updates. Local collection settings and device settings are stored separately, with both available from the client.

图 10. Collector configuration and quick device management

Adding data sources

A new source can have an independent collector module that feeds the common scheduler and Metrics endpoint. Protocol adaptations stay within that module while reusing the device’s existing display path.

The device can independently connect to other Metrics services or Prometheus for different hardware and monitoring scenarios.

Party Mode

The tubes can also be a small desktop toy. I added a “party mode” to the companion with simple random-number, countdown, and manual-value controls.

Digital dice. Set the range to 1–6 and watch the numbers change rapidly, slow down, and stop on the result. Other ranges work for drawing lots or guessing games.
Timed challenges. A glowing countdown adds a little pressure to a board game or short challenge.
Score display. Submit a number manually to show the current score.

The modes share the same number-sequence playback capability. The client prepares the numbers and timing, and the device plays them. Leaving party mode restores the regular metric display. The device gains a way for friends to participate beyond simply glancing at a value.

图 11. Bringing the glowing digits to the game table

Reflections

Software engineering is a capability LLMs have been improving for years. In this project, AI could handle a fairly complete implementation across the firmware and desktop app. It made me consider where a designer’s attention should go as the cost of writing code falls.

Human involvement increasingly centers on design decisions and engineering standards. The split between client and device, domain boundaries, and ownership of state all affect future maintenance. The DRY principle also matters. Shared business rules need a common implementation so that similar features do not gradually diverge. Naming, interfaces, error handling, and testing need consistent requirements through each iteration and acceptance check.

That is the value of documenting boundaries and agreements first, implementing incrementally, and recording validated changes. As code generation becomes easier, explicit rules become more important for engineering consistency. Adding feature after feature without that discipline can accumulate locally functional implementations and defer the maintenance cost.

Low-level SDK adaptation, toolchain configuration, and environment setup can now also be delegated to the agent. Trying an unfamiliar framework costs less effort, allowing choices to follow the project’s needs more closely. My move from Arduino to ESP-IDF reflects that change. The saved effort can go toward architectural trade-offs, interaction, and acceptance testing, making it more feasible for one person to maintain firmware, a web interface, and a desktop companion together.

The rhythm of hobby development has changed as well. Previously, a project could consume my full attention throughout my spare time, from the idea to detailed implementation. Now I spend more time considering options, expressing requirements, and checking results. While the agent writes code or runs tests, I can watch a video and return when it has something to discuss. The project still needs sustained attention, but using fragments of spare time has become easier.

图 12. From design decisions to agent execution

The companion article covers turning the hardware project into a polished presentation video and producing introduction images.

- https://hamhire.tech/en/posts/projects/nixie-indicator-software.html - Licensed under CC BY-NC-ND 4.0

Nixie Indicator, Part 1 — Turning an Idea into Hardware with AI

Thu, 05 Nov 2026 20:00:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/projects/nixie-indicator-hardware.html -

It had been a while since I last built something new. I recently remembered the Nixie displays in Metro 2033, which I played years ago. Their Cold War-era, Soviet clock-shop aesthetic left a lasting impression. The glowing digits inside glass tubes have a distinctive character, and I had wanted to make a Nixie device of my own ever since.

A series of Codex usage-limit resets gave me an opportunity to start. The PCB design demonstration released with GPT 6 Astra in September 2026 had also stuck with me. I decided to try building a small desktop device that would use Nixie tubes to display my remaining token allowance, and see how far AI could take a hardware idea toward a physical object. Spending spare AI quota to build a quota display seemed fitting, putting AI to work on its own allowance.

Before starting, I set one rule for the project.

I would make every change to the design files by describing what I wanted to the agent.

As the human in the loop, I would define requirements, choose between options, inspect the results, and validate the assembled hardware. Feedback from each stage would guide the next round.

I called the project Nixie Indicator. This first article covers the circuits, PCB, enclosure, and hardware bring-up. Firmware, the desktop companion, and the presentation video follow in the next two articles.

Your browser does not support the video tag.

Choosing the Design

Codex and I worked incrementally, using spec-driven development. I started with rough notes on the idea and candidate approaches, then wrote a project overview and roadmap covering the goals, modules, and order of work. We refined the design in stages, recording agreed interfaces and constraints in formal design documents. Updating those documents alongside the implementation gradually gave the project an organized engineering context.

To help the agent understand my development and project-management habits, I also gave it my earlier custom keyboard and Techno Keyer projects as references. Providing existing projects was an important way to shape its context. Concrete examples communicated my preferred organization and design conventions and reduced repeated explanations.

The main components gradually settled into place.

Nixie tubes. Two DGM01 tubes provide the two-digit display.
MCU. An ESP32-S3, which I had used in several other projects, retrieves data over Wi-Fi.
LCD. A small screen provides metric names, units, status, and settings. The idea came from the CWO networked Morse-code desk device I had bought from its maker, Xifengzui.
USB-C. One connector handles both 5 V power and firmware flashing.
Rotary encoder. A side-mounted knob handles selection and confirmation.

I chose DGM01 tubes after watching Sadudu revive Nixie-tube manufacturing in China by making them himself. I admired the work and wanted to use his tubes in my own project.

Sadudu’s Nixie-tube manufacturing video

I split the main electronics into two stacked boards for three reasons.

Separate the high- and low-voltage areas. The display board contains the high-voltage supply and Nixie drivers. The control board holds the MCU, USB interface, and low-voltage supply.
Reduce the desktop footprint. Stacking the boards saves horizontal space.
Allow future variants. A different display board could accommodate tubes such as the Soviet IN-18 while reusing as much of the control board as possible.

The upper display board carries the two tubes. Two sets of headers connect it to the lower control board for low-voltage power and control signals. The LCD sits vertically on a separate front board.

图 1. Exploded board assembly, with the display board above the control and LCD boards

Circuit Design

Power Supply

I settled on a single 5 V USB-C input. One branch feeds an AMS1117-3.3 regulator for the MCU, display logic, and LCD. The other passes through a controlled switch to an off-the-shelf high-voltage module on the display board.

The high-voltage module is the XGGF-HV-tiny from Acorn Workshop, a supplier recommended by Sadudu. I designed the downstream circuits around its nominal output of approximately 170 V, concentrating on the interface, enable control, and mounting space. Startup behavior and operation with both tubes connected would be checked on the actual hardware.

The low-voltage input switch, module enable, and display blanking are controlled separately. Startup follows this sequence.

Keep the outputs blanked while preparing the display data.
Switch on the low-voltage input branch, then enable the high-voltage module.
Release blanking to display the digits.

The boards share a common ground. Their physical separation provides no electrical isolation. I included a separate discharge path for the high-voltage supply and enclosed the pins and solder joints. Residual voltage can remain after the display goes dark and needs to be measured separately.

图 2. Control-board power schematic, including USB input, 3.3 V regulation, and the high-voltage module input switch

Driving the Nixie Tubes

The two tubes have twenty digit cathodes in total. Three 74HC595 shift registers expand the outputs, and twenty MMBTA42 high-voltage transistors switch the individual cathodes. Each tube has its own anode current-limiting resistor.

The ESP32 sends serial data and latches the outputs together. Four of the twenty-four available shift-register outputs are unused. Normal operation selects one digit per tube.

Brightness is controlled by PWM on the shared blanking signal. The final frequency was chosen by comparing results on the assembled board.

图 3. Serial data, latching, and PWM brightness control, shown schematically

PCB Design

I started with component placement, establishing functional areas, positions, and assembly relationships before routing. Getting the overall arrangement right made the connections easier to plan and reduced the need to move large groups of components during routing.

Component Placement

The first layouts quickly showed that functional requirements and connectivity were insufficient on their own. The agent’s initial placement was fairly arbitrary. I had to specify grid alignment, functional grouping, proximity between related components, and space between modules.

After a round or two, the placement began to meet my expectations. Decoupling capacitors, interface protection, and driver resistors needed to sit near their associated connections. I also asked the agent to place equivalent driver transistors according to the actual tube pin positions, then revise the schematic channel assignments to suit their positions relative to the 74HC595s. The wiring could follow the physical layout, with firmware generating display data using the final mapping.

The stacked structure introduced another set of constraints. Both main boards face upward, so components on top of the control board face components on the underside of the display board. An apparently empty area in a two-dimensional layout could sit directly below a high-voltage module or connector in the assembled device. Tube centers, inter-board connectors, and mounting holes also had to stay aligned across the boards.

图 4. Component placement on the control board and the underside of the display board

Routing Iterations

Routing was substantially more complex than placement and took more time. I saw plenty of awkward traces and changes that solved one problem while creating another. A route could look reasonable locally and still fit poorly into the board as a whole. I gradually stopped expecting a perfect first pass. Words like “reasonable,” “tidy,” and “compact” were insufficient. I needed to inspect the board, identify specific problems, and iterate with Codex.

The first scripts focused on individual connections. The overall layout included unnecessary detours, unexpected right angles and acute corners, and other awkward paths. A round took roughly half an hour, with considerable token consumption. I could watch my Pro 100 weekly allowance slowly falling as the iterations continued.

图 5. The first complete routing pass and the final display-board layout

KiCad’s text-based project files let an agent read and modify component coordinates, nets, and traces. We gradually established a repeatable process.

Read. Use project files and design documents to understand placement and routing constraints.

Modify. Adjust component positions and generate routing paths with Python scripts.

Check. Run rule checks and export images for my review before continuing.

Routing became a geometry and path-planning problem, reducing the amount of individual clicking and dragging in the GUI.

I recorded recurring issues as explicit routing rules.

Keep related traces parallel where possible, with consistent bends and fewer short fragments or pointless reversals.
Prefer same-layer connections and avoid repeated vias merely to shorten a local route.
Apply the appropriate constraints to high-voltage nets, power, and ordinary signals. Convenient connectivity should never depend on indiscriminately reducing trace widths or clearances.

Another effective change was to work in stages on local areas. Finishing one group of related components and connections before routing shared signals and power was easier to control than repeatedly revising the whole board. Confirmed areas were retained where possible, and each new change was checked for its effect on existing connections and return paths.

According to my rough notes, it took about ten rounds for routing to approach the intended result. Script execution and automated visual checks eventually fell below ten minutes per round. I still inspected the paths and assembly relationships, while recurring rules were incorporated into the scripts for subsequent iterations.

KiCad’s design rule checking (DRC) was valuable throughout. Explicit trace-width and clearance requirements, checked after each round, exposed unconnected nets and routing violations introduced by the agent and constrained unintended changes.

I also checked the two boards together, including connector alignment and mounting positions, and kept components and metal structures on the opposite board clear of high-voltage areas. The side-mounted encoder affected the upper board as well. Its installed height and position required an edge cutout, followed by adjustments to nearby components and traces.

Enclosure and Assembly Design

Once the PCBs took shape, I used a three-dimensional assembly to check component heights, connector fit, and assembly clearances. Interference that was difficult to see in two dimensions became much clearer. Uncertain bends and fit allowances still needed confirmation with real parts.

Many common components can reuse the 3D models supplied with KiCad footprints. For unusual parts such as Nixie tubes, supplying the necessary datasheets and dimensions was enough for the agent to produce models that worked surprisingly well.

Board dimensions and spacing evolved during layout and assembly design. I wanted a compact device with enough room for components and connectors between the boards. The tubes sit on top, the screen faces forward, USB faces backward, and the knob projects from the right side. The resulting enclosure is 3D-printed in black PA12S. The upper shell includes the complete front frame, while the lower shell wraps around the bottom, sides, and rear.

I wanted a seamless front and no exposed top fasteners. The board assembly therefore mounts inside the upper shell, with enclosure seams along the sides, rear, and underside.

图 6. Enclosure section and interior views of the upper and lower shells

I worked through the fasteners layer by layer using section views. Mounting posts inside the upper shell contain heat-set inserts. Short screws secure the front of the display board, while brass standoffs clamp the rear, creating four suspension points. The rear standoffs also maintain the board spacing and accept the lower-shell screws at their lower ends. The board mounting and lower-shell attachment are independent, so removing the lower shell leaves the upper shell and electronics together.

I then checked screw engagement through each layer, clearance to blind-hole bottoms, and tool access. Reinforcement at the mounting-post roots also had to leave a clear insertion path for the lower shell. Section views let me evaluate those relationships together.

For example, the inter-board connectors and front-board cable can remain connected during enclosure removal, but the projecting encoder restricts how the lower shell can move. After removing the knob and external retaining hardware, the lower shell needs a slight tilt and translation to clear the shaft, rear USB connector, and support posts. Assembly design needs to cover insertion and removal as well as the final fit.

图 7. Board suspension, with rear clamping and independent front display-board mounts

With design documents and assembly models available, having the agent produce an assembly manual was straightforward. Fastener relationships, assembly order, and precautions already had a documented basis. Model views turned those decisions into illustrated instructions. The same models later supported the presentation video, whose materials and camera work are covered in the companion article.

Assembly and Bring-up

JLCPCB manufactured the boards and assembled the basic components. After delivery, I hand-soldered the remaining parts and fitted the Nixie pin sockets. My first check was for shorts with a multimeter. I then tested the modules progressively before assembling the high-voltage display board, tubes, and other main parts for full-device bring-up.

An unexpected issue during dimming

After the tubes were working, I noticed a faint noise at some brightness settings and compared several PWM frequencies. Overall, 500 Hz worked best. The noise became noticeably quieter at 100% brightness.

At 5 kHz it became more obvious. At 16 kHz the noise disappeared, but brightness control became much less effective. At 25 kHz dimming clearly failed. I kept 500 Hz. The exact source of the noise has yet to be confirmed by measurement.

图 8. Illustration of the powered board assembly

Reflections

The project showed me how far AI’s hardware engineering capabilities have progressed. PCB design still required repeated refinement, especially routing. Connectivity was only the beginning, and tidy paths and practical assembly took further work. Given clear requirements, specifications, and rule checks, the agent could nevertheless perform a substantial amount of detailed design.

Its three-dimensional understanding surprised me even more. Datasheet dimensions were enough to create usable models for simple parts. Enclosure splits, board suspension, and assembly clearances could all be developed through discussion. Based on this project, I feel its spatial understanding and modeling already exceed those of most people. The progression from dimensions to models and then to relationships between parts was more mature than I expected.

In this collaboration, AI increasingly felt like an extension of my hands. An octopus can coordinate its arms through higher-level intent without directing every movement individually. Likewise, I could express a design intention and have the agent carry out the detailed operations. My preferences and aesthetic judgment still shaped the result. I remained involved through requirements, inspection, and physical testing, even though every file change went through the agent.

AI brought a substantial productivity improvement to this kind of hardware project. Previously, similar work could occupy weeks of personal time, starting with simulation and verification and progressing through gradual refinement. Now, two or three concentrated days, plus sustained token consumption, can potentially bring the main design to a manufacturable stage. Simulation, checks, and physical verification remain necessary, while drawing, modeling, and repeated revisions take much less time. An idea that starts in spare time has a better chance of becoming a physical device.

Part 2 covers firmware and the desktop companion, including how the device retrieves quota information and turns it into glowing digits.

- https://hamhire.tech/en/posts/projects/nixie-indicator-hardware.html - Licensed under CC BY-NC-ND 4.0

My Homelab, Part 4 — Putting AI Ops into Practice

Thu, 15 Oct 2026 20:00:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/homelab/ai-devops-practice.html -

Years of building and maintaining my Homelab have gradually produced infrastructure spanning local systems and cloud services, along with reasonably standardized maintenance procedures. Environment documentation, configuration management, change execution, and acceptance checks now have a documented basis.

The current approach draws on my years of experience operating SaaS systems.

Declarative configuration and GitOps manage desired state. Monitoring and alerts reveal actual behavior. SOPs record pre-change checks, execution steps, and recovery procedures. I adapted those practices to the scale and maintenance budget of my personal environment.

The diagram below summarizes the infrastructure layers and the engineering governance and observability that span them.

图 1. Infrastructure layers and the practices that span them

The main difficulty in long-term maintenance is the sustained attention it requires, concentrated in several areas.

Every layer needs regular maintenance. Proxmox VE, Ceph, Kubernetes, and the services running on them all need upgrades, compatibility checks, and configuration changes.
Each upgrade needs its own research. Release notes must be read, breaking changes identified, and possible effects on configurations, data, and services assessed before choosing an upgrade path.
Execution and troubleshooting take effort. My deployments have custom settings that can behave differently from standard environments. Diagnosis needs the actual configuration, logs, and runtime state, followed by verification of the fix.

I used to set aside several days of leave each year to maintain the whole environment. Researching versions and upgrade paths, executing changes, observing the results, and handling failures generally required continuous involvement. Standards reduced repeated investigation, but execution and verification still consumed attention.

As AI improved at understanding code, planning tasks, and using tools, I began considering how much more maintenance I could delegate to an agent. Production decisions still require human judgment about business impact. My own Homelab gives me room to experiment, provided I have cold backups of important data and clear recovery paths. The agent can perform more of the actual work while I retain key decisions and acceptance checks.

This article focuses on engineering discipline and context management, sharing how I helped an agent understand an existing environment and participate in maintenance, along with the problems and experience that followed.

Context Management and Engineering Practices

Before introducing an agent, I already had a fairly complete declarative Git repository, with Kustomize and Argo CD managing service deployments. It also contained many scripts for physical machines and VMs, covering initialization, configuration, and routine maintenance. Those accumulated configurations and scripts gave AI a starting point for reading the environment, preparing changes, and reusing operating procedures.

图 2. A maintained cycle between actual configuration and operational work

Maintaining Context Documents

Context is grounded in the current environment’s actual configuration. It records resource relationships, operating conditions, and decision background, and evolves with deployment changes. I use a few maintenance rules.

Record evidence and scope. Document configuration sources, script prerequisites, and acceptance criteria. Mark unconfirmed information for verification before applying old procedures to the current environment.
Update documents with changes. After deployment and verification, record versions, topology, configuration differences, and operating procedures.
Centralize shared conventions. AGENTS.md defines directory responsibilities, authorization boundaries, and verification requirements. Domain-specific documents hold environment details.

Environment documents are organized by responsibility.

Domain	Directory	Responsibilities
Network	`docs/network/`	Device roles, topology, subnets, and connections
Virtualization	`docs/hypervisor/`	Hosts, VM placement, resource allocation, and lifecycle
Storage	`docs/storage/`	Clusters, disks, data placement, and mounts
Kubernetes	`docs/kubernetes/`	Cluster composition, dependencies, maintenance, and troubleshooting evidence
Cloud resources	`docs/cloud/`	Cloud hosts, managed services, domains, and access relationships

The documents also preserve context absent from configuration files, such as reasons for customizations, areas maintained manually, and recovery conditions.

Declarative Kubernetes Management

I generally use Kustomize for services I deploy myself, retaining flexibility over configuration. Directories group services by responsibility. Single-component services remain flat, while multi-component services split where needed.

.
├── apps/
│   └── <group>/
│       └── app.<service>.yml    # Application points to the service entry
└── kubernetes/
    └── <group>/
        ├── <single-component-service>/
        │   ├── kustomization.yml  # Resources, namespace, and images
        │   ├── deploy.yml         # Workload
        │   ├── service.yml        # Service access
        │   └── config/            # ConfigMap generator input files
        └── <multi-component-service>/
            ├── kustomization.yml  # Aggregate components and shared settings
            ├── <component-one>/
            │   ├── kustomization.yml
            │   ├── deploy.yml
            │   └── service.yml
            └── <component-two>/
                ├── kustomization.yml
                ├── statefulset.yml
                └── pvc.yml

Matching groups. apps/ and kubernetes/ use the same responsibility groups. Each Application’s source.path points to the directory containing the service’s kustomization.yml.
Flat by default. A single-component service keeps its resources in one directory, adding routes, certificates, storage, or permissions as needed.
Split by component. Independently describable components get their own subdirectories. The parent aggregates them and maintains shared settings.
Separate manifests from configuration content. Resource files describe deployment structure. config/ holds files used by configMapGenerator, whose output the workload references.

Clear entry points and hierarchy help the agent locate the change scope, inspect rendered manifests, and extend the existing structure with less duplication and scattered configuration.

Accessing the Environment Through Tools

For potentially risky operations, my principle is to use mature tools with explicit rules and auditable execution. I keep direct environmental access behind those tools, which constrain entry points and scope and retain execution records. The agent invokes them within granted authorization.

图 3. Authorized tool access, with sensitive keys retained by the tool

Repository access lets an agent read configuration, prepare patches, and draft plans. Actual maintenance also requires visibility into runtime state and authorized access to nodes.

I manage physical-node and VM SSH connections centrally through XPipe and expose remote operations to the agent through MCP. Connections initially used to inspect configuration and build context also support later authorized maintenance. The agent can check settings, execute commands, and collect results through those tools.

Authorization boundaries and key isolation

Central key management. XPipe retains sensitive SSH keys. The agent can operate without handling private keys or placing them in project files or conversation context.

Authorized operations. The agent uses approved connections. Configuration inspection and changes receive separate authorization, and connectivity alone grants no blanket permission to modify resources.

Human confirmation for critical actions. Operations involving persistent data, node destruction, or other irreversible changes need an explicit target, impact assessment, and recovery arrangements before execution.

With tools connected, the workflow becomes reading documentation and current state, listing the plan and impact, confirming it, executing in stages, and collecting acceptance evidence. When assumptions fail, the plan needs revision before continuing.

Documenting Previously Unrecorded Configuration

My earlier environment documentation was sparse, mostly because I had put it off. It was my own Homelab, and its complexity was manageable. I knew the purpose of subnets and VLANs, routing and access boundaries, service locations, entry points, and storage dependencies well enough to keep much of it in my head.

Once AI became involved, I granted the necessary configuration-reading access through tools. For routers and switches, I exported configuration backups and asked the agent to organize networks, routes, and access rules. It combined those with the declarative repository to document service access, deployments, and storage dependencies. I checked the results and supplied background.

Using AI to prepare environment documentation was much easier than I expected. Router and switch backups were particularly effective. The agent could connect facts spread across interfaces, VLANs, routes, and access rules. Workload, Service, ingress, and storage manifests similarly revealed access paths and dependencies. Documentation finally stopped feeling like a task that required saving up energy for a dedicated session.

I added explanations absent from the configuration, including the reasons for network divisions, access boundaries, and customizations. Combining configuration facts with human context allowed the documentation to explain both operation and intent. Credentials stay outside the general context.

图 4. Configuration facts and human design notes become environment documentation

Archiving and removing obsolete material

Historical material provides traceability and reference. Current operating instructions require current evidence.

Retired devices, invalid settings, and old procedures need separate archives to avoid contaminating current context and leading the agent to incorrect conclusions or actions. Historical references should be checked against present conditions before use.

Material fully superseded by current documentation, with no remaining reference or traceability value, can be removed to reduce redundant context.

AI Ops in Practice

After establishing the initial context, I delegated several routine tasks to see how much research, execution, and troubleshooting the agent could handle. They included Kubernetes upgrades, declarative Grafana management, and GitLab and Argo CD upgrades. The first two cases are covered below, followed by VM and shared-script practices.

图 5. Operational work and maintained context reinforce one another

Upgrading Kubernetes Across Minor Versions

The cluster had gone nearly two years without systematic upgrade maintenance. Kubernetes evolves quickly, while a kubeadm environment still requires research into version changes, supporting-component adjustments, node upgrades, and verification. I decided to try delegating this upgrade to AI.

The work progressed from 1.32 to 1.36 one minor version at a time and included replacing the node operating systems.

I first asked the agent to read environment documents, maintenance scripts, and cluster state and prepare a plan. The aim was to connect research, compatibility assessment, risk identification, and execution. I reviewed the plan and made key decisions.

Inventory the environment and research releases. Check Kubernetes, the container runtime, networking, and storage components. Read target-version notes and identify breaking changes and required adaptations.
Check compatibility and plan the route. Determine which supporting components need upgrades first, then sequence control-plane, worker, and OS changes. Follow the official kubeadm upgrade documentation for minor-version steps.
Identify risks and confirm the plan. The agent collects possible outages, configuration changes, and recovery arrangements. I choose the maintenance window, acceptable impact, and recovery points for my Homelab.
Execute through authorized tools. Adapt supporting components and upgrade nodes in stages, collecting results. Unexpected behavior calls for diagnosis using configuration and logs before revising later steps.
Verify before advancing. Check nodes and real workloads after each upgrade, test new Pods' networking and storage mounts, and verify reboot behavior after OS replacement. Record changes and conclusions before moving to the next release.

图 6. Upgrade stages and human decision points

Working with AI during OS replacement

Before starting the new systems, I had the agent adapt a complete set of maintenance scripts from previous deployments. Existing procedures were reusable, with dependencies and configuration differences checked for the new OS.

I then created blank VMs from a template and authorized their SSH connections through XPipe. The agent used the documented context and scripts to initialize the systems, install dependencies, and join nodes. I supplied the system entry points, while sensitive keys stayed in the tool.

My Homelab can tolerate brief interruptions during maintenance, so some choices reflected the cost of maintaining a personal environment. I remained involved in outage decisions and exception handling.

The biggest change was being able to step away from the terminal. The agent could turn research into operations, then inspect results and troubleshoot. I mainly reviewed plans and confirmed key stages. According to my notes, the main upgrade work took about a day, excluding preparation of the documentation.

Declarative Observability Management

I started the second case with Grafana. The old version’s dashboards were mostly edited in the UI and stored in the database, outside the project’s context. I opened them when needed and added panels, but rarely documented why metrics were chosen, how dashboards should be organized, or what remained to improve.

After upgrading, I tried bringing existing dashboards into declarative management with Git Sync.

Git Sync connects Grafana dashboards to Git

Git Sync synchronizes dashboards and folders with Git, supporting UI editing and repository JSON files. Configuration previously confined to the database becomes something the agent can read, compare, and modify, with design notes maintained alongside it. Collection settings and alert rules remain in their respective declarative deployments.

I asked AI to reassess the dashboards against the actual environment, distinguishing upstream content from local adaptations and identifying the needs of networks, hosts, storage, and services. It located configuration, compared content, and prepared changes. I supplied usage habits and design intentions, then we decided which information to retain and which monitoring gaps to address.

The scope expanded to metric collection and alert rules. I also involved AI in organizing, writing, and maintaining rules across the Homelab. Examples include checking collection coverage against device and service responsibilities, organizing host, storage, certificate, and availability rules, and making alert severity and notification wording consistent.

With dashboards in Git Sync and collection and alerting in declarative manifests, the agent can follow relationships from targets to metrics, panels, and alerts. I mainly confirm whether an alert deserves attention, whether its conditions match actual use, and whether deployment produces the intended result.

Being able to organize the observability design as a whole mattered more than bulk JSON edits. Configuration relationships, design notes, and improvements I had lacked time to address now have a maintained home. New services and network changes can draw on that context to extend monitoring and alerts together.

图 7. An agent handles repeated work across dashboards, collection, and alerts

VM Management and Shared Scripts

I traditionally kept deployment and maintenance scripts in scripts/. OS initialization, network setup, disk expansion, runtime installation, and monitoring integration gradually accumulated reusable procedures.

Managing scripts as part of the project brings several benefits.

Traceability and review. Git preserves changes and their reasons. Script diffs can be checked before execution.
Reuse. The agent can compare scripts with actual settings, extract shared steps, and express node differences such as addresses, interfaces, and disks as explicit parameters.
Iteration. OS and deployment changes can adapt existing scripts, with troubleshooting conclusions and verification results recorded for future work.

AI helps compare, extract, and update scripts. I review critical changes before authorized execution. Each task leaves scripts and explanations that become usable context for the next.

Reflections

For me, AI has become something like an extension of my hands, taking on many tedious tasks previously handled manually. Research, configuration comparisons, repeated operations, and troubleshooting require less continuous attention. I mainly contribute design discussions, plan approval, and acceptance checks. Execution may take just as long, but being able to step away from the terminal already makes a substantial difference in a personal Homelab.

The experience strengthened a few priorities.

Reduce continuous supervision, leaving more attention for design and important decisions.
Use engineering practices and maintained context as the foundation, keeping configuration, documentation, and scripts synchronized.
Accumulate operational experience, recording changes and troubleshooting results for subsequent tasks.

I still decide whether an outage is acceptable, which upgrade route to take, and whether to continue after unexpected results. I can also spend more time and energy exploring new projects.

- https://hamhire.tech/en/posts/homelab/ai-devops-practice.html - Licensed under CC BY-NC-ND 4.0

Code Meeseeks — Building an AI Code Review Tool for the Reviewer

Fri, 31 Jul 2026 20:00:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/projects/code-meeseeks.html -

As AI-generated code became more common in my work, the amount of code needing review grew too. Code review took increasing time and effort. Each review still required understanding the background, tracing the affected modules, and deciding whether the implementation made sense.

To reduce that burden, I tried building a desktop tool with Claude and named it Code Meeseeks. Based on the open-source PR-Agent, it brings pending PRs, code reading, AI analysis, follow-up questions, and comment drafts into one client. The project is open source and has had a small trial within my team.

The name comes from Mr. Meeseeks in Rick and Morty, summoned to help complete a specific task. That seemed fitting for a review assistant.

Source code is on GitHub, with installation and usage information on the project website.

Breaking Down the Requirements

Internal teams, open-source communities, and commercial vendors already offer many team-oriented review tools. I also wanted a tool for the individual reviewer, helping me understand and verify each change. Several needs shaped it.

🔍 Build context for the reviewer

A substantial part of manual review happens before judging an issue. A complex PR in a complex project requires understanding the author’s goal, relationships between changes, and effects on existing behavior. Larger changes increase that reading and verification work.

Reviewers have different familiarity with projects and modules. Familiar code can draw on memory. Unfamiliar modules require following implementations and call relationships. Team-level tools struggle to explain each change at the level each reviewer needs. I wanted explanations that could follow my own progress and build context gradually.

🎯 Retain personal review priorities

Reviewers focus on different concerns, including business correctness, edge cases, error handling, performance, and compatibility. I wanted to state my priorities and direct analysis toward them.

Rule preferences also need adjustment, including code quality, module responsibilities, design style, and project conventions. I wanted to maintain those requirements and match them by repository, combining project standards with my own focus.

💳 Reuse AI subscription allowances

I wanted to use existing AI subscriptions, for example by running reviews through an installed, authenticated Codex CLI or Claude Code. Reusing those accounts and allowances could reduce the additional cost of model APIs.

Model integration therefore needed local CLI support alongside common model APIs and compatible endpoints, leaving a choice based on available tools and accounts.

💬 Keep interacting during review

While reading an explanation, I wanted to ask follow-up questions using actual code and existing analysis, deepening my understanding of a module, call relationship, or specific risk. Later analysis should carry the earlier discussion and code references.

I also wanted to retain decision-making over published feedback. AI produces candidate findings, which I verify, edit, and select before posting to the original platform. Local repository copies, analysis history, and drafts make it easier to return after switching tasks.

For the review itself, I wanted an editor experience close to VS Code, with smooth Diff reading, file navigation, code positioning, and local search for related implementations.

Those requirements led me to a desktop client that places Diffs, findings, and conversation together, allowing an individual to read, analyze, and prepare feedback on existing PRs.

Local storage and model access are configured separately.

Repository copies and drafts stay on the computer. Review context is sent to the model service chosen by the user. The model and deployment arrangement need to fit the code’s permitted use.

A desktop client also means maintaining installers, a local runtime, and cross-platform behavior. Personal settings live on different computers, while shared rules need an agreed update and distribution process. During early validation, I accepted those costs to establish the individual review workflow.

Design Decisions

Building on Mature Review Capabilities

Reusing existing review capabilities was the project’s central design choice. PR-Agent, contributed to the community by Qodo, already supports change descriptions, issue analysis, and PR questions. Code Meeseeks uses it directly as the review engine.

My experience with Qodo

I had tried Qodo reviews on GitHub and liked its change overviews, file-change grouping, and code suggestions. Establishing the structure of a change before reading the important code reduced the effort of building context and strongly influenced my decision to reuse PR-Agent.

An existing review engine lets me focus design and implementation effort on how the reviewer reads results, investigates issues, and confirms and publishes feedback.

The engine runs through an embedded Python runtime. Installers include the required environment to reduce dependency setup for users.

The workflow also follows Qodo’s approach to reading changes, generating findings, asking follow-up questions, and confirming feedback. A typical session proceeds as follows.

Fetch pending PRs and organize them by repository.
Open a PR, read the Diff, and use /describe for an overview and file-change explanations.
Run /review to inspect potential issues and their code locations.
Select code or quote a suggestion and continue with /ask.
Turn useful findings into drafts, edit them, and publish to the code platform.

Generated findings first enter a candidate list and can be edited, discarded, or turned into comment drafts. The reviewer confirms published content. With automatic pre-review enabled, pending PRs can be analyzed in advance so results are ready when the client opens.

Local Repository Caching

Online repository APIs commonly provide PR Diffs as the immediate review context. Understanding unchanged code, cross-file calls, or history requires further searches and reads, limiting what a single request can supply.

The client therefore caches repository mirrors locally and prepares worktrees for the versions involved in a PR. After the first fetch, incremental synchronization keeps them current. Reading and analysis reuse those repositories. File contents are read at the relevant commits and Diffs calculated locally, also supporting fast searches, historical comparisons, and blame analysis.

Local repositories support further context interaction too. A reviewer can explore related implementations from a changed line, and an agent running through a local CLI can inspect worktree files to investigate beyond the Diff and into historical context.

Agent Design

PR-Agent supplies the basic descriptions, reviews, and questions. I added capabilities around the experience I had with Qodo’s commercial version and the local client’s context interactions.

🧩 Architecture diagrams and design explanations

I added architecture output similar to what I had used in Qodo’s commercial product. /describe generates Mermaid diagrams rendered in the client to explain affected modules and relationships.

Alternative implementation ideas and their reasoning also help the reviewer examine design trade-offs against the code.

🔎 References and re-review

Selected code and its location can accompany a question. Existing suggestions can also provide context for another review pass.

Local CLI mode can inspect repository files to check a concern. Results can retain, replace, or close the original finding.

📚 Rule-based context

Markdown rules can be matched by repository and further scoped by project and target branch. Different repositories can use their own conventions and priorities.

The client also reads the reviewed repository’s AGENTS.md, combined with working conventions, long-term memory, and personal preferences. Shared agreements can live in Git, while personal priorities evolve with use.

⚙️ Continuous tasks and execution control

The agent organizes tool calls from natural-language requests, retains task progress and analysis history, and allows changes of direction or cancellation.

New PR commits flag a code-version change, and later conversation can recognize that earlier analysis may be stale. AutoPilot can prepare reviews in advance. Runtime authorization checks control write operations.

Multiple analysis rounds increase model use and waiting time. The client records usage and offers policies such as follow-up limits so the depth can be adjusted to the task.

Visual Design and Interaction Close to VS Code

I used VS Code’s visual style and interaction conventions to make the client familiar to developers. The stack is Electron, React, and TypeScript, with Monaco for code reading, a file tree, side-by-side and unified Diffs, syntax highlighting, and inline comments.

PRs and files occupy the left, code changes the center, and AI analysis and conversation the right. Findings link to locations, selected code can enter a question, and comment drafts can be edited near the relevant lines. Reading, analysis, and feedback preparation connect within the same workspace.

Themes, monospaced fonts, and type size are adjustable. A command palette and keyboard shortcuts expose common actions, following editor conventions to reduce the adjustment required when switching tools.

图 1. Code reading, change descriptions, and inline drafts in Code Meeseeks

The screenshot shows one of the project’s own PRs, using the Chinese interface. The right side explains changes and architecture, the left provides the Diff, and inline drafts remain near their code. The ease of moving between analysis and implementation directly affects the effort of verifying findings.

Multiple Code Hosting Platforms

Internal collaboration at work often uses self-hosted Bitbucket Server. GitLab and GitHub are also common integration targets. I designed a shared adaptation layer so the same review workflow could operate across them.

In my personal experience, Bitbucket offers a relatively good review collaboration experience in enterprise settings. Its interaction and collaboration design also influenced Code Meeseeks.

The client integrates with GitHub, Bitbucket Server / Data Center, and GitLab, including applicable self-hosted instances. Platform adapters fetch PRs, retrieve changes, and handle comments and review actions. Code reading, AI analysis, and draft processing reuse the same higher-level workflow.

Review states, inline comments, and API capabilities differ across platforms. Available actions reflect what each platform supports. Keeping those differences in adapters also makes platform integrations and review workflows easier to maintain independently.

Tool Integration

An optional local HTTP API and companion CLI let external agents or scripts discover PRs, read changes, and invoke reviews. The desktop interface and external tools share the same local review workflow, leaving room for future integrations.

The local API listens on loopback by default and requires token authentication. Operations follow its exposed action scope. GUI, CLI, and agent interfaces share underlying service logic to reduce differences in behavior.

Early Impressions

The project has run for a month, with a small trial in the team. Feedback has been positive and has exposed practical details that needed work.

For me, the clearest benefit is understanding changes more efficiently. Reading an overview before checking key files and candidate issues is easier than constructing all the context from scratch. Some PRs that previously took thirty or forty minutes can now be reviewed in under ten.

Those timings reflect personal impressions from early use. PR size, complexity, and my familiarity vary, and I have no standardized quantitative study yet.

Useful suggestions still need checking against the code. When their assumptions are unclear, I can ask questions, add constraints, and then decide whether to use them. Editing and discarding remain part of incorporating AI output into my review habits.

Client interaction has also become an ongoing area of work. Preserving drafts across page changes, inline positioning, platform differences, and context updates after new commits all affect whether a review proceeds smoothly. Connecting a model leaves many such details to address.

Thoughts on Customized Tools

In my experience, an agent such as Codex, paired with a capable underlying model and a well-tuned harness, can already produce good code reviews. Context organization, tool use, and task execution mechanisms influence both the process and results alongside the model.

For me, Code Meeseeks adds value through further customization of interaction. Organizing pending PRs, code reading, contextual questions, and comment preparation in a familiar interface brings existing review capabilities closer to my own working habits.

Building it also changed my impression of vibe coding. Early in the year, models and agents still felt strained by somewhat complex projects. By mid-2026, in my experience, they had become more than capable of completing moderately sized projects with a meaningful degree of complexity.

- https://hamhire.tech/en/posts/projects/code-meeseeks.html - Licensed under CC BY-NC-ND 4.0

My Homelab, Part 3 — Seven Years with a Ceph Storage Cluster

Sun, 26 Jul 2026 19:50:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/homelab/nas-03.html -

When I first built my Ceph cluster, I planned to write about the experience. I later decided to give it a longer period of stability testing in a home environment before looking back. The cluster has now run for roughly seven years, with disks and nodes gradually replaced along the way.

This article shares my Homelab storage choices and my experience of Ceph’s performance, stability, and maintenance. The failures and performance impressions come from my own use, as a reference for readers with similar requirements.

Choosing a Storage Approach

A NAS provides file services over a network, with many possible storage implementations underneath. Commercial appliances can use conventional RAID or offer mixed-capacity schemes. A self-built NAS might use Linux software RAID, ZFS, or Unraid. Ceph can underpin file services too, although it is itself a distributed storage system.

My earlier storage setup

Before Ceph, I used a hardware RAID card with a JBOD enclosure in 2015. Three issues became apparent over time.

Wasted space with mixed-capacity disks. Arrays were organized around smaller members, leaving extra capacity on newer, larger disks underused.

Slow rebuilds. Replacing a failed disk meant a lengthy rebuild that also affected everyday reads and writes.

Multiple-disk failure risk during rebuilding. While the degraded array rebuilt, another failure could exceed its redundancy and cause data loss.

Comparing Common Storage Options

Common home-storage choices occupy different product and technology layers.

RAID organizes disks through a hardware controller or operating system and commonly underpins NAS storage.
Synology integrates storage management, file sharing, and applications in a NAS appliance. SHR-2 pools are the comparison point here.
ZFS combines a filesystem with volume management and is a common foundation for a self-built NAS.
Unraid is an operating system for self-built storage, managing a main array and separate pools.
Ceph provides distributed block, file, and object storage interfaces.

The capacity bars show aggregate proportions, with metadata and recovery reserves excluded. They do not represent physical partitions. Different replica colors distinguish capacity overhead, with no primary/secondary relationship implied.

Single-disk redundancy leaves no redundancy after one disk fails. Another failure during rebuilding can then cause data loss. For home storage that runs for years while disks age, that is a significant reliability concern. I therefore use configurations able to preserve data through at least two disk failures as the baseline.

The configurations are RAID 6, Synology SHR-2, ZFS RAIDZ2, Unraid dual parity, and Ceph with three replicas.

Aspect	RAID	Synology	ZFS	Unraid	Ceph
Deployment	Single host	Single host	Single host	Single host	Distributed
Configuration	RAID 6	SHR-2	RAIDZ2	Dual parity	Three replicas across hosts
Principle	Striping and dual parity	Combined capacity partitions and dual-disk redundancy	Copy-on-write and dual parity	Independent data disks and two parity disks	Distributed object replicas
Block storage	△ Local block device, with a separate service for network export	✓ iSCSI LUNs through SAN Manager	✓ zvols, with a separate service for network export	△ Additional iSCSI or similar service required	✓ Distributed block devices through RBD
Object storage	△ Separate object-storage service	△ Additional application, depending on model support	△ Separate object-storage service	△ Additional object-storage application	✓ S3-compatible interface through RGW
Mixed capacities	△ Usually limited by the smallest member	✓ Subject to capacity combinations	△ Smallest-member constraint within a vdev	✓ Both parity disks must be at least as large as the largest data disk	✓ Weighted placement, subject to failure domains
Expansion	△ Implementation-dependent	△ Disk-type and capacity constraints	△ Layout- and version-dependent	✓ Add data disks	✓ Add OSDs
Two-disk failures	✓ Within an array	✓ Within a pool	✓ Within each vdev	✓ Within the main array	✓ Data remains if three replicas were healthy beforehand
Failure domain	△ Disk	△ Disk	△ Disk	△ Disk	✓ Customizable hosts, racks, PDUs, data centers, and more
Node maintenance	✗	✗	✗	✗	✓ Replica, quorum, and access-service HA requirements apply
Scale across hosts	✗	✗	✗	✗	✓
Hardware replacement	△ Rebuild disk by disk, controller compatibility affects whole-host migration	△ Rebuild disk by disk, model constraints affect whole-host migration	✓ Replace disks individually, or move the original pool to another host	✓ Rebuild individual disks, or move existing disks to another host	✓ Replace disks or nodes gradually, redistributing affected data
Recovery	Array rebuild	Array rebuild	Resilver	Reconstruct from remaining disks and parity	Recover from other replicas
Rebuild load	Array members	Affected pool members	Affected vdev	Remaining array members and parity disks	Affected OSDs, nodes, and network
Maintenance scope	Host, controller, disks	NAS host and pool	Host, pool, vdevs	Host, array, parity disks	Nodes, network, cluster services
Capacity overhead	Equivalent to two member disks	Dual-disk redundancy, with capacity-combination constraints	Equivalent to two disks per vdev	Two parity disks	Configurable 1/2 for two replicas, 2/3 for three

✓ Supported, △ conditional or requires additional design, ✗ absent from the deployment itself.

Three healthy replicas retain data after two data disks fail, but continued I/O also depends on the minimum replica count and MON quorum. With min_size=2, a PG with only one surviving replica stops I/O. See the pool documentation.

Capacity overhead depends on redundancy policy. Node count does not determine replica count. Three nodes can use two replicas, whose extra copy consumes 1/2 of raw capacity, but that configuration lacks two-disk fault tolerance. Three replicas spend 2/3 on extra copies. Erasure coding can reduce that overhead. Metadata and recovery reserves further reduce usable capacity.

For ordinary home storage such as photos, media, file sharing, and backups, a single-host system is usually sufficient. It costs less in hardware, power, and maintenance and is simpler to manage than a multi-node cluster.

Why I Chose Ceph

Ceph is an open-source distributed storage project originating in Sage Weil’s research. Inktank later commercialized it, and Red Hat acquired Inktank in 2014. In 2022, Red Hat’s Ceph team moved to IBM. Development continues through the community and multiple vendors.

Its foundation is RADOS distributed object storage. Objects map through placement groups (PGs) and CRUSH rules to OSDs, the storage processes managing disks, with replicas retained according to policy. RBD, CephFS, and RGW expose block, file, and object interfaces. The architecture documentation explains the layers. The diagram uses three replicas across hosts.

My choice came down to several requirements.

Mixed capacities and natural replacement cycles. Mixed-capacity support is essential. Disks should be replaced individually as they age, with old and new capacities continuing to work together through weighted placement.
Hardware renewal with limited migration. Disk and node replacements can proceed gradually, with the cluster recovering and rebalancing affected data. This minimizes movement and avoids migrating the entire dataset to another storage system just to replace hardware.
Availability and capacity trade-offs. Critical services need access during single-node maintenance. I accept capacity overhead and maintenance costs, using different redundancy levels for different data classes.

The redundancy overhead is acceptable to me. My household dataset is manageable, HDD storage remains relatively inexpensive, and even in 2026 I still have a stock of enterprise disks formerly used for Chia farming.

I also evaluated GlusterFS early on. Its distributed-filesystem focus seemed best suited to primarily file-oriented use. My Homelab needed VM block storage, file sharing, and object storage together, which led me to Ceph.

Performance in Practice

I initially tried two ways to accelerate HDDs with NVMe, using bcache at the block layer and placing BlueStore metadata on a fast device. Each offered benefits and introduced different failure dependencies.

Experiment with bcache

bcache sits beneath the block device used by an OSD, using NVMe as a cache for HDD capacity.

Cache hits read from NVMe. Misses read from HDD and populate the cache according to policy. Writeback first writes to NVMe and later destages to HDD. Writethrough waits for the HDD write.

The benefit depends on access patterns and hit rate. My NAS contains many infrequently accessed files. Reading cold data for the first time still requires the HDD, limiting the improvement for that workload.

In actual use, I encountered potential stability issues and also had to consider cache-device failure. In writeback mode, NVMe may hold data awaiting destaging, making it a critical part of the storage path. Sharing one cache device across several backing disks can affect multiple devices at once and complicate diagnosis and recovery.

Experiment with BlueStore Metadata Acceleration

Another approach keeps data on HDD while placing BlueStore’s block.db on NVMe. block.db holds RocksDB metadata, and block.wal holds the write-ahead log. With a separate DB device, WAL normally uses that device too. See the BlueStore configuration reference.

A single NVMe can contain separate DB/WAL areas for several HDD OSDs. Each OSD coordinates access, using metadata to locate HDD data blocks and managing data persistence alongside metadata and log updates. Metadata already cached in memory needs no NVMe read.

The earlier FileStore backend depended on a local filesystem such as XFS and an additional journal. BlueStore manages block devices directly, reducing intermediate filesystem overhead and supporting checksums, compression, and metadata placement on faster devices. See the storage backend documentation.

Moving metadata provides no file-content cache. Cold reads still incur HDD seek and media latency.

The largest risk is losing data on associated OSDs when a shared NVMe fails.
Loss of dirty cache data or BlueStore DB/WAL can make an OSD’s data unrecoverable even with an intact HDD. One NVMe serving multiple OSDs concentrates the impact. Recovery depends on complete copies elsewhere in the cluster.

Both approaches increased stability concerns and maintenance complexity in my environment, with limited improvements for cold reads. I eventually moved away from them. My experience informed that personal choice without establishing a universal defect in either design.

The Final Choice of Separate Pools by Medium

I separated HDDs and NVMe into independent pools, using device classes and CRUSH rules to control placement. Workloads needing higher IOPS, throughput, and lower latency use NVMe directly. Capacity-oriented workloads use HDDs, with placement and migration arranged at the application side.

My storage network runs at 10GbE. Tests and long-term use show that the HDD pool meets my needs for NAS files, VM image backups, and capacity-oriented object storage. Small files, random access, concurrency, and recovery load still affect the experience, so these results do not imply that every workload saturates 10GbE.

Here is an early CephFS file read/write test.

The test ran in a CephFS mount with a roughly 2.46 GB file. It reported 854 MB/s for writing and 2.8 GB/s for reading. Cache effects are included, so those values cannot be equated with sustained HDD persistence or network throughput. Together with everyday use, the result supports the suitability of file access performance for my NAS needs.

In mid-2025, before the subsequent broad rise in SSD prices, I replaced a node with an all-flash U.2 NVMe configuration, continuing the move toward flash storage.

Planning a gradual move to 25GbE
I chose a 25GbE SFP28 NIC during that replacement. SFP28 and SFP+ share a compatible physical form factor. A 25G NIC supporting 10G operation can connect to an existing SFP+ 10G switch, allowing upgrades in stages. See NVIDIA’s connector definitions.

My DAC cables are rated for 25G and currently run at 10G with the existing switch. The NIC and cables can be reused when the switch is upgraded. NIC speed support and switch compatibility with the chosen DAC still need checking. The performance experience described here is based on the 10G network.

Stability in Practice

For seven years, the cluster has served everyday storage through disk and node replacements, hardware failures, and several whole-rack power losses. I have experienced no loss of already-written data. The following observations come from that period of operation.

Power Stability

I initially debated adding a UPS, mainly because I worried about data loss after sudden power cuts. A UPS also brings trade-offs.

Lithium battery safety. Thermal runaway can cause fires, with risk depending on chemistry, battery management, and product design.
Lead-acid weight. Weight affects handling and installation.
Long-term capacity loss. Both types age, reducing backup runtime and requiring checks and eventual replacement.

Eaton’s UPS battery documentation discusses differences in safety and lifetime.

My tests produced no data loss. Over the years, the rack lost power roughly three or four times, again with no loss of already-written data. Those experiences made me comfortable with power-loss recovery in my own setup.

My requirement is that writes still incomplete at the instant of power loss may fail, while data confirmed as durable should remain. VM and database behavior still depends on transaction commits, synchronization, and devices honoring flush requests.

The tests and incidents cover a limited set of failures. Ceph replication works alongside device power-loss protection, correct persistence semantics, UPS protection, and independent backups. Replicas in the same rack also share the rack’s power-failure exposure.

Common Failures

HBA failures. I used second-hand server parts. Home cooling was also limited by noise considerations, which may have contributed. Server components' expected airflow needs attention in a home chassis.
Disk-backplane failures. A chassis bought from a small manufacturer developed a front drive-cage backplane fault. Offline-disk diagnosis needs to include backplanes, cables, controllers, and power.
Aging HDD replacement. I replaced disks as reallocated sectors reached warning levels, as part of planned maintenance before complete failure.

图 1. An offline OSD, with osd.8 on pve-03 shown as out/down and the other listed OSDs in/up

Cross-node replication keeps data available on other nodes through such local failures. An HBA or backplane can affect several disks simultaneously, so failure-domain planning needs to consider more than individual disks. Maintenance also requires checking the health of other nodes to avoid overlapping failures.

Ceph Best Practices for a Homelab

A Dedicated Storage Network

I separate the PVE and Ceph networks. PVE carries compute-side management and workload traffic. Ceph carries storage access, OSD replication, heartbeats, and recovery.

The separation is especially useful during recovery. Failed disks, returning nodes, and rebalancing generate extra transfers. Keeping that traffic apart reduces bandwidth contention and makes the storage and compute networks easier to observe individually.

My design has only those two networks. Client access and OSD-to-OSD traffic share the Ceph network, with no further split between public_network and cluster_network. I chose to keep home-network complexity manageable. See the network configuration documentation.

Actual isolation also depends on physical links. VLANs separate logical networks but still share bandwidth on a common uplink. Capacity planning needs to cover both routine access and recovery.

Pool and Replica Policies

I divide pools by medium and data class and choose redundancy separately. Three considerations guide that arrangement.

Medium and workload. Low-latency, higher-I/O workloads use NVMe. Capacity-oriented workloads use HDDs. CRUSH rules constrain placement to the appropriate media.
Data importance and capacity cost. Replica count is per pool. Three replicas retain more redundancy headroom. Two improve capacity efficiency but leave less headroom after a failure. The decision depends on importance, recovery cost, and independent backups.
Replicas and failure domains. Tolerating a whole node offline requires replicas across hosts. Multiple copies on one host share its failure exposure. Separate pool names alone provide no physical-device isolation.

Devices need free space for recovery and rebalancing. Dividing raw capacity by replica count alone overestimates usable space. Pools sharing OSDs also share disk capacity and I/O resources.

Consider size and min_size together. Three replicas with min_size=2 can continue I/O after one copy is lost, assuming quorum and other requirements remain satisfied. With two replicas and the same minimum, losing one stops affected I/O. Reducing replicas changes maintenance availability as well as capacity overhead. See the pool documentation.

Using OSD noout

For a home cluster whose alerts can be monitored and acted on promptly, I favor noout. Temporary network problems, reboots, or connection issues can otherwise cause a recoverable OSD to be automatically marked out, trigger data migration, and require another rebalance when it returns.

noout prevents down OSDs from being automatically marked out after the timeout. It neither keeps them online nor blocks all recovery and movement. The OSD troubleshooting documentation covers setting and clearing it during maintenance.

# Cluster-wide noout affects automatic out behavior across the cluster
ceph osd set noout

# Clear after temporary maintenance and state verification
ceph osd unset noout

For planned work, version support may allow narrowing the scope to affected OSDs or hosts. Retaining cluster-wide noout means actively taking responsibility for failures.

Pay particular attention to OSD down, degraded or undersized PGs, disk health, and capacity alerts. A short outage may justify waiting for a device to return. Permanent failures need replacement or removal so the cluster can restore copies. Continued application access provides no reason to leave the cluster degraded indefinitely.

If the first failed disk remains unattended and further replica-bearing devices fail, redundancy can gradually disappear, making data unavailable or lost. If prompt alert response is impractical, I advise keeping automatic recovery enabled, with sufficient reserve capacity, instead of retaining global noout long-term.

Independent Backups for Important Data

Replicas address device and node failures. Recovering accidental deletion, erroneous overwrites, or malicious deletion requires a separate backup strategy. I retain static backups of cold data and back up selected critical data to cloud object storage.

Independent cold-data copies allow recovery without depending entirely on the original Ceph cluster. Cloud object storage adds a separate location so a rack-level incident cannot affect every copy.

The 3-2-1 backup principle
Retain at least three copies of important data, across at least two types of storage media, with one copy off-site. The three include the original and two backups. Copies inside one Ceph cluster cannot substitute for independent backups. See CISA’s backup guidance.

Cloud backups store selected important data in object storage. I separate routine backup credentials from administrative credentials and limit access to required buckets and prefixes. Daily writers should especially lack permission to delete historical versions or change versioning settings. Versioning retains earlier copies after accidental overwrites or deletions.

Versioning also needs permissions and retention policies. Backup completion, availability of historical versions, and actual file recovery all need periodic checks.

An off-site cluster is another possibility
Ceph supports cross-cluster synchronization through RBD mirroring, CephFS snapshot mirroring, and RGW multisite. With another cluster elsewhere and enough inter-site bandwidth, a home setup could even start entertaining multi-data-center ambitions 😝

Snapshots or retained historical versions are still needed alongside synchronization to recover from accidental deletion and overwriting.

Looking Ahead

After seven years of continuous 24×7 use, hardware failures, aging-disk replacements, and node retirements, Ceph has demonstrated its long-term design reliability in my own application. I have yet to find a better alternative that fits my needs and intend to keep using it for the long term.

- https://hamhire.tech/en/posts/homelab/nas-03.html - Licensed under CC BY-NC-ND 4.0

Techno Keyer — Bringing Retro Displays and Morse Code Together

Sat, 05 Oct 2024 20:00:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/projects/techno-keyer.html -

Since getting into amateur radio in 2023, I have tried various parts of the hobby and earned my Class A and Class B operator certificates. CW was naturally on the list. I bought a dual-lever paddle and spent some time practicing sending and copying Morse code. As a programmer with a fondness for automation, I soon wanted to automate the repetitive work of sending it.

A basic transmitter keyer is essentially an automated switch, so the idea sounded manageable. Around the same time, I acquired a BOE vacuum fluorescent display (VFD) module to experiment with. Its distinctive glow, familiar from electronics of the 1980s and 1990s, suggested a small device with a retro-technology feel. I called it Techno Keyer. The name seemed to suit the era, even though I had yet to be born back then :-)

TL;DR

This article covers the design and implementation of Techno Keyer. The firmware and circuit schematics are available on GitHub for anyone interested in the project.

Techno Keyer on GitHub

Your browser does not support the video tag.

Transmit Mode

The initial goal was straightforward. Read characters from a USB keyboard, encode them as Morse code, and open and close the radio’s keying circuit to send them automatically.

Keyboard Input

Reading a USB keyboard was the first requirement for an automatic keyer, and it became my first obstacle. I initially assumed that a USB-capable MCU would handle it. I built a breadboard prototype around an ESP32-S3 development board and tried the EspUsbHost project from GitHub. An older Logitech membrane keyboard worked as expected.

Reference project EspUsbHost

A spare mechanical keyboard gave a different result. It would fail to initialize properly, so there was no usable key input. Debug output showed the initial connection being detected, followed by failures and repeated restarts. Comparing my results with issues in similar projects pointed to keyboard compatibility in the USB-host setup I was using.

The ESP32-S3 USB-OTG host supports Low Speed and Full Speed devices. I treated the failure as a compatibility issue in my setup and looked for a practical way to handle the keyboards I wanted to use. Espressif USB Host documentation

Following approaches used in other community projects, I tried a CH9350L USB keyboard-and-mouse to serial controller, a chip also used in KVM devices. I bought a development module on Taobao and connected it to the prototype. Keyboard input then worked, although the extra chip raised the cost of the design. Other builders have also used USB-to-PS/2 keyboard connections for similar projects.

Keying the Radio

Once keyboard input worked, the next step was to make the CW output behave like a conventional key. I wanted broad compatibility and a simple control circuit.

A key is a switch that opens and closes a circuit. On the usual 3.5 mm key connector, the sleeve is ground. With a paddle, the other two contacts represent the dit and dah inputs. With a straight key, the tip provides the keying contact.

M0UKD’s simple touch-key circuit uses an NPN transistor as the switching element and was reported to work with several Icom radios. A MOSFET could serve a similar purpose.

A semiconductor switch can respond quickly, but directly connecting the circuits raised a few concerns. Key-input voltages vary between radio designs. The Icom interface I considered used 3.3 V, while other equipment, especially older radios, could expose the circuit to higher voltages. Techno Keyer also has its own USB supply, so connecting the grounds directly could create a ground loop between devices.

I chose an optically isolated solid-state relay as the external switching element. It separates the keyer’s circuit from the radio’s keying circuit. An indicator LED and a buzzer provide visual and audible feedback. The resulting circuit is shown below.

Encoding and Sending

With the hardware approach established, I needed to translate keyboard characters into Morse code. Morse predates ASCII, and its letter and number patterns do not follow a convenient numeric sequence. I used a lookup table to keep the implementation easy to extend.

I represented dits as 0 and dahs as 1. Since a pattern may begin with zero, I stored each pattern in reverse bit order in an eight-bit value, with a leading 1 as an end marker. For example, A is .-, represented as 0b110.

// Morse code table
// 0 -> Dit, 1 -> Dah, Reverse order, Highest bit is 1
const struct morseChar morseTable[] = {
        {'A', 0b110},       // .-
        {'B', 0b10001},     // -...
        {'C', 0b10101},     // -.-.
}

Another approach used in related projects is a binary tree whose branches represent dits and dahs. Traversing the tree locates a character. It offers a compact representation, but I found the table easier to extend for my needs.

A compact tree can be stored as a “magic string”, with each character’s position representing its Morse pattern.
**ETIANMSURWDKGOHVF*L*PJBXCYZQ**54S3***2**+***J16=/***H*7*G*8*90************?_****\"**.****@***'**-********;!*)*****,****:****

Sending a character then becomes a table lookup followed by a series of bit shifts. Each bit determines which signal to send until the end marker is reached.

/**
 * Send one char
 * @param c
 */
void MorseEncoder::sendChar(char c) {
    if (c == ' ') {
        vTaskDelay(7 * _dotTimeMs / portTICK_PERIOD_MS);
    } else {
        uint8_t code = _codec->getCode(c);
        while (code != 1) {
            if (code & 1) {
                _sendSignal(DAH);
            } else {
                _sendSignal(DIT);
            }
            code = code >> 1;
        }
        vTaskDelay(2 * _dotTimeMs / portTICK_PERIOD_MS);
    }
}

/**
 * Send morse signal
 * @param sig
 */
void MorseEncoder::_sendSignal(uint8_t sig) {
    uint16_t sigTimeMs = sig == DIT ?
            _dotTimeMs : _dotTimeMs * 3;

    digitalWrite(CW_PIN, HIGH);
    _buzzer -> on();
    vTaskDelay(sigTimeMs / portTICK_PERIOD_MS);

    digitalWrite(CW_PIN, LOW);
    _buzzer -> off();
    vTaskDelay(_dotTimeMs / portTICK_PERIOD_MS);
}

I assembled a simple breadboard prototype to test the result.

Receive Mode

After implementing the basic transmitter, I decided to add decoding as well.

Audio Processing

Receiving is more involved than switching a keying circuit. The input is analog audio, with interference and background noise from the radio path. Reliable decoding benefits from conditioning the signal to extract the frequency range of interest. A typical processing chain includes noise reduction, filtering, gain, decoding, and debouncing. The radio can handle the first three stages, leaving Techno Keyer to focus on decoding.

CW audio is commonly set to a tone between 500 and 1000 Hz, which can be isolated with a relatively narrow filter. I used an LM567 tone decoder to detect the selected frequency, setting its operating range through the surrounding circuit. An SPI-controlled digital potentiometer lets the MCU adjust the center frequency from the menu.

Decoding the Signal

Morse timing is based on the length of a dit. A dah lasts three units. The gap between elements is one unit, the gap between characters is three units, and the gap between words is seven units.

Human sending is less precise than computer-generated timing. Even the same operator’s elements vary in length. The decoder therefore needs to distinguish short and long elements despite those variations. I mainly followed K4ICY’s implementation, updating the classification threshold as signals arrive and using the geometric mean of the estimated dit and dah durations as a reference.

Reference project K4ICY CW Decoder

Updating the classifications dynamically lets the decoder adapt fairly quickly to different sending speeds. I generated test audio with different simulated operator skill levels. With a clear audio input and reasonably consistent sending, the results were generally good. Machine decoding also handled fast signals at 40 WPM.

Your browser does not support the video tag.

Assembly and Bring-up

Controlling the VFD

The main challenge with the VFD was finding documentation. The Taobao seller supplied limited information and rudimentary example code. I eventually found the relevant manual and used its command descriptions to implement the display controls over SPI.

Circuit Design

I combined the hardware into a two-layer PCB. Using a ready-made ESP32 module kept fabrication costs down and saved me from designing an antenna or moving to a four-layer board. The trade-off was limited space. I also placed all surface-mount components on one side to simplify assembly, making the component side fairly dense.

Circuit schematics

For the rotary encoder, I deliberately chose a right-angle version that could be operated from the edge of the PCB. It avoided an extra support structure or separate board for a conventionally mounted encoder.

Enclosure Design

Once the core functions worked, I wanted a proper enclosure. While looking at other VFD projects, I found a triangular-prism clock whose appearance appealed to me.

I designed a similar triangular-prism enclosure around the dimensions of my VFD module. The central support and side covers were CNC-machined from aluminum alloy for a metal finish, while the front and rear panels were 3D-printed.

Clear acrylic would have been my preferred material for the front panel. A dark-tinted translucent sheet could also have given the display a more polished appearance. I had yet to find a suitable supplier for such a small custom part, so I used transparent 3D-printing material for the time being.

I was pleased with the finished device. Twenty-first-century integrated circuits drive a twentieth-century vacuum fluorescent display to send a nineteenth-century communication code. Combining those technologies gave the project the retro character I had hoped for.

This is BD4WEI, 73

- https://hamhire.tech/en/posts/projects/techno-keyer.html - Licensed under CC BY-NC-ND 4.0

Dvorak Matrix — Building My Own Custom Keyboard from Scratch

Tue, 12 Dec 2023 20:20:00 +0800

Hamhire Tech Tips https://hamhire.tech/en/posts/projects/dvorak-keyboard.html -

After ten years of typing in Dvorak, I still wanted a keyboard that supported my layout natively. Commercial options were limited, so I had been relying on operating-system remapping to adapt the keyboards I used.

By the end of the three pandemic years, the free Dell keyboard I had used in the office for years had shiny keycaps and worn-off legends. The custom-keyboard market was thriving, but much of the customization involved choosing combinations of standard parts. It reminded me of assembling the miniature four-wheel-drive cars I played with as a child. I wanted to try designing the keyboard itself.

Custom PCBs had become affordable, and 3D printing and CNC machining were increasingly accessible. I decided to build a keyboard of my own.

Choosing a Layout

My reasons for switching from QWERTY to Dvorak years earlier were mostly about typing efficiency and comfort.

Speed and efficiency. Dvorak places frequently used letters on the home row to reduce finger travel.
Less finger fatigue. Shorter movements appealed to me as someone who spends long hours typing.
Typing comfort. Its letter arrangement aims to make common sequences more comfortable.
Workload across both hands. The layout aims to distribute typing work more evenly.

The heat maps show frequently used keys concentrated on the home row, with all five vowels under the left hand. The benefits may be less apparent when entering Chinese, but as a programmer who types a great deal of English, I had found Dvorak comfortable over the previous ten years.

Keyboard shortcuts are its biggest inconvenience for me. Many applications position their shortcuts around QWERTY, and those combinations become awkward after remapping. Key-mapping tools or dedicated shortcuts on a Dvorak-oriented keyboard can compensate.

Defining the Requirements

Around 2015, I bought two TypeMatrix 2030 keyboards. Their built-in support for Dvorak was the main attraction.

Several aspects of the design worked well for me.

Native Dvorak support
Dedicated alternatives for common copy-and-paste shortcuts
Centrally placed Backspace, Delete, and Enter keys that either hand could reach
Switching between Dvorak and QWERTY
A compact footprint with a layered numeric keypad
A regular ortholinear grid whose appearance I preferred to staggered rows

My reservations came from using them.

Basic construction with membrane switches and a simple tray-style case
More right-side multimedia keys than I needed
No provision for spill resistance
A price of US$110 each that felt high for the build quality

Both keyboards eventually failed after water spills. The conductive membrane traces were damaged, especially by hot water, leaving individual keys unusable. Repairing those fine traces on plastic film was impractical.

I liked the TypeMatrix layout enough that I would have kept using it if the keyboards had survived. My own design therefore started from its layout and functions, with changes to suit my preferences.

I had also used standard-height mechanical keyboards, but disliked their long travel for sustained typing. Quiet operation mattered more to me than tactile feedback, and linear switches felt comfortable for prolonged use. After trying several switches, I settled on low-profile linear switches.

The basic goals were as follows.

Follow the TypeMatrix 2030 layout approach
- Support Dvorak
- Keep Enter and other editing keys in the center
Remove unnecessary multimedia keys
Support switching between layout layers
Use low-profile linear switches
Use a wired connection

My first revision followed the original closely, including 0.75U-high function keys, several unusual 2U keys, and a 5 × 1.25U spacebar. Finding ready-made keycaps for those dimensions was difficult, especially for low-profile switches. Custom PBT tooling made little sense for a one-off keyboard. After validating the first revision’s circuit and firmware, I adjusted the layout to fit commercially available keycaps.

Keyboard Layout Editor can be used to design the basic layout online.

The function keys became 1U. A 0.25U gap between the function row and the main typing area accommodated the centered 2U Backspace and 2.5U Enter keys. I changed the spacebar to the common 6.25U size and removed less-used keys such as right Alt and right Ctrl. The revised layout could use off-the-shelf keycaps.

Circuit Design

With the layout decided, I moved on to the electronics. I wanted a straightforward keyboard without elaborate extras or key backlighting. The familiar ATmega32U4 had enough GPIO pins for the design. An STM32 was another possibility, but I saw little benefit in the extra complexity and cost for this project.

Switch Matrix

A keyboard’s input mechanism is a matrix of switches. The MCU scans rows and columns through its GPIO pins to determine which switches are closed. I used a column-to-row diode orientation, placing a diode in series with every switch to prevent unwanted current paths when several keys are held simultaneously.

Since I had already defined the physical layout, drawing the matrix mainly involved arranging each switch and diode in its intended row and column.

USB Interface

A USB Type-C connector carries power and data. The keyboard has modest data-rate requirements, so the surrounding circuit mainly addresses ESD protection, shielding, and supply filtering.

A USBLC6-2SC6 diode array provides ESD protection. Discrete protection devices could serve the same purpose, with a different board-area trade-off.
A ferrite bead and capacitors filter the supply, with a resettable fuse in the power path.
A 1 MΩ resistor and capacitor connect the connector shield to ground. The host’s USB grounding also contributes to the shielding arrangement.

The keyboard could operate without all of those protective components, but I wanted protection against faults and accidental static discharge. For a keyboard I was building for myself, the small additional cost was worthwhile.

The Type-C connector’s A5 and B5 pins are the configuration-channel contacts. For this USB-powered device, each needs its own pull-down resistor. Sharing one resistor can cause compatibility problems with some cables and power sources.

MCU Connections

The MCU circuit connects power, ground, data, and a crystal, with most remaining GPIO pins reserved for the switch matrix. Assigning matrix pins after considering the physical PCB layout helps reduce crossed traces and unnecessary vias.

A reset control is needed for firmware flashing. I left two small pads that can be bridged with a metal tool when necessary, avoiding a separate switch that would rarely be used.

Status LEDs

With GPIO pins left over, I added a few LEDs for lock and layout status. Each LED needs a current-limiting resistor. The resistance depends on the LED and desired brightness, and I preferred subdued indicators that would remain comfortable to look at.

PCB Layout

The layout exported by Keyboard Layout Editor can be imported into online plate-generation tools to obtain a CAD drawing. That provides precise switch positions for placing the PCB footprints.

Keyboard Plate Generator ai03 Plate Generator

The switches and through-hole LEDs occupy the front of the board. Surface-mount components on that side would interfere with assembly. Double-sided SMT assembly also costs more, so I placed all surface-mount components on the back.

I wanted flexibility in switch selection, covering Kailh Choc v1/v2 and Cherry low-profile switches. Combining pad and hole positions, following examples from other GitHub projects, let me create a compatible footprint. The arrangement ruled out hot-swap sockets. I already preferred soldered switches, so that trade-off suited me.

A standard 1U key pitch is 0.75 inches, or 19.05 mm. A 0.79375 mm grid, equal to 19.05 mm divided by 24, made component placement convenient. I used 0.25 mm signal traces, approximately 10 mil, and 0.40 mm power traces for additional current margin. The actual load was modest because the keyboard had no backlighting.

I also paid attention to several routing details.

Route the USB data pair together with matched lengths and a continuous reference plane.
Provide ground copper around the USB connector, MCU, and crystal where appropriate.
Keep the crystal close to the MCU.

I then placed the component footprints and routed the connections. Most switch footprints were rotated 90 degrees to simplify routing. Vertical traces generally ran on the top layer and horizontal traces on the bottom, reducing vias. Keeping components on the grid made the layout tidy. Rotating the MCU 45 degrees helped with pin access.

I put the USB connector at the top center for convenient cable placement. Its protection circuitry occupied enough space that the neighboring switches needed different orientations. A mirrored arrangement made the result look orderly.

The ortholinear layout kept placement regular, but larger keys needed stabilizers. Mounting conventional stabilizers on the plate would add height to a low-profile keyboard. Several commercial designs instead used low-profile stabilizers mounted directly to the PCB. Wire stabilizers used on other keyboard designs offered another possibility. I made a small test PCB to compare the mounting arrangements.

The low-profile MX-style stabilizers mounted on the PCB felt best and were easiest to work with. Their height also matched the switches. I added the corresponding mounting holes at the larger keys.

Finally, I reduced excess board area and tightened the space around the through-hole LEDs to control size, cost, and weight. After adding a few optional screw holes and silkscreen markings, the PCB design was complete.

Enclosure Design

The circuit and PCB still needed an enclosure to become a usable keyboard. Before drawing the case, I had to choose a mounting structure.

Choosing a Mount

Keyboard builders have developed several common mounting arrangements, each with different mechanical characteristics.

Tray mount. The PCB attaches directly to posts in a one-piece case. It has few parts and can be inexpensive to manufacture and assemble. Support-point placement can make the feel vary across the keyboard.
Case mount. In top-mount and bottom-mount designs, the plate attaches to the upper or lower case. The plate distributes typing loads and structural support, with its material strongly influencing the feel. The PCB carries less mechanical load.
Sandwich mount. An enlarged plate is clamped between the upper and lower case. Assembly is straightforward, but the mating parts need consistent dimensions. Rigid clamping produces a relatively firm feel.
Plateless mount. The PCB itself supports the switches, using an arrangement similar to tray or top mounting. It can feel softer, while placing more mechanical load on the PCB.
Integrated plate. The upper case and plate form a single part, reducing the part count. Its rigid structure can also amplify typing noise.
Gasket mount. Cushioning material separates the plate assembly from the case, softening the feel compared with a rigid sandwich mount. The additional materials and mounting details can increase cost.

I prefer a relatively firm but consistent typing feel. Top mount suited that preference best. Its parts were more involved to design, but I wanted to try it.

Mechanical Design

Having chosen low-profile switches, I wanted to minimize the enclosure height. The upper and lower parts needed to locate and support the keyboard without interfering with its components. Keeping the design simple also reduced material and weight. A smaller internal cavity helped limit hollow typing noise.

I followed a workflow I knew well. I first drew precise, layered outlines in CAD, then built the solid models in SolidWorks from those profiles. Although I could have done the whole job in a 3D tool, I liked the precision and efficiency of command-driven CAD. Drawing the parts brought back memories of mechanical-drawing classes at university more than a decade earlier, including drawing by hand.

Exporting the PCB model let me check component clearances in the mechanical assembly. Collision checks were useful when reducing the case thickness and positioning reinforcement ribs. The USB opening also required careful checking because it spans the upper and lower case.

The enclosure has three main parts, the upper case, switch plate, and lower case. Their fastening points follow the top-mount arrangement. I considered ordering the plate from a specialist keyboard supplier, but ultimately chose the same aluminum alloy and anodized finish as the upper case, so I had both CNC-machined together. Cutouts and recessed areas reduced weight where material was unnecessary. A slightly wider left border holds three holes for the through-hole LEDs, avoiding separate light pipes.

I allowed roughly 0.1–0.2 mm for fit between mating parts. The lower case would be 3D-printed in ABS. Its tolerances could be looser, but the material’s flexibility made the actual fit manageable. Two lengths of M2 flat-head screws hold the assembly together, with threaded holes in the aluminum upper case.

Firmware

The hardware needed firmware to implement its input behavior. For a wired ATmega32U4 keyboard, QMK was an established framework that already provided the core keyboard functions.

QMK Firmware

Writing code is my day job, so starting a QMK project from its documentation was straightforward. With a nonstandard layout, I had expected to work directly in code from the outset. I also prefer organizing the implementation in a way I can comfortably read and maintain.

QMK supplies keycode definitions, layer switching and combinations, shortcut handling, matrix scanning, and much of the other basic behavior. My main work was defining the keymaps and layout-switching logic. MCU pin assignments go in info.json.

I used four layers for the default Dvorak layout, an alternative QWERTY layout, function combinations, and a numeric keypad.

enum mx_layers {
    _DVORAK = 0,
    _QWERTY,
    _FN,
    _NUMPAD
};

enum mx_keycodes {
    TG_DV = SAFE_RANGE,
    NUM_00
};

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    // Dvorak Layout (Default)
    [_DVORAK] = LAYOUT_dvorak_matrix(
        KC_ESC, KC_F1,  KC_F2,  KC_F3,  KC_F4,  KC_F5,  KC_DEL, KC_F6,  KC_F7,  KC_F8,  KC_F9,  KC_F10, KC_F11, KC_F12,
        KC_GRV, KC_1,   KC_2,   KC_3,   KC_4,   KC_5,   KC_BSPC,KC_6,   KC_7,   KC_8,   KC_9,   KC_0,   KC_LBRC,KC_RBRC,
        KC_TAB, KC_QUOT,KC_COMM,KC_DOT, KC_P,   KC_Y,           KC_F,   KC_G,   KC_C,   KC_R,   KC_L,   KC_SLSH,KC_EQL,
                KC_A,   KC_O,   KC_E,   KC_U,   KC_I,   KC_ENT, KC_D,   KC_H,   KC_T,   KC_N,   KC_S,   KC_MINS,
        KC_LSFT,KC_SCLN,KC_Q,   KC_J,   KC_K,   KC_X,           KC_B,   KC_M,   KC_W,   KC_V,   KC_Z,   KC_BSLS,KC_RSFT,
        KC_LCTL,KC_LGUI,        KC_LALT,                KC_SPC,                         KC_HOME,KC_UP,  KC_END, KC_PGUP,
        MO(_FN),                                                                        KC_LEFT,KC_DOWN,KC_RGHT,KC_PGDN
    ),
    // Qwerty Layout
    [_QWERTY] = LAYOUT_dvorak_matrix(
        KC_ESC, KC_F1,  KC_F2,  KC_F3,  KC_F4,  KC_F5,  KC_DEL, KC_F6,  KC_F7,  KC_F8,  KC_F9,  KC_F10, KC_F11, KC_F12,
        KC_GRV, KC_1,   KC_2,   KC_3,   KC_4,   KC_5,   KC_BSPC,KC_6,   KC_7,   KC_8,   KC_9,   KC_0,   KC_MINS,KC_EQL,
        KC_TAB, KC_Q,   KC_W,   KC_E,   KC_R,   KC_T,           KC_Y,   KC_U,   KC_I,   KC_O,   KC_P,   KC_LBRC,KC_RBRC,
                KC_A,   KC_S,   KC_D,   KC_F,   KC_G,   KC_ENT, KC_H,   KC_J,   KC_K,   KC_L,   KC_SCLN,KC_QUOT,
        KC_LSFT,KC_Z,   KC_X,   KC_C,   KC_V,   KC_B,           KC_N,   KC_M,   KC_COMM,KC_DOT, KC_SLSH,KC_BSLS,KC_RSFT,
        KC_LCTL,KC_LGUI,        KC_LALT,                KC_SPC,                         KC_HOME,KC_UP,  KC_END, KC_PGUP,
        MO(_FN),                                                                        KC_LEFT,KC_DOWN,KC_RGHT,KC_PGDN
    ),
    // Functions
    [_FN] = LAYOUT_dvorak_matrix(
        _______,TG_DV,  _______,_______,_______,_______,KC_INS, _______,_______,_______,_______,KC_PSCR,_______,TG(_NUMPAD),
        _______,_______,_______,_______,_______,_______,KC_VOLU,_______,_______,_______,_______,_______,_______,_______,
        _______,_______,_______,_______,_______,_______,        _______,_______,_______,_______,KC_PSLS,KC_PAST,KC_PMNS,
                _______,_______,_______,_______,_______,KC_VOLD,_______,_______,_______,KC_P7,  KC_P8,  KC_P9,
        KC_CAPS,_______,_______,_______,_______,_______,        _______,_______,_______,KC_P4,  KC_P5,  KC_P6,  KC_PPLS,
        _______,C(KC_INS),      S(KC_INS),              KC_MUTE,                        KC_P1,  KC_P2,  KC_P3,  KC_PENT,
        _______,                                                                        KC_P0, NUM_00,  KC_PDOT,KC_PENT
    ),
    // Number Pad
    [_NUMPAD] = LAYOUT_dvorak_matrix(
        _______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,
        _______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,_______,
        _______,_______,_______,_______,_______,_______,        _______,_______,_______,_______,KC_PSLS,KC_PAST,KC_PMNS,
                _______,_______,_______,_______,_______,_______,_______,_______,_______,KC_P7,  KC_P8,  KC_P9,
        _______,_______,_______,_______,_______,_______,        _______,_______,_______,KC_P4,  KC_P5,  KC_P6,  KC_PPLS,
        _______,_______,        _______,                _______,                        KC_P1,  KC_P2,  KC_P3,  KC_PENT,
        _______,                                                                        KC_P0, NUM_00,  KC_PDOT,KC_PENT
    ),
};

The custom key handlers switch between Dvorak and QWERTY and provide a double-zero key, similar to the 00 key on some calculators. Following TypeMatrix’s approach, Fn combinations on the left side provide copy and paste shortcuts that remain convenient with Dvorak.

bool process_record_user(uint16_t keycode, keyrecord_t *record) {
// Debug Output
#ifdef CONSOLE_ENABLE
    uprintf("KL: kc: 0x%04X, col: %2u, row: %2u, pressed: %u, time: %5u, int: %u, count: %u\n", keycode, record->event.key.col, record->event.key.row, record->event.pressed, record->event.time, record->tap.interrupted, record->tap.count);
#endif
    switch (keycode) {
        case TG_DV:
            // Toggle Dvorak Layer
            if (record->event.pressed) {
                if (IS_LAYER_ON_STATE(default_layer_state, _QWERTY)) {
                    default_layer_set(1 << _DVORAK);
                    set_single_persistent_default_layer(_DVORAK);
                } else {
                    default_layer_set(1 << _QWERTY);
                    set_single_persistent_default_layer(_QWERTY);
                }
            }
            return false;
        case NUM_00:
            // Double Zero
            if (record->event.pressed) {
                SEND_STRING("00");
            }
            return false;
        default:
            return true;
    }
}

After compiling the firmware with QMK, I used QMK Toolbox and the PCB’s reset pads to flash it onto the MCU.

Manufacturing and Assembly

I ordered the PCB and SMT assembly through JLCPCB. The assembly service could place the surface-mount components along with the board order. Since I designed the circuit in KiCad, my workflow involved importing it into EasyEDA, associating the fabrication parts, checking the result, and uploading the board and assembly files. At order confirmation, I paid particular attention to the orientation and polarity of the MCU, crystal, ICs, and diodes. Automatic placement still needed a manual check.

For the upper case and plate, I used JLC’s 3D Monkey CNC service with 6061 aluminum and a space-gray anodized finish. The same service printed the ABS lower case. Threaded features required separate 2D drawings with machining notes, which were straightforward to prepare in SolidWorks.

I also considered softer 5-series aluminum and pilot holes that could be tapped during screw installation as a possible way to reduce machining cost.

Once the orders were placed, there was a short wait. The PCB arrived relatively quickly. CNC machining and 3D printing took a little longer, possibly because I ordered during the National Day holiday and there was a backlog. Everything was finished in about a week.

The machined upper case and plate fit together neatly. Snapping switches into the plate was satisfying, a little like assembling Lego.

Next, I positioned the switches in the plate, soldered them to the PCB, and installed the stabilizers and wires. The Kailh 1350 stem design limited keycap choices, particularly with switches rotated 90 degrees. I ultimately chose Cherry low-profile switches for their cross-shaped stems, keycap compatibility, and relatively quiet operation.

The unusual Dvorak arrangement needed uniform-profile keycaps, with the same shape across rows. I chose a set from the NuPhy Air96 that suited the anodized case. Their PBT material also appealed to me for long-term use and resistance to developing a shiny surface.

The finished space-gray aluminum case and predominantly gray keycaps looked good together.

Afterword

I planned to use the keyboard for a while before deciding what to change in another revision. The Fn combinations felt slightly awkward because I had been conservative about key spacing. I also wanted a rotary control, but finding a smooth, non-detented encoder that fit the low-profile height was proving harder than expected.

The project gave me a taste of the enjoyment that technology creators such as He Tongxue and Zhihui Jun find in designing their own devices. I had never taken an electronic product through the entire process from an initial idea to manufacturing. Completing it over roughly two weeks of spare time was satisfying. It reminded me of the resourceful engineers in Jules Verne’s nineteenth-century novels, solving one practical problem after another through engineering.

Access to affordable manufacturing also made a strong impression. For a small personal project, turning an idea into a physical object was remarkably accessible. I wondered what further designs might become possible if custom integrated-circuit fabrication became similarly approachable one day.

References

- https://hamhire.tech/en/posts/projects/dvorak-keyboard.html - Licensed under CC BY-NC-ND 4.0