hx711-pico-c
hx711.h File Reference
#include <stdbool.h>
#include <stdint.h>
#include "hardware/pio.h"
#include "pico/mutex.h"

Go to the source code of this file.

Data Structures

struct  hx711_t
 
struct  hx711_config_t
 

Macros

#define HX711_MUTEX_BLOCK(mut, ...)
 
#define HX711_READ_BITS   UINT8_C(24)
 
#define HX711_POWER_DOWN_TIMEOUT   UINT8_C(60)
 
#define HX711_MIN_VALUE   INT32_C(-0x800000)
 
#define HX711_MAX_VALUE   INT32_C(0x7fffff)
 
#define HX711_PIO_MIN_GAIN   UINT8_C(0)
 
#define HX711_PIO_MAX_GAIN   UINT8_C(2)
 

Typedefs

typedef void(* hx711_pio_init_t) (hx711_t *const)
 
typedef void(* hx711_program_init_t) (hx711_t *const)
 

Enumerations

enum  hx711_rate_t { hx711_rate_10 = 0 , hx711_rate_80 }
 
enum  hx711_gain_t { hx711_gain_128 = 0 , hx711_gain_32 , hx711_gain_64 }
 

Functions

void hx711_init (hx711_t *const hx, const hx711_config_t *const config)
 
void hx711_close (hx711_t *const hx)
 Stop communication with the HX711. More...
 
void hx711_set_gain (hx711_t *const hx, const hx711_gain_t gain)
 Sets the HX711 gain. More...
 
int32_t hx711_get_twos_comp (const uint32_t raw)
 Convert a raw value from the HX711 to a 32-bit signed int. More...
 
bool hx711_is_min_saturated (const int32_t val)
 Returns true if the HX711 is saturated at its minimum level. More...
 
bool hx711_is_max_saturated (const int32_t val)
 Returns true if the HX711 is saturated at its maximum level. More...
 
unsigned short hx711_get_settling_time (const hx711_rate_t rate)
 Returns the number of milliseconds to wait according to the given HX711 sample rate to allow readings to settle. More...
 
unsigned char hx711_get_rate_sps (const hx711_rate_t rate)
 Returns the numeric sample rate of the given rate. More...
 
unsigned char hx711_get_clock_pulses (const hx711_gain_t gain)
 Returns the clock pulse count for a given gain value. More...
 
int32_t hx711_get_value (hx711_t *const hx)
 Obtains a value from the HX711. Blocks until a value is available. More...
 
bool hx711_get_value_timeout (hx711_t *const hx, int32_t *const val, const uint timeout)
 Obtains a value from the HX711. Blocks until a value is available or the timeout is reached. More...
 
bool hx711_get_value_noblock (hx711_t *const hx, int32_t *const val)
 Obtains a value from the HX711. Returns immediately if no value is available. More...
 
static bool hx711__is_initd (hx711_t *const hx)
 Check whether the hx struct has been initalised. More...
 
static bool hx711__is_state_machine_enabled (hx711_t *const hx)
 Check whether the hx struct's state machines are running. More...
 
bool hx711_is_value_valid (const int32_t v)
 Check whether the given value is valid for a HX711 implementation. More...
 
bool hx711_is_pio_gain_valid (const uint32_t g)
 Check whether a given value is permitted to be transmitted to a PIO State Machine to set a HX711's gain according to the PIO program implementation. More...
 
bool hx711_is_rate_valid (const hx711_rate_t r)
 Check whether the given rate is within the range of the predefined rates. More...
 
bool hx711_is_gain_valid (const hx711_gain_t g)
 Check whether the given gain is within the range of the predefined gains. More...
 
void hx711_wait_settle (const hx711_rate_t rate)
 Convenience function for sleeping for the appropriate amount of time according to the given sample rate to allow readings to settle. More...
 
void hx711_wait_power_down ()
 Convenience function for sleeping for the appropriate amount of time to allow the HX711 to power down. More...
 
uint32_t hx711_gain_to_pio_gain (const hx711_gain_t gain)
 Convert a hx711_gain_t to a numeric value appropriate for a PIO State Machine. More...
 
static bool hx711__try_get_value (PIO const pio, const uint sm, uint32_t *const val)
 Attempts to obtain a value from the PIO RX FIFO if one is available. More...
 

Variables

const unsigned short HX711_SETTLING_TIMES [3]
 
