CoreAPI Class Reference

Description

Provides access to core Grabba driver and hardware functionality, such as opening and closing communications.

This API provides access to device-wide functionality, and to selected features common to all Grabba hardware (e.g. battery level).

Callbacks to user-provided code may be triggered when the driver connects to or disconnects from the Grabba device. Refer to the ConnectionListener class for the details of these callbacks and how to enable them.

Most calls to this and other driver APIs will not succeed until a connection to a Grabba device has been established. This connection may be triggered by calling open(), typically in the onResume handler for an activity, and then either waiting for a connection event or polling the output of connected() until it returns true.

If open() has been called, close() or deferredClose() must be called at a later time to terminate any active connections and free resources. Typically this should take the form of a call to deferredClose() in the onPause handler for an activity, however this call may occur earlier if an activity no longer needs access to the Grabba Driver.

Thread safety: This class is fully thread-safe.

Note

This class has no non-static methods or data; consequently, object creation is disabled.

Static Public Member Functions
static byte	batteryLevel ()
	Query the battery level of a connected Grabba device. More...
static void	close ()
	Close the communication channel to the device if it has previously been opened. More...
static boolean	closePending ()
	Query whether a deferredClose() operation is currently pending. More...
static boolean	connected ()
	Query whether the driver is currently connected to a Grabba device. More...
static void	deferredClose (int interval)
	Close the communication channel to the device if it has previously been opened, after a given interval has elapsed. More...
static String	deviceModel ()
	Query the model number of a connected Grabba device. More...
static String	driverVersion ()
	Query the version number of the Grabba driver. More...
static String	hardwareVersion ()
	Query the hardware version number of a connected Grabba device. More...
static boolean	open (@NonNull Context ctxt)
	Attempt to open the communications channel to the device. More...
static boolean	opened ()
	Query whether the communication channel has been opened. More...
static String	serialNumber ()
	Query the serial number of a connected Grabba device. More...

Member Function Documentation

batteryLevel()

static byte batteryLevel ( )

static

Query the battery level of a connected Grabba device.

This is a non-blocking call; the driver polls the battery level at regular intervals and caches the value internally.

Returns

Battery percentage of the connected device if there is one, otherwise zero.

close()

static void close ( )

static

Close the communication channel to the device if it has previously been opened.

If the communication channel is open (even if not connected), then this call will close it, preventing further communication with the hardware. If the communication channel is already closed, then this call has no effect.

This is a blocking call, and consequently should not typically be triggered from any thread or other context which is latency-sensitive (e.g. UI threads). The one exception to this is that it may be desirable to call this from the UI thread in an activity's onPause handler; doing so would ensure that the Grabba driver is fully closed prior to application suspension or shutdown.

Note

This call will trigger a disconnection event if the communication channel was previously connected. It will block until all driver internals have completed processing of this disconnection event, but is not guaranteed to block for sufficient time to allow application code to complete its own handling of the disconnect event. If application code is relying on completion of a close operation prior to suspension or shutdown, it must ensure that any pertinent application code finishes executing before the suspension or shutdown takes place.

See also

deferredClose() for cases where the app may attempt to re-open comms in the very near future (e.g. switching activities within the same Android app). Android applications in which more than one activity accesses the Grabba driver should generally use deferredClose() instead of close().

closePending()

static boolean closePending ( )

static

Query whether a deferredClose() operation is currently pending.

This is a non-blocking call.

Returns

True if deferredClose() has been called, it has not been cancelled by a subsequent call to open(), and its interval has not yet expired; false otherwise.

connected()

static boolean connected ( )

static

Query whether the driver is currently connected to a Grabba device.

This is a non-blocking call; it will return the current state immediately, without waiting for any in-progress operations to complete.

Returns

True if the communication channel is open and a Grabba device is connected; false otherwise.

deferredClose()

static void deferredClose ( int  interval )

static

Close the communication channel to the device if it has previously been opened, after a given interval has elapsed.

This call is asynchronous, and will trigger processing as follows:

• If open() is called prior to the given interval expiring, then deferredClose() has no effect (i.e. open() cancels deferredClose(), channel stays open)
• If close() is called prior to the given interval expiring, then deferredClose() has no effect (i.e. close() closes the channel as usual)
• If the interval expires without any calls to open() or close() in the meantime, then deferredClose() will call close() at that time.

Note that other applications will be unable to access the Grabba Driver whilst the interval elapses, so it is important to avoid setting it too high. However, if set too low there is a risk that the connection may be lost, which is likely to involve a delay of several seconds for re-establishment.

Parameters

interval

Duration in milliseconds which this call will wait before calling close(), subject to there being no open() or close() calls in the meantime. The permitted range is 0-5000ms (i.e. 0-5s); any values outside that range will be clamped. Values in the 1000-2000ms (i.e. 1-2s) range are likely to be reasonable for most applications.

deviceModel()

static String deviceModel ( )

static

Query the model number of a connected Grabba device.

This is a non-blocking call; the driver caches the model number internally.

Returns

Model number string (e.g. "S-5472-WSQ+") of the connected device if there is one, otherwise an empty string.

driverVersion()

static String driverVersion ( )

static

Query the version number of the Grabba driver.

This is a non-blocking call.

Returns

Driver version number string, e.g. "2.0.0-alpha-1". See the versioning page for details of the numbering scheme.

hardwareVersion()

static String hardwareVersion ( )

static

Query the hardware version number of a connected Grabba device.

This is a non-blocking call; the driver caches the hardware version number internally.

Returns

Hardware version number string (e.g. "4.6") of the connected device if there is one, otherwise an empty string.

open()

static boolean open ( @NonNull Context  ctxt )

static

Attempt to open the communications channel to the device.

If the communications channel is presently closed (or has yet to be opened for the first time), then this call will attempt to open the channel. If the communications channel is already opened, then this call has no effect other than cancelling any pending deferredClose() calls.

This is a non-blocking call; consequently, it can't report on the success or failure of a connection attempt. If a connection attempt succeeds, any active ConnectionListener objects will receive events, and can trigger callbacks into application code; consequently, constructing an object of a ConnectionListener subclass is recommended prior to the first call to open().

If a connection attempt fails, or if an existing connection is lost, then the driver will automatically attempt to reconnect; there is no need to call open() again. If it is necessary to guarantee disconnection, then close() should be called; open() can then be called again if a subsequent reconnection is needed.

Note

If open() has been called, then close() or deferredClose() must be called before the activity is paused, even if the connection has not been established. This will typically take the form of a call to deferredClose() in the onPause handler, but the call can occur earlier if an activity no longer needs access to the Grabba Driver.

Parameters

ctxt	Android context in which the driver is to operate; should be the context of the enclosing application. If the supplied context is not an application-level context, then the driver will obtain a reference to the associated application context from it, so as to avoid memory leaks.

Returns

True if this call opens the communications channel (i.e. if it was previously closed); false if it was already opened, or if this call cancelled a deferredClose() operation which was pending.

opened()

static boolean opened ( )

static

Query whether the communication channel has been opened.

This is a non-blocking call; it will return the current state immediately, without waiting for any in-progress open or close operations to complete.

Note

An open communication channel does not imply a connected device (unlike the converse); call connected() if you need to query connection status.

Returns

True if the communication channel is currently open; false otherwise.

serialNumber()

static String serialNumber ( )

static

Query the serial number of a connected Grabba device.

This is a non-blocking call; the driver caches the serial number internally.

Returns

Serial number string (e.g. "70025158") for the connected device if there is one, otherwise an empty string.