Quick start¶

Install¶

Install the library according to your language/platform:

Instantiate an IoTizeDevice 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:

Java

// 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)// ...

Typescript

// For bluetooth low energy communication
// ONLY AVAILABLE in node.js environment
import { NobleBleAdapter }  from "@iotize/device-com-ble.node";

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

// For websocket 
// AVAILABLE in browser or node.js
import { WebSocketProtocol }  from "@iotize/device-com-websocket.js";
let protocol = new WebSocketProtocol({
    url: 'ws://yourhost:yourport'
});


// MQTT 
// AVAILABLE in browser or node.js
import { SocketProtocol } from "@iotize/device-com-mqtt.js";
let protocol = new MqttProtocol({
    host: 'yourhost',
    port: 'yourport',
    // TODO
});

Instantiate your device¶

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

Java

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

// Connect to the device
device.connect();

Typescript

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, ...)
    });

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

Java

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);
    }
});

Typescript

let device: IoTizeDevice = ...; // Device object you have created above

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

let responsePromise = device.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 code: ${response.codeRet()}`);
        }
    })
    .catch((err) => {
        // No response from device (ie: device is not connected or request timeout)
    });

// OR sugar syntax with await:
try{
    let serialNumber = (await device.service.device.getSerialNumber()).body();
}
catch (ex){
    // No response from device (ie: device is not connected or request timeout)
}