const unsigned char HX711_SAMPLE_RATES [2]
 
const unsigned char HX711_CLOCK_PULSES [3]
 

Macro Definition Documentation

◆ HX711_MAX_VALUE

#define HX711_MAX_VALUE   INT32_C(0x7fffff)

Definition at line 53 of file hx711.h.

◆ HX711_MIN_VALUE

#define HX711_MIN_VALUE   INT32_C(-0x800000)

Definition at line 52 of file hx711.h.

◆ HX711_MUTEX_BLOCK

#define HX711_MUTEX_BLOCK (   mut,
  ... 
)
Value:
do { \
mutex_enter_blocking(&mut); \
__VA_ARGS__ \
mutex_exit(&mut); \
} while(0)

Definition at line 36 of file hx711.h.

◆ HX711_PIO_MAX_GAIN

#define HX711_PIO_MAX_GAIN   UINT8_C(2)

Definition at line 56 of file hx711.h.

◆ HX711_PIO_MIN_GAIN

#define HX711_PIO_MIN_GAIN   UINT8_C(0)

Definition at line 55 of file hx711.h.

◆ HX711_POWER_DOWN_TIMEOUT

#define HX711_POWER_DOWN_TIMEOUT   UINT8_C(60)

Definition at line 50 of file hx711.h.

◆ HX711_READ_BITS

#define HX711_READ_BITS   UINT8_C(24)

Definition at line 49 of file hx711.h.

Typedef Documentation

◆ hx711_pio_init_t

typedef void(* hx711_pio_init_t) (hx711_t *const)

Definition at line 90 of file hx711.h.

◆ hx711_program_init_t

typedef void(* hx711_program_init_t) (hx711_t *const)

Definition at line 91 of file hx711.h.

Enumeration Type Documentation

◆ hx711_gain_t

Enumerator
hx711_gain_128 
hx711_gain_32 
hx711_gain_64 

Definition at line 67 of file hx711.h.

67  {
68  hx711_gain_128 = 0,
71 } hx711_gain_t;
hx711_gain_t
Definition: hx711.h:67
@ hx711_gain_64
Definition: hx711.h:70
@ hx711_gain_32
Definition: hx711.h:69
@ hx711_gain_128
Definition: hx711.h:68

◆ hx711_rate_t

Enumerator
hx711_rate_10 
hx711_rate_80 

Definition at line 62 of file hx711.h.

62  {
63  hx711_rate_10 = 0,
65 } hx711_rate_t;
hx711_rate_t
Definition: hx711.h:62
@ hx711_rate_10
Definition: hx711.h:63
@ hx711_rate_80
Definition: hx711.h:64

Function Documentation

◆ hx711__is_initd()

static bool hx711__is_initd ( hx711_t *const  hx)
static

Check whether the hx struct has been initalised.

Parameters
hx
Returns
true
false

Definition at line 347 of file hx711.c.

347  {
348  return hx != NULL &&
349  hx->_pio != NULL &&
350 #ifndef HX711_NO_MUTEX
351  mutex_is_initialized(&hx->_mut) &&
352 #endif
353  pio_sm_is_claimed(hx->_pio, hx->_reader_sm);
354 }
PIO _pio
Definition: hx711.h:78
uint _reader_sm
Definition: hx711.h:81
mutex_t _mut
Definition: hx711.h:85

References hx711_t::_mut, hx711_t::_pio, and hx711_t::_reader_sm.

Referenced by hx711__is_state_machine_enabled(), hx711_close(), hx711_init(), hx711_power_down(), and hx711_power_up().

◆ hx711__is_state_machine_enabled()

static bool hx711__is_state_machine_enabled ( hx711_t *const  hx)
static

Check whether the hx struct's state machines are running.

Parameters
hx
Returns
true
false

Definition at line 356 of file hx711.c.

356  {
357  return hx711__is_initd(hx) &&
359 }
bool hx711__is_initd(hx711_t *const hx)
Check whether the hx struct has been initalised.
Definition: hx711.c:347
bool util_pio_sm_is_enabled(PIO const pio, const uint sm)
Check whether a given state machine is enabled.
Definition: util.c:366

References hx711_t::_pio, hx711_t::_reader_sm, hx711__is_initd(), and util_pio_sm_is_enabled().

