hx711_multi.h File Reference

#include <stdint.h>
#include <strings.h>
#include "hardware/pio.h"
#include "pico/mutex.h"
#include "pico/platform.h"
#include "hx711.h"

Go to the source code of this file.

Data Structures
struct	hx711_multi_t
struct	hx711_multi_config_t

Macros
#define	HX711_MULTI_CONVERSION_DONE_IRQ_NUM   UINT8_C(0)
	PIO interrupt number which is set by the reader PIO State Machine when a conversion period ends. It is the period of time between a conversion ending and the next period beginning. More...
#define	HX711_MULTI_DATA_READY_IRQ_NUM   UINT8_C(4)
	PIO interrupt number which is used between the awaiter and reader PIO State Machines to indicate when data is ready to be retrieved. It is not used directly within the main set of code, but is used to validate that the IRQ number is properly available. More...
#define	HX711_MULTI_ASYNC_READ_COUNT   UINT8_C(NUM_PIOS)
	Only one instance of a hx711_multi can operate within a PIO. So the maximum number of concurrent asynchronous read processes is limited to the numeer of PIOs available. More...
#define	HX711_MULTI_ASYNC_PIO_IRQ_IDX   UINT8_C(0)
	IRQ index defaults for PIO and DMA. More...
#define	HX711_MULTI_ASYNC_DMA_IRQ_IDX   UINT8_C(0)
#define	HX711_MULTI_MIN_CHIPS   UINT8_C(1)
	Minimum number of chips to connect to a hx711_multi. More...
#define	HX711_MULTI_MAX_CHIPS   UINT8_C(MIN(NUM_BANK0_GPIOS, 32))
	The max number of chips could technically be the same as the number of bits output from the PIO State Machine. But this is always going to be limited by the number of GPIO input pins available on the RP2040. So we take the minimum of the two just in case it ever increases. More...

Typedefs
typedef void(*	hx711_multi_pio_init_t) (hx711_multi_t *const)
typedef void(*	hx711_multi_program_init_t) (hx711_multi_t *const)

Enumerations
enum	hx711_multi_async_state_t { HX711_MULTI_ASYNC_STATE_NONE = 0 , HX711_MULTI_ASYNC_STATE_WAITING , HX711_MULTI_ASYNC_STATE_READING , HX711_MULTI_ASYNC_STATE_DONE }
	State of the read as it moves through the async process. More...

Functions
static void	hx711_multi__init_asert (const hx711_multi_config_t *const config)
static void	hx711_multi__init_pio (hx711_multi_t *const hxm)
	Subroutine for initialising PIO. More...
static void	hx711_multi__init_dma (hx711_multi_t *const hxm)
	Subroutine for initialising DMA. More...
static void	hx711_multi__init_irq (hx711_multi_t *const hxm)
	Subroutine for initialising IRQ. More...
static bool	hx711_multi__async_dma_irq_is_set (hx711_multi_t *const hxm)
	Whether a given hxm is the cause of the current DMA IRQ. More...
static bool	hx711_multi__async_pio_irq_is_set (hx711_multi_t *const hxm)
	Whether a given hxm is the cause of the current PIO IRQ. More...
static hx711_multi_t *const	hx711_multi__async_get_dma_irq_request ()
	Get the hxm which caused the current DMA IRQ. Returns NULL if none found. More...
static hx711_multi_t *const	hx711_multi__async_get_pio_irq_request ()
	Get the hxm which caused the current PIO IRQ. Returns NULL if none found. More...
static void	hx711_multi__async_start_dma (hx711_multi_t *const hxm)
	Triggers DMA reading; moves request state from WAITING to READING. More...
static bool	hx711_multi__async_is_running (hx711_multi_t *const hxm)
	Check whether an async read is currently occurring. More...
static void	hx711_multi__async_finish (hx711_multi_t *const hxm)
	Stop any current async reads and stop listening for DMA and PIO IRQs. More...
static void __isr __not_in_flash_func()	hx711_multi__async_pio_irq_handler ()
	ISR handler for PIO IRQs. More...
static void __isr __not_in_flash_func()	hx711_multi__async_dma_irq_handler ()
	ISR handler for DMA IRQs. More...
static bool	hx711_multi__async_add_reader (hx711_multi_t *const hxm)
	Adds hxm to the array for ISR access. Returns false if no space. More...
static void	hx711_multi__async_remove_reader (const hx711_multi_t *const hxm)
	Removes the given hxm from the request array. More...
static bool	hx711_multi__is_initd (hx711_multi_t *const hxm)
	Check whether the hxm struct has been initialised. More...
static bool	hx711_multi__is_state_machines_enabled (hx711_multi_t *const hxm)
	Check whether the hxm struct has PIO State Machines which are enabled. More...
void	hx711_multi_pinvals_to_values (const uint32_t *const pinvals, int32_t *const values, const size_t len)
	Convert an array of pinvals to regular HX711 values. More...
void	hx711_multi_init (hx711_multi_t *const hxm, const hx711_multi_config_t *const config)
void	hx711_multi_close (hx711_multi_t *const hxm)
	Stop communication with all HX711s. More...
void	hx711_multi_set_gain (hx711_multi_t *const hxm, const hx711_gain_t gain)
	Sets the HX711s' gain. More...
void	hx711_multi_get_values (hx711_multi_t *const hxm, int32_t *const values)
	Fill an array with one value from each HX711. Blocks until values are obtained. More...
bool	hx711_multi_get_values_timeout (hx711_multi_t *const hxm, int32_t *const values, const uint timeout)
	Fill an array with one value from each HX711, timing out if failing to obtain values within the timeout period. More...
void	hx711_multi_async_start (hx711_multi_t *const hxm)
	Start an asynchronos read. This function is not mutex protected. More...
bool	hx711_multi_async_done (hx711_multi_t *const hxm)
	Check whether an asynchronous read is complete. This function is not mutex protected. More...
