Quick start¶

IoTize APIs General Architecture¶

The IoTize APIs are separated into multiple layers.

IMAGE ALT TEXT HERE

Protocol API¶

This layer controls receiving/transceiving raw data from/to Tap devices.

Client API¶

This layer builds and parses LwM2M commands and responses.

Tap API (Core features)¶

This API provides features specific to IoTize Tap :

Easy access to exposed Tap services with a user friendly API through named functions. Data encoding and decoding is managed for you.
Read/Modify target application variables
Target application variables monitoring
Encrypted communications
User authentication

Extensions¶

You can easily build more advanced features based on the Tap's API. Separate libraries provide extra features:

Relay library: Creates a relay (gateway) between two communication protocols. For example, you can create a relay that transforms incoming socket commands into Bluetooth Low Energy commands.
Configuration library: Configures your IoTize device using configuration scripts.

Setup the communication protocol¶

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:

Typescript

// For websocket
// brower/node.js
import { WebSocketProtocol } from '@iotize/device-com-websocket.js';

let webSocketProtocol = new WebSocketProtocol({
  url: 'ws://yourhost:yourport',
});

// BLE (Bluetooth low energy)
// node.js
import { NobleBLEAdapter, Peripheral } from '@iotize/device-com-ble.node';
let noblePeriferal: 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,
});

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

Swift

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)

Timeout options (optional)¶

For each protocol, you can configure timeout for connect/disconnect and send operations.

Values are in milliseconds
There is no recommanded value, it depends on your application

Typescript

import { AbstractComProtocol } from '@iotize/device-client.js/protocol/impl';
import { ComProtocol } from '@iotize/device-client.js/protocol/api';
import { Tap } from '@iotize/device-client.js/device';

let tap: Tap; // Your device instance...

let protocol: ComProtocol = tap.protocol; // ... your protocol instance (it should extends AbstractComProtocol)
if (protocol instanceof AbstractComProtocol) {
  protocol.options.connect.timeout = 1000 * 5; // 5 seconds for connect timeout
  protocol.options.disconnect.timeout = 1000 * 5; // 5 seconds for disconnect timeout
  protocol.options.send.timeout = 1000 * 10; // 10 seconds for connect timeout
}

Setup the Tap device instance¶

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

Typescript

import { ComProtocol } from '@iotize/device-client.js/protocol/api';
import { Tap } from '@iotize/device-client.js/device';

let protocol: ComProtocol; // Your protocol object (see above)

let tap = Tap.fromProtocol(protocol);

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

Java

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

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

Swift

let tap: TapDevice = TapDevice.from(protocol: comProtocol)
try tap.connect()

Send requests to the tap¶

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

The list of available request are organized into multiple services. See the list of services and functions available here: ../tap-device/service

For example, let's read the serial number from the IoTize Tap using the request getSerialNumber()

Typescript

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

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

Swift

let tap: TapDevice = ...; // Device object you have created above
let serialNumber = try tap.service.device.getSerialNumber().body()

Note

Your tap may return an error code. See Tap device result codes.