Referenced by hx711_get_value(), hx711_get_value_noblock(), hx711_get_value_timeout(), hx711_power_up(), and hx711_set_gain().

◆ hx711__try_get_value()

static bool hx711__try_get_value ( PIO const  pio,
const uint  sm,
uint32_t *const  val 
)
static

Attempts to obtain a value from the PIO RX FIFO if one is available.

Parameters
piopointer to PIO
smstate machine
valpointer to raw value from HX711 to set
Returns
true if value was obtained
false if value was not obtained

Definition at line 516 of file hx711.c.

519  {
520 
521  assert(pio != NULL);
522  check_sm_param(sm);
523  assert(util_pio_sm_is_enabled(pio, sm));
524  assert(val != NULL);
525 
526  static const uint byteThreshold = HX711_READ_BITS / 8;
527 
528  return util_pio_sm_try_get(
529  pio,
530  sm,
531  val,
532  byteThreshold);
533 
534 }
#define HX711_READ_BITS
Definition: hx711.h:49
bool util_pio_sm_try_get(PIO const pio, const uint sm, uint32_t *const word, const uint threshold)
Attempts to get a word from the state machine's RX FIFO if more than threshold words are in the buffe...
Definition: util.c:484

References HX711_READ_BITS, util_pio_sm_is_enabled(), and util_pio_sm_try_get().

Referenced by hx711_get_value_noblock(), and hx711_get_value_timeout().

◆ hx711_close()

void hx711_close ( hx711_t *const  hx)

Stop communication with the HX711.

Parameters
hx

Definition at line 123 of file hx711.c.

123  {
124 
125  //state machines do not have to be running in order
126  //to close
127  assert(hx711__is_initd(hx));
128 
129  HX711_MUTEX_BLOCK(hx->_mut,
130 
131  pio_sm_set_enabled(
132  hx->_pio,
133  hx->_reader_sm,
134  false);
135 
136  pio_sm_unclaim(
137  hx->_pio,
138  hx->_reader_sm);
139 
140  pio_remove_program(
141  hx->_pio,
142  hx->_reader_prog,
143  hx->_reader_offset);
144 
145  );
146 
147 }
#define HX711_MUTEX_BLOCK(mut,...)
Definition: hx711.h:36
const pio_program_t * _reader_prog
Definition: hx711.h:79
uint _reader_offset
Definition: hx711.h:82

References hx711_t::_mut, hx711_t::_pio, hx711_t::_reader_offset, hx711_t::_reader_prog, hx711_t::_reader_sm, hx711__is_initd(), and HX711_MUTEX_BLOCK.

◆ hx711_gain_to_pio_gain()

uint32_t hx711_gain_to_pio_gain ( const hx711_gain_t  gain)

Convert a hx711_gain_t to a numeric value appropriate for a PIO State Machine.

Parameters
gain
Returns
uint32_t

gain value is 0-based and calculated by: gain = clock pulses - 24 - 1 ie. gain of 128 is 25 clock pulses, so gain = 25 - 24 - 1 gain = 0

Definition at line 495 of file hx711.c.

495  {
496 
505  assert(hx711_is_gain_valid(gain));
506 
507  const uint32_t clockPulses =
509 
510  assert(hx711_is_pio_gain_valid(clockPulses));
511 
512  return clockPulses;
513 
514 }
bool hx711_is_gain_valid(const hx711_gain_t g)
Check whether the given gain is within the range of the predefined gains.
Definition: hx711.c:382
bool hx711_is_pio_gain_valid(const uint32_t g)
Check whether a given value is permitted to be transmitted to a PIO State Machine to set a HX711's ga...
Definition: hx711.c:368
unsigned char hx711_get_clock_pulses(const hx711_gain_t gain)
Returns the clock pulse count for a given gain value.
Definition: hx711.c:259

References hx711_get_clock_pulses(), hx711_is_gain_valid(), hx711_is_pio_gain_valid(), and HX711_READ_BITS.

Referenced by hx711_multi_power_up(), hx711_multi_set_gain(), hx711_power_up(), and hx711_set_gain().

◆ hx711_get_clock_pulses()

unsigned char hx711_get_clock_pulses ( const hx711_gain_t  gain)

Returns the clock pulse count for a given gain value.

Parameters
gain
Returns
unsigned char

Definition at line 259 of file hx711.c.

