{"id":16344964,"url":"https://github.com/davidegrayson/minimu9-ahrs","last_synced_at":"2025-08-03T00:07:54.709Z","repository":{"id":3688789,"uuid":"4759111","full_name":"DavidEGrayson/minimu9-ahrs","owner":"DavidEGrayson","description":"Program for reading data from the Pololu MinIMU-9 over I²C.  Works on the Raspberry Pi and other embedded ARM Linux boards.","archived":false,"fork":false,"pushed_at":"2023-07-21T22:34:40.000Z","size":1066,"stargazers_count":171,"open_issues_count":8,"forks_count":66,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-06T11:45:56.657Z","etag":null,"topics":["accelerometer","gyro","magnetometer","minimu9","minimu9-ahrs","pololu","raspberry-pi","rpi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"yupferris/rustendo64","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DavidEGrayson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-23T07:07:43.000Z","updated_at":"2025-03-07T23:12:58.000Z","dependencies_parsed_at":"2024-10-26T16:53:47.435Z","dependency_job_id":"330b3293-c899-4beb-aee5-987f603e35f5","html_url":"https://github.com/DavidEGrayson/minimu9-ahrs","commit_stats":{"total_commits":237,"total_committers":5,"mean_commits":47.4,"dds":0.09704641350210974,"last_synced_commit":"c254f3cd5c82e5a4ecf6b9ee26dc03d2529e6fcb"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidEGrayson%2Fminimu9-ahrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidEGrayson%2Fminimu9-ahrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidEGrayson%2Fminimu9-ahrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DavidEGrayson%2Fminimu9-ahrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DavidEGrayson","download_url":"https://codeload.github.com/DavidEGrayson/minimu9-ahrs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154998,"owners_count":21056542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accelerometer","gyro","magnetometer","minimu9","minimu9-ahrs","pololu","raspberry-pi","rpi"],"created_at":"2024-10-11T00:29:34.076Z","updated_at":"2025-04-10T03:51:58.213Z","avatar_url":"https://github.com/DavidEGrayson.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# minimu9-ahrs\n\n**minimu9-ahrs** is a program for reading sensor data from the Pololu MinIMU-9\nand similar boards over I²C.  It supports the following sensor chips:\n\n* LSM6DS33 accelerometer and gyro\n* LSM6DSO accelerometer and gyro\n* LIS3MDL magnetometer\n* LSM303D magnetometer and accelerometer\n* LSM303DLHC magnetometer and accelerometer\n* LSM303DLM magnetometer and accelerometer\n* LSM303DLH magnetometer and accelerometer\n* L3GD20H gyro\n* L3GD20 gyro\n* L3G4200D gyro\n\nThis program works with any board that has a magnetometer, acceleromter, and a\ngyro from the list above.  This includes the following Pololu products:\n\n* MinIMU-9 [v0][mv0], [v1][mv1], [v2][mv2], [v3][mv3], [v5][mv5], [v6][mv6]\n* AltIMU-10 [v3][av3], [v4][av4], [v5][av5], [v6][av6]\n* [Balboa 32U4 Balancing Robot Kit][balboa]\n\nThe program can output the raw sensor data from the magnetometor, accelerometer,\nand gyro or it can use that raw data to compute the orientation of the IMU.\nThis program was designed and tested on the [Raspberry Pi], but it will probably\nwork on any embedded Linux board that supports I²C.\n\n## Getting started\n\n### Enabling I²C\n\nFirst, you need to make sure your system supports I²C.  Try typing\n`ls /dev/i2c*`: if you don't see a device there named something like\n`/dev/i2c-1` then your I²C is not enabled properly.\n\nOn a **Raspberry Pi running Raspbian**, you should run `sudo raspi-config`\nand browse its menus to find the option to enable I²C.\n\nHere are some other related resources that might be useful for you when\nfiguring out how to enable I²C:\n\n* [Configuring Your Pi for I²C by Adafruit](https://learn.adafruit.com/adafruit-16-channel-servo-driver-with-raspberry-pi/configuring-your-pi-for-i2c/)\n* [Guide to interfacing a Gyro and Accelerometer with a Raspberry Pi](https://ozzmaker.com/berryimu/)\n\n### Managing device permissions\n\nAfter enabling the I²C devices, you should set them up so that your user has\npermission to access them.  That way, you won't have to run `sudo`.\n\nFirst, run `groups` to see what groups your user belongs to.  If `i2c` is on the\nlist, then that is good.  If you are not on the `i2c` group, then you should add\nyourself to it by running `sudo usermod -a -G i2c $(whoami)`, logging out, and\nthen logging in again.  If your system does not have an `i2c` group, you can\ncreate one or use a different group like `plugdev`.\n\nNext, run `ls -l /dev/i2c*` to make sure that your I²C devices have their group\nset to `i2c`.  The group name is shown in the fourth column, and will usually be\n`root` or `i2c`.  If the devices are not in the `i2c` group, then you should fix\nthat by making a file called `/etc/udev.d/rules.d/i2c.rules` with the following\nline in it:\n\n    SUBSYSTEM==\"i2c-dev\" GROUP=\"i2c\"\n\nAfter making this file, you can make it take effect by running\n`sudo udevadm trigger` (or rebooting).\n\nIf you get an error about permission being denied, double check that you have done these steps correctly.\n\n### Soldering\n\nThe MinIMU-9 and AltIMU-9 boards come with male header pins, and you will need\nto solder these into the board in order to make a solid connection.\n\n### Wiring\n\nYou will need to power your IMU board and connect it to the I²C bus of your\nembedded computer board.  The correct connections for the Raspberry Pi and a\nMinIMU-9 are listed below:\n\n| Raspberry Pi pin | MinIMU-9 pin |\n|------------------|--------------|\n| GND              | GND          |\n| 3V3 Power        | VDD          |\n| GPIO 2 (SDA)     | SDA          |\n| GPIO 3 (SCL)     | SCL          |\n\nBelow is a [picture][wiring_pic] with a MinIMU-9 v2 showing how to make those\nconnections.\n\n[![][wiring_pic_small]][wiring_pic]\n\nYou will need four female-female jumper wires designed for 0.1\"-spaced pins.\nPololu's [Female-Female Premium Jumper Wires][ffwires] work well.\n\n### Determining which bus to use\n\nThe default I²C bus used by this program is `/dev/i2c-1`.\nOn most Raspberry Pi boards, this bus is accessible on the GPIO connector.\n\nIf you want to use a different bus, you should make a configuration file\nin your home directory named\n`~/.minimu9-ahrs` with a single line of the form `i2c-bus=BUSNAME`, where\n`BUSNAME` is the full path to the bus you want to use.\n\nFor example, to use `/dev/i2c-0` by default, the config file should read:\n\n    i2c-bus=/dev/i2c-0\n\nIf you are not sure which bus to use, you could try running `i2cdetect` on each\navailable bus as described below.\n\n### Checking your setup\n\nAfter you have enabled I²C, given yourself the proper permissions, soldered the\nMinIMU-9, and connected it to the Raspberry Pi, you should check your setup by\nrunning `i2cdetect`.  Try running `i2cdetect -y N`, where `N` is the number of\nthe I²C bus you want to use (typically 1 or 0).  The output should look similar\nto this:\n\n```\n$ i2cdetect -y 1\n     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f\n00:          -- -- -- -- -- -- -- -- -- -- -- -- --\n10: -- -- -- -- -- -- -- -- -- -- -- -- -- 1d -- --\n20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --\n30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --\n40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --\n50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --\n60: -- -- -- -- -- -- -- -- -- -- -- 6b -- -- -- --\n70: -- -- -- -- -- -- -- --\n```\n\nThe exact output will depend on the type of IMU\nyou are using, but the important thing is that the body of the printed table\nshould contain a few hex numbers representing the addresses of I²C devices that\nwere detected on the bus.\n\nIf the `i2cdetect` command is not recognized, you should install the `i2c-tools`\npackage.  On Raspbian, you can run `sudo apt-get install i2c-tools` to install\nit.\n\nIf you do not see a few hex numbers in the body of the table, then make sure\nyour soldering and wiring are correct and try selecting a different bus by\nchanging the bus number argument `N`.\n\nIf you get a permission denied error, make sure you have configured the device\npermissions properly as described above.\n\nIf you get a \"No such file or directory\" error referring to your I²C device,\nmake sure that you have properly enabled I²C as described above.\n\n### Building from source\n\nTo build `minimu9-ahrs`, you first need to install some libraries that it\ndepends on.  On Raspbian, you can install these dependencies by running:\n\n    sudo apt-get install libi2c-dev libeigen3-dev libboost-program-options-dev\n\nThen, to build `minimu9-ahrs`, navigate to the top-level directory of the source\ncode and then run this command:\n\n    make\n\nFinally, to install minimu9-ahrs onto your system, run:\n\n    sudo make install\n\n### Looking at raw values\n\nAs a first test, you should look at the raw readings from the sensors on your\nIMU to make sure it is OK.  Run `minimu9-ahrs --mode raw`.  The output should\nlook something like this:\n\n```\n  -1318   -3106   -1801     1896    1219    3679        5      18       3\n  -1318   -3106   -1801     1898    1200    3681        0      24      -1\n  -1318   -3106   -1801     1899    1200    3688       15      17       2\n  -1309   -3105   -1799     1874    1201    3671       17      20      -1\n  -1309   -3105   -1799     1898    1214    3663       11      15      -2\n```\n\n**Yes, there will be noise in all the readings, even if your IMU is not moving\nat all.** That is totally normal.\n\nThis output consists of three vectors.  From left to right they are the raw\nmagnetometer reading, the raw accelerometer reading, and the raw gyro reading.\nEach vector consists of three integers, in X-Y-Z order.  You should turn the\ndevice and make sure that the raw readings change correspondingly.  For example,\nwhen the X axis of the board is pointing straight up, the accelerometer's X\nreading (the 4th number on each line) should be positive and the other two\ncomponents of the acceleration should be close to zero.\n\n### Calibrating\n\nThe magnetometer will need to be calibrated to create a mapping from the\nellipsoid shape of the raw readings to the unit sphere shape that we want the\nscaled readings to have.  The calibration feature for the `minimu9-ahrs` assumes\nthat the shape of the raw readings will be an ellipsoid that is offset from the\norigin and stretched along the X, Y, and Z axes.  It cannot handle a rotated\nellipsoid.  It can be informative to run `minimu9-ahrs --mode raw \u003e output.tsv`\nwhile moving the magnetometer and then make some scatter plots of the raw\nmagnetometer readings in a spreadsheet program to see what shape the readings\nhave.\n\nTo calibrate the magnetometer, run `minimu9-ahrs-calibrate` and follow the\non-screen instructions when they tell you to start rotating the IMU through as\nmany different orientations as possible.  Once the script has collected enough\ndata, it saves the data to `~/.minimu9-ahrs-cal-data` and then runs a separate\nPython script (`minimu9-ahrs-calibrator`) to create a calibration.\n\nThe Python script previously had a complicated algorithm powered by SciPy that\nwould take about 20 minutes to run and was not reliable.  Currently, the script\njust uses a very simple algorithm that finds the minimum and maximum values of\neach axis of the magnetometer and uses those as the calibration values.  This is\nprobably not the best way to calibrate your magnetometer; there are more\nadvanced ways that might work better.\n\nThe `minimu9-ahrs-calibrate` script saves the calibration file to\n`~/.minimu9-ahrs-cal`.  The calibration file is simply a one-line file with 6\nnumbers separated by spaces: minimum x, maximum x, minimum y, maximum y, minimum\nz, maximum z.  These numbers specify the linear mapping from the raw ellipsoid\nto the unit sphere.  For example, if \"minimum x\" is -414, it means that a\nmagnetometer reading of -414 on the X axis will get mapped to -1.0 when the\nreadings are scaled.\n\n### Looking at Euler angles\n\nRun `minimu9-ahrs --output euler`.  It will print a stream of floating-point\nnumbers, nine per line.  The first three numbers are the yaw, pitch, and roll\nangles of the board in degrees.  All three Euler angles should be close zero\nwhen the board is oriented with the Z axis facing down and the X axis facing\ntowards magnetic north.  From that starting point:\n\n* A positive `yaw` corresponds to a rotation about the Z axis that is\n  clockwise when viewed from above.\n* A positive `pitch` correspond to a rotation about the Y axis that would\n  cause the X axis to aim higher into the sky.\n* A positive `roll` would correspond to a counter-clockwise rotation about\n  the X axis.\n\nThe way you should think about it is that board starts in the neutral position,\nthen the yaw rotation is applied, then the pitch rotation is applied, and then\nthe roll rotation is applied to get the board to its final position.\n\nLook at the Euler angle output as you turn the board and make sure that it looks\ngood.\n\n\n## Man page\n\nFor more information about `minimu9-ahrs`, including all the options it supports\nand a precise description of its output format, view the man page by running\n`man minimu9-ahrs`.\n\n\n## Related projects\n\n* [ahrs-visualizer] - another program by me that provides a 3D display of\n  the orientation output from `minimu9-ahrs`.\n* [Pololu MinIMU-9 Step-by-Step][kim] - an alternative tutorial by Mike Kim\n  that explains how to use minimu9-ahrs and ahrs-visualizer.\n* [RTIMULib2](https://github.com/RTIMULib/RTIMULib2) - another project\n  that works with the MinIMU-9 and the Raspberry Pi.\n\n## Version history\n\n- 4.0.0 (2023-07-11):\n  - Added support for the MinIMU-9 v6 (LSM6DSO and LIS3MDL).\n  - Changed the default I²C bus to /dev/i2c-1 to better serve Raspberry Pi users.\n  - Updated the minimu9-ahrs-calibrator script to use Python 3.\n- 3.0.0 (2017-04-15):\n  - Added support for the MinIMU-9 v5 (LSM6DS33 and LIS3MDL).\n  - Added support for a configuration file at `~/.minimu9-ahrs`.\n  - Fixed a bug that resulted in corrections from the accelerometer always being applied\n    even if the acceleration magnitude was not close to 1 g (thanks nxdefiant).\n  - Use a Linux timerfd for more accurate timing (thanks to nxdefiant for the idea).\n  - Made the `minimu9-ahrs-calibrate` script store the raw data in `~/.minimu9-ahrs-cal-data`.\n  - Changed the minimu9-ahrs-calibrator Python script to just do simple minima/maxima\n    because the fancy optimization algorithm was not reliable.\n  - Fixed the way boost_program_options is linked.\n  - Expanded the README so it can replace the wiki.\n- 2.0.0 (2014-07-08):\n  - Added support for the MinIMU-9 v3 (LSM303D and L3GD20H)\n  - Removed the right-shifting of raw accelerometer outputs; the raw readings are now\n    signed 16-bit numbers that can range from -32768 to 32767.  Previously the readings\n    were signed 12-bit numbers, so this new version effectively gives readings that\n    are greater by a factor of 16.\n  - Changed the minimu9-ahrs-calibrator Python script to use SciPy instead of the old optimization algorithm.\n  - Changed the minimu9-ahrs-calibrator script to print a warning if there are fewer than 300 input vectors instead of exiting.\n  - Changed the minimu9-ahrs-calibrator script to print a warning if the calibration looks wrong.\n- 1.1.1 (2012-10-17)\n- 1.1.0 (2012-10-15)\n- 1.0.0 (2012-10-06)\n\n[ahrs-visualizer]: https://github.com/DavidEGrayson/ahrs-visualizer\n[minimu9-ahrs source code]: https://github.com/DavidEGrayson/minimu9-ahrs\n[Raspberry Pi]: https://www.raspberrypi.org\n[kim]: http://www.nacionale.com/pololu-minimu9-step-by-step/\n[av3]: https://www.pololu.com/product/2469\n[av4]: https://www.pololu.com/product/2470\n[av5]: https://www.pololu.com/product/2739\n[av6]: https://www.pololu.com/product/2863\n[mv0]: https://www.pololu.com/product/1264\n[mv1]: https://www.pololu.com/product/1265\n[mv2]: https://www.pololu.com/product/1268\n[mv3]: https://www.pololu.com/product/2468\n[mv5]: https://www.pololu.com/product/2738\n[mv6]: https://www.pololu.com/product/2862\n[balboa]: https://www.pololu.com/product/3575\n[ffwires]: https://www.pololu.com/catalog/category/66\n[wiring_pic]: http://www.davidegrayson.com/minimu9-ahrs/wiring.jpg\n[wiring_pic_small]: http://www.davidegrayson.com/minimu9-ahrs/wiring_560px.jpg\n[i2cdetect_sample]: https://gist.github.com/DavidEGrayson/2f0531a149d964574565\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidegrayson%2Fminimu9-ahrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidegrayson%2Fminimu9-ahrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidegrayson%2Fminimu9-ahrs/lists"}