Building a Human68k Utility for Joystick Axis Calibration

The Sharp X68000 is often described through its arcade conversions, FM sound and distinctive tower case, yet its input hardware deserves equal attention. A joystick that feels accurate on a modern USB adapter can behave quite differently when connected directly to an original machine. Ageing potentiometers, worn connectors, different controller designs and game-specific assumptions all affect the usable travel of an analogue axis.

A small Human68k calibration utility is a practical way to make that behaviour measurable. Rather than guessing at a dead zone or replacing a joystick immediately, the program can record the raw positions, identify the real centre and endpoints, and save values that other software can use. The project also provides a useful example of careful X68000 programming: access the hardware through suitable system interfaces, keep the display simple, and make every result reproducible.

Define the calibration problem

A joystick axis is usually represented as a numeric value rather than a direction. The physical control has a centre position, a minimum reached by moving fully one way, and a maximum reached by moving fully the other way. On an original X68000, the numbers returned by the joystick interface may not occupy the entire theoretical range. A nominal 8-bit axis might produce values such as 18 to 232, with the resting position around 126.

That distinction matters because many games interpret the centre and limits differently. A fixed midpoint of 128 may cause a character or cursor to creep if the controller rests at 135. A fixed dead zone may be too small for a noisy potentiometer and too large for a tight modern replacement. The utility should therefore measure the individual controller instead of treating the documented numeric range as a guarantee.

Calibration should produce at least three values for each axis: minimum, centre and maximum. It is also useful to record the observed spread while the stick is released. If the centre moves by several counts from sample to sample, the saved dead zone should be based on that movement rather than an arbitrary constant. The program can report these results in plain language, such as “horizontal centre 127, stable range 124–130”.

Choose a safe Human68k interface

The first implementation decision is how the program obtains joystick data. A well-behaved Human68k tool should use the available IOCS or library-level joystick routine where possible. This keeps the code compatible with different X68000 models and avoids relying on undocumented I/O details that may change with expansion hardware or emulator configuration. If direct hardware access is required for a particular experiment, isolate it behind a small function and document the assumptions clearly.

The program should also distinguish a missing reading from a genuine axis value. Some interfaces return button bits and axis data together, while others provide separate fields or status flags. Define a structure containing horizontal and vertical values, button state and a validity indicator. The rest of the application can then work with a clean record rather than repeatedly decoding hardware-specific bit fields.

A compact command-line program is appropriate for Human68k. It can run in a text console, display instructions, collect samples and write a small configuration file to disk. Keep the display within the conventional screen width used by the machine and avoid depending on ANSI features that may not be available in every shell. Building with a period-appropriate C compiler, or with a modern cross-development environment targeting Human68k, makes the source easier to preserve and rebuild later.

Sample the resting position

Calibration should begin with the stick released. Ask the operator to leave the controller untouched for a short settling period, then collect a block of readings at a steady interval. The interval does not need to be extremely fast; a sample every 10 to 20 milliseconds is sufficient for detecting drift while keeping the program simple. Store the values in a small integer array or update running statistics if memory is limited.

The centre should not be calculated from one reading. Use the median of the sample block, or discard the highest and lowest readings before calculating an average. A median is especially useful when an old potentiometer produces occasional spikes. Alongside the centre, calculate the lowest and highest resting values. These figures show whether the controller is electrically stable and give the operator a reason to clean or replace it before blaming software.

After the resting sample, display a clear instruction to move the stick fully left and fully right, holding it at each endpoint. Repeat the process for up and down. Several readings at each endpoint are preferable to one captured value because a mechanical joystick may not reach exactly the same position every time. Use the lowest observed value for one end and the highest observed value for the other, but retain a small margin if the endpoint is visibly noisy.

The user interface should make accidental calibration difficult. Require a button press to begin each stage, and provide a way to cancel without overwriting the previous file. This is particularly helpful when working with an X68000 beside a CRT in a cramped hobby room, where reading small text and holding the joystick steady can be awkward.

Convert raw values into useful output

Once the samples are collected, map the raw axis into a standard logical range. A common choice is 0 to 255, although a signed range such as -127 to 127 may be more convenient for game code. For a positive direction, a piecewise mapping is preferable:

• Values at or below the measured minimum map to the lower limit.
• Values between minimum and centre are scaled across the negative half.
• Values between centre and maximum are scaled across the positive half.
• Values at or beyond either endpoint are clamped.

Piecewise scaling matters because the centre is rarely exactly halfway between the two physical endpoints. A single formula based on minimum and maximum can leave a noticeable bias around the resting position. Integer arithmetic is adequate for the X68000, but use a wider intermediate type when multiplying so that extreme values cannot overflow before division.

