Geocaching Tour Guide

In this learn guide we’re building a GPS tour guide. When we get to a location, it’ll display an image on screen and playback music or audio clips. This uses the Adafruit HalloWing and Ultimate GPS FeatherWing. All of the components are housed in our 3D printed case that snaps together.

Location Based Images & Audio

When the device is nearby a logged location,  a green circle will appear on screen. Once the coordinates are close, a custom image displays on screen and music starts playing! This is totally customizable so imagine unlocking secret music or sounds at geocached locations. So you can get creative and theme it out to fit your project.

This is written in Adafruit’s Circuit Python so we can easily add and edit locations in a txt file.  The HalloWing works like a USB drive so all of the libraries and assets are stored on the device. This means you can write code and make quick changes on any computer.

Prerequisite Guides

If you're new to Adafruit Feather M4 Express, CircuitPython or soldering, take a moment to walk through the following guides to get you started.

Geocaching Music Player

We took this to Disney’s Epcot so the national anthems will play while we walk through World Showcase.

Circuit Diagram

This provides a visual reference for wiring of the components. They aren't true to scale, just meant to be used as reference. This diagrams was created using Fritzing software.

Adafruit Library for Fritzing

Use our Fritzing parts library to create circuit diagrams for your projects. Download the library or just grab the individual parts. Files are hosted on our github repo linked below.

Wired Connections

Ultimaker GPS FeatherWing

  • EN pin to Switch
  • GND pin to Switch

HalloWing M0 Express

  • Speaker port to Speaker
  • Battery port to 400mAh battery
  • Sense port to Button


The Adafruit HalloWing M0 Express can be powered via USB or JST-PH using a 3.7v lipo battery. In this project, a 4400mAh lipo battery is used. The lipo battery is rechargeable via the USB port on the Adafruit HalloWing M0 Express.

Setup Adafruit HalloWing M0 for CircuitPython

Your HalloWing M0 should already come with CircuitPython but maybe there's a new version, or you overwrote your board with Arduino code! In that case, see the below for how to reinstall or update CircuitPython. Otherwise you can skip this and proceed with the build.

CircuitPython Libraries

Install the following Adafruit libraries for Circuit Python by downloading the latest bundle. Unzip the file and locate the needed libraries. Drop the libraries into a folder named "lib" on the CIRCUITPY drive.

Required CircuitPython Libraries:

  • adafruit_bus_device
  • adafruit_gps.mpy
  • adafruit_debouncer.mpy

Before continuing make sure your board's lib folder or root filesystem has the adafruit_bus_device, adafruit_debouncer.mpy and adafruit_gps.mpy files are copied over.


The screen on the HalloWing will display a welcome message and proceed to acquire GPS satellites. Once it has acquired a fix, an audible "chirp" will sound letting you know it's ready. Depending on the location, a colored circle will appear on the display. A red circle means the locations are far way, yellow is close and green is nearby. Once a location is targeted, an image of the establishment will be displayed, followed by an audible name of the location and detailed description. Pressing the button will replay the name and detail audio if at a current location. 

Upload The Code

Copy and paste the code below into a new text document (we recommend using Mu as your editor, which is designed for CircuitPython.). Save the file and name it as

Once the files has been uploaded to the drive, the board will automatically reboot and run the code.

GPS Locations

Use the locations.txt file to add, remove or change locations. The structure of the locations are setup in a chronological order, followed by longitude, latitude, name of bitmap image, name of title wav file, and name of details wav file. Here's an example of a location.


Image Assets

Bitmap images reside on the root of the CIRCUITPY drive (Image must be in the bitmap format). The "welcome", "missing" and "acquiring fix" messages are bitmap images, as well as the green, yellow and red circles. Images of the locations can be renamed and modified – These will need to be 128 pixels by 128 pixels in size. Location image file names must match the titles in the locations.txt file.

Audio Files

The audio files can be changed to whatever sounds you'd like, just make sure they're in the right file format and title matches the code and locations.txt file. Audio files need to be in the following format.

  • WAV, Mono PCM, 11.025kHz

See this guide on how to convert audio formats for microcontroller projects.

3D Printed Parts

Parts are designed to be 3D printed with FDM based machines. STL files are oriented to print "as is". Parts are listed below with file name and description. Parts require tight tolerances that might need adjusting slice setting. Reference the suggested settings below.


Houses most of the electronis.


Snap fits over the display window cutout. 


Snap fits over the box enclosure.


Attaches to box and secures button with screws.

Slice Settings

Use these settings as reference. Values listed were used in Ultimaker's CURA 3.X slicing software.

  • 0.2mm Layer Height / 0.4mm nozzle
  • 0.38mm Line Width (inner & outer widths)
  • 60mm/s printing speed
  • 20% infill

Tap Mounting Holes

I used a set of screw taps to create threads in the various mounting holes. This greatly improves fastening screws. of the A mix of metric sizes are used here. M2.5 tap for the GPS FeatherWing. M2 tap for the button.

Install Bezel

The bezel features four posts that snap fit into the holes of the top cover. Reference the photo and orient the bezel with the top cover. Press the bezel onto the top cover.



Design Source Files

The enclosure assembly was designed in Fusion 360. This can be downloaded in different formats like STEP, SAT and more. Electronic components like the board, displays, connectors and more can be downloaded from our Fusion 360 CAD parts github repo.

Glitter Infused Filament from Fillamentum

The material used to print the some of the parts in this project are from Fillamentum. From the PLA Extrafill line of filaments, Vertigo Galaxy PLA and  Rapunzel Silver PLA was used. Translucent PLA material was used to print the bhl-headlight-b.stl part.

Install Headers on GPS FeatherWing

