The CLUE Tracker Points You To A Target, Using CircuitPython

What Is a CLUE Tracker (and why it’s addictive)

A CLUE Tracker is a handheld gadget that shows your current GPS location, then points you toward a target
coordinate by displaying a compass heading and distance. Think “geocaching without the map” or “treasure hunt
mode” for real life. You’re not following turn-by-turn directions; you’re following the arrow of destiny (and
occasionally your gut).

The magic is that it can be surprisingly simple hardware: an Adafruit CLUE board for the screen + sensors, a
STEMMA QT GPS breakout for location, and a battery. No phone required, no internet required, and no “Allow
Location Access?” pop-up waiting to ruin your vibe.

This style of “point-to-target navigation” is useful for more than fun: hiking meetups, fieldwork, locating a
hidden campsite, or marking a “return here” spot while you wander. It’s also a great beginner-friendly intro to
navigation concepts: bearing, distance, heading, calibration, and why compasses sometimes act like they’re being
haunted.

Why CircuitPython makes this build ridiculously doable

CircuitPython is the friendly, maker-focused Python that runs on microcontrollers. The workflow is basically:
plug in the board → it shows up like a USB drive → edit code.py → save → the board re-runs your
program. It feels less like “embedded development” and more like “teaching a tiny computer new tricks.”

For a project like this, that matters. You’ll tweak target coordinates, adjust display layouts, smooth sensor
readings, and probably add one more feature because you can’t help yourself. CircuitPython keeps iteration fast
and the library ecosystem hugeespecially for Adafruit hardware (GPS drivers, display helpers, sensor wrappers,
BLE tools, and more).

Hardware checklist (minimal parts, maximum joy)

Core parts

• Adafruit CLUE (nRF52840) color display, buttons, buzzer, built-in sensors, and a STEMMA QT
  connector for I2C expansion.
• STEMMA QT GPS module the popular choice here is a compact GPS breakout that supports I2C
  (perfect for the CLUE’s STEMMA QT port).
• STEMMA QT/Qwiic cable the tiny JST-SH 4-pin cable that makes wiring feel like cheating.
• Battery a LiPo is common for portability; you can also use a battery pack depending on your
  setup.

Nice-to-haves

• Enclosure 3D printed or laser-cut; protects the parts and makes it feel “real.”
• On/off switch because unplugging a battery gets old fast.
• Optional buzzer/haptics tuning the CLUE’s beep is great for “getting warmer” feedback.

One of the coolest aspects of this build is how “weekend-project” it can be: the CLUE already includes a screen,
buttons, a buzzer, and motion sensorsso your external wiring can be as simple as “plug the GPS in and go.”

The navigation math: distance + bearing in plain English

Your GPS gives you latitude and longitude. Your target is another latitude and longitude. The tracker needs two
answers:

1. Distance: How far am I from the target?
2. Bearing: In what direction is the target from my current position?

There are fancy geodesy options (great-circle distance, rhumb lines, ellipsoid models), but for a handheld
“walk toward the prize” tool, the standard haversine distance + initial bearing
formula works well. It’s accurate enough for human-scale navigation and easy to compute on a microcontroller.

Distance (haversine)

Haversine estimates the great-circle distance between two points on a sphere. Earth isn’t a perfect sphere, but
it’s close enough for this useespecially if you’re not trying to dock a spacecraft.

Bearing (initial course)

Bearing is the angle (usually 0–360°) you’d face at your current position to head toward the target. If your
compass says you’re facing 40° and the target bearing is 70°, you need to turn 30° to the right. If the target
bearing is 10°, you’re almost thereunless your compass is lying, which we’ll address in a moment.

Example: CircuitPython math helper

Compass reality: heading, calibration, and declination

A CLUE Tracker needs to know which way you’re facing so it can point you toward the target. The CLUE board
includes a magnetometer as part of its sensor suite, which means you can compute a compass heading. But here’s
the deal: magnetometers are sensitive, dramatic, and easily offended by nearby metal, electronics, magnets,
batteries, and sometimes your own confidence.

1) Magnetic vs. true north (declination matters)

