[Feature] Implement awaitable ADC reading

[laurensvalk]

The method pbdrv_adc_update_soon is a bit of a hack to get a value sooner than the typical 10 ms sample time. It mainly exists to support the NXT color sensor (on EV3). It does 4 sequential ADC measurements to measure light intensity while the LED is red/green/blue/none, and we would rather not have it take 40 ms per color measurement, or be just out of sync and get bad results. The current implementation in lib/pbio/src/port_dcm_ev3.c is this:

pbio_error_t pbio_port_dcm_await_new_nxt_analog_sample(pbio_port_dcm_t *dcm, pbio_os_timer_t *timer, const pbdrv_ioport_pins_t *pins, uint32_t *value) {
    pbio_os_state_t *state = &dcm->child;

    PBIO_OS_ASYNC_BEGIN(state);

    // Wait for LED to settle.
    PBIO_OS_AWAIT_MS(state, timer, 1);

    // Request a new ADC sample.  <---- would be nice if we could "pbdrv_adc_await_channel" instead of "soon" + "time"
    pbdrv_adc_update_soon();
    PBIO_OS_AWAIT_MS(state, timer, 4);

    // Get the value.
    uint8_t pin = dcm->category == DCM_CATEGORY_NXT_COLOR ? 6 : 1;
    *value = pbio_port_dcm_get_mv(pins, pin);  // this calls pbdrv_adc_get_ch and just scales it

    PBIO_OS_ASYNC_END(PBIO_SUCCESS);
}

Instead of doing it that way, perhaps we could have a complimentary function to pbdrv_adc_get_ch called something like pbdrv_adc_await_ch that will handle this at the pbdrv/adc_ev3 level and return the value when it is ready. Any ADC settling time (however long that is?) could be handled there as well, so the application code can just await it instead of hard coding this 4 ms wait.

Other ideas for doing this better would be welcome too.

Side note: would it make sense to scale ADC measurements to mV at the driver level instead of having the application level do it?

[dlech]

This wouldn't be the most efficient way to do this. It would require lots of reprogramming of the ADC SPI controller.

Since we have a very efficient ADC polling now with DMA that doesn't have to get reconfigured on each poll, I would be tempted to bump the ADC poll time up to every 1 or 2 ms. Then also run all of the pbio_port_dcm_await_new_nxt_analog_sample() protothreads in parallel so that if there are 4 NXT color sensors connected, it only takes 4 ADC readings instead of 16 to get through them all.

would it make sense to scale ADC measurements to mV at the driver level instead of having the application level do it?

Yes.

[laurensvalk]

Increasing poll frequency sounds good. Then we can drop the poll_soon altogether.

run all of the pbio_port_dcm_await_new_nxt_analog_sample() protothreads in parallel

This is more or less what's happening at the moment. It runs as part of that sensor port's process and all ports run in parallel.

[dlech]

This is more or less what's happening at the moment.

Very good. I must not be very awake yet and didn't notice there wasn't in index variable in the for loop. 😪

[laurensvalk]

Completed via pybricks/pybricks-micropython#322

[laurensvalk]

Some notes here. The whole SPI DMA operation takes about 2200 microseconds for 18 commands, including dummy commands at the end. That is about 120 microseconds per channel. The lowest channel for sensors is ADC channel 5. We need to ensure that its value is sampled after toggling the LED. So we do need some slight delay after setting the LED color. At least (18 - 5) * 120 us = 1560 us, and we might as well add a little bit of settling time if we have to do this anyway.

The code does this already, but we can avoid millisecond rounding now that we have a microsecond clock. The awaitable is already polled on the DMA completion event, so there is no extra polling here. It just waits until the next DMA completion is later than the start time plus the delay.

Will submit this shortly.