Copyright (c) 2015 Scott Russell ([email protected]), released under the MIT license. See the LICENSE file for licensing details.
A Digital balance library for creating scales on the Arduino, including smoothing, taring and calibration.
All calibrations and internal calculations use grams, but the adjustedValue and adjustedRawValue functions accept unit values and will return measurements in the appropriate units. Unit options are:
Q2BALANCE_UNIT_GRAM, Q2BALANCE_UNIT_POUND, Q2BALANCE_UNIT_OUNCE, Q2BALANCE_UNIT_GRAIN, Q2BALANCE_UNIT_TROY, Q2BALANCE_UNIT_PWT, Q2BALANCE_UNIT_CARAT and Q2BALANCE_UNIT_NEWTON.
Pounds units are returned in decimal pounds, not pounds and ounces.
Before calibration, the balance will not report a value. Calibration requires the zero calibration point (the value of the sensor with nothing on it) and one measurement of a known weight to be set.
Up to 10 calibration setpoints are available to map a sensor's linearity through specific measurement windows. To behave lie a "normal" digital scale, simply use a single calibration setpoint, index 0. Calibration setpoints must be entered in order, so to set calibrations at 100g, 1000g and 5000g, set them in index 0, 1, and 2 respectively. If set in this way, measurements between 100 and 5000 g will use the middle index automatically, and measurements over 5000g will use index 2. As another example, for fine-grained precision, setpoints could be set at 10g, 50g and 100g and used in a similar fashion.
The zero calibration is set by removing all weight from the sensor and calling calibrateZero.
Calibration setpoints are set by calling calibrate with the mass in grams.
Taring sets the zero point of the value returned from the scale. This is separate from the zero calibration point. Taring allows a scale user to reset "zero" for successive weighings.
The Q2Balance class handles all balance functions. It takes no construction arguments.
Return | Function | Description |
---|---|---|
float | adjustedValue | The current value with smoothing and adjusted for calibration and taring. If no calibration markers are set, 0 is returned. |
float | adjustedRawValue | The current value without smoothing and adjusted for calibration and taring. If no calibration markers are set, 0 is returned. |
none | calibrateZero | Set the "zero" calibration for the balance. Requires a parameter, milliseconds to wait for settling. Accepts callback. |
none | calibrate | Set a calibration marker - requires calibration index (0-9), the calibration mass (in mg - 1000 for 1kg) and # milliseconds to wait for settling. Accepts callback. |
bool | calibrating | True if the balance is currently calibrating. |
Struct | getCalibration | get the current calibration data (for saving too EEPROM etc). |
long | jitter | The amount of "jitter" or noise collected during the last settle. |
void | measure | register a new measurement with the balance. Requires a long value. |
long | rawValue | The most recent measurement without smoothing. |
bool | settling | True if the balance is currently settling. |
long | smoothValue | The most recent measurement with smoothing. |
long | settle | Settle the balance (wait for it to calm down) requires # of milliseconds to wait. |
void | setCalibration | Load a set of calibration markers (for loading from EEPROM etc). |
bool | taring | true if the balance is currently taring. |
bool | tared | true if the balance has been tared and has not "broken tare" yet. |
none | tare | Tare the balance requires # of milliseconds to settle. Accepts callback. |
none | tick | Balance main processing (taring, settling, calibration). Call frequently to maintain accuracy. |
none | printCalibration | Print (to serial) information about a specific calibration setpoint. Accepts an index parameter. (For debugging) |
none | printCalibrations | Print (to serial) information about all calibration setpoints. (For debugging) |
The functions tare(), calibrateZero() and calibrate() accept callback functions ( void (*afterTared)(void) / void (*afterCalibrated)(void) ) as the last parameter. These callbacks will fire upon successful completion of the operation. If the operation does not complete (due to an error or bad condition) these callbacks will not fire at all.
Type | Setting | Default | Description |
---|---|---|---|
long | TARELIMIT | 110 | Tare will be "broken" when the measurement's absolute distance from the last tare exceeds this amount. |
long | JUMPLIMIT | 200 | If the measurement changes more than this distance from the last measurement, stop smoothing and jump to the new value. |
long | SAMPLE_COUNT | 10 | The number of samples to use for smoothing. |
There is an example using the HX711 library in the examples folder.