If you're new to using CircuitPython, there's a full getting started guide here.

If you don't already have a preferred editor, Adafruit suggests using the Mu editor to edit your code and use the interactive REPL in CircuitPython. You can learn about Mu and installation in this tutorial.

Get the Code

Download the CircuitPython code from the GitHub repository.  You can use this download link to get a zip file, or, if you're familiar with Git, you can clone the repository with the following command:

git clone https://github.com/adafruit/glitterpos.git

git clone https://github.com/adafruit/glitterpos.git

Connect a USB cable to the Feather M4 Express, and use your computer to copy the contents of the glitterpos file folder to the CIRCUITPY drive that appears when you plug the Feather in. If you don't have a CIRCUITPY drive but do have a FEATHERBOOT drive, you will need to first load CircuitPython onto the Feather then load the libraries for talking to the sensors and radio.

Once the code is copied and the Feather has had a chance to reboot, you should see a test pattern appear on the NeoPixel ring:

At this point, the GlitterPOS box will wait until it has a GPS fix and then begin broadcasting and listening for coordinates.  There are a few more steps, however, before it's ready to use.

Configuration

On each box, you'll need to edit a configuration file called glitterpos_cfg.py:

"""Configuration values for the Glitter Positioning System."""

# id should be a unique integer value for each box:
MY_ID = 0

# Compass calibration values.  From the CircuitPython REPL, use `import
# calibrate` to find values for MAG_MIN and MAG_MAX:
MAG_MIN = [-0.1883, -0.16002, -0.53634]
MAG_MAX = [0.5887, 0.72618, 0.19474]

# Magnetic North - should be customized for your rough location:
DECLINATION_RAD = 0.1451 # Declination for Boulder, CO

"""Configuration values for the Glitter Positioning System."""

# id should be a unique integer value for each box:
MY_ID = 0

# Compass calibration values.  From the CircuitPython REPL, use `import
# calibrate` to find values for MAG_MIN and MAG_MAX:
MAG_MIN = [-0.1883, -0.16002, -0.53634]
MAG_MAX = [0.5887, 0.72618, 0.19474]

# Magnetic North - should be customized for your rough location:
DECLINATION_RAD = 0.1451 # Declination for Boulder, CO

MY_ID should be a unique integer.  For the first box, you should leave it set to 0.  On the second box, use 1, on the third use 2, etc. This number will be transmitted when the box sends coordinates over LoRa, and used by the other boxes to keep track of its position and choose a display color.

Compass Calibration

MAG_MIN and MAG_MAX are compass calibration values. They specify the minimum and maximum magnetometer values from the LSM9DS1. In order to get a reliable compass heading from your device, you'll need to set these for each box.

This process can be a bit finicky, so we've written code to simplify the task.  Begin by connecting to the serial console on the Feather M4 Express.

You should now see a stream of debugging information, including GPS fix quality, headings, and data packets sent:

Press Ctrl-C to interrupt the running code, and hit any other key to enter the CircuitPython REPL:

You'll be presented with a prompt.  Now, type import calibrate:

This will load and run a function that records minimum and maximum values for the magnetometer.  Now, move the box in a figure eight and rotate it around the x, y, and z axes multiple times until the MAG_MIN and MAG_MAX values don't appear to be changing.  Copy those values into your glitterpos_cfg.py.

Mike Tuupola has a good writeup on magnetometer calibration which goes into more detail.

Magnetic North

Because magnetic north varies from true north by different amounts depending on where you're at on the surface of the earth, you'll need to find the correct magnetic declination and set DECLINATION_RAD for your general location.

Start by finding your local declination. You can get this value from a few different places:

• magnetic-declination.com - offers a clickable map.
• The NCEI Magnetic Field Calculators - requires that you know either your coordinates, a local United States zip code, or a country and city.

Here's an example for Boulder, CO using the NCEI site:

And here's one using magnetic-north.com:

Both give positive 8 degrees, 19 minutes.  In order to use this, you'll need to convert it to radians.  In decimal degrees, that's 8*60 + 19 / 60 = 8.3166°.  To find radians, multiply by π/180:

8.3166 * (π/180) = 0.1451

So you can set DECLINATION_RAD = 0.1451 and be reasonably comfortable with the result.

Wolfram Alpha also provides a quick answer here:

With those values set on each GlitterPOS box, you should be ready to strike out and track your friends' whereabouts very imprecisely.