void	hx711_multi_async_get_values (hx711_multi_t *const hxm, int32_t *const values)
	Get the values from the last asynchronous read. This function is not mutex protected. More...
void	hx711_multi_sync (hx711_multi_t *const hxm, const hx711_gain_t gain)
	Attempt to synchronise all connected chips. This does not include a settling time. More...
uint32_t	hx711_multi_get_sync_state (hx711_multi_t *const hxm)
	Returns the state of each chip as a bitmask. The 0th bit is the first chip, 1th bit is the second, and so on. More...
bool	hx711_multi_is_syncd (hx711_multi_t *const hxm)
	Determines whether all chips are in sync. More...

Variables
hx711_multi_t *	hx711_multi__async_read_array [HX711_MULTI_ASYNC_READ_COUNT]
	Array of hxm for ISR to access. This is a global variable. More...

Macro Definition Documentation

HX711_MULTI_ASYNC_DMA_IRQ_IDX

#define HX711_MULTI_ASYNC_DMA_IRQ_IDX   UINT8_C(0)

Definition at line 66 of file hx711_multi.h.

HX711_MULTI_ASYNC_PIO_IRQ_IDX

#define HX711_MULTI_ASYNC_PIO_IRQ_IDX   UINT8_C(0)

IRQ index defaults for PIO and DMA.

Definition at line 65 of file hx711_multi.h.

HX711_MULTI_ASYNC_READ_COUNT

#define HX711_MULTI_ASYNC_READ_COUNT   UINT8_C(NUM_PIOS)

Only one instance of a hx711_multi can operate within a PIO. So the maximum number of concurrent asynchronous read processes is limited to the numeer of PIOs available.

Definition at line 60 of file hx711_multi.h.

HX711_MULTI_CONVERSION_DONE_IRQ_NUM

#define HX711_MULTI_CONVERSION_DONE_IRQ_NUM   UINT8_C(0)

PIO interrupt number which is set by the reader PIO State Machine when a conversion period ends. It is the period of time between a conversion ending and the next period beginning.

Definition at line 43 of file hx711_multi.h.

HX711_MULTI_DATA_READY_IRQ_NUM

#define HX711_MULTI_DATA_READY_IRQ_NUM   UINT8_C(4)

PIO interrupt number which is used between the awaiter and reader PIO State Machines to indicate when data is ready to be retrieved. It is not used directly within the main set of code, but is used to validate that the IRQ number is properly available.

Definition at line 52 of file hx711_multi.h.

HX711_MULTI_MAX_CHIPS

#define HX711_MULTI_MAX_CHIPS   UINT8_C(MIN(NUM_BANK0_GPIOS, 32))

The max number of chips could technically be the same as the number of bits output from the PIO State Machine. But this is always going to be limited by the number of GPIO input pins available on the RP2040. So we take the minimum of the two just in case it ever increases.

Definition at line 80 of file hx711_multi.h.

HX711_MULTI_MIN_CHIPS

#define HX711_MULTI_MIN_CHIPS   UINT8_C(1)

Minimum number of chips to connect to a hx711_multi.

Definition at line 71 of file hx711_multi.h.

Typedef Documentation

hx711_multi_pio_init_t

typedef void(* hx711_multi_pio_init_t) (hx711_multi_t *const)

Definition at line 124 of file hx711_multi.h.

hx711_multi_program_init_t

typedef void(* hx711_multi_program_init_t) (hx711_multi_t *const)

Definition at line 125 of file hx711_multi.h.

Enumeration Type Documentation

hx711_multi_async_state_t

enum hx711_multi_async_state_t

State of the read as it moves through the async process.

Enumerator
HX711_MULTI_ASYNC_STATE_NONE
HX711_MULTI_ASYNC_STATE_WAITING
HX711_MULTI_ASYNC_STATE_READING
HX711_MULTI_ASYNC_STATE_DONE

Definition at line 85 of file hx711_multi.h.

             {
    HX711_MULTI_ASYNC_STATE_NONE = 0,
    HX711_MULTI_ASYNC_STATE_WAITING,
    HX711_MULTI_ASYNC_STATE_READING,
    HX711_MULTI_ASYNC_STATE_DONE
} hx711_multi_async_state_t;

Function Documentation

hx711_multi__async_add_reader()

static bool hx711_multi__async_add_reader ( hx711_multi_t *const  hxm )

static

Adds hxm to the array for ISR access. Returns false if no space.

Parameters

hxm

Returns

true

false

Definition at line 405 of file hx711_multi.c.

                              {
 
        assert(hx711_multi__async_read_array != NULL);
 
        for(uint i = 0; i < HX711_MULTI_ASYNC_READ_COUNT; ++i) {
            if(hx711_multi__async_read_array[i] == NULL) {
                hx711_multi__async_read_array[i] = hxm;
                return true;
            }
        }
 
        return false;
 
}

References hx711_multi__async_read_array, and HX711_MULTI_ASYNC_READ_COUNT.

Referenced by hx711_multi_init().

hx711_multi__async_dma_irq_handler()

static void __isr __not_in_flash_func() hx711_multi__async_dma_irq_handler ( )

static

ISR handler for DMA IRQs.

Definition at line 383 of file hx711_multi.c.

                                                                     {
 
    hx711_multi_t* const hxm =
        hx711_multi__async_get_dma_irq_request();
 
    assert(hx711_multi__is_state_machines_enabled(hxm));
    assert(hxm->_async_state == HX711_MULTI_ASYNC_STATE_READING);
 
    hxm->_async_state = HX711_MULTI_ASYNC_STATE_DONE;
 
    dma_irqn_acknowledge_channel(
        hxm->_dma_irq_index,
        hxm->_dma_channel);
 
    hx711_multi__async_finish(hxm);
 
    irq_clear(
        util_dma_get_irqn(
            hxm->_dma_irq_index));
 
}

