LevelGuage Documentation
LevelGuage is a browser based roll and pitch gauge built around an ESP32 and an MPU6050 3 axis gyroscope and accelerometer.
The hardware is quite simple, an ESP32, a MPU6050 breakout from Sparkfun or a number of other suppliers and a power supply.
The software was specifically written to allow me to level my caravan when travelling alone, but it could be modified for any other purpose simply by changing the images used to display the vehicle.
There are plenty of references and examples available for connecting and using the MPU6050.
The interface is written to emulate the variety of purpose built RV and caravan levellers available. The goal was to have a finished product that worked out cheaper than the $AU250 or more that these sell for. The finished level gauge, mounted in a metal case with LiPo battery was approximately $AU100.
There are software only apps that require 2 mobile phones to work (one in the van, one in the car) but if there were two of us I wouldn't need the app :) - thus the hardware based solution.
Using parts from eBay or from a supplier like Altronics, mounting in a plastic bulkhead case and powering from a 12VDC phone charger rather than internal battery, you should be able to build this for about $AU35-70
When powered on the ESP32 creates a standalone access point, then initialises the MPU6050 and serves up the web interface.
Connect to the WiFi network LEVEL on your smartphone, the open a browser and browse to http://192.168.4.1, the interface will be displayed.
A number of icons are included in the package - if you save the webpage as a desktop shortcut on most smartphone platforms the shortcut should be represented by the LevelGuage icon:
When the hardware is mounted in a suitable case, place on a level surface and perform calibration.
Calibration performs a number of functions:
- Adjusts the "dead zone" or "level zone". This a a value that indicates what is a acceptable tilt range that will still be considered level. There are seperate values for roll and pitch. In the example above the software will consider roll angles between plus or minus 0.5 degrees as level and pitch angles in the range of plus or minus 1.2 degrees as level. When the detected angles of the caravan fall within these ranges the background of the image will turn green (see examples above and below).
- Sets the wheelbase and drawbar length of the vehicle. Wheelbase is measured from the outside of the tires and is used to calculate the height adjustment required to make the vehicle level. Drawbar length is used to determine if the jockey wheel needs to be raised or lowered and by how much. Measured from the axle (or between the two axles for tandem wheels) to the jockey wheel. Both measurements are in whole cm.
- Sets the zero position for the measurements. Make sure that the vehicle is on a level surface (both pitch and roll). Any tilt will render the device inaccurate. This can be done on a known level surface outside the vehicle before mounting. Note that in an upcoming version this action will be optional, you will be able to set the level zones and wheelbase without zeroing the gauge. This is currently available in the Dev stream for download but hasn't been tested.
Ensure when mounting the device to place it in the correct orientation, i.e. when you raise the front of the device the image on the pitch angle responds correctly.
The software has extensive comments - only the broad functions will be covered here. Library and other requirements are covered in the ReadMe file.
This performs the following functions:
- Creates a standalone WiFi Access Point to allow connection of a smartphone or tablet
- Initialises the MPU6050
- Reads the saved calibration data from a SPIFFS partition
- Creates a web server instance to serve the web interface from the SPIFFS partition
- Creates a web socket connection that will receive either a request for roll and pitch data, or will receive a calibration request
- Configures icons for various platforms - thanks to https://realfavicongenerator.net/
- Sets up grid which will contain the canvas objects to draw images and text
- Displays the web form for doing calibration
- Executes the main script
This is a function driven piece of JavaScript which does most of the heavy lifting for this app:
- Sets up canvases and the images to load into them
- Initialises all the calibration variables
- On page load resizes the canvas objects to fit the window / cards
- Opens the web socket connection
Once the web socket connection is opened the app will request an update from the ESP32 server every 300 milliseconds. This is often enough to class as "real time" updates, and since the MPU6050 frequency is set to 5Hz it will only have new data available 5 times a second anyhow, so updating more often would be a waste of resources.
Requests for updates are asynchronous - the app will not wait for data after a request. All messaging is handled by web socket events. The app:
- Receives an update via the web socket. Any update includes the current calibration data plus the current roll and pitch data
- Calculates height adjustment figures
- Draws the rotated images and updates the associated text
The final function is used to validate the calibration form data and send the the calibration web socket message.