IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation: the Raspberry Pi 5, the GY-271 magnetometer and the 2.4-inch TFT with the compass card

IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation

40
700
60
25
60
PCBWay

Hello friends, I hope you all are doing great. Today, I am going to share the IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation, the thirtieth project of our IoT Projects series. If you have searched for a Proteus simulation of a Raspberry Pi compass with a GY-271 magnetometer and a TFT display, here is a complete one. A Raspberry Pi 5 reads the Earth's magnetic field from a QMC5883L on a GY-271 module, works out the heading, draws a turning compass card on a 2.4-inch ILI9341 TFT, calibrates out a magnet fixed near the sensor, adds the magnetic declination, warns when something disturbs the field, and serves a live web dashboard that you can open on a laptop or a phone.

A digital compass is in every phone, drone and car navigation system, and it is more interesting than it looks: the sensor measures a tiny field, about a hundred times weaker than a fridge magnet, and anything magnetic near it pulls the reading off. In this tutorial, we will go through the circuit, learn what a magnetometer measures and how the heading comes from two of its axes, read the QMC5883L over I2C, see why a nearby magnet ruins the heading and how a calibration turn removes it, add the declination, drive the ILI9341 over SPI and draw on it from frame buffers, walk through the Python program, and then run the simulation: the board turned to north, east and southwest, a magnet on the board, a calibration while the board spins, the declination, and a tilt that shows why phones also need an accelerometer. At the end, you can download the project with the program, every library file and the Python runtime the Pi needs.

NOTICE: Our team has put a lot of effort into this project: the circuit, the code and every part in the simulation are our own work, and you get them all free. Your feedback is the fuel that keeps us going, so please tell us what you think in the comments below. And if our free projects help you, you can buy us a coffee. So, let's get started with the IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation:

IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation: the Raspberry Pi 5, the GY-271 magnetometer and the 2.4-inch TFT with the compass card
Figure: The Raspberry Pi 5 digital compass in a Proteus simulation.
Raspberry Pi 5 digital compass Proteus simulation: the ILI9341 compass card turning, the magnet, the calibration and the tilt
Figure: The digital compass simulation in motion: north, east, southwest, a magnet, the calibration turn, the declination and a tilt.

What Does This Digital Compass Do?

  • Measures the Earth's field: X, Y and Z from a QMC5883L, 30 counts a microtesla, 200 readings a second.
  • Works out the heading: 0 to 360 degrees clockwise from magnetic north, and the 16 compass points.
  • A turning compass card: drawn on a 2.4-inch TFT, N always pointing north, a yellow mark where the board points.
  • Calibrates out magnets: one full turn of the board finds the hard-iron offsets.
  • Adds the declination: the angle between magnetic and true north, in half-degree steps.
  • Warns of disturbance: a horizontal field far from its calibrated strength means a magnet nearby or a tilted board.
  • A dashboard: the heading, the field, the offsets, CAL and the declination from a laptop or a phone.

It is a great project for learning I2C, SPI, a little trigonometry and the art of calibration. In the simulation, the GY-271's pop-up turns the board, puts a magnet on it and tilts it, and the TFT's pop-up shows the screen.

Components Used in the Proteus Simulation

All the parts come from our Proteus libraries, each with its own tutorial. The project zip at the end includes every LIB and DLL file.

The parts of the digital compass and their library posts
PartProteus deviceLibrary postConnection
Raspberry Pi 5RASPBERRY PI 5Raspberry Pi 5 Library for ProteusPI1, Ethernet 192.168.1.51
GY-271 with the QMC5883LQMC5883LADVTEPHMC5883L / QMC5883L Compass Library for ProteusU1, I2C1 at 0x0D
TFT 2.4" ILI9341, 320 x 240TFT24ILI9341ADVTEPTFT ILI9341 Library for ProteusTFT1, SPI0 CE0
Laptop WiFi MonitorLAPTOP WIFI MONITORLaptop WiFi MonitorPC1
Mobile WiFi MonitorMOBILE WIFI MONITORMobile WiFi MonitorMOB1

