Revision history:
1.62 - May 2018
- add API to clear discovered device list
- update demo app
1.6.1 - April 2018
- Add support for Bluetooth Low Energy
1.5.0
- Initial release
Here is the latest Android SDK:
Airconsole SDK for Android / Java
---------------------------------
Introduction:
This document describes the Airconsole Software Development Kit (SDK) for communicating with Airconsole devices
from Java based applications, including those running on the Android mobile operating system.
More information on Airconsole devices can be found at http://www.get-console.com/airconsole
The SDK supports conecting to Airconsole using the following transports:
- TCP/IP via RFC2217 (all Java platforms)
- Bluetooth 2.1 Serial Port Profile (Android platforms only)
- Bluetooth Low Energy (Android v23+ platforms only)
Organisation of the SDK:
The SDK consists of a series of source code, libraries, and documentation. The SDK is laid out as follows,
/lib - contains the Airconsole binary library/JAR airconsolesdk-X.Y.Z.jar which contains the Java classes
required for Airconsole support. This also includes an optional third party library jmdns-A.B.C.jar which
allows for discovery of IP based devices via mDNS
/doc - contains JavaDoc documentation for the Airconsole SDK classes
/3rdparty - contains 3rd party libraries which add optional support for SDK features such as mDNS discovery
/examples - contains two sample applications
a.) airconsoledemo which is an Android application that builds in Android Studio
b.) consoledemo which is a standalone Java application that uses the command line
Getting Started:
For building Android applications you will need the Android SDK and an IDE that supports Android. We recommend
Anrdoid Studio available at https://developer.android.com/studio/index.html
For building standalone Java applications, there are no additional requirements above the Java SDK. This can
be downloaded from Oracle at http://www.oracle.com/technetwork/java/javase/downloads/index.html
To test that your setup is working correctly you should try compiling and running the supplied sample
applications found in the /examples folder of the SDK
Structure of the Library:
The Airconsole library can be found in the package nz.co.cloudstore.airconsole. It consists of a single
concrete class and a collection of interfaces.
- Airconsole.java - this concrete class is the entry point for applications. It supplies an interface
to the AirconsoleMgr interface and a factory method to create AirconsoleSession instances
- AirconsoleMgr.java - this interface allows applications to scan the network / BTLE advertisements /
paired Bluetooth devices for an Airconsole and then maintains a list of discovered devices.
AirconsoleDevice objects can be created by helper methods on this interface
- AirconsoleDevice.java - this interface represents a physical Airconsole device and reports the properties
of the device such as the number of serial ports, firmware revision, etc.
- AirconsoleSession.java - this interface represents a connection to a serial port on an Airconsole. It
provides an InputStream and OutputStream which applications can use to read/write serial data.
Line properties of the serial session (such as baud rate, etc) can also be set using this class
Typical Application Workflow:
An application would normally,
a.) Discover devices to connect to (optional as device IP address may already be known)
- request an AirconsoleMgr interface from the Airconsole class by calling Airconsole.getAirconsoleMgr()
- register as a listener on AirconsoleMgr by calling mgr.addAirconsoleMgrListener()
- use the AirconsoleMgr interface to start scanning the network for available devices by calling
mgr.startScanning(transport, params). The transport parameter indicates which transport will be used
AirconsoleDevice.Transport.TRANSPORT_IP, AirconsoleDevice.Transport.TRANSPORT_BT or
AirconsoleDevice.Transport.TRANSPORT_BTLE, the params parameter specifies optional transport specific
scanning parameters that will be used
b.) Once an AirconsoleDevice has been discovered (AirconsoleMgrListener) or created
(AirconsoleMgr.getDefaultDevice or AirconsoleMgr.getIPDevice) the application will create a session
to communicate with the serial port
- create an AirconsoleSession instance by calling Airconsole.createSession(device);
- register as a listener on AirconsoleSession for session related events
- call the AirconsoleSession.connect() method and wait until the sessionDidConnect() method is called
on the listener
c.) After the connection has been successful, the application will configure serial port settings and
create input/output streams to send serial data
- call AirconsoleSession.setLineProperties() to set the baud rate and other line settings
- call getInputStream() and getOutputStream() to get an InputStream and OutputStream which can be used
to send/receive data
- enter a loop processing and sending data using the stream
d.) Disconnect from the session once complete
- call the AirconsoleSession.disconnect() method
Transport Specific Details:
The Airconsole supports connections over TCP/IP (RFC2217 and rawserial), Bluetooth (Bluetooth 2.1 SPP and
Bluetooth Low Energy)
- TCP/IP connections are support on all Java platforms, but automated discovery requires that multicast
DNS (also known as mDNS, Bonjour or ZeroConf) be available via the jmdns library. mDNS requires that
multicast is available on your Android device
- Bluetooth 2.1 connections require an Android device with Bluetooth support and that the Bluetooth has
been paired in the operating system before the application starts
- Bluetooth Low Energy connections require an Android device with Bluetooth support and location services
enabled
Notes on Android Multicast:
If your device supports multicast, multicast permissions should be added to your app manifest. The following
permissions are required:
- INTERNET
- ACCESS_NETWORK_STATE
- CHANGE_WIFI_STATE
- CHANGE_WIFI_MULTICAST_STATE
- ACCESS_WIFI_STATE
Multicast mDNS scanning works best when the scanning is bound to a particular network interface - usually the
WiFi interface on the Android device. You should pass in this binding IP address as one of the scan parameters
e.g.
HashMap<String, Object> params = new HashMap<>();
params.put(AirconsoleMgr.KEY_BINDING_IP, bindingIP);
mgr.startScanning(AirconsoleDevice.Transport.TRANSPORT_IP, params);
Notes on Android Bluetooth Classic / EDR / 2.1:
- Only connections to pre-paired devices are supported. You should make sure that your Airconsole has been paired
in the operating systems Bluetooth page
- Be sure to add in the BLUETOOTH permission to your application manifest
- Scanning for bluetooth devices requires that the BluetoothAdapter be passed as a parameter
e.g.
HashMap<String, Object> btParams = new HashMap<>();
btParams.put(AirconsoleMgr.KEY_BLUETOOTH_ADAPTER, BluetoothAdapter.getDefaultAdapter());
mgr.startScanning(AirconsoleDevice.Transport.TRANSPORT_BT, btParams);
Notes on Android Bluetooth Low Energy BTLE
- Connections to Airconsole only reliably works with Android version 23 and above (Android 6.0 up)
- Location services must be enabled to connect to a Bluetooth Low Energy device
- Be sure to add in the BLUETOOTH and ACCESS_FINE_LOCATION permissions to your application manifest
- Scanning for bluetooth devices requires that the BluetoothAdapter and COntext be passed as parameters
e.g.
HashMap<String, Object> btParams = new HashMap<>();
btParams.put(AirconsoleMgr.KEY_BLUETOOTH_ADAPTER, BluetoothAdapter.getDefaultAdapter());
btParams.put(AirconsoleMgr.KEY_CONTEXT, this.getApplicationContext());
mgr.startScanning(AirconsoleDevice.Transport.TRANSPORT_BTLE, btParams);
For further details visit our website at http://www.get-console.com/airconsole or http://www.get-console.com/developer