10
In the first part we looked at the HX711 hardware for implementing weigh scales systems.
This part will cover how software interacts with the hardware, requirements for a library and how to write a weigh scale application.
All the code described in this article can be found in my libraries code repository as the MD_HX711 library and examples.
Requirements
The most basic components of weighing machines a weight sensor, processing device and an interface (for example, these could be a load cell/HX711, a microprocessor and a display, respectively). They usually also have a method for taring the weight (eg, a switch). Other advanced features can be built into the device but they are refinements on the basics.
The simplest user interface for the scale is to continuously send to the interface the measured value. For a display output this would be just shown (like bathroom or kitchen scales) and/or it could be output through an external interface such as a serial port. Many industrial weight scales work exactly like this.
Therefore to implement a minimal weighing system we need a software framework, such as an Arduino library, that:
- Enables access to all the HX711 features (ie, both channels of data, resetting the device and Channel A gain selection).
- Can work in the background so that the application code implementing the weight scale functionality is free from dealing with hardware related operations. Preferably this works by either periodically polling the HX711 or by external interrupt.
- Allows the device to be tared and calibrated.
- As a minimum provides the readings from the device as raw, tared or calibrated values.
There are many HX711 libraries available and many provide lots of functions above the basics outlined above. However, I could not find one allowed easy access to Channel B or worked using an external interrupt. So I decided that it was time to write my own.
Library Implementation
Reading Device Data
The core of the library is a function used to implement the device communication protocol described in the previous post. The HX711ReadData() code is a straightforward sequential implementation of the CLK/DAT sequencing and timing required by the interface. The function returns the 24-bit DAC number received as a 32-bit integer.
int32_t MD_HX711::HX711ReadData(uint8_t mode)
// read data and set the mode for next read depending on what
// options are selected in the library
{
// local variables are faster for pins
uint8_t clk = _pinClk;
uint8_t data = _pinDat;
// data read controls
int32_t value = 0;
uint32_t mask = 0x800000L;
do // Read data bits from the HX711
{
digitalWrite(clk, HIGH);
delayMicroseconds(1); // T2 typ 1us
if (digitalRead(data) == HIGH) value |= mask;
digitalWrite(clk, LOW);
delayMicroseconds(1); // T3 typ 1us
mask >>= 1;
} while (mask > 0);
// Set the mode for the next read (just keep clocking)
do
{
digitalWrite(clk, HIGH);
delayMicroseconds(1);
digitalWrite(clk, LOW);
delayMicroseconds(1);
mode--;
} while (mode > 0);
return(value);
}Note that the microsecond timing in this function is moot given that digitalWrite() and digitalRead() are quite slow compared to native processor register read/write.
HX711ReadData() is called from readNB() (read non-blocking), which puts the correct library context around the hardware call. This includes:
- working out which channel we need to ask for in the next iteration.
- setting the gain for the channel being requested.
- managing the interrupt context.
- saving the data received to the correct internal storage register.
The reason that we have a non-blocking read is that this method is designed to be called safely by an ISR for an external interrupt.
void MD_HX711::readNB(void)
// NON-Blocking read the data from the HX711 in an IRQ
// safe manner.
{
uint8_t extras = 0;
int32_t value;
_inISR = true;
// set the next read channel
if (_enableB) _nextReadA = !_nextReadA;
// now work out how many extra clock cycles send when reading data
if (!_nextReadA) extras = 2; // Channel B gain 32
else if (_mode == GAIN_128) extras = 1; // Channel A gain 128
else extras = 3; // Channel B gain 64
// do the read
noInterrupts();
value = HX711ReadData(extras);
interrupts();
// sign extend the returned data
if (value & 0x800000) value |= 0xff000000;
// save the data to the right index value
channel_t ch = (_enableB && _nextReadA) ? CH_B : CH_A;
_chanData[ch].raw = value;
// increment the counter
_readCounter++;
_inISR = false;
}The last received data for each channel is stored in library registers and can be retrieved using the getRaw(), getTared() and getCalibrated() methods, depending on what data the application needs.
Device Reset
The HX711 is reset by powering it down using the CLK pin held HIGH then back up again a very small time later.
inline void MD_HX711::powerDown(void)
// Set the CLK to low for at least 60us.
{
digitalWrite(_pinClk, HIGH);
delayMicroseconds(64); // at least 60us HIGH
}
inline void MD_HX711::powerUp(void)
// set the CLK to high
{
digitalWrite(_pinClk, LOW);
}
This resets the device into a default state, so the library implements a reset() method that does the same and keeps the library and device synchronized.
void MD_HX711::reset(void)
// set defaults and power cycle the hardware
{
powerDown();
powerUp();
// set the library defaults
enableChannelB(false);
setGainA(GAIN_128);
disableISR();
_nextReadA = true;
_readCounter = 0;
for (uint8_t ch = 0; ch < NUM_CHAN; ch++)
{
_chanData[ch].raw = 0;
_chanData[ch].tare = 0;
_chanData[ch].calib = 0;
_chanData[ch].range = 0.0;
}
}
Tare and Calibration
The values returned from the hardware are 24-bit ADC values converting the amplified Wheatstone differential voltage to a number. This number must be calibrated to convert the value to a meaningful reading.
To calibrate the readings we first need to assume the Wheatstone bridge provides a linear response to the changes in weight (ie, there is a simple proportional relationship). This is the blue line in the figure. We know this assumption is not correct (see this article) but it is close enough if we choose the right load cell for the application.
The first part of calibration is to tare the readings with no force on the sensor (autoZeroTare() or setTare() methods). This provides the information to shift the ‘raw’ blue response curve to the green curve (line A0B0 shift to A1B1) by subtracting the tare ADC value. This locks in the zero point for the conversions and returned by the getTared() method.
The next part is to calibrate the actual slope of the conversion line – moving the green curve A1B1 to the red curve A1B2 in the diagram. This is done by applying a known force to the sensor (such as a known mass) and noting the ADC value returned (setCalibration()).
By setting the zero point and one known point, and assuming a linear response in the range of values being measured, the converted value y can be easily computed for any ADC value x using the getCalibrated() method.
Polled or External Interrupt?
The library supports both a polled and an interrupt driven approach to obtaining data from the HX711. Up to four separate HX711 devices on unique external interrupts are supported, using the technique described in this past post.
The enableInterruptMode() method is used by the application to toggle interrupt mode on/off as needed.
Polled Mode
This is the default operating mode for the library.
In polled mode the public read() method is synchronously invoked to wait for and obtain the next value from the hardware. If channel B is enabled the library will alternate reading channels (A, B, A, B, etc). The read() method returns the identifier of the channel last processed and the data is retrieved with getRaw(), getTared() and getCalibrated(), as required.
As the read() method is synchronous (it blocks waiting for the next data to be available read from the hardware) the isReady() method can be used to determine if there is data ready for processing. This allows an application to check before calling read() to avoid unnecessary application delays caused by the library.
Interrupt Mode
In interrupt mode the library will process data received from the HX711 in the background, based on an interrupt generated by the device DAT signal going low.
Interrupt mode requires that the I/O pin connected to the DAT signal supports external interrupts (eg, for an Arduino Uno this would be pins 2 or 3).
The application can monitor the getReadCount() method to determine when new data has been received. In interrupt mode the read() method becomes non-blocking and returns the id of the channel whose data was the last received so that it can be read with getRaw(), getTared() and getCalibrated().
Prototyping Weigh Scales
Once the basic hardware related functions of the library were coded and broadly tested, it was time to prototype a weight scale to complete the weigh scale code.
Hardware
I was testing with a 1kg bar-type load cell, so a small scale was adequate. A 100mm diameter top and a bottom plate were modelled in Fusion360, shown below, and 3D printed in ABS.
The top plate is a solid disc. The bottom is more open to save material and give access to the screws for joining the top plate and load cell. Both plates include a small pad to lift the load cell so that it is cantilevered it between the two plates. Machine screws (M4) connect all the components together.
Additional hardware required for this prototype was:
- A 2 line by 20 character LCD module. In this instance it used an I2C interface to the processor, but any other size module and interface that works with LiquidCrystal (or clones) library will work.
- A tact switch to tare and calibrate the scale.
The final configuration is shown in the photo above, along with a few of the objects used to test the scale and my 1kg bag of rice used to for calibration.
Software
As the library does most of the heavy lifting, the application software becomes straighforward.
The software described here is the MD_HX711_WeighScale example from the library.
This example implements a weigh scale that
- Can be tared and calibrated using a tact single switch. A Single press of the switch sets the tare, double press sets the calibration to 1000g.
- Tare and calibration settings are stored in EEPROM and loaded at startup.
- Updates the LCD display with the current weight as soon as a new weight is available.
- Demonstrates receiving data from the HX711 in either polled or interrupt driven mode, set by a #define at compile time.
Configuration Parameters are loaded at startup. The EEPROM data includes two signature bytes so that the software can detect a ‘first time’ run and initialize the data to sensible defaults. All changes to configuration values are immediately and transparently saved to EEPROM.
The tact switch is managed by the MD_UISwitch library (also described in this previous post). This allows the application to test for either a press/double press in the main loop() and do the necessary for each case.
Taring is done to set the scale ‘zero’ by a simple pressing of the tact switch. This is usually when the sale is empty by could equally be when the scale has a container on it.
Calibration is carried out by putting a known 1000g weight (my not-very-accurate bag of rice) on the scale and double pressing the switch.
This application needs to be non-blocking for the user switch to work properly. In this case it turns out there is minimal difference to the application’s structure between interrupt and polled modes. In polled mode it monitors isReady() before calling read() to read the data; in interrupt mode it checks getReadCount() to know when new data is available.
One wrinkle is that when the weight is zero, ADC noise fluctuation around the zero point causes the scale to display 0.0 and -0.0. To prevent what looks like a flickering minus sign, the application calculates and displays a ‘damped’ weight calculated as
float dampedWeight(float newReading)
// Dampen the fluctuations in readings value and make any small // negative values 0.0
{
const float PORTION = 0.80;
static float lastReading = 0.0;
// dampen
lastReading += PORTION * (newReading - lastReading);
// kill small negative values
if (lastReading < 0.0 && lastReading > -0.1)
lastReading = 0.0;
return(lastReading);
}
If a weight is negative by less that the least significant figure (ie between 0.0 and -0.1) then we can display it as zero. This completely eliminates the visual distraction of the ‘flickering’ minus.
Additionally, this function also dampens the changes to the displayed weight by only adding in PORTION (80%) of the change between the current and last reading. This dampens the ADC noise but also has the side effect of a pleasing ‘converging value’ animation on the weighscale display.