References hx711_multi_t::_async_state, hx711_multi_t::_dma_channel, hx711_multi_t::_dma_irq_index, hx711_multi__async_finish(), hx711_multi__async_get_dma_irq_request(), hx711_multi__is_state_machines_enabled(), HX711_MULTI_ASYNC_STATE_DONE, HX711_MULTI_ASYNC_STATE_READING, and util_dma_get_irqn().

Referenced by hx711_multi__init_irq(), and hx711_multi__is_initd().

hx711_multi__async_dma_irq_is_set()

static bool hx711_multi__async_dma_irq_is_set ( hx711_multi_t *const  hxm )

static

Whether a given hxm is the cause of the current DMA IRQ.

Parameters

hxm

Returns

true

false

Definition at line 232 of file hx711_multi.c.

                              {
 
        assert(hx711_multi__is_initd(hxm));
 
        return dma_irqn_get_channel_status(
            hxm->_dma_irq_index,
            hxm->_dma_channel);
 
}

References hx711_multi_t::_dma_channel, hx711_multi_t::_dma_irq_index, and hx711_multi__is_initd().

Referenced by hx711_multi__async_get_dma_irq_request().

hx711_multi__async_finish()

static void hx711_multi__async_finish ( hx711_multi_t *const  hxm )

static

Stop any current async reads and stop listening for DMA and PIO IRQs.

Parameters

hxm

hx711_multi__async_get_dma_irq_request()

static hx711_multi_t* const hx711_multi__async_get_dma_irq_request ( )

static

Get the hxm which caused the current DMA IRQ. Returns NULL if none found.

Returns

hx711_multi_t* const

Definition at line 254 of file hx711_multi.c.

                                                              {
 
    assert(hx711_multi__async_read_array != NULL);
 
    for(uint i = 0; i < HX711_MULTI_ASYNC_READ_COUNT; ++i) {
 
        if(hx711_multi__async_read_array[i] == NULL) {
            continue;
        }
        
        if(hx711_multi__async_dma_irq_is_set(hx711_multi__async_read_array[i])) {
            return hx711_multi__async_read_array[i];
        }
 
    }
 
    return NULL;
 
}

References hx711_multi__async_dma_irq_is_set(), hx711_multi__async_read_array, and HX711_MULTI_ASYNC_READ_COUNT.

Referenced by hx711_multi__async_dma_irq_handler().

hx711_multi__async_get_pio_irq_request()

static hx711_multi_t* const hx711_multi__async_get_pio_irq_request ( )

static

Get the hxm which caused the current PIO IRQ. Returns NULL if none found.

Returns

hx711_multi_t* const

Definition at line 274 of file hx711_multi.c.

                                                              {
 
    assert(hx711_multi__async_read_array != NULL);
 
    for(uint i = 0; i < HX711_MULTI_ASYNC_READ_COUNT; ++i) {
 
        if(hx711_multi__async_read_array[i] == NULL) {
            continue;
        }
 
        if(hx711_multi__async_pio_irq_is_set(hx711_multi__async_read_array[i])) {
            return hx711_multi__async_read_array[i];
        }
 
    }
 
    return NULL;
 
}

References hx711_multi__async_pio_irq_is_set(), hx711_multi__async_read_array, and HX711_MULTI_ASYNC_READ_COUNT.

Referenced by hx711_multi__async_pio_irq_handler().

hx711_multi__async_is_running()

static bool hx711_multi__async_is_running ( hx711_multi_t *const  hxm )

static

Check whether an async read is currently occurring.

Parameters

hxm

Returns

true

false

Definition at line 319 of file hx711_multi.c.

                              {
 
        assert(hx711_multi__is_state_machines_enabled(hxm));
 
        switch(hxm->_async_state) {
            case HX711_MULTI_ASYNC_STATE_WAITING:
            case HX711_MULTI_ASYNC_STATE_READING:
                return true;
            default:
                //anything else is not considered running
                return false;
        }
 
}

References hx711_multi_t::_async_state, hx711_multi__is_state_machines_enabled(), HX711_MULTI_ASYNC_STATE_READING, and HX711_MULTI_ASYNC_STATE_WAITING.

Referenced by hx711_multi_async_start(), hx711_multi_get_values(), and hx711_multi_get_values_timeout().

hx711_multi__async_pio_irq_handler()

static void __isr __not_in_flash_func() hx711_multi__async_pio_irq_handler ( )

static

ISR handler for PIO IRQs.

Definition at line 361 of file hx711_multi.c.

                                                                     {
 
    hx711_multi_t* const hxm = 
        hx711_multi__async_get_pio_irq_request();
 
    assert(hx711_multi__is_state_machines_enabled(hxm));
    assert(hxm->_async_state == HX711_MULTI_ASYNC_STATE_WAITING);
 
    hx711_multi__async_start_dma(hxm);
 
    //disable listening until required again
    pio_set_irqn_source_enabled(
        hxm->_pio,
        hxm->_pio_irq_index,
        util_pio_get_pis_from_pio_interrupt_num(HX711_MULTI_CONVERSION_DONE_IRQ_NUM),
        false);
 
    irq_clear(
        util_pio_get_irq_from_index(hxm->_pio, hxm->_pio_irq_index));
 
}

References hx711_multi_t::_async_state, hx711_multi_t::_pio, hx711_multi_t::_pio_irq_index, hx711_multi__async_get_pio_irq_request(), hx711_multi__async_start_dma(), hx711_multi__is_state_machines_enabled(), HX711_MULTI_ASYNC_STATE_WAITING, HX711_MULTI_CONVERSION_DONE_IRQ_NUM, util_pio_get_irq_from_index(), and util_pio_get_pis_from_pio_interrupt_num().

Referenced by hx711_multi__init_irq(), hx711_multi__is_initd(), and hx711_multi_close().

hx711_multi__async_pio_irq_is_set()

