From ea46197d6f96c26005016c74039c4cad272d67ba Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Wed, 27 Apr 2022 17:47:00 +0200 Subject: [PATCH 1/7] Initial draft - Add LIST_PROBES, SELECT_PROBE commands - Add RETURN_PROBES, PROBE_SATUS_CHANGED events - Add probe nick name to ProbeInfo pracelable - Add new Probes parcelable for RETURN_PROBES payload --- .../java/me/clarius/mobileapi/MobileApi.java | 53 +++++++++ .../java/me/clarius/mobileapi/ProbeInfo.java | 13 ++- .../java/me/clarius/mobileapi/Probes.java | 104 ++++++++++++++++++ 3 files changed, 169 insertions(+), 1 deletion(-) create mode 100644 mobileapi/src/main/java/me/clarius/mobileapi/Probes.java diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java b/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java index 7868ba5..0a0dbdc 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java @@ -192,6 +192,35 @@ public class MobileApi public static final int MSG_COPY_RAW_DATA = 17; + //! Query the service with all available ultrasound probes and their connection status. + //! + //! The reply will be delived with the MSG_RETURN_PROBES. + //! + //! Parameters(s): + //! - Message.replyTo: client's Messenger where the reply should be sent. This field is mandatory; if missing, the query will be ignored. + //! - Message.arg1 (optional): callback parameter for MSG_RETURN_PROBES. + //! + //! \version Added in version x.x.x + + public static final int MSG_LIST_PROBES = 18; + + //! Select a scanner and try to connect to it. Follows the same behaviour as the "Select Scanner" UI element in the Clarius app. Tries to connect to the probes wifi automatically. Follows the connection setup as configured in the Clarius app, i.e. direct Wifi or pre-configured custom SSID. + //! + //! The MSG_RETURN_STATUS will be + //! - 0 if the scanner or scan application does not exist, if the license for the mobile API cannot be used or for any other reason the request for connection cannot be executed. + //! - 1 if the request was successful. This does not mean that the probe has been successfully connected. For this, listen to the MSG_PROBE_STATUS_CHANGED + //! + //! The event MSG_PROBE_STATUS_CHANGED will inform you whether the connection has succeeded. + //! + //! Parameter(s): + //! - Bundle[KEY_SELECTED_PROBE]: String, the serial number of the probe to connect to + //! - Message.replyTo (optional): if set, Messenger to send the MSG_RETURN_STATUS message to. + //! - Message.arg1 (optional): callback parameter for MSG_RETURN_STATUS. + //! + //! \version Added in version x.x.x + + public static final int MSG_SELECT_PROBE = 19; + // Messages from server to client. //! Return the outcome of a command sent by the client. @@ -376,6 +405,28 @@ public class MobileApi public static final int MSG_RAW_DATA_COPIED = 123; + //! Reply to query MSG_LIST_PROBES + //! + //! Parameters: + //! - Bundle[KEY_PROBES]: me.clarius.mobileapi.Probes, a list of probes that are available to the current Clarius user + //! - Message.arg1: callback parameter copied from the Message.arg1 sent by the client. + //! + //! \version Added in version x.x.x + + public static final int MSG_RETURN_PROBES = 124; + + //! Server event for the current probe connection status + //! + //! Parameters: + //! - Message.arg1: int + //! 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 status 0) the MSG_SELECT_PROBE needs to be initiated again. The MobileAPI does not retry a failed attempt for you. + //! + //! \version Added in version x.x.x + public static final int MSG_PROBE_STATUS_CHANGED = 125; + // Bundle keys public static final String KEY_IMAGE_SIZE = "size"; @@ -405,6 +456,8 @@ public class MobileApi public static final String KEY_CAPTURE_ID = "captureID"; public static final String KEY_FILE_NAME = "fileName"; public static final String KEY_SIZE_BYTES = "sizeBytes"; + public static final String KEY_SELECTED_PROBE = "selectedProbe"; + public static final String KEY_PROBES = "listProbes"; // Predefined bundle values diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java b/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java index 3739e57..ebb2769 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java @@ -9,6 +9,7 @@ public class ProbeInfo implements Parcelable { public String model; //!< model type public String serial; //!< serial # + public String name; //!< nick name of the scanner, added in version x.x.x public int battery; //!< battery percentage public int temperature; //!< temperature percentage (of max) public int version; //!< version (1 = Clarius 1st Generation, 2 = Clarius HD) @@ -22,7 +23,8 @@ public ProbeInfo() { model = ""; serial = ""; - battery = 0; + name = ""; + battery = 0; temperature = 0; version = 0; elements = 0; @@ -55,6 +57,13 @@ private ProbeInfo(Parcel in) battery = in.readInt(); serial = in.readString(); model = in.readString(); + // Added in version x.x.x: + try { + name = in.readString(); + } catch (Exception e) { + // TODO(sven): Check if actual exception occcurs + // NOTE(sven): Read if available, don't crash for backwards compatibility + } } @Override @@ -69,6 +78,8 @@ public void writeToParcel(Parcel out, int flags) out.writeInt(battery); out.writeString(serial); out.writeString(model); + // Added in version x.x.x: + out.writeString(name); } @Override diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java new file mode 100644 index 0000000..00c81e2 --- /dev/null +++ b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java @@ -0,0 +1,104 @@ +package me.clarius.mobileapi; + +import android.os.Parcel; +import android.os.Parcelable; + +//! A list of available ultrasound scanners for the current Clarius user + +// NOTE(sven): This could also be done by reusing the ProbeInfo Parcelable and +// we would just add some fields. +public class Probe implements Parcelable +{ + public String model; //!< model type + public String serial; //!< serial + public String name; //!< nick name of the scanner + public int version; //!< version (1 = Clarius 1st Generation, 2 = Clarius HD) + public int battery; //!< battery percentage, 0 if scanner is not available + public boolean isAvailable; //!< true, if the scanner is ready to connect + public boolean isConnected; //!< true, if the scanner is connected and ready for imaging + + // Parcelable interface + + public static final Parcelable.Creator CREATOR = new Parcelable.Creator() + { + public Prob createFromParcel(Parcel in) + { + return new Probe(in); + } + public Probe[] newArray(int size) + { + return new Probe[size]; + } + }; + + private Probe(Parcel in) + { + version = in.readInt(); + temperature = in.readInt(); + battery = in.readInt(); + serial = in.readString(); + model = in.readString(); + name = in.readString(); + } + + @Override + public void writeToParcel(Parcel out, int flags) + { + out.writeInt(version); + out.writeInt(temperature); + out.writeInt(battery); + out.writeString(serial); + out.writeString(model); + out.writeString(name); + } + + @Override + public int describeContents() + { + return 0; + } +} + +public class Probes implements Parcelable +{ + public Probes[] probes; + + //! Default constructor sets everything to zero. + //! Note: required for JNI for Android 8 API 26. + public ProbeInfo() + { + probes = null + } + + // Parcelable interface + + public static final Parcelable.Creator CREATOR = new Parcelable.Creator() + { + public Probes createFromParcel(Parcel in) + { + return new Probes(in); + } + + public Probes[] newArray(int size) + { + return new Probes[size]; + } + }; + + private Probes(Parcel in) + { + probes = in.createTypedArray(Probe.CREATOR); + } + + @Override + public void writeToParcel(Parcel out, int flags) + { + out.writeTypedArray(probes, 0); + } + + @Override + public int describeContents() + { + return 0; + } +} From 87ba13dc1832e9b8df3c6dff3006703f86193bcb Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Thu, 28 Apr 2022 10:39:19 +0200 Subject: [PATCH 2/7] Add isVirtual, fix typo in constructor name --- mobileapi/src/main/java/me/clarius/mobileapi/Probes.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java index 00c81e2..6d24116 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java @@ -14,6 +14,7 @@ public class Probe implements Parcelable public String name; //!< nick name of the scanner public int version; //!< version (1 = Clarius 1st Generation, 2 = Clarius HD) public int battery; //!< battery percentage, 0 if scanner is not available + public boolean isVirtual; //!< true, if the scanner is a virtual demo scanner public boolean isAvailable; //!< true, if the scanner is ready to connect public boolean isConnected; //!< true, if the scanner is connected and ready for imaging @@ -65,7 +66,7 @@ public class Probes implements Parcelable //! Default constructor sets everything to zero. //! Note: required for JNI for Android 8 API 26. - public ProbeInfo() + public Probe() { probes = null } From 59f4276af227aa9e5032717ecead0a2a60e82b14 Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Thu, 28 Apr 2022 10:39:34 +0200 Subject: [PATCH 3/7] Explain MSG_RETURN_STATUS meaning --- mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java | 1 + 1 file changed, 1 insertion(+) diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java b/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java index 0a0dbdc..50fff9f 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java @@ -200,6 +200,7 @@ public class MobileApi //! - Message.replyTo: client's Messenger where the reply should be sent. This field is mandatory; if missing, the query will be ignored. //! - Message.arg1 (optional): callback parameter for MSG_RETURN_PROBES. //! + //! MSG_RETURN_STATUS Message.arg2 will be 0 if the request failed, i.e. the Clarius user is not logged in and the available probes cannot be retrieved. //! \version Added in version x.x.x public static final int MSG_LIST_PROBES = 18; From 128d8ce309331bb961811d1530ae3e94394eabc8 Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Thu, 28 Apr 2022 10:42:53 +0200 Subject: [PATCH 4/7] Provide application name for MSG_SELECT_PROBE --- mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java b/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java index 50fff9f..3ac146c 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/MobileApi.java @@ -214,7 +214,8 @@ public class MobileApi //! The event MSG_PROBE_STATUS_CHANGED will inform you whether the connection has succeeded. //! //! Parameter(s): - //! - Bundle[KEY_SELECTED_PROBE]: String, the serial number of the probe to connect to + //! - Bundle[KEY_SELECT_PROBE]: String, the serial number of the probe to connect to + //! - Bundle[KEY_SELECT_APPLICATION]: String, the name of the application to use for the scanner, i.e. vascular. A list of available applications is defined here: TODO //! - Message.replyTo (optional): if set, Messenger to send the MSG_RETURN_STATUS message to. //! - Message.arg1 (optional): callback parameter for MSG_RETURN_STATUS. //! @@ -457,7 +458,8 @@ public class MobileApi public static final String KEY_CAPTURE_ID = "captureID"; public static final String KEY_FILE_NAME = "fileName"; public static final String KEY_SIZE_BYTES = "sizeBytes"; - public static final String KEY_SELECTED_PROBE = "selectedProbe"; + public static final String KEY_SELECT_PROBE = "selectProbe"; + public static final String KEY_SELECT_APPLICATION = "selectApplication"; public static final String KEY_PROBES = "listProbes"; // Predefined bundle values From 40fbffa2b6cd3aacdac092be4f602b6a0d58defe Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Thu, 28 Apr 2022 12:35:21 +0200 Subject: [PATCH 5/7] Update mobileapi/src/main/java/me/clarius/mobileapi/Probes.java Co-authored-by: Norbert Naskov <3404751+nnaskov@users.noreply.github.com> --- mobileapi/src/main/java/me/clarius/mobileapi/Probes.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java index 6d24116..9a02aa1 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java @@ -66,7 +66,7 @@ public class Probes implements Parcelable //! Default constructor sets everything to zero. //! Note: required for JNI for Android 8 API 26. - public Probe() + public Probes() { probes = null } From c0493a5b6fc9c812f0eb94d1fa1705593128f4d8 Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Thu, 28 Apr 2022 12:35:26 +0200 Subject: [PATCH 6/7] Update mobileapi/src/main/java/me/clarius/mobileapi/Probes.java Co-authored-by: Norbert Naskov <3404751+nnaskov@users.noreply.github.com> --- mobileapi/src/main/java/me/clarius/mobileapi/Probes.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java index 9a02aa1..c27b08b 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/Probes.java @@ -62,7 +62,7 @@ public int describeContents() public class Probes implements Parcelable { - public Probes[] probes; + public Probe[] probes; //! Default constructor sets everything to zero. //! Note: required for JNI for Android 8 API 26. From db3d3e0ce4db3e485c74d1681c5981604223601f Mon Sep 17 00:00:00 2001 From: Sven Mischkewitz Date: Thu, 28 Apr 2022 15:05:55 +0200 Subject: [PATCH 7/7] Remove unnecessary try-catch block --- .../src/main/java/me/clarius/mobileapi/ProbeInfo.java | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java b/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java index ebb2769..01527e5 100644 --- a/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java +++ b/mobileapi/src/main/java/me/clarius/mobileapi/ProbeInfo.java @@ -58,12 +58,7 @@ private ProbeInfo(Parcel in) serial = in.readString(); model = in.readString(); // Added in version x.x.x: - try { - name = in.readString(); - } catch (Exception e) { - // TODO(sven): Check if actual exception occcurs - // NOTE(sven): Read if available, don't crash for backwards compatibility - } + name = in.readString(); } @Override