Both parts are models with pop-ups. The GY-271's pop-up sets the board's heading, puts a magnet on it, tilts it or turns it a full circle, and shows what the program read, the heading from that reading, the chip's registers and the last I2C transaction byte by byte. The TFT's pop-up shows the screen, the commands the controller received and the SPI traffic.

Proteus Simulation of the Digital Compass: the Circuit

Digital compass Proteus simulation circuit: the Raspberry Pi 5 with the GY-271 magnetometer and the 2.4-inch ILI9341 TFT
Figure: The complete circuit of the digital compass on an A3 Proteus sheet.
The Raspberry Pi 5 connections
PartPinsRaspberry Pi 5 header
U1 GY-271VCC / GND / SDA / SCL3V3 (pin 1) / GND (pin 6) / SDA1 GPIO2 (pin 3) / SCL1 GPIO3 (pin 5)
TFT1 ILI9341CS / DC / RESETCE0 GPIO8 (pin 24) / GPIO25 (pin 22) / GPIO24 (pin 18)
TFT1 ILI9341SDI / SCKMOSI GPIO10 (pin 19) / SCLK GPIO11 (pin 23)
TFT1 ILI9341VCC / LED / GND3V3 (pin 1) / 3V3 (pin 1) / GND (pin 6)

The GY-271 shares the Pi's I2C bus and takes its 3.3 V from the header. The TFT sits on SPI0 with two extra pins: DC tells the controller whether a byte is a command or data, and RESET restarts it. Its VCC and its backlight LED take the Pi's 3.3 V too, and its logic pins work at the Pi's 3.3 V levels. The touch controller's pins stay unused. (Many 2.4-inch modules also have a regulator and accept 5 V on VCC; at 3.3 V, some of them want the regulator bypassed with the J1 jumper - check yours.)

How the Digital Compass Works

What a Magnetometer Measures

The Earth's magnetic field points north and, in most places, also down into the ground: in the simulation it is 50 microtesla, 60 degrees below the horizon, so 25 microtesla point north and 43.3 point down. The QMC5883L measures the field along its three axes with magnetoresistive sensors, 16 bits each. At its plus or minus 8 gauss range, 3,000 counts are one gauss, so 30 counts are one microtesla. Lying flat, the chip's X and Y axes see only the horizontal, northward part of the field, split between them by the board's heading.

The Heading from Two Axes

With the board flat, X = 25 cos(heading) and Y = 25 sin(heading), so the heading is atan2(Y, X), turned into degrees from 0 to 360. Worked example from our run: at the start the program read X = 23.1 and Y = 1.5 microtesla, and atan2(1.5, 23.1) = 3.7 degrees, although the board pointed exactly north. Every real chip has small offsets of its own, here a few tenths of a microtesla on each axis, and they are enough to move the heading by almost 4 degrees. The program averages four readings as vectors, not as angles, so 359 and 1 degree average to 0, not to 180.

Hard Iron and the Calibration Turn

A magnet, a steel screw or a speaker near the sensor adds its own constant field, and it turns with the board. Turn the board a full circle and the X and Y readings, which should draw a circle around zero, draw the same circle shifted: its centre is the unwanted field, the hard-iron offset. The calibration therefore asks for one full turn and keeps the lowest and the highest X and Y: the middle of each range is the offset, and half the range is the true horizontal field. Worked example: if X runs from 10 to 60 microtesla during the turn, its offset is 35 and the field 25. After that, the heading is atan2 of the readings minus the offsets.

Declination and Disturbance

A compass points to magnetic north, not to the geographic North Pole. The angle between them, the declination, depends on where you are, and it is a few degrees in most countries; east is positive. The program simply adds it. It also watches the strength of the corrected horizontal field: if it moves more than 25 percent away from the calibrated value, something magnetic is near the sensor, or the board is tilted, and the heading is not to be trusted. The screen and the dashboard then say DISTURBED.

Drawing on the ILI9341