The GPS FeatherWing comes with two headers. Cut the headers so there's a 12-pin and a 16-pin. Match the headers with pins on the GPS FeatherWing and fit them under the PCB. Each header will need to soldered to the pins on the FeatherWing. I recommend seating the headers to a breadboard to make soldering easier – This keeps the header pins in place while soldering. 




Note about short headers

I recommend using standard headers. Short headers for the Adafruit Feather boards are available but the 3D printed base was designed around the standard headers. If you do use short headers, the microUSB port will not line up with the hole on the case.

Wiring Button

Use a 3-pin JST-PH cable to connect the button to the sensor port on the HalloWing. Cut the cable so it's at least 76mm(3in) in length. The button only needs two wired connections so we can cutoff the red (middle) wire from the cable. Using wire stripper, remove a bit of insulation. To make it easier to attach the wire to the button, tin the exposed strands of wire with a bit of solder. 



Attaching Wires to Button

The button features two sets of contacts. We only need one set of pins to connect the wires. Polarity doesn't matter for the wires but we need to use the contacts that are not shared. The photo on the left shows which pins are being shared. The wires need to connect to one red pin and one blue pin.

Connect Wires to Button

I suggest using a pair of third helping hands to hold the button in place while soldering. Solder the two wires to the pins on the button. The JST-PH connector from the cable plugs directly into the sense port on the HalloWing M0 Express.




Wiring Slide Switch

We'll need a set of wires to connect the slide switch to the GPS FeatherWing. I suggest using a 4-wire ribbon cable to keep the wires bundled together. The slide switch only needs two wires, so we can peel off a 2-wire set from the ribbon cable. The wire set should be at least 78mm (3in) in length.  Using wire strippers, remove a bit of insulation from the tips of each wire. To make it easier to attach the wires to the pins on the switch, apply a bit of solder to the exposed stands of wire.




Connect Wires to Switch

I suggest using third helping hands to secure the slide switch while soldering. The slide switch only needs two pins wired, one middle pin and either the far left or right. 



Connect Switch to GPS Feather Wing

The two wires from the switch need to connect to the EN and GND pins on the GPS FeatherWing. I suggest using a vise to secure the PCB while soldering. Solder the two wires to the pins on the bottom of the GPS FeatherWing PCB – This will make the assembly easier once we secure the PCB to the 3D printed enclosure.

Installing Button

The button is attached to the 3d printed case using a bracket and two M2 x 5mm flat head metric machine screws. Press the button through the hole in the side of the case. Hold it in place and fit the bracket over the body of the button. 




Secure Button

Insert and fasten the machine screws through the mounting holes on the side of the 3d printed case. Make sure the mounting holes on the bracket are lined up with the holes on the case.




Install GPS FeatherWing

We'll need four M2.5 x 5mm flat head metric machine screws. Place the GPS FeatherWing PCB over the four standoffs on the case (the orientation needs to match the photo). Hold the PCB in place while driving the machine screws into the standoffs.




Secured GPS FeatherWing

The PCB should be flush with the standoffs. Double check to ensure the PCB is in the correct orientation.

Install Slide Switch

Grab the slide switch and press it into the holder on the case. Insert it at an angle so the actuator on the switch fits through the small hole on the case.

Switch Actuator

Test the switch by sliding the actuator. The switch holder should keep it in place. If you have issues keeping the switch in place, use super glue to adhere it to the case.

Connect Battery

The HallowWing has a built-in ON/OFF slide switch. Since we are using an external slide switch, I suggest setting the built-in switch to the OFF position (we'll turn it on later in the assembly). Plug in the JST-PH cable from the battery into the power port on the HalloWing.

Connect Speaker

Plug in the oval speaker to the audio port on the HalloWing. This uses a "Molex PicoBlade" (1.25mm pitch 2-pin) cable, which makes plugging into a board easy.

Installing Components

Double check the components are properly oriented before proceeding with the assembly. Follow the photo for reference.

Connect Button

Plug in the 3-pin JST-PH connector from the button to the sense port on the HalloWing.

Installing Speaker

Peel the sticker from the oval speaker (pull on  the little tab). Place the speaker sticky side down onto the oval shaped holder inside the case. 



Secure Battery

The battery can be placed inside the case, next to the push button. To keep the battery in place, I used small pieces of mounting tack to keep the battery from shaking around inside the case.

Install HalloWing to GPS FeatherWing

Place the HalloWing over the GPS FeatherWing and check the headers are oriented correctly. Carefully press the HalloWing onto the GPS FeatherWing, making sure the header pins are aligned.

Fit Wires

Excess wiring can be tucked underneath the PCB and inside case.

Turn On HalloWing

Using a set of tweezers, flip the built-in slide switch so it's set to the ON position on the HalloWing. If it's left on the OFF position, the slide external switch can not power the circuit.

Install Top Cover

Get ready to fit the top cover onto the case. Reference the photo for the correct orientation.

Snap Fit Top Cover 

Fit the cover onto the case. Make sure the bezel does not obstruct the display on the HalloWing. Slowly and gently!

Install Lanyard

The case has two tabs on the outside for clipping a lanyard. 

USB Port

The microUSB port on the HalloWing is accessible through the hole on the side of the top cover. 



Final Test

Powering on the circuit should display the welcome message, followed by the acquiring fix image (these can be changed by updating the bitmap images). The GPS fix works best outdoors and can take a few minutes.

Use it!

There's some interesting ideas that can be done with just a few changes to the image and audio assets.

  • museum art exhibits details or history
  • unlock messages ILR RPG game style
  • play music at landmark locations

This guide was first published on Nov 27, 2018. It was last updated on Mar 08, 2024.