update docs and names for consistency and completeness

Author: Randall-Scharpf

ports/atmel-samd/common-hal/spitarget/SPITarget.c

@@ -154,6 +154,8 @@ void common_hal_spitarget_spi_target_construct(spitarget_spi_target_obj_t *self,
     claim_pin(ss);
 
     self->running_dma.failure = 1; // not started
+    self->mosi_packet = NULL;
+    self->miso_packet = NULL;
 
     spi_m_sync_enable(&self->spi_desc);
 }
@@ -185,6 +187,10 @@ void common_hal_spitarget_spi_target_transfer_start(spitarget_spi_target_obj_t *
     if (self->running_dma.failure != 1) {
         mp_raise_RuntimeError(MP_ERROR_TEXT("Async SPI transfer in progress on this bus, keep awaiting."));
     }
+
+    self->mosi_packet = mosi_packet;
+    self->miso_packet = miso_packet;
+
     Sercom* sercom = self->spi_desc.dev.prvt;
     self->running_dma = shared_dma_transfer_start(sercom, miso_packet, &sercom->SPI.DATA.reg, &sercom->SPI.DATA.reg, mosi_packet, len, 0);
 
@@ -231,5 +237,9 @@ int common_hal_spitarget_spi_target_transfer_close(spitarget_spi_target_obj_t *s
     }
     int res = shared_dma_transfer_close(self->running_dma);
     self->running_dma.failure = 1;
+
+    self->mosi_packet = NULL;
+    self->miso_packet = NULL;
+
     return res;
 }

ports/atmel-samd/common-hal/spitarget/SPITarget.h

@@ -15,6 +15,9 @@ typedef struct {
     uint8_t MISO_pin;
     uint8_t SS_pin;
 
+    uint8_t* mosi_packet;
+    uint8_t* miso_packet;
+
     dma_descr_t running_dma;
 } spitarget_spi_target_obj_t;
 

shared-bindings/spitarget/SPITarget.c

@@ -85,6 +85,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(spitarget_spi_target___exit___obj, 4,
 //|         If a packet has already been queued for this SPI bus but has not yet been transferred, an error will be raised.
 //|
 //|         :param bytearray miso_packet: Packet data to be sent from secondary to main on next request."""
+//|         :param bytearray mosi_packet: Packet to be filled with data from main on next request."""
 //|
 STATIC mp_obj_t spitarget_spi_target_load_packet(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     mp_check_self(mp_obj_is_type(pos_args[0], &spitarget_spi_target_type));
@@ -115,14 +116,14 @@ STATIC mp_obj_t spitarget_spi_target_load_packet(size_t n_args, const mp_obj_t *
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_KW(spitarget_spi_target_load_packet_obj, 1, spitarget_spi_target_load_packet);
 
-//|     def try_transfer(self, *, timeout: float = -1) -> bool:
+//|     def wait_transfer(self, *, timeout: float = -1) -> bool:
 //|         """Wait for an SPI transfer from the main device.
 //|
 //|         :param float timeout: Timeout in seconds. Zero means wait forever, a negative value means check once
 //|         :return: True if the transfer is complete, or False if no response received before the timeout
 //|         :rtype: ~bool"""
 //|
-STATIC mp_obj_t spitarget_spi_target_try_transfer(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+STATIC mp_obj_t spitarget_spi_target_wait_transfer(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
     mp_check_self(mp_obj_is_type(pos_args[0], &spitarget_spi_target_type));
     spitarget_spi_target_obj_t *self = MP_OBJ_TO_PTR(pos_args[0]);
     if (common_hal_spitarget_spi_target_deinited(self)) {
@@ -160,14 +161,14 @@ STATIC mp_obj_t spitarget_spi_target_try_transfer(size_t n_args, const mp_obj_t
 
     return mp_const_false;
 }
-STATIC MP_DEFINE_CONST_FUN_OBJ_KW(spitarget_spi_target_try_transfer_obj, 1, spitarget_spi_target_try_transfer);
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(spitarget_spi_target_wait_transfer_obj, 1, spitarget_spi_target_wait_transfer);
 
 STATIC const mp_rom_map_elem_t spitarget_spi_target_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&spitarget_spi_target_deinit_obj) },
     { MP_ROM_QSTR(MP_QSTR___enter__), MP_ROM_PTR(&default___enter___obj) },
     { MP_ROM_QSTR(MP_QSTR___exit__), MP_ROM_PTR(&spitarget_spi_target___exit___obj) },
     { MP_ROM_QSTR(MP_QSTR_load_packet), MP_ROM_PTR(&spitarget_spi_target_load_packet_obj) },
-    { MP_ROM_QSTR(MP_QSTR_try_transfer), MP_ROM_PTR(&spitarget_spi_target_try_transfer_obj) },
+    { MP_ROM_QSTR(MP_QSTR_wait_transfer), MP_ROM_PTR(&spitarget_spi_target_wait_transfer_obj) },
 
 };
 

shared-bindings/spitarget/__init__.c

@@ -11,6 +11,49 @@
 //| """Serial Peripheral Interface protocol target
 //|
 //| The `spitarget` module contains classes to support an SPI target.
+//|
+//| Example that emulates an SPI analog-to-digital converter::
+//|
+//|   import board
+//|   import analogio
+//|   from spitarget import SPITarget
+//|
+//|   ain0 = analogio.AnalogIn(board.A0)
+//|   ain1 = analogio.AnalogIn(board.A1)
+//|   selected_channel = ain0
+//|
+//|   def map_adc_channel(index):
+//|       return ain0 if (index == 0) else ain1
+//|
+//|   mosi_buffer = bytearray(2)
+//|   miso_buffer = bytearray(2)
+//|   with SPITarget(sck=board.D12, mosi=board.D13, miso=board.D11, ss=board.D10) as device:
+//|       while True:
+//|           # Convert analog signal to array of bytes
+//|           reading = selected_channel.value
+//|           miso_buffer[0] = (reading >> 8) & 0xFF
+//|           miso_buffer[1] = (reading) & 0xFF
+//|           # Send array of bytes over SPI to main
+//|           device.load_packet(mosi_buffer, miso_buffer)
+//|           device.wait_transfer(0)
+//|           # Handle command from main, which sets the ADC channel
+//|           selected_channel = map_adc_channel((mosi_buffer[0] << 8) | mosi_buffer[1])
+//|
+//| Communicating with the ADC emulator from the REPL of an attached CircuitPython board might look like ::
+//|
+//|   >>> import busio
+//|   >>> spi = busio.SPI(board.SCK, board.MOSI, board.MISO)
+//|   >>> spi.try_lock()
+//|   True
+//|   >>> spi.write(bytearray([0, 0])) # ADC command: read from A0
+//|   >>> adc_result = bytearray(2)
+//|   >>> spi.readinto(adc_result)
+//|   >>> adc_result
+//|   bytearray(b'\xc4\x16')
+//|   >>> spi.unlock()
+//|
+//| """
+
 
 
 STATIC const mp_rom_map_elem_t spitarget_module_globals_table[] = {