WebGL Example

Included with the BNO055 library is an example of how to send orientation readings to a webpage and use it to rotate a 3D model.  Follow the steps below to setup and run this example.

Dependencies

First you need to install the flask Python web framework.  Connect to your board in a command terminal and run the following command (assuming you've already followed the previous steps to install the BNO055 library and its dependencies):

Download: file
sudo pip install flask

You will also need to be using a web browser that supports WebGL on your computer or laptop.  I recommend and have tested the code for this project with the latest version of Chrome.

Start Server

Next navigate to the webgl_demo example folder by running:

Download: file
cd ~/Adafruit_Python_BNO055/examples/webgl_demo

You will need to edit the server.py file and modify the bno setup lines near the top just like you did for the simpletest.py example on the previous page.  Be sure to leave only one bno = ... line uncommented depending on how the BNO055 is connected to your hardware.

Now run the server.py web server by executing:

Download: file
sudo python server.py

You should see text like the following after the server starts running:

Download: file
 * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
 * Restarting with stat

If you see an error message carefully check you've installed the BNO055 library and the simpletest.py example works.  Also ensure the flask web framework has been installed and try again.

Now open a web browser on your computer and navigate to your board's IP address or hostname on port 5000.  For example on a Raspberry Pi http://raspberrypi:5000/ might work, or on a BeagleBone Black http://beaglebone:5000/ is the URL to try.  If neither URL works you'll need to look up the IP address of your device and then access it on port 5000.  For example if your board has the IP address 192.168.1.5 you would access http://192.168.1.5:5000/.

Once the page loads you should see something like the following:

If you move the BNO055 sensor you should see the 3D model move too.  However when the demo first runs the sensor will be uncalibrated and likely not providing good orientation data.  Follow the next section to learn how to calibrate the sensor.

Sensor Calibration

The video below shows an overview of calibrating the BNO055 sensor.  Following the video is a more detailed description of the calibration process.

To use the BNO055 sensor you'll need to make sure it's calibrated every time the sensor is powered on or reset.  Luckily the BNO055 takes care of most calibration for you, but you will need to move the sensor in certain ways to complete the calibration.  Section 3.10 of the datasheet has all the details on calibration, but in general you can follow the steps below to calibrate each sensor.

First notice the bottom middle column of the web page shows the current calibration status of the BNO055 sensor.  There are 4 parts of the sensor that are individually calibrated, the system (or fusion algorithm), gyroscope, accelerometer, and magnetometer.  Each component has a calibration level from 0 to 3 where 0 is uncalibrated and 3 is fully calibrated.  Ideally you want all 4 components to be at least a calibration level of 3 to get the best orientation data.  However you should still get reasonable results if a few of the sensors and the system are calibrated to level 2 or 3.

  • Gyroscope
    • The gyroscope is the easiest to calibrate and will most likely be fully calibrated by the time you load the web page.  To calibrate the gyroscope place the sensor down on a table and let it sit motionless for a few seconds.
  • Magnetometer
    • The magnetometer is slightly more complicated to calibrate.  You need to pick up the BNO055 sensor and move it through a figure 8 or infinity pattern continuously until the magnetometer calibrates.  In most cases the sensor will calibrate after about a dozen movements through the figure 8 pattern.  Be careful as any large metal objects near the sensor could change or slow the calibration.
  • Accelerometer
    • The accelerometer calibration requires holding the sensor in about 6 different positions for a few seconds.  Think of a cube and the 6 faces on it and try to slowly move the sensor between each face, holding it there for a few seconds.  If the accelerometer is calibrating after about 3-4 faces you'll see its level jump from 0 to 1 and then up to 3 after moving to more faces.
    • Another good way I've found to calibrate the accelerometer is to rotate the board along an axis and hold it for a few seconds at each 45 degree angle.  You'll know the calibration is working when you see the calibration level go from 0 to 1 after holding at a few different 45 degree angles.
  • System
    • The system, or fusion algorithm, will calibrate once all the sensors have started to calibrate.  You'll likely see the system calibration increase as each sensor finishes calibration.  Once all the sensors have calibrated let the sensor sit for a few moments to finish calibrating the system.

Once the board is calibrated you should see each calibration level at a level of 3 like below:

To save time in the future you can click the Save Calibration button on the right and the calibration data will be written to a calibration.json file.  When you restart the server in the future press Load Calibration to load the file and its calibration.  You might still need to calibrate the magnetometer again after loading calibration, but the accelerometer and system calibration generally happen much quicker from a loaded configuration.

Note that each time the sensor is powered on or reset (like when the server is run again) it will need to be calibrated again for best results!  In your own scripts that use the BNO055 library after calibrating you can call the get_calibration() function and save the returned list of data (it will return 22 integers), then reload it later using the set_calibration() function of the library.

Usage

After calibrating the sensor you can move the board around and see the 3D model rotate.  However you might notice the orientation and rotation of the 3D model doesn't exactly match that of the BNO055 sensor.  This is because the axes of the BNO sensor need to be matched to the axes of the 3D model so that turning the sensor left/right turns the model left/right, etc.

You can line up the axes of the sensor and 3D model by using the Straighten button.  First you'll need to place the BNO sensor in a very specific orientation.  Place the sensor flat in front of you and with the row of SDA, SCL, etc. pins facing away from you like shown below:

Then click the Straighten button and you should see the 3D model snap into its normal position:

Now move the BNO055 sensor around and you should see your movements exactly matched by the 3D model!

You can also change the 3D model by clicking the Model drop down on the right and changing to a different model, like a cat statue:

That's all there is to using the BNO055 WebGL demo!

To stop the server go back to the terminal where it was started and press Ctrl-C.  You might also need to run the following command to kill any Python process that remains running (sometimes if the browser is still running it can keep a zombie flask process running):

Download: file
sudo pkill -9 python

Describing how all of the WebGL code works is a little too complex for this guide, however the high level components of the example are:

  • flask web service framework: This is a great, simple web framework that is used by server.py to serve the main index.html page and expose a few web service endpoints to read BNO sensor data and save/load calibration data.
  • HTML5 server sent events: This is how data is sent from the server to the webpage.  With SSE a connection is kept open and data is pushed to the client web page.  BNO sensor readings are taken and sent over SSE where they're use to update the orientation of the model.  This page has a little more info on how to use HTML5 SSE with the flask framework (although it uses a more complex multiprocessing framework called gevent that isn't necessary for simple apps like this demo).
  • Three.js: This is the JavaScript library that handles all the 3D model rendering.
  • Bootstrap & jQuery: These are a couple other JavaScript libraries that are used for the layout and some core functionality of the page.

That's all there is to using the BNO055 WebGL demo.  Enjoy using the BNO055 absolute orientation sensor in your own projects!

This guide was first published on Jul 20, 2015. It was last updated on Jul 20, 2015. This page (WebGL Example) was last updated on Oct 12, 2019.