The ILI9341 controls a 240 x 320 glass. The Pi sends it commands with DC low and their data with DC high: SLPOUT wakes it, COLMOD 0x55 picks 16 bits a pixel, MADCTL 0xE8 turns the picture to landscape, 320 x 240, the right way up with the module's header on the left, and DISPON switches the glass on. To draw, the program sets a window with CASET and PASET and sends RAMWR followed by the window's pixels, two bytes each in the RGB565 format: 5 bits of red, 6 of green, 5 of blue. Worked example: red is 0xF800, yellow 0xFFE0. The controller takes writes up to 10 MHz, so the program asks for exactly that; in the simulation the Pi's SPI ran at 8 MHz, as the TFT's pop-up measured, safely below the limit.

Sending pixels one by one would mean thousands of tiny SPI transfers. Instead, the program draws each part of the screen into a frame buffer in the Pi's memory and sends it in one write: the compass card is 200 x 200 pixels, 80,000 bytes, 80 ms at 8 MHz, sent only when the heading changes by half a degree. The text uses our own 5 x 7 pixel font, scaled up.

The Python Code Explained

The whole program is included in the download. It uses lgpio for the I2C bus and the TFT's DC and RESET pins, spidev for the SPI bus, the math module for the angles, threads for the compass and the calibration, and the standard library's http.server for the dashboard. At the top are the numbers:

COUNTS_PER_UT = 30.0                                     # +-8 G: 3000 counts a gauss
CAL_S = 10.0                                             # s of turning for a calibration
H_NOMINAL = 25.0                                         # uT: the horizontal field before a calibration (50 uT, 60 degrees down)
DISTURBED = 0.25                                         # the horizontal field off by more than 25 %: something magnetic nearby

The QMC5883L

        lgpio.i2c_write_byte_data(self.h, 0x09, 0x1D)    # OSR 512, +-8 G, 200 Hz, continuous
        n, b = lgpio.i2c_read_i2c_block_data(self.h, 0x00, 6)
        v = [int.from_bytes(bytes(b[k:k + 2]), 'little', signed=True) for k in (0, 2, 4)]

The Heading and the Calibration

        heading = (math.degrees(math.atan2(ay, ax)) + decl) % 360
            s['off_x'], s['off_y'] = (hi[0] + lo[0]) / 2, (hi[1] + lo[1]) / 2
        disturbed = abs(h_ut - h_ref) > DISTURBED * h_ref

The TFT

        self.cmd(0x36, [0xE8])                            # landscape, header on the left (row / column exchange + both mirrors), BGR
        self.cmd(0x2A, [x >> 8, x & 0xFF, (x + w - 1) >> 8, (x + w - 1) & 0xFF])
            self.spi.writebytes2(data)

The compass card turns by minus the heading, so its N stays on magnetic north while the yellow mark at the top shows where the board points:

        a = math.radians(deg - heading)

The pages are / (the dashboard), /cal (a 10-second calibration), /decl_down and /decl_up (the declination -/+ 0.5 degree) and /data (JSON). The dashboard puts its links first and stays short, because the WiFi Monitors show one screen of a page.

How to Run the Proteus Simulation

  1. Download the project zip below and install the library files and the TEPPi folder (the steps are under the download button).
  2. Open Pi-5-Digital-Compass.pdsprj from the Proteus Simulation folder. Keep digital_compass.py and the DLL files next to it.
  3. Press Play. The TFT shows the compass card with the board pointing north.
  4. In the GY-271's pop-up (U1), turn the board with the compass points or the -15 / +15 buttons.
  5. Open the Laptop WiFi Monitor (PC1) or the Mobile WiFi Monitor (MOB1) and press Go.
  6. Put the MAGNET on the board, press CAL on the dashboard and, within 10 seconds, ROTATE 360 in the pop-up.

Simulation Results: the Digital Compass in Proteus

Here is the run that made the screenshots of this tutorial, 47.5 seconds of simulation. The times are the program's own, the seconds since it started, as it printed them in the Pi's terminal.

Pointing North