A magnetometer points to magnetic north, not true north. The difference is
called magnetic declination, and it varies depending on where you are on Earth. If you want your
bearing math (which is usually true-north based) to line up with your compass heading, you’ll want to correct
heading by adding declination (east positive, west negativedepending on the convention you choose).

Practical approach: store a declination value for your region and make it user-adjustable in code. If you’re
building a travel-ready device, consider letting the user input declination or selecting from presets.

2) Hard-iron and soft-iron distortions (a.k.a. “Why is my north over there?”)

If your device is near magnetic materials, your magnetometer readings can be shifted or stretched:

• Hard-iron distortion: constant offsets (like a nearby magnet pulling all readings).
• Soft-iron distortion: scaling/warping (like the magnetic field is being squished into an
  oval).

The beginner-friendly fix is a min/max calibration: rotate the device through many orientations,
record min and max values on each axis, compute offsets, and optionally scale axes so your “circle” looks more
like a circle. Is it perfect? No. Is it often “good enough” for walking toward a target? Absolutely.

3) Tilt compensation (because you rarely hold gadgets perfectly flat)

A simple 2D compass assumes the magnetometer is level. If you tilt the device, heading can drift. Tilt
compensation uses the accelerometer (and/or gyro) to correct the magnetometer vector so heading remains stable
even when you’re holding the device at an angle. This is one of those upgrades that makes a project feel
“professional.”

If you want a pragmatic middle ground: you can start without tilt compensation and add it later. Just put a note
on-screen like “Hold flat for best accuracy” until you’re ready to level up.

Quick and usable heading code (with calibration + declination)

That’s the “works today” version. As you improve the tracker, you can add soft-iron scaling and tilt
compensationboth of which can dramatically reduce that “why is it pointing at the snack table?” problem.

Putting it together: CircuitPython structure + example code

The CLUE Tracker concept breaks neatly into four loops that run forever:

1. Read GPS (lat, lon, fix quality, satellites, time)
2. Read heading (magnetometer; optionally tilt-compensated)
3. Compute distance + bearing to the target
4. Render UI (numbers + arrow + “you’re getting close” feedback)

Step 1: Set up CircuitPython and libraries

Install CircuitPython on the CLUE (UF2 drag-and-drop), then copy the required libraries into
/lib on the CIRCUITPY drive. At minimum, you’ll typically use:

• adafruit_clue (easy access to screen + sensors)
• adafruit_gps (GPS parsing)
• displayio / adafruit_display_text (rendering)

Step 2: Connect the GPS module via STEMMA QT

If your GPS breakout supports I2C (many STEMMA QT GPS boards do), you can connect it directly to the CLUE’s
STEMMA QT port. That means no soldering and no pin-mapping headaches. Just plug in the cable,
and you’re already 80% done. (The remaining 20% is you arguing with a compass. It’s tradition.)

Step 3: A practical “target pointer” example

The following code is a compact, readable starting point. It:

• Reads GPS coordinates
• Computes distance and bearing to a fixed target
• Reads a basic heading from the magnetometer
• Shows “turn left/right” guidance and an arrow-friendly delta angle

Step 4: Make the arrow feel “alive”

The code above provides a signed delta angle, which is the secret sauce for UI. Once you have that number, you
can:

• Draw a rotating arrow sprite
• Pick one of eight compass arrows (↑ ↗ → ↘ ↓ ↙ ← ↖)
• Use sound patterns: faster beeps as dist shrinks
• Flash the NeoPixel when you’re aligned

A good first upgrade is “8-direction arrow mapping” because it’s simple and surprisingly satisfying.

Pro tips and real-world gotchas

GPS doesn’t love ceilings

If you test indoors, you may wait forever for a fix. GPS works best with open sky. For quick testing, step
outside, let it lock, then walk around while watching distance change. That first moment when “Dist” updates as
you move is wildly satisfying.

Keep magnets and power wires away from the magnetometer

Your battery, charging cable, and nearby electronics can distort compass readings. If your heading jumps around
near the battery, try repositioning the GPS/battery in the enclosure, or add calibration and smoothing.

Smoothing is not cheating

Sensor readings can jitter. A simple moving average or exponential smoothing on heading and distance can make
the interface feel calmer. Your user experience improves instantly, and your tracker stops acting like it drank
three espressos.

Arrival radius beats “exact coordinate”

