API Proposal - Connect to the Clarius probe without user interaction

[mischkew]

Summary

This draft proposes new client commands and server events to allow an API user to connect to the Clarius probe, without the user having to open the Clarius app explicitly. In summary, it would allow a 3rd party app to implement the scanner selection dropdown itself.

Rationale

This is important to lower any friction for existing Clarius and/ or ThinkSono users for adoption. A user does not expect to have to switch to the Clarius app and manually need to start a scan to enable imaging in a 3rd party app. This lead to user frustration in our testing. Even though there is the 3rd party integration option via MSG_3P_PACKAGE, the task for the user is not entirely clear without manual explanation. Also, in situations where the connection to the probe is dropped, manual intervention by the user is required. Ideally, a 3rd party app could attempt to reconnect to the probe automatically.

We believe that this change can greatly enhance the UX of any user who want to try 3rd party application with the Clarius scanner.

Proposal

The code diff shows the proposal of API specification. The text below gives more context on the envisioned functionality.

1. Listing available probes:

The API should allow to manually query a list of available probes for the currently logged in Clarius user (MSG_LIST_PROBES). A return event will deliver a parcelable with the probe information (MSG_RETURN_PROBES). In this draft, I designed it as a list of a new Probe class, provided in the return bundle. Alternatively, we could reuse the existing ProbeInfo parcelable. For each probe, we want to know all data points to potentially reimplement the scanner selection dropdown, i.e:

• name
• model
• serial
• availability for connection
• connection status

The MSG_RETURN_STATUS can be used to check if the request succeeded, i.e. if the user is not logged in, the list request should fail with status 0.

2. Selecting a probe / establishing a connection

The API should allow to explicitly connect to an available scanner with a client command (MSG_SELECT_PROBE). The probe is selected by providing the serial number and the application name (i.e. vascular). The request to connect to the probe may fail, i.e. when trying to connect to a probe that is not available or no license is granted or the application for the selected probe does not exist or the application for a virtual scanner is not downloaded. The MSG_RETURN_STATUS returns 0 in that case.

In order to check whether the probe is actually available for connection an explicit MSG_PROBE_STATUS_CHANGED server event is introduced with the following states:

• 0 - a previously successfully connected probe disconnected or a connection attempt failed
• 1 - probe connected successfully and is ready for imaging (bluetooth + wifi available)

If a connection attempt failed (i.e MSG_RETURN_STATUS 0) the MSG_SELECT_PROBE needs to be initiated again. The MobileAPI does not retry a failed attempt automatically.

---

This draft does not support to query available applications for each scanner. This may be solvable by providing a specification, i.e. which set of applications is supported for which scanner/ model/ version combination. Otherwise, the list of available applications could also be returned as part of the MSG_RETURN_PROBES server event.

As a side note: The MSG_LICENSE_CHANGED event cannot be used to distinguish whether a probe is not properly connected vs the probe has no mobile API license. We currently use this event to indicate to the user that the mobile api has to be enabled in the first place, though we cannot deliver a consistent UX due to this behaviour. The possibility of a MSG_PROBE_STATUS_CHANGED would allow for a more explicit interface and resolve those challenges as well.

[nnaskov]

This is not discoverable and leads to user frustration in our testing. sounds better like this This leads to user frustration in our testing.

[mischkew]

Thanks @nnaskov, makes sense. I also have to test the try-catch clause I introduced.