static bool hx711_multi__async_pio_irq_is_set ( hx711_multi_t *const  hxm )

static

Whether a given hxm is the cause of the current PIO IRQ.

Parameters

hxm

Returns

true

false

Definition at line 243 of file hx711_multi.c.

                              {
 
        assert(hx711_multi__is_initd(hxm));
 
        return pio_interrupt_get(
            hxm->_pio,
            HX711_MULTI_CONVERSION_DONE_IRQ_NUM);
 
}

References hx711_multi_t::_pio, hx711_multi__is_initd(), and HX711_MULTI_CONVERSION_DONE_IRQ_NUM.

Referenced by hx711_multi__async_get_pio_irq_request().

hx711_multi__async_remove_reader()

static void hx711_multi__async_remove_reader ( const hx711_multi_t *const  hxm )

static

Removes the given hxm from the request array.

Parameters

hxm

Definition at line 421 of file hx711_multi.c.

                                    {
 
        //we don't care whether it's initd at this point
        //or whether the SMs are running; just remove it
        //from the array
        assert(hxm != NULL);
        assert(hx711_multi__async_read_array != NULL);
 
        for(uint i = 0; i < HX711_MULTI_ASYNC_READ_COUNT; ++i) {
            if(hx711_multi__async_read_array[i] == hxm) {
                hx711_multi__async_read_array[i] = NULL;
                return;
            }
        }
 
}

References hx711_multi__async_read_array, and HX711_MULTI_ASYNC_READ_COUNT.

Referenced by hx711_multi_close().

hx711_multi__async_start_dma()

static void hx711_multi__async_start_dma ( hx711_multi_t *const  hxm )

static

Triggers DMA reading; moves request state from WAITING to READING.

Parameters

hxm

Definition at line 294 of file hx711_multi.c.

                              {
 
        assert(hx711_multi__is_state_machines_enabled(hxm));
        assert(hxm->_async_state == HX711_MULTI_ASYNC_STATE_WAITING);
 
        util_pio_sm_clear_rx_fifo(
            hxm->_pio,
            hxm->_reader_sm);
 
        //listen for DMA done
        dma_irqn_set_channel_enabled(
            hxm->_dma_irq_index,
            hxm->_dma_channel,
            true);
 
        hxm->_async_state = HX711_MULTI_ASYNC_STATE_READING;
 
        dma_channel_set_write_addr(
            hxm->_dma_channel,
            hxm->_buffer,
            true); //trigger
 
}

References hx711_multi_t::_async_state, hx711_multi_t::_buffer, hx711_multi_t::_dma_channel, hx711_multi_t::_dma_irq_index, hx711_multi_t::_pio, hx711_multi_t::_reader_sm, hx711_multi__is_state_machines_enabled(), HX711_MULTI_ASYNC_STATE_READING, HX711_MULTI_ASYNC_STATE_WAITING, and util_pio_sm_clear_rx_fifo().

Referenced by hx711_multi__async_pio_irq_handler(), and hx711_multi_async_start().

hx711_multi__init_asert()

static void hx711_multi__init_asert ( const hx711_multi_config_t *const  config )

static

Definition at line 44 of file hx711_multi.c.

                                              {
 
        assert(config != NULL);
 
        assert(util_uint_in_range(
            config->chips_len,
            HX711_MULTI_MIN_CHIPS,
            HX711_MULTI_MAX_CHIPS));
 
        assert(config->pio != NULL);
        check_pio_param(config->pio);
        assert(config->pio_init != NULL);
 
        assert(config->awaiter_prog != NULL);
        assert(config->awaiter_prog_init != NULL);
 
        assert(config->reader_prog != NULL);
        assert(config->reader_prog_init != NULL);
 
        assert(util_pio_irq_index_is_valid(config->pio_irq_index));
        assert(util_dma_irq_index_is_valid(config->dma_irq_index));
 
#ifndef NDEBUG
        {
            //make sure none of the data pins are also the clock pin
            const uint l = config->data_pin_base + config->chips_len - 1;
            for(uint i = config->data_pin_base; i <= l; ++i) {
                assert(i != config->clock_pin);
            }
        }
#endif
 
}

References hx711_multi_config_t::awaiter_prog, hx711_multi_config_t::awaiter_prog_init, hx711_multi_config_t::chips_len, hx711_multi_config_t::clock_pin, hx711_multi_config_t::data_pin_base, hx711_multi_config_t::dma_irq_index, HX711_MULTI_MAX_CHIPS, HX711_MULTI_MIN_CHIPS, hx711_multi_config_t::pio, hx711_multi_config_t::pio_init, hx711_multi_config_t::pio_irq_index, hx711_multi_config_t::reader_prog, hx711_multi_config_t::reader_prog_init, util_dma_irq_index_is_valid(), and util_pio_irq_index_is_valid().

Referenced by hx711_multi_init().

hx711_multi__init_dma()

static void hx711_multi__init_dma ( hx711_multi_t *const  hxm )

static

Subroutine for initialising DMA.

Parameters

hxm

Casting dma_claim_unused_channel to uint is OK in this circumstance. Ordinarily it would return -1 if the claim failed, but since the flag is given to require a DMA channel, panic would be called instead.

Do not set ring buffer. ie. do not use channel_config_set_ring. If, for whatever reason, the DMA transfer fails, subsequent transfer invocations will reset the write address.

PIO RX FIFO output is 32 bits, so the DMA read needs to match or be larger.

DMA is always going to read from the same location, which is the PIO FIFO.

Each successive read from the PIO RX FIFO needs to be to the next array buffer position.

DMA transfers are paced based on the PIO RX DREQ.

Quiet needs to be disabled in order for DMA to raise an interrupt when each transfer is complete. This is necessary for this implementation to work.