The program starts with the board pointing exactly north and reads 3.8 degrees N, with a horizontal field of 23.1 microtesla instead of 25. That is the chip's own small offsets at work, as in the worked example above: a real chip is never perfect. The TFT shows the card with N at the top, under the yellow mark, and the dashboard says NOT CALIBRATED.

Raspberry Pi 5 terminal in the Proteus simulation: digital_compass.py starts and reads 3.8 degrees north
Figure: The Pi's terminal at the start: the first heading and the dashboard address.
GY-271 QMC5883L pop-up in the Proteus simulation: the board at north and the readings of the three axes
Figure: The GY-271's pop-up: the board at 0 degrees, the Earth's field 50 microtesla, 60 degrees down, and what the program read.
TFT ILI9341 pop-up in the Proteus simulation: the compass card at north, 003 degrees, OK
Figure: The TFT at the start: the card at N, 003 degrees, 23.1 microtesla, OK.
Laptop WiFi Monitor in the Proteus simulation: the digital compass dashboard
Figure: The dashboard on the laptop: the heading, the field, the offsets and the declination.
Mobile WiFi Monitor in the Proteus simulation: the digital compass dashboard on a phone
Figure: The same dashboard on the phone.

Turning the Board: East and Southwest

At 8.4 seconds the board turns to east in the GY-271's pop-up. The program follows it through NNE, NE and ENE to 94.3 degrees E, and the card turns the other way: N now points to the left of the screen, because magnetic north is on the board's left when it faces east. At 11.9 seconds the board faces southwest and the heading reads 219.2 degrees SW. Without a calibration, the chip's offsets still cost a few degrees.

TFT pop-up in the Proteus simulation: the compass card turned, the heading 094 degrees east
Figure: The board facing east: the card turned, 094 degrees E.
GY-271 pop-up in the Proteus simulation: the board turned to east, the readings of the axes
Figure: The GY-271's pop-up with the board at 90 degrees.
TFT pop-up in the Proteus simulation: the heading 219 degrees southwest
Figure: Southwest: 219 degrees SW.
Laptop dashboard in the Proteus simulation: the heading southwest before a calibration
Figure: The dashboard at southwest.

A Magnet on the Board

At 14.5 seconds a magnet goes on the board, fixed to it like a speaker or a steel screw would be. The pop-up shows what it adds: X +35, Y -22 and Z +18 microtesla, more than the Earth's own horizontal field. The heading jumps to 291.8 degrees WNW although the board still faces southwest, 67 degrees off, and the program prints "DISTURBED: the horizontal field 41.6 uT, expected 25.0". The screen and the dashboard both turn red.

GY-271 pop-up in the Proteus simulation: a magnet on the board pulls the heading 67 degrees off
Figure: The magnet on: the reading says 292 degrees W while the board faces 225 degrees.
TFT pop-up in the Proteus simulation: the heading pulled to 292 degrees WNW, DISTURBED
Figure: The TFT: 292 degrees WNW, 41.4 microtesla, DISTURBED.
The Raspberry Pi 5 digital compass Proteus simulation running with a magnet on the board
Figure: The whole simulation with the magnet on the board.
Laptop dashboard in the Proteus simulation: DISTURBED, the horizontal field 40.9 microtesla
Figure: The dashboard: DISTURBED, the horizontal field 40.9 microtesla against the expected 25.

The Calibration Turn

At 20 seconds CAL on the laptop starts a 10-second calibration, and ROTATE 360 in the pop-up turns the board a full circle in 8 seconds. Watch the heading during the turn: it does not go round, it swings from 304 to 351 degrees, back to 301, and so on. That is what a strong hard-iron offset does: the circle of readings is shifted so far that it no longer surrounds zero, and atan2 only sweeps part of the compass. The program does not care: it only keeps the lowest and the highest X and Y.

Laptop dashboard in the Proteus simulation: CAL started, turn the board a full circle
Figure: CAL pressed on the laptop: "turn the board a full circle now".
TFT pop-up in the Proteus simulation: the card during the calibration turn, CAL
Figure: During the turn: the screen says CAL, and the horizontal field reaches 53.5 microtesla.

