The Mobile API allows third party applications to obtain images produced by a Clarius Ultrasound Scanner in real time. It also supports sending user commands such as changing the imaging depth or taking a capture.
Note: Virtual scanners are supported without a license since version 8.0.1.
https://clariusdev.github.io/mobileapi/reference/10.3.0
Starting with Clarius App version 9.4.0, the Mobile API is distributed as an Android package. The package is hosted in the GitHub Gradle registry which requires authentication (a GitHub account is needed).
Generate a GitHub Personal Access Token (PAT) with the read:packages
scope.
Refer to the GitHub documentation for instructions to generate tokens.
Create a file secrets.properties
in the project's root folder (which will be read by the Gradle build script) with the following content:
// file /secrets.properties
// do not put quotes (') around the values
gpr.user=your_user_name
gpr.token=personal_access_token_with_read_packages_scope
Alternatively, if the secrets file is missing, the build script will attempt to read the environment variables GITHUB_ACTOR
and GITHUB_TOKEN
.
On your Android device, start the Clarius App and connect to your scanner.
Open this project in Android Studio and run the example application on your Android device.
Optional: run both applications in split screen, otherwise let the Clarius App run in the background.
In the example application, select Menu ⋮
> connect
to start receiving images.
Usage:
Function menu ∑
: configure imaging like depth, gain or ultrasound mode.
Menu ⋮
> Ask *
: obtain imaging information, like the current depth or gain.
Menu ⋮
> settings
: configure the image rendered by the Clarius App and sent over the API.
The Mobile API communicates with the Clarius App instead of the ultrasound scanner directly (as is the case when using the Cast API). Therefore, the Clarius App must be installed and running on the same Android device. The Clarius App takes care of connecting to the probe and pre-processing the images before serving them through the API.
flowchart LR
prb[Probe]
subgraph dev[Android Device]
3p[3rd Party App]
subgraph app[Clarius App]
api[Mobile API]
end
api-- Images -->3p
3p-- Commands -->api
end
prb-- Images/Wi-Fi -->app
On Android, the Mobile API is implemented as an Android Bound Service running in the Clarius App itself. Refer to the Android developer guide for details about bound services.
The interface to the bound service is provided by an Android Messenger.
Android Messengers allow interprocess communications (IPC) by exchanging Message
objects containing an action code and a payload.
The sequence of messages and their content constitute the communication protocol which is described below.
Context.bindService()
and receives the server's IBinder
.
This IBinder
is used to create a Messenger that can send messages to the server.replyTo
field of a Message
object with code MSG_REGISTER_CLIENT
.
This Messenger is used by the server to send messages to the client.MSG_CONFIGURE_IMAGE
).MSG_NEW_PROCESSED_IMAGE
) and other notable events such as button presses, freeze state, etc.MSG_USER_FN
).All messages and their associated payload are described in the https://clariusdev.github.io/mobileapi repository.
The service operates only when the Clarius App is connected to a scanner with the appropriate license. Contact Clarius for licensing options: https://clarius.com/contact/.
However, the service accepts binding requests from clients even when no proper license is active to accommodate workflows where the license is removed for legitimate reasons, for example when a probe is disconnected to save battery. In this case, the service enters a restricted mode where it stops handling requests and sending updates, but will resume normal operation as soon as a licensed scanner is connected again.
The license check workflow is as follows:
MSG_LICENSE_UPDATE
) and no client request is handled (except MSG_REGISTER_CLIENT
and MSG_UNREGISTER_CLIENT
). The service will reply MSG_NO_LICENSE
to any other requestMSG_LICENSE_UPDATE
and changes its mode of operation:
Workflow to obtain raw data:
MSG_USER_FN
, this will trigger the following actions:
MSG_RAW_DATA_AVAILABLE
MSG_COPY_RAW_DATA
to request a copy, include the following data:
MSG_RAW_DATA_COPIED