understand TinyUSB USBTMC protocols

4 Oct 2023

In this post, I attempt to understand the flows that the USBTMC class driver follows for:

standard SCPI query / response
standard SCPI command only
*STB? status byte requests
service requests
triggers

For each scenario, I'll try to figure out how the logic flows, what flags are set or cleared, payloads, etc...

SCPI Query: *IDN?

main.c tud_task()
usbd.c tud_task_ext()
  case DCD_EVENT_XFER_COMPLETE 
    if ( 0 == epnum ) -> else
usbtmc_device.c usbtmcd_xfer_cb()
  case STATE_IDLE
    case USBTMC_MSGID_DEV_DEP_MSG_OUT:
usbtmc_device.c handle_devMsgOutStart()
usbtmc_device.c handle_devMsgOut()
usbtmc_app.c tud_usbtmc_msg_data_cb()
  if(transfer_complete && (len >=1)
    query_received = true;
    queryState = 1
    scpi_instrument_input();

main.c usbtmc_app_task_iter()
usbtmc_app.c usbtmc_app_task_iter()
  case querystate 1-> 2 case querystate 2:
    querystate 3:
    set MAV 0x10
    set SRQ 0x40
  case querystate 3:
  // here I reply. I (or you :)) need to check what happens if the SCPI engine didn't generate acommand. 
  // that happens if the SCPI was a command, not a query.
  // will it then do the right thing?

After a reply is complete, the usb_tmc.c state machine calls tud_usbtmc_msgBulkIn_complete_cb()

start side note 1

One thing I found, is that when I send a command (does not reply) instead of a query (replies), tud_usbtmc_msgBulkIn_complete_cb() is not called and MAV isn't reset....
This call originates from the usbtmc_device.c. A file that I do not have control over.

I am taking the "executive" decision" to clear that flag myself if the SCPI didn't return a value (because it got a command instead of a query). This is how I rewrote case 3 (transmit). Check the else clause at the end:

 case 3: // time to transmit;
    if(/* TODO check if I can just ignore this*/ bulkInStarted &&  (buffer_tx_ix == 0)) {
      if(reply_len) // if this was a SCPI query, there will be a reply.
      {
        tud_usbtmc_transmit_dev_msg_data(reply,  tu_min32(reply_len,msgReqLen),true,false);
        queryState = 0;
        bulkInStarted = 0;
        reply_len = 0;
      }
      else
      {
        buffer_tx_ix = tu_min32(buffer_len,msgReqLen);
        tud_usbtmc_transmit_dev_msg_data(buffer, buffer_tx_ix, buffer_tx_ix == buffer_len, false);
      }
      // MAV is cleared in the transfer complete callback.
    }
    else { // this is not thread safe. When you port this to a multi-threaded device, take care to put guard rails
      // jc 20231004: when there is no reply from the scpi engine (the input was a command, not a query)
      // mark as if a reply was sent
      // MAV is cleared here
      if(! reply_len) { 
        // if this was a SCPI query, reply_len woulkd be > 0
        // and tud_usbtmc_msgBulkIn_complete_cb() would clear all of this.
        uint8_t status = getSTB();
        status &= (uint8_t) ~(IEEE4882_STB_MAV); // clear MAV
        setSTB(status);
        queryState = 0;
        bulkInStarted = 0;
        buffer_tx_ix = 0;
        query_received = false;
      }
    }

This code should only be called when a SCPI string is sent that does not generate a reply (a command instead of a query)

end side note 1

start side note 2

or should I not set the MAV bit? if there's no reply? In the end, it's the Message Available Bit

end side note 2

todo

Top Comments

Parents

Jan Cumps over 2 years ago

ggabe , the TinyUSB example sets SRQ bit (0x40) in the STB when it receives a SCPI command. https://github.com/hathach/tinyusb/blob/b394ae1786911a89ea3437d7090cda477ca7df6c/examples/device/usbtmc/src/usbtmc_app.c#L219

I ported this to the firmware

Are you aware that this is normal? I start to expect that this is a test case, not default behaviour ...
- Cancel
- Vote Up 0 Vote Down
- Sign in to reply
- More
- Cancel
ggabe over 2 years ago in reply to Jan Cumps
1. The SRQ bit is only set after a certain delay (125ms), for strictly testing purposes with the included python test client.
2. I rebuilt the test example, and the python test cases passing pedantically. However, no events fire ( we know that from the SCPI lab tool already)
- Cancel
- Vote Up +1 Vote Down
- Sign in to reply
- More
- Cancel

Jan Cumps over 2 years ago in reply to ggabe

I simpified my MAV change.

Instead of setting MAV in the state machine, and having a specific ELSE clause to clear it when no answer,
I moved the setting of the MAV to the part of the code that gets the first data set:

void setReply (const char *data, size_t len) {
  // attach replies to the buffer until the SCPI engine is finished.
  // no one should run away with the data, because only one core has focus 
  // on scpi engine and USB state machine 
  // on getting the first data, set MAV

  if (!reply_len) { // set MAV when first part of command written (i.e.: buffer still empty)
    uint8_t status = getSTB();
    status |= 0x10u; // MAV
    setSTB(status);
  }
  memcpy(reply + (reply_len * sizeof reply[0]), data, len);
  reply_len += len;
}

... and removed my specific handling.

It means that if no reply expected, MAV is never set.

I also removed the SQR bit set and all the intermediate "test steps" in the app state machine:

void usbtmc_app_task_iter(void) {
  switch(queryState) {
  case 0: // no query
    break;
  case 1: // query
    queryState = 2;
    break;
  case 2: // time to transmit;
    if(bulkInStarted &&  (buffer_tx_ix == 0)) {
      if(reply_len) // if this was a SCPI query, there will be a reply.
      {
        tud_usbtmc_transmit_dev_msg_data(reply,  tu_min32(reply_len,msgReqLen),true,false);
        queryState = 0;
        bulkInStarted = 0;
        reply_len = 0;
      }
      else
      {
        buffer_tx_ix = tu_min32(buffer_len,msgReqLen);
        tud_usbtmc_transmit_dev_msg_data(buffer, buffer_tx_ix, buffer_tx_ix == buffer_len, false);
      }
      // MAV is cleared in the transfer complete callback.
    }
    break;
  default:
    TU_ASSERT(false,);
    return;
  }
}

Only available in temporary feature branch https://github.com/jancumps/pico_scpi_usbtmc_labtool/tree/issue-57-should-code-set-MAV-bit-if-SCPI-doesn't-generate-a-reply

Comment