At 30 seconds: "CAL done: X 8.4 to 58.0, Y -45.8 to 4.5 uT - offsets X 33.2, Y -20.6 uT, the horizontal field 25.0 uT". The offsets are the magnet's +35 and -22 plus the chip's own small offsets, and half the range gives exactly the Earth's 25 microtesla. With the magnet still on the board, the heading now reads 224.4 degrees SW: the board faces 225 degrees.

TFT pop-up in the Proteus simulation: calibrated, 224 degrees southwest with the magnet still on
Figure: Calibrated: 224 degrees SW, 25.0 microtesla, OK, with the magnet still on the board.
GY-271 pop-up in the Proteus simulation: the readings after the calibration, the magnet still on
Figure: The GY-271's pop-up after the calibration: the readings have not changed, the program's maths has.
Laptop dashboard in the Proteus simulation: CALIBRATED, offsets X 33.2 and Y -20.6 microtesla
Figure: The dashboard: 224.4 degrees SW, CALIBRATED, offsets X 33.2 and Y -20.6 microtesla.

The Declination

From 33.8 seconds, DECL +0.5 on the phone four times sets the declination to +2.0 degrees, as for a town where magnetic north lies 2 degrees east of true north. The heading moves from 224.4 to 226.5 degrees: it now gives the direction from true north.

Phone dashboard in the Proteus simulation: the declination set to +2.0 degrees
Figure: The phone after four presses of DECL +0.5: the declination +2.0 degrees.
TFT pop-up in the Proteus simulation: 227 degrees southwest with the declination added
Figure: The TFT: 227 degrees SW with the declination.

Tilting the Board

At 38.6 seconds TILT 30 tilts the board by 30 degrees. Part of the Earth's strong downward field now falls on the chip's X and Y axes: the horizontal field reads 41.1 microtesla and the heading 207.2 degrees SSW, 20 degrees wrong. The program cannot correct it, but it notices it: DISTURBED. This is why phones combine the magnetometer with an accelerometer that knows which way is down. At 43 seconds the board lies flat again, the field is normal, and the heading is back to 226.5 degrees SW.

TFT pop-up in the Proteus simulation: tilted 30 degrees, 207 degrees SSW and DISTURBED
Figure: Tilted by 30 degrees: 207 degrees SSW, DISTURBED.
GY-271 pop-up in the Proteus simulation: the board tilted 30 degrees, the downward field mixed in
Figure: The GY-271's pop-up with the board tilted: the downward field mixes into X and Y.
Laptop dashboard in the Proteus simulation: the tilt flagged as DISTURBED
Figure: The dashboard flags the tilt.
Laptop dashboard at the end of the Proteus simulation: 226.5 degrees SW, CALIBRATED
Figure: The dashboard at the end: 226.5 degrees SW, calibrated, the declination +2.0 degrees.
Raspberry Pi 5 terminal: the whole digital compass Proteus simulation run, the calibration and the tilt
Figure: The terminal at the end: every heading change, the calibration and the disturbance messages.

The Numbers of the Run

The results of the digital compass simulation
WhatResult
North, before a calibration3.8 degrees, horizontal 23.1 microtesla
East / southwest94.3 / 219.2 degrees
The magnet (X +35, Y -22, Z +18 uT)291.8 degrees with the board at 225, DISTURBED at 41.6 microtesla
Calibrationoffsets X 33.2, Y -20.6 microtesla, field 25.0; then 224.4 degrees
Declination +2.0 degrees226.5 degrees
Tilt 30 degrees207.2 degrees, DISTURBED at 41.1 microtesla
The TFTMADCTL E8 (landscape), SPI at 8 MHz, 8,155,437 pixels written
Simulation47.5 s of simulation

Download the Project Files

Click the button below to download IoT-Digital-Compass-Raspberry-Pi-5-Proteus-Simulation-v1.0.zip (about 13.4 MB, without the source code of the models):

IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation V1.0
  • Proteus Simulation: Pi-5-Digital-Compass.pdsprj, the program digital_compass.py and copies of the models.
  • Python Code: digital_compass.py, the complete program.
  • Proteus Library Files: the LIB files of the Raspberry Pi 5, the GY-271, the ILI9341 and the two WiFi Monitors.
  • Proteus Model Files: the DLL models and the TEPPi folder, the Python 3.11 and the runtime that the Pi board runs.
  • README.txt: the installation steps, the properties, the test results and the links to every library post.

No Proteus yet? Read How to Download and Install Proteus 7 and 8. New to libraries? Follow How to Install a New Library in Proteus.

How to Install the Project Files

  1. Close Proteus and extract the whole zip file, for example to your Desktop.
  2. Copy the files from Proteus Library Files into the LIBRARY folder of Proteus.
  3. Copy everything in Proteus Model Files, the DLL files and the TEPPi folder, into the MODELS folder.
  4. Start Proteus and open the project from the Proteus Simulation folder.

Changing the Code

The program is plain Python 3: edit digital_compass.py beside the project and press Play again; the Pi board runs the new file. The calibration time, the disturbance limit and the colours are at the top. The same program runs on a real Raspberry Pi 5 with Raspberry Pi OS, lgpio and spidev; enable I2C and SPI in raspi-config. For our other Raspberry Pi 5 project with an I2C chip and smooth graphics on the sheet, see the IoT Robot Arm Controller with Raspberry Pi 5.

Ideas to Extend the Project

  • Add an accelerometer, such as an MPU-6050, and compensate the tilt as phones do.
  • Save the calibration to a file, so the compass starts calibrated.
  • Add soft-iron calibration: scale each axis so the circle of readings is a true circle.
  • Show a course to steer: set a target heading on the dashboard and draw an arrow towards it.
  • Add a GPS module and point to a waypoint.
  • Use the TFT's touch screen to start the calibration.

From Simulation to Real Hardware

  • Keep it away from steel and magnets: speakers, motors, screws and even the TFT's backlight current pull a compass; mount the sensor a few centimetres away.
  • Calibrate in place: calibrate with the sensor mounted where it will work, with everything around it.
  • Find your declination: look it up for your town; it changes slowly over the years.
  • Check the chip: many GY-271 boards sold as HMC5883L carry a QMC5883L at 0x0D; run i2cdetect to see which one you have.
  • Mind the axes: the board's printed X arrow is the axis the heading is measured along.

Troubleshooting

  • No reading, an I2C error: SDA and SCL swapped, or the chip is an HMC5883L at 0x1E.
  • The heading swings unevenly as the board turns: hard iron; run CAL with a full turn.
  • DISTURBED all the time: a magnet near the sensor after the calibration, or the board tilted.
  • The TFT stays dark: no power on VCC or LED, or RESET held low.
  • A garbled picture: the SPI clock above 10 MHz, or DC and CS swapped.
  • The terminal cannot start Python: the TEPPi folder is not in MODELS.

Limitations of the Simulation

  • The field comes from the GY-271's pop-up: an ideal Earth's field, one magnet and one tilt angle.
  • There is no tilt compensation: without an accelerometer, a tilted compass reads wrong, in the simulation as in real life.
  • The network is simulated: the dashboard travels between the Pi and the two monitors inside Proteus; the times in this tutorial are simulation time.
  • Raspberry Pi is a trademark of Raspberry Pi Ltd; the QMC5883L is made by QST and the ILI9341 by Ilitek. This project is not made or endorsed by them or by Labcenter.

So, that was all about the IoT Digital Compass with Raspberry Pi 5 - Proteus Simulation. I hope it helps you build your own compass: a magnetometer on I2C, the heading from atan2, a calibration turn that removes the magnets around it, the declination, and a turning compass card drawn on a TFT from frame buffers, all tested in a simulation before you solder a wire. More IoT projects with the ESP32 and the Raspberry Pi 5 are coming in this series. If you have any questions, ask in the comments and I will help you out. Till the next tutorial, take care and have fun!


Comments

0

Join the conversation