Definition at line 108 of file hx711_multi.c.

                                                     {
 
    hxm->_dma_channel = (uint)dma_claim_unused_channel(true);
 
    dma_channel_config cfg = dma_channel_get_default_config(
        hxm->_dma_channel);
 
    channel_config_set_transfer_data_size(
        &cfg,
        DMA_SIZE_32);
 
    channel_config_set_read_increment(
        &cfg,
        false);
 
    channel_config_set_write_increment(
        &cfg,
        true);
 
    channel_config_set_dreq(
        &cfg,
        pio_get_dreq(
            hxm->_pio,
            hxm->_reader_sm,
            false));
 
    channel_config_set_irq_quiet(
        &cfg,
        false);
 
    dma_channel_configure(
        hxm->_dma_channel,
        &cfg,
        NULL,                               //don't set a write address yet
        &hxm->_pio->rxf[hxm->_reader_sm],   //read from reader pio program rx fifo
        HX711_READ_BITS,                    //24 transfers; one for each HX711 bit
        false);                             //false = don't start now
 
}

References hx711_multi_t::_dma_channel, hx711_multi_t::_pio, hx711_multi_t::_reader_sm, and HX711_READ_BITS.

Referenced by hx711_multi_init().

hx711_multi__init_irq()

static void hx711_multi__init_irq ( hx711_multi_t *const  hxm )

static

Subroutine for initialising IRQ.

Parameters

hxm

The idea here is that the PIO and DMA IRQs can be set up, enabled, and routed out to NVIC IRQs and be enabled at this point. If and when IRQs need to be disabled, they can be done at the source BEFORE being routed out to NVIC and triggering a system-wide interrupt.

DMA interrupts can always remain enabled. They will only trigger following a PIO interrupt.

The PIO source interrupt MUST REMAIN DISABLED until the point at which it is required to listen to them.

Definition at line 182 of file hx711_multi.c.

                                                     {
 
    dma_irqn_set_channel_enabled(
        hxm->_dma_irq_index,
        hxm->_dma_channel,
        true);
 
    irq_set_exclusive_handler(
        util_dma_get_irqn(hxm->_dma_irq_index),
        hx711_multi__async_dma_irq_handler);
 
    irq_set_enabled(
        util_dma_get_irqn(hxm->_dma_irq_index),
        true);
 
    pio_set_irqn_source_enabled(
        hxm->_pio,
        hxm->_pio_irq_index,
        util_pio_get_pis_from_pio_interrupt_num(
            HX711_MULTI_CONVERSION_DONE_IRQ_NUM),
        false);
 
    irq_set_exclusive_handler(
        util_pio_get_irq_from_index(hxm->_pio, hxm->_pio_irq_index),
        hx711_multi__async_pio_irq_handler);
 
    irq_set_enabled(
        util_pio_get_irq_from_index(hxm->_pio, hxm->_pio_irq_index),
        true);
 
}

References hx711_multi_t::_dma_channel, hx711_multi_t::_dma_irq_index, hx711_multi_t::_pio, hx711_multi_t::_pio_irq_index, hx711_multi__async_dma_irq_handler(), hx711_multi__async_pio_irq_handler(), HX711_MULTI_CONVERSION_DONE_IRQ_NUM, util_dma_get_irqn(), util_pio_get_irq_from_index(), and util_pio_get_pis_from_pio_interrupt_num().

Referenced by hx711_multi_init().

hx711_multi__init_pio()

static void hx711_multi__init_pio ( hx711_multi_t *const  hxm )

static

Subroutine for initialising PIO.

Parameters

hxm

Casting pio_claim_unused_sm to uint is OK in this circumstance. Ordinarily it would return -1 if the claim failed, but since the flag is given to require a PIO State Machine, panic would be called instead.

Definition at line 79 of file hx711_multi.c.

                                                     {
 
    //adding programs and claiming state machines
    //will panic if unable; this is appropriate.
    hxm->_awaiter_offset = pio_add_program(
        hxm->_pio,
        hxm->_awaiter_prog);
 
    hxm->_reader_offset = pio_add_program(
        hxm->_pio,
        hxm->_reader_prog);
 
    hxm->_awaiter_sm = (uint)pio_claim_unused_sm(
        hxm->_pio,
        true);
 
    hxm->_reader_sm = (uint)pio_claim_unused_sm(
        hxm->_pio,
        true);
 
}

References hx711_multi_t::_awaiter_offset, hx711_multi_t::_awaiter_prog, hx711_multi_t::_awaiter_sm, hx711_multi_t::_pio, hx711_multi_t::_reader_offset, hx711_multi_t::_reader_prog, and hx711_multi_t::_reader_sm.

Referenced by hx711_multi_init().

hx711_multi__is_initd()

static bool hx711_multi__is_initd ( hx711_multi_t *const  hxm )

static

Check whether the hxm struct has been initialised.

Parameters

hxm

Returns

true

false

hx711_multi__is_state_machines_enabled()

static bool hx711_multi__is_state_machines_enabled ( hx711_multi_t *const  hxm )

static

Check whether the hxm struct has PIO State Machines which are enabled.

Parameters

hxm

Returns

true

false

hx711_multi_async_done()

bool hx711_multi_async_done

(

hx711_multi_t *const

hxm

)

Check whether an asynchronous read is complete. This function is not mutex protected.

Parameters

hxm

Returns

true

false

Definition at line 767 of file hx711_multi.c.

                                                      {
    assert(hx711_multi__is_initd(hxm));
    return hxm->_async_state == HX711_MULTI_ASYNC_STATE_DONE;
}

References hx711_multi_t::_async_state, hx711_multi__is_initd(), and HX711_MULTI_ASYNC_STATE_DONE.

Referenced by hx711_multi_async_get_values(), hx711_multi_get_values(), hx711_multi_get_values_timeout(), and hx711_multi_set_gain().

hx711_multi_async_get_values()

void hx711_multi_async_get_values	(	hx711_multi_t *const	hxm,
		int32_t *const	values
	)

