Cordova-Plugin-Flomio

Flomio's plugin for Cordova, for use with v2.3 of the Flomio iOS SDK. This plugin is only supported for the FloBLE Plus or FloBLE Micro

Installation
Example
API
Tag
TagStatus
DeviceInfo
DeviceConfiguration
PowerOperation
CommunicationStatus

NDEF
- IRecord
- IMessage

Add Pro SDK for Offline usage
Use with Ionic

Installation

Download and install Node plus the Cordova CLI

$ sudo npm install -g cordova

Create your Cordova example app:

$ cordova create hello com.example.hello HelloWorld

Add the plugin to it:

$ cordova plugin add https://github.com/flomio/cordova-plugin-flomio#<latest-commit-code>

Example

const deviceConfiguration = {
    powerOperation: flomioPlugin.PowerOperation.AutoPollingControl, 
    deviceType: 'floble-plus'
}
flomioPlugin.setConfiguration(deviceConfiguration)
flomioPlugin.init()
flomioPlugin.addConnectedDevicesListener(this.flomioConnectedDevicesListener.bind(this))
flomioPlugin.addTagDiscoveredListener(this.flomioTagDiscovered.bind(this))

Prepare the app:

$ cordova platform add ios
$ cordova prepare

Open the generated Xcode project:

$ open platforms/ios/*.xcodeproj

Add your provisioning profile and signing identity and then build and run the app on an iOS device.

API

init

Initializes the plugin and begins a session. To configure the session, use setConfiguration before initialization.

    flomioPlugin.init([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that is called if init was successful.
onFailure:(Optional) The callback that is called if there was an error.

setConfiguration

Configures the current session. Changes the device type and power operation.

const deviceConfiguration = {
    powerOperation: flomioPlugin.PowerOperation.AutoPollingControl, 
    deviceType: 'floble-plus'
}
flomioPlugin.setConfiguration(deviceConfiguration)

Parameters

deviceConfiguration: DeviceConfiguration

getConfiguration

Returns the current configuration of the session.

    flomioPlugin.getConfiguration([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns the DeviceConfiguration object.
onFailure:(Optional) The callback that is called if there was an error.

startReaders

Starts the readers after they has been stopped with StopReaders or SleepReaders.

   flomioPlugin.startReaders([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that is called if startReaders was successful.
onFailure:(Optional) The callback that is called if there was an error.

stopReaders

Stops the readers. Depending on the PowerOperation configuration the readers either stop scanning or disconnect from bluetooth.

    flomioPlugin.stopReaders([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that is called if stopReaders was successful.
onFailure:(Optional) The callback that is called if there was an error.

sleepReaders

Stops the reader from polling and will set the reader to sleep after 60 seconds during future use.

    flomioPlugin.sleepReaders([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that is called if sleepReaders was successful.
onFailure:(Optional) The callback that is called if there was an error.

selectSpecificDeviceId

Use this before initialization to only connect to a certain device with a known deviceId.

    flomioPlugin.selectSpecificDeviceId(deviceId, [onSuccess], [onFailure]);

Parameters

deviceId: The unique ID code of the target reader.
onSuccess:(Optional) The callback that is called if selectSpecificDeviceId was successful.
onFailure:(Optional) The callback that is called if there was an error.

sendApdu

Sends an APDU command to a target device

    flomioPlugin.sendApdu(deviceId, apdu, [onSuccess], [onFailure]);

Parameters

deviceId: The unique ID code of the target reader.
apdu: The APDU command in hexadecimal format (string|Buffer).
onSuccess:(Optional) The callback that is called if sendApdu was successful, it returns a hexadecimal response APDU as a string.
onFailure:(Optional) The callback that is called if there was an error.

getBatteryLevel

Gets the battery level of the currently connected device.

    flomioPlugin.getBatteryLevel([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns a number which represents the battery level between 0 - 100%
onFailure:(Optional) The callback that is called if there was an error.

getCommunicationStatus

Gets the latest communication status of the device

      flomioPlugin.getCommunicationStatus([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns the latest communication status of the device
onFailure:(Optional) The callback that is called if there was an error.

writeNdef

Write NDEF formatted data to a tag in proximity of a specified target device.

    const url = 'http://www.flomio.com'
    const ndefMessage = [
        flomioPlugin.ndef.uriRecord(url)
    ]
    flomioPlugin.writeNdef(deviceId, ndefMessage, [onSuccess], [onFailure]);

Parameters

deviceId: The unique ID code of the target reader.
ndefMessage: The NDEF formatted data to be written to the tag.
onSuccess:(Optional) The callback that is called if writeNdef was successful.
onFailure:(Optional) The callback that is called if there was an error. This will occur if a tag is removed while writing.

write

Write unformatted data to a tag in proximity of a specified target device.

    const data = '00000000'
    flomioPlugin.write(deviceId, data, [onSuccess], [onFailure]);

Parameters

deviceId: The unique ID code of the target reader.
data: The unformatted data (string|Buffer) to be written to the tag.
onSuccess:(Optional) The callback that is called if write was successful.
onFailure:(Optional) The callback that is called if there was an error.

launchNativeNfc

Starts iOS 11 CoreNfc Reader session with compatible devices.

    flomioPlugin.launchNativeNfc([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns the NDEF object if a tag is tapped on the iPhone.
onFailure:(Optional) The callback that is called if there was an error with reading or if the session was invalidated.

readNdef

Retrieve NDEF formatted data from a tag in proximity of a specified target device. When a tag is found, in your addTagDiscoveredListener success callback, call readNdef.

    flomioPlugin.readNdef(deviceId, [onSuccess], [onFailure]);

Example

 function flomioTagDiscovered(result) {
    flomioPlugin.readNdef(result.deviceId, this.onNdefFound.bind(this), this.onReadNdefFail.bind(this),)
 }
  
 function onNdefFound(response) {
     console.log(JSON.stringify(response.ndefMessage));
 }
 function onReadNdefFail(error) {
     console.log(error.message)
 }

Parameters

deviceId: The unique ID code of the target reader.
onSuccess:(Optional) The callback that returns the NDEF object if a tag NDEF data is successfully read from a tag.
onFailure:(Optional) The callback that is called if there was an error with reading.

addConnectedDevicesListener

Registers for device discovery events. When a devices is connected, the onSuccess callback returns a DeviceInfo object.

    flomioPlugin.addConnectedDevicesListener([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns a DeviceInfo object when a devices is connected or has updates to report.
onFailure:(Optional) The callback that is called if there was an error.

addTagDiscoveredListener

Registers for tag discovery events. When a tag is tapped, the onSuccess callback returns a Tag object.

      flomioPlugin.addTagDiscoveredListener([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns a Tag object when a tag is tapped.
onFailure:(Optional) The callback that is called if there was an error.

addTagStatusChangeListener

Registers for status change events. When a tag is added/removed from field, the onSuccess callback returns a TagStatus object.

      flomioPlugin.addTagStatusChangeListener([onSuccess], [onFailure]);

Parameters

onSuccess:(Optional) The callback that returns a TagStatus object when a tag is added/removed from the reader field.
onFailure:(Optional) The callback that is called if there was an error.

Tag

Object

Name	Type	Default	Description
uid	`string`		The unique ID of the tag.
atr	`string`		The Answer To Reset (ATR) of the tag. This can be used to determine the tag's manufacturer or issuer and other details.

DeviceInfo

Object

Name	Type	Description
deviceId	`string`	The unique ID / serial number of the connected reader.
batteryLevel	`number`	a number which represents the battery level between 0 - 100%.
hardwareRevision	`string`	The devices hardware revision string.
firmwareRevision	`string`	The devices firmware revision string.
communicationStatus	`CommunicationStatus`	See CommunicationStation for details.

DeviceConfiguration

Object

Name	Type	Default	Description
deviceType	`string`	`'floble-plus'`	The device type for the current session. Only `floble-plus` and `floble-micro` are supported at the moment.
powerOperation	`PowerOperation`	`0`	Describes how startReaders and stopReaders operate. See PowerOperation for details.

PowerOperation

enum

Name	Type	Default	Description
AutoPollingControl	`number`	`0`	startReaders and stopReaders turns on/off the reader from polling.
BluetoothConnectionControl	`number`	`1`	startReaders and stopReaders turns on/off bluetooth, this can be used when exiting from/returning to your app.

CommunicationStatus

enum

Name	Type	Default	Description
Scanning	`number`	`0`	The device is connected and scanning for tags.
Connected	`number`	`1`	The device is connected to bluetooth but not scanning for tags.
Disconnected	`number`	`2`	The device is disconnected from bluetooth and not scanning for tags.

TagStatus

enum

Name	Type	Default	Description
NotPresent	`number`	`0`	A tag is not in range of the reader
Present	`number`	`1`	A tag is in range of the reader.

NDEF

Object

The ndef object provides functions for creating IRecords.

IMessage

Array

Represents an NDEF (NFC Data Exchange Format) data message that contains one or more IRecords.

IRecord

Object

Represents a NDEF (NFC Data Exchange Format) record as defined by the NDEF specification.

Name	Type	Description
tnf	`number`	The Type Name Format field of the payload.
type	`Buffer or string`	The type of the payload.
id	`Buffer`	The identifier of the payload
payload	`Buffer`	The data of the payload
value	`string?`	An optional convenience parameter which will return the payload as text for Text and URI records.

The flomioPlugin.ndef object provides functions for creating IRecords

Create a URI record

    const record = flomioPlugin.ndef.uriRecord("http://www.flomio.com");

Create a plain text record

    const record = flomioPlugin.ndef.textRecord("Plain text message");

Create an empty record

    const record = flomioPlugin.ndef.emptyRecord();

Add Pro SDK for Offline usage

Add libSDKClassesPro.a to a folder named resources. Add this and the scripts folder from this repo to the root of your project (same directory as package.json). So your project structure looks like this
```
├── ProjectName
│   ├── scripts
│   │   ├── copyProSDK.js
│   ├── resources
│   │   ├── libSDKClassesPro.a
│   ├── package.json
│   ├── node_modules
```
Add
```
<hook src="scripts/copyProSDK.js" type="after_plugin_install" />
```
to config.xml after
```
<platform name="ios">
```
Then when you add the Flomio Cordova Plugin, the ProSDK will be added to your project instead of the Basic SDK.

Use with Ionic

Installation

Install:

ionic cordova plugin add https://github.com/flomio/cordova-plugin-flomio#<latest-commit-code>

Copy the directory ionic-native/cordova-plugin-flomio in this repo to node_modules/@ionic-native in your project. So your project structure looks like this

 
   ├── ProjectName
   │   ├── node_modules
   │   │   ├── @ionic-native
   │   │   │   ├── cordova-plugin-flomio

Add Ndef and FlomioPlugin to your app's module.

Usage

import {
 FlomioPlugin,
 PowerOperation,
 CommunicationStatus,
 DeviceConfiguration,
 DeviceInfo,
 Tag,
 Ndef
} from '@ionic-native/cordova-plugin-flomio'

private deviceId: string
constructor(  private flomio: FlomioPlugin,
             private ndef: Ndef) { }

initReader () {
   this.platform.ready().then(() => {
       const configuration: DeviceConfiguration = {
           powerOperation: PowerOperation.AutoPollingControl,
           deviceType: 'floble-plus'
       }
       
       this.flomio.setConfiguration(configuration)
       this.flomio.init()
       this.addListeners()
   })
 }

addListeners() {
   this.flomio.addConnectedDevicesListener().subscribe((device: DeviceInfo) => {
       console.log(`deviceId: ${device.deviceId}`)
       this.deviceId = device.deviceId
   })

   this.flomio.addTagDiscoveredListener().subscribe(async (tag: Tag) => {
       console.log(`tag uid: ${tag.uid}`)
       const response = await this.flomio.readNdef(this.deviceId)
       console.log(JSON.stringify(response))
   })
 }

flomio/cordova-plugin-flomio

Cordova-Plugin-Flomio

Contents

Installation

Example

API

init

Parameters

setConfiguration

Parameters

getConfiguration

Parameters

startReaders

Parameters

stopReaders

Parameters

sleepReaders

Parameters

selectSpecificDeviceId

Parameters

sendApdu

Parameters

getBatteryLevel

Parameters

getCommunicationStatus

Parameters

writeNdef

Parameters

write

Parameters

launchNativeNfc

Parameters

readNdef

Parameters

addConnectedDevicesListener

Parameters

addTagDiscoveredListener

Parameters

addTagStatusChangeListener

Parameters

Tag

DeviceInfo

DeviceConfiguration

PowerOperation

CommunicationStatus

TagStatus

NDEF

IMessage

IRecord

Add Pro SDK for Offline usage

Use with Ionic

Installation

Usage