259  {
260  assert(hx711_is_gain_valid(gain));
261  assert((int)gain <= count_of(HX711_CLOCK_PULSES) - 1);
262  return HX711_CLOCK_PULSES[(int)gain];
263 }
const unsigned char HX711_CLOCK_PULSES[]
Definition: hx711.c:44

References HX711_CLOCK_PULSES, and hx711_is_gain_valid().

Referenced by hx711_gain_to_pio_gain().

◆ hx711_get_rate_sps()

unsigned char hx711_get_rate_sps ( const hx711_rate_t  rate)

Returns the numeric sample rate of the given rate.

Parameters
rate
Returns
unsigned char

Definition at line 253 of file hx711.c.

253  {
254  assert(hx711_is_rate_valid(rate));
255  assert((int)rate <= count_of(HX711_SAMPLE_RATES) - 1);
256  return HX711_SAMPLE_RATES[(int)rate];
257 }
bool hx711_is_rate_valid(const hx711_rate_t r)
Check whether the given rate is within the range of the predefined rates.
Definition: hx711.c:375
const unsigned char HX711_SAMPLE_RATES[]
Definition: hx711.c:39

References hx711_is_rate_valid(), and HX711_SAMPLE_RATES.

◆ hx711_get_settling_time()

unsigned short hx711_get_settling_time ( const hx711_rate_t  rate)

Returns the number of milliseconds to wait according to the given HX711 sample rate to allow readings to settle.

Parameters
rate
Returns
unsigned short

Definition at line 247 of file hx711.c.

247  {
248  assert(hx711_is_rate_valid(rate));
249  assert((int)rate <= count_of(HX711_SETTLING_TIMES) - 1);
250  return HX711_SETTLING_TIMES[(int)rate];
251 }
const unsigned short HX711_SETTLING_TIMES[]
Definition: hx711.c:34

References hx711_is_rate_valid(), and HX711_SETTLING_TIMES.

Referenced by hx711_wait_settle().

◆ hx711_get_twos_comp()

int32_t hx711_get_twos_comp ( const uint32_t  raw)

Convert a raw value from the HX711 to a 32-bit signed int.

Parameters
raw
Returns
int32_t

Definition at line 231 of file hx711.c.

231  {
232  return
233  (int32_t)(-(raw & +HX711_MIN_VALUE)) +
234  (int32_t)(raw & HX711_MAX_VALUE);
235 }
#define HX711_MIN_VALUE
Definition: hx711.h:52
#define HX711_MAX_VALUE
Definition: hx711.h:53

References HX711_MAX_VALUE, and HX711_MIN_VALUE.

Referenced by hx711_get_value(), hx711_get_value_noblock(), hx711_get_value_timeout(), and hx711_multi_pinvals_to_values().

◆ hx711_get_value()

int32_t hx711_get_value ( hx711_t *const  hx)

Obtains a value from the HX711. Blocks until a value is available.

Parameters
hx
Returns
int32_t

Block until a value is available

NOTE: remember that reading from the RX FIFO simultaneously clears it. That's why we can keep calling this function hx711_get_value and be assured we'll be getting a new value each time, even if the RX FIFO is currently empty.

Definition at line 265 of file hx711.c.

265  {
266 
268 
269  uint32_t rawVal;
270 
271  HX711_MUTEX_BLOCK(hx->_mut,
272 
282  rawVal = pio_sm_get_blocking(
283  hx->_pio,
284  hx->_reader_sm);
285 
286  );
287 
288  return hx711_get_twos_comp(rawVal);
289 
290 }
int32_t hx711_get_twos_comp(const uint32_t raw)
Convert a raw value from the HX711 to a 32-bit signed int.
Definition: hx711.c:231
bool hx711__is_state_machine_enabled(hx711_t *const hx)
Check whether the hx struct's state machines are running.
Definition: hx711.c:356

References hx711_t::_mut, hx711_t::_pio, hx711_t::_reader_sm, hx711__is_state_machine_enabled(), hx711_get_twos_comp(), and HX711_MUTEX_BLOCK.

◆ hx711_get_value_noblock()

bool hx711_get_value_noblock ( hx711_t *const  hx,
int32_t *const  val 
)

Obtains a value from the HX711. Returns immediately if no value is available.

Parameters
hx
valpointer to the value
Returns
true if a value was available and val is set
false if a value was not available

Definition at line 322 of file hx711.c.