Get the values from the last asynchronous read. This function is not mutex protected.

Parameters

hxm
values

Definition at line 772 of file hx711_multi.c.

                           {
        assert(hx711_multi__is_initd(hxm));
        assert(hx711_multi_async_done(hxm));
        hx711_multi_pinvals_to_values(
            hxm->_buffer,
            values,
            hxm->_chips_len);
}

References hx711_multi_t::_buffer, hx711_multi_t::_chips_len, hx711_multi__is_initd(), hx711_multi_async_done(), and hx711_multi_pinvals_to_values().

Referenced by hx711_multi_get_values(), and hx711_multi_get_values_timeout().

hx711_multi_async_start()

void hx711_multi_async_start

(

hx711_multi_t *const

hxm

)

Start an asynchronos read. This function is not mutex protected.

Parameters

hxm

Definition at line 734 of file hx711_multi.c.

                                                       {
 
    assert(hx711_multi__is_state_machines_enabled(hxm));
    assert(!hx711_multi__async_is_running(hxm));
 
    //if starting the following statements would lead to an
    //immediate interrupt, DMA may not be properly set up,
    //so disable until it is
    const uint32_t status = save_and_disable_interrupts();
 
#ifndef HX711_NO_MUTEX
    mutex_enter_blocking(&hxm->_mut);
#endif
 
    hxm->_async_state = HX711_MULTI_ASYNC_STATE_WAITING;
 
    //if pio interrupt is already set, we can bypass the
    //IRQ handler and immediately trigger dma
    if(pio_interrupt_get(hxm->_pio, HX711_MULTI_CONVERSION_DONE_IRQ_NUM)) {
        hx711_multi__async_start_dma(hxm);
    }
    else {
        pio_set_irqn_source_enabled(
            hxm->_pio,
            hxm->_pio_irq_index,
            util_pio_get_irq_from_index(hxm->_pio, hxm->_pio_irq_index),
            true);
    }
 
    restore_interrupts(status);
 
}

References hx711_multi_t::_async_state, hx711_multi_t::_mut, hx711_multi_t::_pio, hx711_multi_t::_pio_irq_index, hx711_multi__async_is_running(), hx711_multi__async_start_dma(), hx711_multi__is_state_machines_enabled(), HX711_MULTI_ASYNC_STATE_WAITING, HX711_MULTI_CONVERSION_DONE_IRQ_NUM, and util_pio_get_irq_from_index().

Referenced by hx711_multi_get_values(), hx711_multi_get_values_timeout(), and hx711_multi_set_gain().

hx711_multi_close()

void hx711_multi_close

(

hx711_multi_t *const

hxm

)

Stop communication with all HX711s.

Parameters

hxm

Definition at line 566 of file hx711_multi.c.

                                                 {
 
    assert(hx711_multi__is_initd(hxm));
 
#ifndef HX711_NO_MUTEX
    mutex_enter_blocking(&hxm->_mut);
#endif
 
    //make sure the disabling and removal of IRQs and
    //handlers is atomic
    UTIL_INTERRUPTS_OFF_BLOCK(
 
        //interrupts are off, but cancel any running
        //async reads
        dma_channel_abort(hxm->_dma_channel);
 
        irq_set_enabled(
            util_pio_get_irq_from_index(hxm->_pio, hxm->_pio_irq_index),
            false);
 
        irq_set_enabled(
            util_dma_get_irqn(hxm->_dma_irq_index),
            false);
 
        pio_set_irqn_source_enabled(
            hxm->_pio,
            hxm->_pio_irq_index,
            util_pio_get_pis_from_pio_interrupt_num(HX711_MULTI_CONVERSION_DONE_IRQ_NUM),
            false);
 
        dma_irqn_set_channel_enabled(
            hxm->_dma_irq_index,
            hxm->_dma_channel,
            false);
 
        hxm->_async_state = HX711_MULTI_ASYNC_STATE_NONE;
 
        hx711_multi__async_remove_reader(hxm);
 
        irq_remove_handler(
            util_pio_get_irq_from_index(hxm->_pio, hxm->_pio_irq_index),
            hx711_multi__async_pio_irq_handler);
 
        irq_remove_handler(
            util_dma_get_irqn(hxm->_dma_irq_index),
            hx711_multi__async_pio_irq_handler);
 
    );
 
    //at this point it is impossible for a relevant DMA
    //or PIO IRQ to occur, so we can turn interrupts
    //back on
 
    util_dma_channel_set_quiet(
        hxm->_dma_channel,
        true);
 
    pio_set_sm_mask_enabled(
        hxm->_pio,
        (1 << hxm->_awaiter_sm) | (1 << hxm->_reader_sm),
        false);
 
    dma_channel_unclaim(
        hxm->_dma_channel);
 
    pio_sm_unclaim(
        hxm->_pio,
        hxm->_awaiter_sm);
 
    pio_sm_unclaim(
        hxm->_pio,
        hxm->_reader_sm);
 
    pio_remove_program(
        hxm->_pio,
        hxm->_awaiter_prog,
        hxm->_awaiter_offset);
 
    pio_remove_program(
        hxm->_pio,
        hxm->_reader_prog,
        hxm->_reader_offset);
 
#ifndef HX711_NO_MUTEX
    mutex_exit(&hxm->_mut);
#endif
 
}

References hx711_multi_t::_async_state, hx711_multi_t::_awaiter_offset, hx711_multi_t::_awaiter_prog, hx711_multi_t::_awaiter_sm, hx711_multi_t::_dma_channel, hx711_multi_t::_dma_irq_index, hx711_multi_t::_mut, hx711_multi_t::_pio, hx711_multi_t::_pio_irq_index, hx711_multi_t::_reader_offset, hx711_multi_t::_reader_prog, hx711_multi_t::_reader_sm, hx711_multi__async_pio_irq_handler(), hx711_multi__async_remove_reader(), hx711_multi__is_initd(), HX711_MULTI_ASYNC_STATE_NONE, HX711_MULTI_CONVERSION_DONE_IRQ_NUM, util_dma_channel_set_quiet(), util_dma_get_irqn(), UTIL_INTERRUPTS_OFF_BLOCK, util_pio_get_irq_from_index(), and util_pio_get_pis_from_pio_interrupt_num().

