Skip to content

Quick start

IoTize APIs General Architecture

The IoTize APIs are separated into multiple layers.


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


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

Here are some examples of communication protocols you can use:

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

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

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

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.

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

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

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

// Connect to the device
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()

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();
  .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 {
        `Unsuccessful response with error: ${ResponseError.createErrorMessage(
  .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 =;

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

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

    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()


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