GPS accuracy varies. Declaring “ARRIVED” within 10–25 meters usually feels right. If you demand perfect
precision, you’ll end up wandering in circles like you’re auditioning for a nature documentary.

Fun upgrades: waypoints, haptics, and “hot/cold” modes

Multiple targets (waypoints)

Store a list of targets and let Button A/B cycle through them. Suddenly your tracker becomes a pocket waypoint
navigator. Great for hikes (“waterfall,” “car,” “campsite”) or scavenger hunts.

“Set target to current location”

One button can “drop a pin” by saving your current GPS position as the target. That’s a practical feature for
returning to a spotespecially if your sense of direction is… aspirational.

BLE beacon mode

The CLUE’s nRF52840 supports Bluetooth LE, which opens the door to games like hide-and-seek using RSSI signal
strength. RSSI-based distance is noisy, but as a “getting warmer” mechanic it’s fantasticespecially indoors
where GPS is weak.

Conclusion

The CLUE Tracker is the perfect blend of practical and playful: a tiny navigator that teaches real concepts
(bearing, distance, heading, calibration) while still feeling like a gadget from an adventure movie. With
CircuitPython, the barrier to entry is low and the ceiling is highyou can start with a simple target arrow and
evolve it into a full waypoint tool, a geocaching companion, or a beacon-powered party game.

Start simple: get GPS working, compute distance/bearing, show the numbers. Then add the “delight layer”: arrows,
beeps, smoothing, and calibration. Before you know it, you’ll be pointing at a target with a grin that says,
“I built this,” which is the best compass direction of all.

SEO Tags (JSON)

Field Notes: of CLUE Tracker War Stories

The first time you take a CLUE Tracker outside, you’ll learn a humbling truth: nature does not care that your
code is elegant. Nature cares about “open sky,” “magnetic interference,” and whether you remembered to charge
the battery. My personal favorite testing location is a parking lot, because it offers two critical resources:
sky and snacks. If your GPS won’t lock, you can at least emotionally recover with a granola bar.

Here’s what usually happens. You step outside, power up, and stare at “GPS: acquiring fix…” like it’s a dramatic
season finale. After a minute, you start bargaining. “If you get a fix, I’ll finally label my cables.” Then it
locks, satellites appear, and you feel like a wizarduntil the compass tells you north is suspiciously close to
“that random sedan.”

That’s when you do the calibration dance. If someone’s watching, it looks like you’re trying to summon rain.
You rotate the device slowly, then faster, then in a figure-eight, then you hold it up like Simba because maybe
the sky needs to see it. The good news: calibration works. The bad news: you will forget you calibrated it, put
it near a metal water bottle, and immediately un-calibrate it with enthusiasm.

The funniest bug I’ve seen is the “infinite confidence arrow.” Your code draws a bold arrow and prints “ON
COURSE,” but you’re walking into a bush. The numbers say you’re getting closer, but the path says you’re about
to meet a thorny plant on a first-name basis. That’s when you remember: this device points you toward a
coordinate, not toward a safe route. The CLUE Tracker is a navigator, not a therapist. It will not stop you
from making choices.

Another classic moment is declination. You set a target, your bearing math is correct, your compass heading is
stable, and yet the arrow is consistently off by a chunk of degrees that feels too large to be “noise.” That’s
the Earth politely reminding you that magnetic north and true north are not the same thing, and it would like
credit for being complicated. The fix is simpleadjust declinationbut the emotional damage is permanent. You
will never again trust “north” without asking, “Which one?”

Once you get it dialed in, the tracker becomes weirdly addictive. You start setting targets just to watch the
distance drop. You’ll pick a nearby landmark“that bench”and follow the arrow like you’re in a video game with
one quest: Bench Acquisition. And when it finally reads “ARRIVED 🎉,” you’ll feel a ridiculous sense of victory,
because you didn’t just go somewhereyou computed your way there. That’s the whole charm: it turns movement into
feedback, and feedback into a grin.

Final tip from the field: when the tracker works perfectly, don’t immediately add five features at once. Make
one small upgradean 8-direction arrow, a nicer font layout, a smoother heading filterthen test again. The CLUE
Tracker rewards patience. Also, it rewards snacks, but that’s true of most engineering.