hx711_multi_get_sync_state()

uint32_t hx711_multi_get_sync_state

(

hx711_multi_t *const

hxm

)

Returns the state of each chip as a bitmask. The 0th bit is the first chip, 1th bit is the second, and so on.

Parameters

hxm

Returns

uint32_t

Definition at line 862 of file hx711_multi.c.

                              {
        assert(hx711_multi__is_state_machines_enabled(hxm));
        return pio_sm_get_blocking(hxm->_pio, hxm->_awaiter_sm);
}

References hx711_multi_t::_awaiter_sm, hx711_multi_t::_pio, and hx711_multi__is_state_machines_enabled().

Referenced by hx711_multi_is_syncd().

hx711_multi_get_values()

void hx711_multi_get_values	(	hx711_multi_t *const	hxm,
		int32_t *const	values
	)

Fill an array with one value from each HX711. Blocks until values are obtained.

Parameters

hxm
values

Definition at line 682 of file hx711_multi.c.

                           {
 
        assert(hx711_multi__is_state_machines_enabled(hxm));
        assert(values != NULL);
        assert(!hx711_multi__async_is_running(hxm));
 
        hx711_multi_async_start(hxm);
        while(!hx711_multi_async_done(hxm)) {
            tight_loop_contents();
        }
        hx711_multi_async_get_values(hxm, values);
 
}

References hx711_multi__async_is_running(), hx711_multi__is_state_machines_enabled(), hx711_multi_async_done(), hx711_multi_async_get_values(), and hx711_multi_async_start().

hx711_multi_get_values_timeout()

bool hx711_multi_get_values_timeout	(	hx711_multi_t *const	hxm,
		int32_t *const	values,
		const uint	timeout
	)

Fill an array with one value from each HX711, timing out if failing to obtain values within the timeout period.

Parameters

hxm
values
timeout	microseconds

Returns

true if values obtained within the timeout period

false if values not obtained within the timeout period

Definition at line 698 of file hx711_multi.c.

                        {
 
        assert(hx711_multi__is_state_machines_enabled(hxm));
        assert(values != NULL);
        assert(!hx711_multi__async_is_running(hxm));
 
        const absolute_time_t end = make_timeout_time_us(timeout);
        bool success = false;
 
        hx711_multi_async_start(hxm);
 
        while(!time_reached(end)) {
            if(hx711_multi_async_done(hxm)) {
                success = true;
                break;
            }
        }
 
        if(success) {
            hx711_multi_async_get_values(hxm, values);
        }
        else {
            //if timed out, cancel DMA and stop listening
            //for IRQs and exit mutex. Do this atomically!
            UTIL_INTERRUPTS_OFF_BLOCK(
                hx711_multi__async_finish(hxm);
            );
        }
 
        return success;
 
}

References hx711_multi__async_finish(), hx711_multi__async_is_running(), hx711_multi__is_state_machines_enabled(), hx711_multi_async_done(), hx711_multi_async_get_values(), hx711_multi_async_start(), and UTIL_INTERRUPTS_OFF_BLOCK.

hx711_multi_init()

void hx711_multi_init	(	hx711_multi_t *const	hxm,
		const hx711_multi_config_t *const	config
	)

Definition at line 516 of file hx711_multi.c.

                                              {
 
        hx711_multi__init_asert(config);
 
#ifndef HX711_NO_MUTEX
        //this doesn't need to be an interrupts-off block
        //because the mutex will protect the hxm from reads
        //until init returns, and the source IRQs aren't
        //enabled anyway
        mutex_init(&hxm->_mut);
#endif
 
        HX711_MUTEX_BLOCK(hxm->_mut, 
 
            hxm->_clock_pin = config->clock_pin;
            hxm->_data_pin_base = config->data_pin_base;
            hxm->_chips_len = config->chips_len;
 
            hxm->_pio = config->pio;
            hxm->_awaiter_prog = config->awaiter_prog;
            hxm->_reader_prog = config->reader_prog;
 
            hxm->_pio_irq_index = config->pio_irq_index;
            hxm->_dma_irq_index = config->dma_irq_index;
 
            hxm->_async_state = HX711_MULTI_ASYNC_STATE_NONE;
 
            hx711_multi__async_add_reader(hxm);
 
            util_gpio_set_output(hxm->_clock_pin);
 
            util_gpio_set_contiguous_input_pins(
                hxm->_data_pin_base,
                hxm->_chips_len);
 
            hx711_multi__init_pio(hxm);
 
            config->pio_init(hxm);
            config->awaiter_prog_init(hxm);
            config->reader_prog_init(hxm);
 
            hx711_multi__init_dma(hxm);
            hx711_multi__init_irq(hxm);
 
        );
 
}

References hx711_multi_t::_async_state, hx711_multi_t::_awaiter_prog, hx711_multi_t::_chips_len, hx711_multi_t::_clock_pin, hx711_multi_t::_data_pin_base, hx711_multi_t::_dma_irq_index, hx711_multi_t::_mut, hx711_multi_t::_pio, hx711_multi_t::_pio_irq_index, hx711_multi_t::_reader_prog, hx711_multi_config_t::awaiter_prog, hx711_multi_config_t::awaiter_prog_init, hx711_multi_config_t::chips_len, hx711_multi_config_t::clock_pin, hx711_multi_config_t::data_pin_base, hx711_multi_config_t::dma_irq_index, hx711_multi__async_add_reader(), hx711_multi__init_asert(), hx711_multi__init_dma(), hx711_multi__init_irq(), hx711_multi__init_pio(), HX711_MULTI_ASYNC_STATE_NONE, HX711_MUTEX_BLOCK, hx711_multi_config_t::pio, hx711_multi_config_t::pio_init, hx711_multi_config_t::pio_irq_index, hx711_multi_config_t::reader_prog, hx711_multi_config_t::reader_prog_init, util_gpio_set_contiguous_input_pins(), and util_gpio_set_output().

