scale.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "pico/time.h"
#include "mass.h"
#include "scale_adaptor.h"

Go to the source code of this file.

Data Structures
struct	scale_options_t
struct	scale_t

Enumerations
enum	strategy_type_t { strategy_type_samples = 0 , strategy_type_time }
enum	read_type_t { read_type_median = 0 , read_type_average }

Functions
void	scale_options_get_default (scale_options_t *const opt)
	Fill options will default values. More...
void	scale_init (scale_t *const sc, scale_adaptor_t *const adaptor, const mass_unit_t unit, const int32_t ref_unit, const int32_t offset)
	Initialise the scale with a hx711_t. More...
bool	scale_normalise (const scale_t *const sc, const double *const raw, double *const normalised)
	Adjusts a raw value to a normalised value according to the scale's reference unit and offset. Returns true if the operation succeeded. More...
bool	scale_get_values_samples (scale_t *const sc, int32_t *const arr, const size_t len)
	Fills arr with len number of samples from the scale. Returns true if the operation succeeded. More...
bool	scale_get_values_timeout (scale_t *const sc, int32_t *const arr, const size_t arrlen, size_t *const len, const uint timeout)
	Fills arr with as many number of samples as possible up to the timeout. Returns true if the operation succeeded. More...
bool	scale_read (scale_t *const sc, double *const val, const scale_options_t *const opt)
	Obtains a value from the scale according to the given options. Returns true if the operation succeeded. More...
bool	scale_zero (scale_t *const sc, const scale_options_t *const opt)
	Zeros the scale (tare) by adjusting its offset from 0 according to the given options. Returns true if the operation succeeded. More...
bool	scale_weight (scale_t *const sc, mass_t *const m, const scale_options_t *const opt)
	Obtains a weight from the scale according to the given options. Returns true if the operation succeeded. More...

Variables
static const scale_options_t	SCALE_DEFAULT_OPTIONS

Enumeration Type Documentation

read_type_t

enum read_type_t

Enumerator
read_type_median
read_type_average

Definition at line 42 of file scale.h.

             {
    read_type_median = 0,
    read_type_average
} read_type_t;

strategy_type_t

enum strategy_type_t

Enumerator
strategy_type_samples
strategy_type_time

Definition at line 37 of file scale.h.

             {
    strategy_type_samples = 0,
    strategy_type_time
} strategy_type_t;

Function Documentation

scale_get_values_samples()

bool scale_get_values_samples	(	scale_t *const	sc,
		int32_t *const	arr,
		const size_t	len
	)

Fills arr with len number of samples from the scale. Returns true if the operation succeeded.

Parameters

sc
arr
len

Returns

true

false

Definition at line 76 of file scale.c.

                      {
 
        assert(sc != NULL);
        assert(sc->_adaptor != NULL);
        assert(arr != NULL);
 
        for(size_t i = 0; i < len; ++i) {
            if(!sc->_adaptor->get_value(sc->_adaptor, &(arr[i]))) {
                return false;
            }
        }
 
        return true;
 
}

References scale_t::_adaptor, and scale_adaptor::get_value.

Referenced by scale_read().

scale_get_values_timeout()

bool scale_get_values_timeout	(	scale_t *const	sc,
		int32_t *const	arr,
		const size_t	arrlen,
		size_t *const	len,
		const uint	timeout
	)

Fills arr with as many number of samples as possible up to the timeout. Returns true if the operation succeeded.

Parameters

sc
arr	buffer
arrlen	Size of buffer
len	Will be set to the number of samples obtained
timeout	Microseconds

Returns

true

false

Definition at line 95 of file scale.c.

                        {
 
        assert(sc != NULL);
        assert(sc->_adaptor != NULL);
        assert(arr != NULL);
        assert(arrlen > 0);
        assert(len != NULL);
 
        //the absolute end time for seeking values (now + timeout)
        const absolute_time_t end = make_timeout_time_us(timeout);
        int32_t val; //temporary value from the adaptor
        int64_t diff; //difference in us from current time to end; updated
 
        //reset len to 0
        *len = 0;
 
        for(;;) {
 
            if(*len >= arrlen) {
                //no more room left
                break;
            }
 
            //update the time diff between now and the end
            diff = absolute_time_diff_us(get_absolute_time(), end);
 
            if(diff <= 0) {
                //timeout reached
                break;
            }
 
            if(sc->_adaptor->get_value_timeout(sc->_adaptor, &val, (uint)diff)) {
 
                //new value available, so increase the counter
                //this is the actual number of values obtained
                ++(*len);
 
                //store the value in the array
                arr[(*len) - 1] = val;
 
            }
            else {
                /* the last get_value_timeout call might fail because there is little time
                   left until the timeout is reached, so fail only if no values were read at all. */
                break;
            }
 
        }
 
        return *len > 0;
 
}

References scale_t::_adaptor, and scale_adaptor::get_value_timeout.

Referenced by scale_read().

scale_init()

void scale_init	(	scale_t *const	sc,
		scale_adaptor_t *const	adaptor,
		const mass_unit_t	unit,
		const int32_t	ref_unit,
		const int32_t	offset
	)

Initialise the scale with a hx711_t.

Parameters