324  {
325 
327  assert(val != NULL);
328 
329  bool success;
330  uint32_t tempVal;
331 
332  HX711_MUTEX_BLOCK(hx->_mut,
333  success = hx711__try_get_value(
334  hx->_pio,
335  hx->_reader_sm,
336  &tempVal);
337  );
338 
339  if(success) {
340  *val = hx711_get_twos_comp(tempVal);
341  }
342 
343  return success;
344 
345 }
bool hx711__try_get_value(PIO const pio, const uint sm, uint32_t *const val)
Attempts to obtain a value from the PIO RX FIFO if one is available.
Definition: hx711.c:516

References hx711_t::_mut, hx711_t::_pio, hx711_t::_reader_sm, hx711__is_state_machine_enabled(), hx711__try_get_value(), hx711_get_twos_comp(), and HX711_MUTEX_BLOCK.

◆ hx711_get_value_timeout()

bool hx711_get_value_timeout ( hx711_t *const  hx,
int32_t *const  val,
const uint  timeout 
)

Obtains a value from the HX711. Blocks until a value is available or the timeout is reached.

Parameters
hx
valpointer to the value
timeoutmaximum time to wait for a value in microseconds
Returns
true if a value was obtained within the timeout
false if a timeout was reached

Definition at line 292 of file hx711.c.

295  {
296 
298  assert(val != NULL);
299 
300  bool success = false;
301  const absolute_time_t endTime = make_timeout_time_us(timeout);
302  uint32_t tempVal;
303 
304  assert(!is_nil_time(endTime));
305 
306  HX711_MUTEX_BLOCK(hx->_mut,
307  while(!time_reached(endTime)) {
308  if((success = hx711__try_get_value(hx->_pio, hx->_reader_sm, &tempVal))) {
309  break;
310  }
311  }
312  );
313 
314  if(success) {
315  *val = hx711_get_twos_comp(tempVal);
316  }
317 
318  return success;
319 
320 }

References hx711_t::_mut, hx711_t::_pio, hx711_t::_reader_sm, hx711__is_state_machine_enabled(), hx711__try_get_value(), hx711_get_twos_comp(), and HX711_MUTEX_BLOCK.

◆ hx711_init()

void hx711_init ( hx711_t *const  hx,
const hx711_config_t *const  config 
)

There was originally a call here to gpio_put on the clock pin to power up the HX711. I have decided to remove this and also remove enabling the state machine from the pio init function. This does leave the HX711's power state undefined from the perspective of the code, but does give a much clearer separation of duties. This function merely init's the hardware and state machine, and the hx711_set_power function sets the power and enables/disables the state machine.

There was originally a call here to gpio_pull_up on the data pin to prevent erroneous data ready states. This was incorrect. Page 4 of the datasheet states: "The 25th pulse at PD_SCK input will pull DOUT pin back to high (Fig.2)."

Definition at line 50 of file hx711.c.

52  {
53 
54  assert(!hx711__is_initd(hx));
55 
56  assert(hx != NULL);
57  assert(config != NULL);
58 
59  assert(config->pio != NULL);
60  assert(config->pio_init != NULL);
61 
62  assert(config->reader_prog != NULL);
63  assert(config->reader_prog_init != NULL);
64 
65  check_gpio_param(config->clock_pin);
66  check_gpio_param(config->data_pin);
67  assert(config->clock_pin != config->data_pin);
68 
69 #ifndef HX711_NO_MUTEX
70  mutex_init(&hx->_mut);
71 #endif
72 
74 
75  hx->_clock_pin = config->clock_pin;
76  hx->_data_pin = config->data_pin;
77  hx->_pio = config->pio;
78  hx->_reader_prog = config->reader_prog;
79 
81 
95  gpio_set_input_enabled(
96  hx->_data_pin,
97  true);
98 
107  //either statement below will panic if it fails
108  hx->_reader_offset = pio_add_program(
109  hx->_pio,
110  hx->_reader_prog);
111 
112  hx->_reader_sm = (uint)pio_claim_unused_sm(
113  hx->_pio,
114  true);
115 
116  config->pio_init(hx);
117  config->reader_prog_init(hx);
118 
119  );
120 
121 }
uint clock_pin
Definition: hx711.h:95
hx711_pio_init_t pio_init
Definition: hx711.h:99
const pio_program_t * reader_prog
Definition: hx711.h:101
hx711_program_init_t reader_prog_init
Definition: hx711.h:102
uint data_pin
Definition: hx711.h:96
uint _data_pin
Definition: hx711.h:76
uint _clock_pin
Definition: hx711.h:75
void util_gpio_set_output(const uint gpio)
Initialises and sets GPIO pin to output.
Definition: util.c:185