hx711_multi_is_syncd()

bool hx711_multi_is_syncd

(

hx711_multi_t *const

hxm

)

Determines whether all chips are in sync.

Parameters

hxm

Returns

true

false

Definition at line 868 of file hx711_multi.c.

                              {
 
        assert(hx711_multi__is_state_machines_enabled(hxm));
 
        //all chips should either be 0 or 1 which translates
        //to a bitmask of exactly 0 or 2^chips
        const uint32_t allReady = (uint32_t)pow(2, hxm->_chips_len);
        const uint32_t state = hx711_multi_get_sync_state(hxm);
 
        return state == 0 || state == allReady;
 
}

References hx711_multi_t::_chips_len, hx711_multi__is_state_machines_enabled(), and hx711_multi_get_sync_state().

hx711_multi_pinvals_to_values()

void hx711_multi_pinvals_to_values	(	const uint32_t *const	pinvals,
		int32_t *const	values,
		const size_t	len
	)

Convert an array of pinvals to regular HX711 values.

Parameters

pinvals
values
len	number of values to convert

Definition at line 462 of file hx711_multi.c.

                      {
 
        assert(pinvals != NULL);
        assert(values != NULL);
        assert(len > 0);
 
        //construct an individual chip value by OR-ing
        //together the bits from the pinvals array.
        //
        //each n-th bit of the pinvals array makes up all
        //the bits for an individual chip. ie.:
        //
        //pinvals[0] contains all the 24th bit HX711 values
        //for each chip, pinvals[1] contains all the 23rd bit
        //values, and so on...
        //
        //(pinvals[0] >> 0) & 1 is the 24th HX711 bit of the 0th chip
        //(pinvals[1] >> 0) & 1 is the 23rd HX711 bit of the 0th chip
        //(pinvals[1] >> 2) & 1 is the 23rd HX711 bit of the 3rd chip
        //(pinvals[23] >> 0) & 1 is the 0th HX711 bit of the 0th chip
        //
        //eg.
        //rawvals[0] = 
        //    ((pinvals[0] >> 0) & 1) << 24 |
        //    ((pinvals[1] >> 0) & 1) << 23 |
        //    ((pinvals[2] >> 0) & 1) << 22 |
        //...
        //    ((pinvals[23]) >> 0) & 1) << 0;
 
        for(size_t chipNum = 0; chipNum < len; ++chipNum) {
 
            //reset to 0
            //this is the raw value for an individual chip
            uint32_t rawVal = 0;
 
            //reconstruct an individual twos comp HX711 value from pinbits
            for(size_t bitPos = 0; bitPos < HX711_READ_BITS; ++bitPos) {
                const uint shift = HX711_READ_BITS - bitPos - 1;
                const uint32_t bit = (pinvals[bitPos] >> chipNum) & 1;
                rawVal |= bit << shift;
            }
 
            //then convert to a regular ones comp
            values[chipNum] = hx711_get_twos_comp(rawVal);
 
            assert(hx711_is_value_valid(values[chipNum]));
 
        }
 
}

References hx711_get_twos_comp(), hx711_is_value_valid(), and HX711_READ_BITS.

Referenced by hx711_multi_async_get_values().

hx711_multi_set_gain()

void hx711_multi_set_gain	(	hx711_multi_t *const	hxm,
		const hx711_gain_t	gain
	)

Sets the HX711s' gain.

Parameters

hxm
gain

Definition at line 655 of file hx711_multi.c.

                             {
 
        assert(hx711_multi__is_state_machines_enabled(hxm));
 
        const uint32_t gainVal = hx711_gain_to_pio_gain(gain);
 
        assert(hx711_is_pio_gain_valid(gain));
 
        pio_sm_drain_tx_fifo(
            hxm->_pio,
            hxm->_reader_sm);
 
        pio_sm_put(
            hxm->_pio,
            hxm->_reader_sm,
            gainVal);
 
        hx711_multi_async_start(hxm);
 
        while(!hx711_multi_async_done(hxm)) {
            tight_loop_contents();
        }
 
}

References hx711_multi_t::_pio, hx711_multi_t::_reader_sm, hx711_gain_to_pio_gain(), hx711_is_pio_gain_valid(), hx711_multi__is_state_machines_enabled(), hx711_multi_async_done(), and hx711_multi_async_start().

hx711_multi_sync()

void hx711_multi_sync	(	hx711_multi_t *const	hxm,
		const hx711_gain_t	gain
	)

Attempt to synchronise all connected chips. This does not include a settling time.

Parameters

hxm
gain	initial gain to set to all chips

Definition at line 853 of file hx711_multi.c.

                             {
        assert(hx711_multi__is_initd(hxm));
        hx711_multi_power_down(hxm);
        hx711_wait_power_down();
        hx711_multi_power_up(hxm, gain);
}

References hx711_multi__is_initd(), hx711_multi_power_down(), hx711_multi_power_up(), and hx711_wait_power_down().

Variable Documentation

hx711_multi__async_read_array

hx711_multi_t* hx711_multi__async_read_array[ HX711_MULTI_ASYNC_READ_COUNT]

extern

Array of hxm for ISR to access. This is a global variable.

Definition at line 40 of file hx711_multi.c.

Referenced by hx711_multi__async_add_reader(), hx711_multi__async_get_dma_irq_request(), hx711_multi__async_get_pio_irq_request(), and hx711_multi__async_remove_reader().