sc	Pointer to scale_t
hx	Pointer to hx711_t
unit	The mass_unit_t to output mass_t's in
ref_unit	The reference unit to use (see: calibration)
offset	The offset from 0 (see: calibration)

Definition at line 39 of file scale.c.

                          {
 
        assert(sc != NULL);
        assert(adaptor != NULL);
        assert(ref_unit != 0);
 
        sc->_adaptor = adaptor;
        sc->unit = unit;
        sc->ref_unit = ref_unit;
        sc->offset = offset;
 
}

References scale_t::_adaptor, scale_t::offset, scale_t::ref_unit, and scale_t::unit.

scale_normalise()

bool scale_normalise	(	const scale_t *const	sc,
		const double *const	raw,
		double *const	normalised
	)

Adjusts a raw value to a normalised value according to the scale's reference unit and offset. Returns true if the operation succeeded.

Parameters

sc
raw
normalised

Returns

true

false

Definition at line 57 of file scale.c.

                              {
 
        assert(sc != NULL);
        assert(raw != NULL);
        assert(normalised != NULL);
 
        //protect against div / 0
        if(sc->ref_unit == 0) {
            return false;
        }
 
        *normalised = (*raw - sc->offset) / sc->ref_unit;
        return true;
 
}

References scale_t::offset, and scale_t::ref_unit.

Referenced by scale_weight().

scale_options_get_default()

void scale_options_get_default

(

scale_options_t *const

opt

)

Fill options will default values.

Parameters

opt

Definition at line 33 of file scale.c.

                                {
        assert(opt != NULL);
        *opt = SCALE_DEFAULT_OPTIONS;
}

References SCALE_DEFAULT_OPTIONS.

scale_read()

bool scale_read	(	scale_t *const	sc,
		double *const	val,
		const scale_options_t *const	opt
	)

Obtains a value from the scale according to the given options. Returns true if the operation succeeded.

Parameters

sc
val
opt

Returns

true

false

Definition at line 153 of file scale.c.

                                      {
 
        assert(sc != NULL);
        assert(val != NULL);
        assert(opt != NULL);
 
        size_t len;
        bool ok = false; //assume error
 
        switch(opt->strat) {
            case strategy_type_time:
                ok = scale_get_values_timeout(
                    sc,
                    opt->buffer,
                    opt->bufflen,
                    &len,
                    opt->timeout);
                break;
 
            case strategy_type_samples:
            default:
                assert(opt->bufflen >= opt->samples);
                len = opt->samples;
                ok = scale_get_values_samples(
                    sc,
                    opt->buffer,
                    len);
                break;
        }
 
        //exit early if fail
        if(!ok) {
            return false;
        }
 
        switch(opt->read) {
            case read_type_average:
                util_average(opt->buffer, len, val);
                break;
 
            case read_type_median:
            default:
                util_median(opt->buffer, len, val);
                break;
        }
 
        return true;
 
}

References scale_options_t::buffer, scale_options_t::bufflen, scale_options_t::read, read_type_average, read_type_median, scale_options_t::samples, scale_get_values_samples(), scale_get_values_timeout(), scale_options_t::strat, strategy_type_samples, strategy_type_time, scale_options_t::timeout, util_average(), and util_median().

Referenced by scale_weight(), and scale_zero().

scale_weight()

bool scale_weight	(	scale_t *const	sc,
		mass_t *const	m,
		const scale_options_t *const	opt
	)

Obtains a weight from the scale according to the given options. Returns true if the operation succeeded.

Parameters

sc
m
opt

Returns

true

false

Definition at line 231 of file scale.c.

                                      {
 
        assert(sc != NULL);
        assert(m != NULL);
        assert(opt != NULL);
 
        double val;
 
        //if the read fails, return false
        if(!scale_read(sc, &val, opt)) {
            return false;
        }
 
        //if normalising the value fails, return false
        if(!scale_normalise(sc, &val, &val)) {
            return false;
        }
 
        mass_init(m, sc->unit, val);
 
        return true;
 
}

References mass_init(), scale_normalise(), scale_read(), and scale_t::unit.

scale_zero()

bool scale_zero	(	scale_t *const	sc,
		const scale_options_t *const	opt
	)

Zeros the scale (tare) by adjusting its offset from 0 according to the given options. Returns true if the operation succeeded.

Parameters

sc
opt

Returns

true

false

Definition at line 206 of file scale.c.

                                      {
 
        assert(sc != NULL);
        assert(opt != NULL);
 
        double val;
        const int32_t refBackup = sc->ref_unit;
        bool ok = false;
 
        sc->ref_unit = 1;
 
        if((ok = scale_read(sc, &val, opt))) {
            //only change the offset if the read
            //succeeded
            sc->offset = (int32_t)round(val);
        }
 
        sc->ref_unit = refBackup;
 
        return ok;
 
}

References scale_t::offset, scale_t::ref_unit, and scale_read().

Variable Documentation

SCALE_DEFAULT_OPTIONS

const scale_options_t SCALE_DEFAULT_OPTIONS

static

Initial value:

= {
    .strat = strategy_type_samples,
    .read = read_type_median,
    .samples = 3, 
    .timeout = 1000000, 
    .buffer = NULL,
    .bufflen = 0
}

Definition at line 56 of file scale.h.

Referenced by scale_options_get_default().