References hx711_t::_clock_pin, hx711_t::_data_pin, hx711_t::_mut, hx711_t::_pio, hx711_t::_reader_offset, hx711_t::_reader_prog, hx711_t::_reader_sm, hx711_config_t::clock_pin, hx711_config_t::data_pin, hx711__is_initd(), HX711_MUTEX_BLOCK, hx711_config_t::pio, hx711_config_t::pio_init, hx711_config_t::reader_prog, hx711_config_t::reader_prog_init, and util_gpio_set_output().

◆ hx711_is_gain_valid()

bool hx711_is_gain_valid ( const hx711_gain_t  g)

Check whether the given gain is within the range of the predefined gains.

Parameters
g
Returns
true
false

Definition at line 382 of file hx711.c.

382  {
383  return util_int_in_range(
384  (int)g,
386  hx711_gain_64);
387 }

References hx711_gain_128, and hx711_gain_64.

Referenced by hx711_gain_to_pio_gain(), hx711_get_clock_pulses(), hx711_power_up(), and hx711_set_gain().

◆ hx711_is_max_saturated()

bool hx711_is_max_saturated ( const int32_t  val)

Returns true if the HX711 is saturated at its maximum level.

Parameters
val
Returns
true
false

Definition at line 242 of file hx711.c.

242  {
243  assert(hx711_is_value_valid(val));
244  return val == HX711_MAX_VALUE;
245 }
bool hx711_is_value_valid(const int32_t v)
Check whether the given value is valid for a HX711 implementation.
Definition: hx711.c:361

References hx711_is_value_valid(), and HX711_MAX_VALUE.

◆ hx711_is_min_saturated()

bool hx711_is_min_saturated ( const int32_t  val)

Returns true if the HX711 is saturated at its minimum level.

Parameters
val
Returns
true
false

Definition at line 237 of file hx711.c.

237  {
238  assert(hx711_is_value_valid(val));
239  return val == HX711_MIN_VALUE;
240 }

References hx711_is_value_valid(), and HX711_MIN_VALUE.

◆ hx711_is_pio_gain_valid()

bool hx711_is_pio_gain_valid ( const uint32_t  g)

Check whether a given value is permitted to be transmitted to a PIO State Machine to set a HX711's gain according to the PIO program implementation.

Parameters
g
Returns
true
false

Definition at line 368 of file hx711.c.

