Skip to content

Quick start

Install

Install the library according to your language/platform:

Instantiate a TapDevice object

Configure the communication protocol to use

IoTize devices support multiple communication protocols (See communication protocols user guide for more information).

Note for Javascript users: Each communication protocol is in a separate package. You can see the list on npmjs.org

Here are some examples of communication protocols you can use:

// For websocket 
// brower/node.js
import { WebSocketProtocol }  from "@iotize/device-com-websocket.js";
import { noble } from "@iotize/device-com-ble.node/dist/types/noble";
let webSocketProtocol = new WebSocketProtocol({
    url: 'ws://yourhost:yourport'
});

// BLE (Bluetooth low energy)
// node.js
import { NobleBLEAdapter }  from "@iotize/device-com-ble.node/dist/lib";
let noblePeriferal: noble.Peripheral; // see noble doc for how to get a peripheral instance https://github.com/noble/noble
let bleProtocol = new NobleBLEAdapter(noblePeriferal)

// Socket 
// node.js ONLY
import { SocketProtocol } from "@iotize/device-com-socket.node";
let socketProtocol = new SocketProtocol({
    host: 'yourhost',
    port: 2000
});

// For bluetooth low energy communication from a mac address
ComProtocol protocol = BLEProtocol.fromAddress(context, "AA:BB:CC:DD:EE")// ...

// For bluetooth WIFI communication 
ComProtocol protocol = WIFIProtocol.fromIP(context, "192.168.1.50")// ...

// For NFC communication 
android.nfc.tag myNfcTag = // ...
ComProtocol protocol = NFCProtocl.create(context, myNfcTag)// ...
import TapDeviceClient

// Websocket
let webSocketServerUrl = URL(string: "ws://yourhost:yourport")
let comProtocol: ComProtocol = WebSocketProtocol(url: webSocketServerUrl)

// Socket (based on IBM BlueSocket library)
let socketServerUrl = URL(string: "tcp://yourhost:yourport")
let comProtocol: ComProtocol = BlueSocketProtocol(url: webSocketServerUrl)

Instantiate your device

Once you've chosen a communication protocol you can instantiate an IoTizeDevice object and connect to it.

// Instantiate your IoTizeDevice object from the ComProtocol
IoTizeDevice device = IoTizeDevice.fromProtocol(comProtocol);

// Connect to the device
device.connect();
let protocol: ComProtocol = ... ; // Your protocol object (see above)

let device = IoTizeDevice.create();
let connectionPromise: Promise<void> = device.connect(protocol);

connectionPromise
    .then(() => {
        // You are now connected and ready to send commands
    })
    .catch((err: Error) => {
        // An error occured during connection (timeout, unreachable, ...)
    });
let tap: TapDevice = TapDevice.from(protocol: comProtocol)
try tap.connect()

Send commands

Once you are connected to an IoTize device, you can perform IoTize device API calls.

Available commands are organized into multiple services. See the list of services and functions available here: IoTizeDeviceServices (android javadoc)

For example, let's read the serial number from the IoTize Tap using the command IoTizeDeviceServices

import { Tap } from "@iotize/device-client.js/device";
import { Response } from "@iotize/device-client.js/client/api/response";
import { ResponseError } from "@iotize/device-client.js/client/api/response/response-error";
let tap: Tap; // Device object you have created above

// Make sure you are connected 
console.log(`Is device connected: ${tap.isConnected()}`); // Should return true

let responsePromise = tap.service.device.getSerialNumber();
responsePromise
    .then((response: Response<string>) => {
        // Received a response from the device, it does not mean the request was successful
        // You must check response here
        if (response.isSuccess()){
            let serialNumber = response.body(); // Calling .body() will throw an error if request was unsuccessful
            // Do whatever you want with the serial number...
        }
        else{
            console.error(`Unsuccessful response with error: ${ResponseError.createErrorMessage(response)}`);
        }
    })
    .catch((err) => {
        // No response from device (ie: device is not connected or request timeout)
    });

// OR with await:
try{
    let serialNumber = (await tap.service.device.getSerialNumber()).body();
}
catch (error){
    // No response from device (ie: device is not connected or request timeout)
    console.error(`Unsuccessful response with error: ${error.message}`);
}

IoTizeDevice device = IoTizeDevice.fromProtocol(
        // Your protocol
);

Call<String> commandCall = device.services.device.getSerialNumber();

// Execute command synchronously
Response<String> response = commandCall.execute();
if (response.isSuccessful()){
    String serialNumber = response.body();
    Log.i("yourtag", "Serial number is : " + serialNumber);
}
else{
    Log.w("yourtag", "Iotize error code: " + response.codeRet());
}

// OR execute command asynchronously
commandCall.enqueue(new ICallback<String>() {
    @Override
    public void onResponse(Call<String> call, Response<String> response) {
        if (response.isSuccessful()){
            String serialNumber = response.body();
            Log.i("yourlogtag", "Serial number is : " + serialNumber);
        }
        else{
            Log.w("yourtag", "Iotize error code: " + response.codeRet());
        }
    }

    @Override
    public void onFailure(Call<String> call, Throwable throwable) {
        Log.e("yourlogtag", "Error occured: " + throwable.getMessage(), throwable);
    }
});
let tap: TapDevice = ...; // Device object you have created above
let serialNumber = try tap.service.device.getSerialNumber().body()