Access the iOS External Accessory API as a Cordova plugin
This Cordova plugin is specific to iOS and provides access to the iOS External Accessory API
- iOS
The External Accessory API is specific to iOS. It was developed to communicate originally with a Bluetooth Classic Temperature Probe (from BlueTherm) which requires External Accessory API. The plugin was written to be device generic and contains no specific code for the probe.
Using standard Cordova plugin, this plugin is accessed through
var pluginAPI = cordova.plugins.iOSExternalAccessory;
Since Apple Apps that access External Accessory devices (either over USB or BlueTooth classic) must declare the Transport Protocols that the device they will be using the only thing that needs to be set to use this plugin is the UISupportedExternalAccessoryProtocols plist entry, this is currently set via the plugin.xml of this plugin.
<config-file target="*-Info.plist" parent="UISupportedExternalAccessoryProtocols">
<array>
<string>uk.co.etiltd.bluetherm1</string>
</array>
</config-file>
In a similar manner to other Cordova plugins, all methods take 0 or more input parameters followed by success and error callback functions.
The success function will accept a single object/array with the result of the function.
The error function accepts a single string error message.
Return the version of the plugin
getVersion(success, error);
function success(info)
function error(msg)
Get the version of the plugin
info: {
version: "1.0.0" // Version of the plugin
}
Return a list of currently connected devices
listDevices(success, error);
function success(deviceArray)
function error(msg)
This maps directly to a call to
[[EAAccessoryManager sharedAccessoryManager] connectedAccessories]
-
deviceArray: Array of objects of type
device: { name: accessory.name, // String id: accessory.connectionID, // Number connected: accessory.connected, // Bool manufacturer: accessory.manufacturer, // String modelNumber: accessory.modelNumber, // String serialNumber: accessory.serialNumber, // String firmwareRevision: accessory.firmwareRevision, // String hardwareRevision: accessory.hardwareRevision, // String protocolStrings: accessory.protocolStrings // String [] }
Attempt to connect to a device
connect(deviceId, protocolString, success, error);
function success(sessionId)
function error(msg)
Will attempt to connect to the device with specified deviceId and protocolString, on success will return a sessionId string which represents the session.
- deviceId: Should be the
idfield ofdeviceobject returned by thelistDevicesmethod. - protocolString: Should be the Protocol String that is used to create the session.
- success: Returns
sessionIdstring to be used in further Accessory Session calls
- sessionId: Id of the newly created session
Write data to a session
AccessorySession_write(sessionId, data, success, error)
function success()
function error(msg)
With a valid sessionId the data parameter will be converted to a byte array and written to the device.
- sessionId: Should be the return value of the
connectcall, invalid sessionIds will generate errors - data: Should be the bytes to write to the device. Will accept an
Array of integer, aUint8Arrayor a base64 encoded string.
Note Actual data may be written on a background thread within the plugin. And the success function may be called before the actual data is written to the device.
Nothing
Subscribe to raw data read from the devices session
AccessorySession_subscribeRawData(sessionId, success, error)
function success(rawdata)
function error(msg)
Each session can have 1 subscribed read event function, once called the success function will be called with data buffers as it is read from the device. The data buffers will be 1 or more bytes of data and should be converted to a usable Uint8Array using
function success(rawdata) {
var bytes = new Uint8Array(rawdata)
// do something with your data
}
- sessionId: The session to subscribe to read events to
- rawdata: Read data with 1 or more bytes
Unsubscribe from receiving read data
AccessorySession_unsubscribeRawData(sessionId, success, error)
function success()
function error(msg)
Unsubscribe from receive read data
- sessionId: The session to unsubscribe from
Nothing
Disconnect the session and close both read and write streams
AccessorySession_disconnect(sessionId, success, error)
function success()
function error(msg)
Disconnect the session with sessionId and close the read and write streams
- sessionId: The session to disconnect
Nothing
List currently connected sessions
listSessions(success, error)
function success(sessionArray)
function error(msg)
Will list all currently connected sessions recorded by the plugin. Can be useful during development/debugging to find all sessions and perhaps disconnect them all before starting a fresh.
-
sessionArray: An array of objects (similar to listDevices) of type
session: { sessionId: session ID // String name: accessory.name, // String id: accessory.connectionID, // Number connected: accessory.connected, // Bool manufacturer: accessory.manufacturer, // String modelNumber: accessory.modelNumber, // String serialNumber: accessory.serialNumber, // String firmwareRevision: accessory.firmwareRevision, // String hardwareRevision: accessory.hardwareRevision, // String protocolStrings: accessory.protocolStrings // String [] }
Listen to device Connects and Disconnects
subscribeDeviceChanges(success, error)
function success(args)
function error(msg)
Will listen to External Accessory device Connects and Disconnects and call the success function on each event.
-
args: An object of type
args: { event: "connected" or "disconnected" name: accessory.name, // String id: accessory.connectionID, // Number connected: accessory.connected, // Bool manufacturer: accessory.manufacturer, // String modelNumber: accessory.modelNumber, // String serialNumber: accessory.serialNumber, // String firmwareRevision: accessory.firmwareRevision, // String hardwareRevision: accessory.hardwareRevision, // String protocolStrings: accessory.protocolStrings // String [] }
Unsubscribe to device Connects and Disconnects
unsubscribeDeviceChanges(success, error)
function success()
function error(msg)
Will unsubscribe from listening to device Connects and Disconnects
Nothing
When the App is Paused the Plugin will automatically remember which device sessions are currently connected and On Resume will attempt to reconnect them, sessionId's will remain unchanged.
The plugin was originally developed to access a BlueTherm Thermometer Probe over BlueTooth (classic), to my amazement I could not find a Cordova plugin which accesses the External Accessory API which I needed to communicate with the probe - so I wrote this one. There is a (cross platform BlueTooth Low Energy)[https://github.com/don/BluetoothSerial] plugin which was taken as inspiration for the API on this plugin but it does not handle BlueTooth classic devices on iOS.
If you use this plugin and want to put your App on the AppStore you will need to apply for the Apple MFI program, I actually don't know too much about this as I am yet to push my App to the AppStore and I think I will be ok since BlueTherm have their device as MFI compliant and our App will be running under their compliance umbrella.