368  {
369  return util_uint32_t_in_range(
370  g,
373 }
#define HX711_PIO_MAX_GAIN
Definition: hx711.h:56
#define HX711_PIO_MIN_GAIN
Definition: hx711.h:55

References HX711_PIO_MAX_GAIN, and HX711_PIO_MIN_GAIN.

Referenced by hx711_gain_to_pio_gain(), hx711_multi_power_up(), hx711_multi_set_gain(), hx711_power_up(), and hx711_set_gain().

◆ hx711_is_rate_valid()

bool hx711_is_rate_valid ( const hx711_rate_t  r)

Check whether the given rate is within the range of the predefined rates.

Parameters
r
Returns
true
false

Definition at line 375 of file hx711.c.

375  {
376  return util_int_in_range(
377  (int)r,
379  hx711_rate_80);
380 }

References hx711_rate_10, and hx711_rate_80.

Referenced by hx711_get_rate_sps(), and hx711_get_settling_time().

◆ hx711_is_value_valid()

bool hx711_is_value_valid ( const int32_t  v)

Check whether the given value is valid for a HX711 implementation.

Parameters
v
Returns
true
false

Definition at line 361 of file hx711.c.

361  {
362  return util_int32_t_in_range(
363  v,
366 }

References HX711_MAX_VALUE, and HX711_MIN_VALUE.

Referenced by hx711_is_max_saturated(), hx711_is_min_saturated(), and hx711_multi_pinvals_to_values().

◆ hx711_set_gain()

void hx711_set_gain ( hx711_t *const  hx,
const hx711_gain_t  gain 
)

Sets the HX711 gain.

Parameters
hx
gain

Before putting anything in the TX FIFO buffer, assume the worst-case scenario which is that there's something already in there. There ought not to be, but clearing it ensures the following pio_sm_put* call does not need to block as this function to change the gain should take precedence.

At this point the current value in the RX FIFO will have been calculated based on whatever the previous set gain was. So, the RX FIFO needs to be cleared.

NOTE: checking for whether the RX FIFO is not empty won't work. A conversion may have already begun before any bits have been moved into the ISR.

UPDATE: the worst-case scenario here is that the pio_sm_put call has occurred after the pio "pull", because we then need to wait until the following "pull" in the state machine. If this happens:

  1. there may already be a value in the RX FIFO; and
  2. another value will need to be read and discarded following which the new gain will be set.

To handle 1.: Clear the RX FIFO with a non-blocking read. If the RX FIFO is empty, no harm done because the call won't block.

To handle 2.: Read the "next" value with a blocking read to ensure the "next, next" value will be set to the desired gain.

Immediately following the above blocking call, the state machine will pull in the data in the pio_sm_put call above and pulse the HX711 the correct number of times to set the desired gain.

No further communication with the state machine from this function is required. Any other function(s) wishing to obtain a value from the HX711 need only block until one is there (or check the RX FIFO level).

Definition at line 149 of file hx711.c.

149  {
150 
152  assert(hx711_is_gain_valid(gain));
153 
154  const uint32_t pioGain = hx711_gain_to_pio_gain(gain);
155 
156  assert(hx711_is_pio_gain_valid(pioGain));
157 
158  HX711_MUTEX_BLOCK(hx->_mut,
159 
168  pio_sm_drain_tx_fifo(
169  hx->_pio,
170  hx->_reader_sm);
171 
172  pio_sm_put(
173  hx->_pio,
174  hx->_reader_sm,
175  pioGain);
176 
204  //1. clear the RX FIFO with the non-blocking read
205  pio_sm_get(
206  hx->_pio,
207  hx->_reader_sm);
208 
209  //2. wait until the value from the currently-set gain
210  //can be safely read and discarded
211  pio_sm_get_blocking(
212  hx->_pio,
213  hx->_reader_sm);
214 
227  );
228 
229 }
uint32_t hx711_gain_to_pio_gain(const hx711_gain_t gain)
Convert a hx711_gain_t to a numeric value appropriate for a PIO State Machine.
Definition: hx711.c:495

References hx711_t::_mut, hx711_t::_pio, hx711_t::_reader_sm, hx711__is_state_machine_enabled(), hx711_gain_to_pio_gain(), hx711_is_gain_valid(), hx711_is_pio_gain_valid(), and HX711_MUTEX_BLOCK.

◆ hx711_wait_power_down()

void hx711_wait_power_down ( )

Convenience function for sleeping for the appropriate amount of time to allow the HX711 to power down.

Definition at line 491 of file hx711.c.

491  {
492  sleep_us(HX711_POWER_DOWN_TIMEOUT);
493 }
#define HX711_POWER_DOWN_TIMEOUT
Definition: hx711.h:50

References HX711_POWER_DOWN_TIMEOUT.

Referenced by hx711_multi_sync().

◆ hx711_wait_settle()

void hx711_wait_settle ( const hx711_rate_t  rate)

Convenience function for sleeping for the appropriate amount of time according to the given sample rate to allow readings to settle.

Parameters
rate

Definition at line 487 of file hx711.c.

487  {
488  sleep_ms(hx711_get_settling_time(rate));
489 }
unsigned short hx711_get_settling_time(const hx711_rate_t rate)
Returns the number of milliseconds to wait according to the given HX711 sample rate to allow readings...
Definition: hx711.c:247

References hx711_get_settling_time().

Variable Documentation

◆ HX711_CLOCK_PULSES

const unsigned char HX711_CLOCK_PULSES[3]
extern

Definition at line 44 of file hx711.c.

Referenced by hx711_get_clock_pulses().

◆ HX711_SAMPLE_RATES

const unsigned char HX711_SAMPLE_RATES[2]
extern

Definition at line 39 of file hx711.c.

Referenced by hx711_get_rate_sps().

◆ HX711_SETTLING_TIMES

const unsigned short HX711_SETTLING_TIMES[3]
extern

Definition at line 34 of file hx711.c.

Referenced by hx711_get_settling_time().