imu-tools (GitHub repo) is a set of programs for transmitting and visualizing IMU sensor data on an MQTT network.

Upgrade Instructions

These are instructions for how to upgrade the imu-tools project and folder that you previously installed (via git clone) on your computer, in order to take advantage of newer features.

Instructions in this font are commands that are entered into the Terminal.


Open a Terminal window
cd imu-tools
Sets the following terminal commands to operate within the “imu-tools” folder
git stash
Sets aside any modifications that you've made to files in the folder, such as the replacement 3d-model.js file that I instructed you to install on Tuesday.
git pull
Fetches the latest changes from GitHub, and installs them in the directory on your computer.
pipenv run webserver
Runs a local web server, that serves web pages that allow you to inspect the IMU data. If this command produces an error OSError: [Errno 48] Address already in use, it means you have already done this in another Terminal window that is still open. You can ignore the error and proceed.
In a web browser, open
Opens the main page of the web tools. The links in this page open other pages such as the 3D model page that we have been working with previously.

Things to Try

  • View the index page. What models are present? (Note: you will have to enter the hostname, username, and password onto this page. The fact that you've entered these into the model page doesn't carry over to this page. Leave the device_id blank, in order to see multiple devices.)
  • View the bar chart page. How do the graphs correspond to the orientation and motion of your sensor board? (Note: you will have to enter the hostname, username, password, and device_id on this page.)
  • Open the 3D model page. How do the rotation (rx, ry, and rz) and displacement (dx, dy, dz) settings affect the display of the model? Continue to explore how the orientation of the board itself effects the model.
  • Replace the device_id from the 3D model page. See if you can figure out what's going on. Which model corresponds to your board?

Release Notes


  • The “Calibrate” button sets the model baseline orientation. Hold all the sensors in their natural orientation, and then press this button.
  • The MQTT host can be a URL, with a schema and port number; e.g. ws://localhost:80 or wss://localhost:443. The schema should be one of ws or wss. If it is "wss", the web client will initiate an SSL connection.
  • All the web pages share storage for MQTT connection settings. Setting the MQTT connection settings on one page will cause these to be used on any other page that is subsequently opened or reloaded.
  • Using the GUI to change the MQTT connection settings causes the MQTT client to reconnect.
  • Remove the network.ini and network.ini.tpl files. The command-line scripts take arguments instead, and also read the values of MQTT_* environment variables. This simplifies the setup instructions.


  • The index page (at now shows a list of sensors on the network.
  • A new “Bar Chart” page displays all the sensor values as bar graphs. (This page is written as a p5.js sketch. The source is in eweb/barchart.js.)
  • When the 3D model web page displays data from multiple sensors, they repel each other via spring forces.
  • A new GUI panel on the 3D model web page allows the selection of the model file name. It defaults to “bunny”, which serves the model at web/models/bunny.obj. Place another file in that directory and replace the word “bunny” in the GUI in order to use a different model instead. To load an STL model, include the “.stl“ suffix in the model name.
  • The new GUI panel also controls whether the axes are displayed, the initial rotation of the model (which will be different for different OBJ and STL files), and the displacement of the model from the origin (useful for modeling a device at the end of a wand, for example).
  • Pages display the MQTT connection status.
  • In the web pages, the MQTT host can be followed by a port selector.
  • The mqtt-pub and mqtt-sub command-line tools take parameters to specify the MQTT host, port, username, and password. Type mqtt-pub --help and mqtt-sub --help for info.