The dead zone should be calculated around the measured centre. If the resting samples occupy 124 through 130, a calibration file might store a centre of 127 and an inner range of seven counts on either side. Values inside that band become zero or neutral. Outside it, the program should rescale the remaining travel so that the player still receives the full logical range without needing to push harder than necessary.

Avoid silently hiding poor hardware. If the measured endpoint is very close to the centre, or if the resting spread is unusually large, report a warning and allow the user to save the result only after explicit approval. A calibration utility should describe a failing controller, not turn unreliable readings into apparently precise data.

Design a durable calibration file

Human68k software benefits from a simple text format that can be inspected with ordinary tools. A file might contain a version number, controller or port identifier, horizontal minimum, horizontal centre, horizontal maximum, vertical minimum, vertical centre, vertical maximum and dead-zone values. One key-value pair per line is easier to edit than a binary structure and remains understandable decades later.

Include enough metadata to explain how the values were produced. A timestamp is useful, but the important details are the selected port, the software version and perhaps a short user label. If the X68000 has two controllers attached, never assume that calibration for the first port applies to the second. A replacement joystick, extension cable or adapter can change the readings enough to justify a separate profile.

Write the new file to a temporary name, flush it, and then rename it into place. This reduces the risk of leaving a truncated configuration after a reset or power interruption. Keep the previous profile as a backup, using a predictable extension or rotating filename. The same cautious approach is valuable when preserving other X68000 data; documenting cartridge ROM backups follows the same principle of making old software usable without losing the original reference material.

The runtime side can read the file at startup and fall back to sensible defaults if it is absent or malformed. Validate that minimum is below centre, centre is below maximum, and every value lies within the supported raw range. Invalid data should produce a readable error rather than causing a game or utility to behave unpredictably.

Test with hardware and emulators

Testing should cover more than a single controller. Try an original digital joystick, an analogue unit with ageing potentiometers, and any modern adapter commonly used with the X68000. Compare the displayed raw readings, the calculated centre and the feel of the rescaled output. An emulator can provide a useful repeatable test environment, but it should not replace testing on physical hardware because emulator input ranges are often cleaner and more symmetrical.

A simple live monitor is valuable during development. Show raw horizontal and vertical values, calibrated values, button states and a small bar or crosshair. The crosshair makes drift obvious without requiring the operator to interpret changing numbers. Add a slow-moving average only for display; preserve the raw samples for calibration decisions so that filtering does not conceal noise.

Australia’s local market can make this kind of testing more varied than expected. Original controllers appear through eBay Australia, Gumtree and retro-computing groups in Sydney, Melbourne and Brisbane, while imported parts may arrive with different plugs or adapter wiring. Allow for controllers that have been repaired or modified rather than assuming every unit matches a Japanese retail example. When buying a second-hand joystick, record its condition and connector arrangement alongside the calibration file.

Power and repair work also deserve care. Australian mains supply is nominally 230–240 volts at 50 Hz, and an X68000 power-supply repair should be completed before investigating input faults that may be caused by unstable rails. Disconnect the machine before opening it, use proper isolation and observe capacitor safety. Calibration cannot correct a supply problem that is affecting the computer’s input circuitry.

Integrate the tool with games and preservation

The utility can remain independent, but its greatest value comes when other Human68k programs can consume the saved profile. A small reusable conversion function can accept a raw reading and return a signed calibrated value, while a separate button routine handles digital input. Keeping these responsibilities separate allows games to choose their own response curves without duplicating the hardware calibration logic.

Provide a diagnostic mode that prints the original values as well as the converted values. This helps developers identify whether an unusual result originates in the joystick, the calibration file or the game’s movement code. It also creates a useful record when comparing a real X68000 with an emulator or a later hardware recreation.

Preservation projects benefit from recording the calibration tool’s source, compiler settings and sample configuration files. Store the source in a plain directory structure that can be copied to floppy disk, hard disk image or a modern repository. Include a short README describing the expected joystick interface, the raw range observed during development and the limitations of the implementation. Future users should be able to rebuild the program without guessing which headers or libraries were required.

A practical release can contain the executable, source code, example profile, test log and a brief licence notice. Keep the program small, avoid unnecessary resident components and make it safe to run from a write-protected disk. These choices suit the X68000’s original working environment while also making the project convenient for current enthusiasts using compact flash storage, SCSI2SD devices or emulation.

Build the utility around measured behaviour, conservative file handling and documented Human68k interfaces. Then test it with several controllers, publish the source and keep the calibration profiles with the hardware records. That small tool can turn an unpredictable joystick into a documented, repeatable input device and add another practical piece to the living history of the Sharp X68000.